USE PRINTER / PUNCH command

Summary

Privileges

Any user

Function

The output destination is determined by the operating system as follows:

Operating system	Directs out put to a...
z/OS or z/VM	Dynamically allocated printer or punch device
z/OS or z/VSE with the CICS terminal interface	CICS printer
z/VSE/POWER	Printer or punch device

Syntax

USE [{PRINTER | PUNCH}] [name] [[WITH option] [,option]...]

Where:

name is the name of an output destination. Under z/OS and z/VM, the name can be 1 to 8 characters.

For the PRINTER and PUNCH forms of the USE command, options are those defined in DEFINE PRINTER command and DEFINE PUNCH command.

Syntax notes

An output destination name is optional. If one is specified, it must be a template created by a prior DEFINE PRINTER or DEFINE PUNCH command. Template attributes must be valid in the current operating environment. For example, the BURST attribute can be specified only under z/OS. Options indicated in the WITH phrase of the USE command override the attributes of the template.

Any number of USE output attributes can be specified. Options must be separated by commas or by one or more blanks.

Because PRINTER or PUNCH is a valid output name, the following command is valid:

USE PRINTER PRINTER

The ROUTER option must be specified in the USE command or in the DEFINE PRINTER or DEFINE PUNCH command referenced by the USE command.

Example

The following examples illustrate the USE command under native z/OS. This example directs the output of a template named PAY3 to a printer:

USE PRINTER PAY3

The following example performs the function of the previous command without specifying the PRINTER keyword:

USE PAY3

The following command changes the TAG attribute of the template named THIRDP and directs the output to a punch device:

USE PUNCH THIRDP WITH TAG=SEVENTH

In this example, the USE PRINTER command defines the output destination:

USE PRINTER - WITH ROUTER=MVS,CLASS=H, - ROUTE=THIRD,COPIES=2, - HDR1=PAYROLL,HDR3=ROOM_12

The following examples illustrate the USE command under native z/VM:

USE PRINTER PAY3 WITH TAG=SIXTH USE PUNCH THIRDP WITH NOHOLD USE THIRDP WITH TAG=SEVENTH USE PRINTER - WITH ROUTER=VM,CLASS=H, - ID=RSCS,TAG=THIRD,NAME=PAYROLL, - DIST=ROOM_12,NOSEP

Usage notes

The USE PRINTER and USE PUNCH commands, under z/OS or z/VM, direct output to a dynamically allocated printer or punch device.

For a guest operating system under z/VM, USE PRINTER and USE PUNCH commands direct output to a printer or punch device.

The USE PRINTER command and the DEFINE PRINTER command provide the CICS user with direct printer support to CICS 3280- and TTY/TWX-type printers. (Support is not available for 3289 printers and the pseudo conversational facility.) Because a spooling capability is not provided, the user's terminal is locked until printing is completed. This feature can be used only with Model 204 CICS terminal interfaces.

The amount of time that the CICS interface waits for a CICS printer to become available is specified by the WAITTIME parameter. If the parameter is set too low, CICS cannot start the printer transaction in time.

Model 204 CICS printer support uses CICS Temporary Storage queues to spool the output, reducing the waiting time for the terminal.

The modes of operation for a USE PRINTER request are:

Mode of operation	Action
WAITTIME greater than 0	M204PSFS starts the printer transaction and waits a maximum of WAITTIME to determine if the printer is acquired for the printer task. If the printer is acquired, M204PSFS writes all print data to a Temporary Storage queue. When the last data record is received, it "wakes" the printer task to print, and releases the terminal to the user. However, specifying &PRTWAIT=YES in CICFG forces the terminal user to wait for the physical end of printing before releasing the terminal. If the printer is not acquired, a warning message is displayed and no printing is attempted.
WAITTIME less than or equal to 0	Print data is placed in Temporary Storage and the printer task is queued, whether or not the printer is currently available. If the Temporary Storage queues are written to AUXILIARY storage, the print queues are recoverable, although not through a cold start.

For a USE PRINTER transaction in OBCIPR, a message is written to the CICS job log when the printing is completed. The message contains the printer's terminal ID and the Temporary Storage queue name. A message is written to the job log for any abend of the printer transaction.

The IBM-supplied sample DCT is modified as follows:

MSGUSR DFHDCT TYPE=SDSCI, BLKSIZE=132, BUFNO=1, SCNAME=MSGUSR, RECFORM=VARUNB, ECSIZE=132, TYPEFLE=OUTPUT CSSL DFHDCT TYPE=EXTRA, DESTID=CSSL, RSL=PUBLIC, DSCNAME=MSGUSR M204 DFHDCT TYPE=INDIRECT, M204 MESSAGES DESTID=M204, RSL=PUBLIC, INDDEST=CSSL

Using CICS printers and z/VSE/POWER

The syntax for the form of the USE command that allows printed output on CICS printers is as follows:

USE PRINTER name WITH ROUTER=CICS [,option ...]

where name is the name of an output destination.

For example:

USE PRINTER PROD1 WITH ROUTER=CICS - TERMID=L86A TRANSID=U204

The USE command supports directed output under z/VSE/POWER. The syntax for this form of the USE command is as follows:

USE [{PRINTER | PUNCH}] [name] WITH ROUTER=POWER [,option...]

Where:

name is the name of an output destination.

Referencing a previous definition

In the USE command, the output destination and the characteristics of the output sent to it can be described either by referencing a previously defined destination or by specifying the destination in the USE command itself.

The system administrator can define an output destination and describe the characteristics (for example, output identifiers, number of copies, form name) of the output to be sent to it in a DEFINE PRINTER or DEFINE PUNCH command.

By specifying the name of a previously defined destination in the USE command, you cause output to be sent to this destination. The output has the characteristics defined by the system manager.

For example, if you specify:

USE PRINTER USEREXT

Model 204 obtains the definition of the USEREXT device from the DEFINE PRINTER command specified by the system administrator, and sends output to that device according to the options specified in that command.

If desired, you can override output characteristics established by the system manager by specifying alternative values through the WITH phrase of the USE command. For example, if you specify:

USE PRINTER USEREXT WITH TAG=EXT02

Model 204 obtains the definition of the USEREXT device from the appropriate DEFINE PRINTER command, but replaces the TAG value specified in that command with the EXT02 value you specify.

WITH is not a valid output name.

The following example shows how a destination is defined and referenced in a Model 204 session. Suppose that the system manager issues the following command:

DEFINE PRINTER BOSTON1 WITH ROUTER=VM, ID=RSCS, - TAG=BOSTON1, SCOPE=SYSTEM

You can then reference this definition as follows:

USE BOSTON1 BEGIN CARS: FIND ALL RECORDS END FIND FOR EACH RECORD IN CARS . . .

Report A is produced

. . . END

In this example, report A is directed to the virtual machine RSCS with a tag of BOSTON1.

In the next example, the system manager defines the USERJIM destination as follows:

DEFINE PRINTER USERJIM WITH ROUTER=VM, ID=JIM, - SCOPE=SYSTEM

You can specify the following:

USE USERJIM BEGIN CARS: FIND ALL RECORDS END FIND FOR EACH RECORD IN CARS . . .

Report A is produced

. . . END MORE USE . MORE PRINT: FOR EACH RECORD IN CARS . . .

Report B is produced

. . . END

In this example, reports A and B are sent to the JIM reader.

USE output name

If the output name specified in the USE command does not match the name specified in the DEFINE PRINTER or DEFINE PUNCH definition, Model 204 assumes that the name represents a sequential output data set of the kind described in USE command: To a sequential data set.

The specified output name must be of the form OUTxxxxx. If a data set definition statement for the OUTxxxxx name cannot be found in the Job Control Language or EXEC procedure for the run and OUTxxxxx is not the name of a DEFINE DATASET definition, Model 204 displays a message that the data set does not exist.

If Model 204 is running with an external security interface, a USE command of the form USE OUTxxxxx results in a check to determine whether you are authorized for the request. You must have the appropriate WRITE level privileges for the output data set. If you do not have this authority, the USE command fails, the attempt is logged as a security violation, and a Model 204 error message is displayed.

For more information, refer to the Security interfaces topics.

Defining the destination in the USE command

You can define the output destination in a USE command. However, in general, it is recommended that the system administrator define destinations so that possible configuration changes do not affect a user's commands.

Suppose that you specify:

USE PRINTER WITH ROUTER=VM, ID=JIM

Model 204 sends the output from this request to the virtual machine with the ID of JIM.

Dynamically allocating output

The USE command (and the DEFINE PRINTER command) support the dynamic allocation parameter, OUTPUT, to allow you to use special formatting options that are not supported directly on these Model 204 commands themselves. See the example and discussion in Dynamically allocating output.