View source for USE PRINTER / PUNCH command

==Summary==
<dl>
<dt>Privileges
<dd>Any user
<dt>Function
<dd>
<p>The output destination is determined by the operating system as follows:</p>
<table>
   
<tr class="head"> 
<th><p>Operating system </p></th> 
<th><p>Directs out put to a...</p></th> </tr>
   
<tr> 
<td>z/OS or z/VM </td> 
<td>Dynamically allocated printer or punch device</td> </tr>
 
<tr> 
<td>z/OS or z/VSE with the CICS terminal interface</td> 
<td>CICS printer</td> </tr>
 
<tr> 
<td>z/VSE/POWER</td> 
<td>Printer or punch device</td> </tr> 
</table>
</dl>

==Syntax==
<p class="syntax"><b>U</b>SE [{PRINTER | PUNCH}] [<i>name</i>] [[WITH <i>option</i>] [,<i>option</i>]...] 
</p>
 
Where:
<p>
<var class="term">name</var> is the name of an output destination. Under z/OS and z/VM, the name can be 1 to 8 characters.</p>
<p>
For the <var>PRINTER</var> and <var>PUNCH</var> forms of the <var>USE</var> command, options are those defined in [[DEFINE PRINTER command]] and [[DEFINE PUNCH command]].</p>

===Syntax notes===
<p>
An output destination name is optional. If one is specified, it must be a template created by a prior <var>DEFINE PRINTER</var> or <var>DEFINE PUNCH</var> command. Template attributes must be valid in the current operating environment. For example, the <var>BURST</var> attribute can be specified only under z/OS. Options indicated in the <var>WITH</var> phrase of the <var>USE</var> command override the attributes of the template.</p>
<p>
Any number of <var>USE</var> output attributes can be specified. Options must be separated by commas or by one or more blanks.</p>
<p>
Because <var>PRINTER</var> or <var>PUNCH</var> is a valid output name, the following command is valid:</p>
<p class="code">USE PRINTER PRINTER 
</p>
<p>
The <var>ROUTER</var> option must be specified in the <var>USE</var> command or in the <var>DEFINE PRINTER</var> or <var>DEFINE PUNCH</var> command referenced by the <var>USE</var> command.</p>

==Example==
The following examples illustrate the <var>USE</var> command under native z/OS. This example directs the output of a template named <code>PAY3</code> to a printer: 
<p class="code">USE PRINTER PAY3
</p>
<p>
The following example performs the function of the previous command without specifying the <var>PRINTER</var> keyword: </p>
<p class="code">USE PAY3
</p>
<p>
The following command changes the TAG attribute of the template named <code>THIRDP</code> and directs the output to a punch device: </p>
<p class="code">USE PUNCH THIRDP WITH TAG=SEVENTH
</p>
<p>
In this example, the <var>USE PRINTER</var> command defines the output destination:</p>
<p class="code">USE PRINTER - 
  WITH ROUTER=MVS,CLASS=H, -
  ROUTE=THIRD,COPIES=2, -
  HDR1=PAYROLL,HDR3=ROOM_12
</p>
<p>
The following examples illustrate the <var>USE</var> command under native z/VM: </p>
<p class="code">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    
</p>

==Usage notes==
<p>
The <var>USE PRINTER</var> and <var>USE PUNCH</var> commands, under z/OS or z/VM, direct output to a dynamically allocated printer or punch device.</p>
<p>
For a guest operating system under z/VM, <var>USE PRINTER</var> and <var>USE PUNCH</var> commands direct output to a printer or punch device. </p>
<p>
The <var>USE PRINTER</var> command and the <var>DEFINE PRINTER</var> 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 <var class="product">Model&nbsp;204</var> CICS terminal interfaces.</p>
<p>
The amount of time that the CICS interface waits for a CICS printer to become available is specified by the <var>WAITTIME</var> parameter. If the parameter is set too low, CICS cannot start the printer transaction in time.        </p>
<p><var class="product">Model&nbsp;204</var> CICS printer support uses CICS Temporary Storage queues to spool the output, reducing the waiting time for the terminal.</p>
<p>
The modes of operation for a <var>USE PRINTER</var> request are:</p>

<table> 
<tr class="head"> <th>Mode of operation</th> 
<th>Action</th> </tr>
   
<tr> <td><var>WAITTIME</var> greater than 0</td> 
<td>M204PSFS starts the printer transaction and waits a maximum of <var>WAITTIME</var> to determine if the printer is acquired for the printer task.
<p>
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 <code>&amp;PRTWAIT=YES</code> in CICFG forces the terminal user to wait for the physical end of printing before releasing the terminal. </p>
<p>
If the printer is not acquired, a warning message is displayed and no printing is attempted.</p></td> </tr>
 
<tr> <td><var>WAITTIME</var>  less than or equal to 0</td> 
<td>Print data is placed in Temporary Storage and the printer task is queued, whether or not the printer is currently available.
<p>
If the Temporary Storage queues are written to AUXILIARY storage, the print queues are recoverable, although not through a cold start. </p></td> </tr>
</table>

<p>
For a <var>USE PRINTER</var> 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.</p>
<p>The IBM-supplied sample DCT is modified as follows: </p>
<p class="code">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 
</p>

====Using CICS printers and z/VSE/POWER====
<p>
The syntax for the form of the USE command that allows printed output on CICS printers is as follows: </p>
<p class="syntax">USE PRINTER <span class="term">name</span> WITH ROUTER=CICS [,<span class="term">option</span> ...]
</p>
<p>
where <var class="term">name</var> is the name of an output destination. </p>
<p>
For example: </p>
<p class="code">USE PRINTER PROD1 WITH ROUTER=CICS -   
TERMID=L86A TRANSID=U204
</p>
<p>
The <var>USE</var> command supports directed output under z/VSE/POWER. The syntax for this form of the <var>USE</var> command is as follows: </p>
<p class="code">USE [{PRINTER | PUNCH}] [<var class="term">name</var>] WITH ROUTER=POWER 
[,<var class="term">option</var>...]
</p>
<p>
Where:  </p>
<p>
<var class="term">name</var> is the name of an output destination.</p>

====Referencing a previous definition====
<p>
In the <var>USE</var> 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 [[USE PRINTER / PUNCH command#Defining the destination in the USE command|specifying the destination in the USE command itself]].</p>
<p>
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 <var>[[DEFINE PRINTER command|DEFINE PRINTER]]</var> or <var>[[DEFINE PUNCH command|DEFINE PUNCH]]</var> command. </p>
<p>
By specifying the name of a previously defined destination in the <var>USE</var> command, you cause output to be sent to this destination. The output has the characteristics defined by the system manager.</p>
<p>
For example, if you specify: </p>
<p class="code">USE PRINTER USEREXT 
</p>
<p>
<var class="product">Model&nbsp;204</var> obtains the definition of the <code>USEREXT</code> device from the <var>DEFINE PRINTER</var> command specified by the system administrator, and sends output to that device according to the options specified in that command.</p>
<p>
If desired, you can override output characteristics established by the system manager by specifying alternative values through the <var>WITH</var> phrase of the <var>USE</var> command. For example, if you specify: </p>
<p class="code">USE PRINTER USEREXT WITH TAG=EXT02
</p>
<p>
<var class="product">Model&nbsp;204</var> obtains the definition of the <code>USEREXT</code> device from the appropriate <var>DEFINE PRINTER</var> command, but replaces the <var>TAG</var> value specified in that command with the <code>EXT02</code> value you specify.</p>
<p>
<code>WITH</code> is not a valid output name.</p>
<p>
The following example shows how a destination is defined and referenced in a <var class="product">Model&nbsp;204</var> session. Suppose that the system manager issues the following command:</p>
<p class="code">DEFINE PRINTER BOSTON1 WITH ROUTER=VM, ID=RSCS, - 
TAG=BOSTON1, SCOPE=SYSTEM 
</p>
<p>
You can then reference this definition as follows: </p>
<p class="code">USE BOSTON1
BEGIN
CARS:  FIND ALL RECORDS
       END FIND
       FOR EACH RECORD IN CARS
  .
  .
  . 
</p>
<p>
Report A is produced</p>
<p class="code">  .
  .
  . 
END 
</p>
<p>
In this example, report A is directed to the virtual machine <code>RSCS</code> with a tag of <code>BOSTON1</code>.</p>
<p>
In the next example, the system manager defines the <code>USERJIM</code> destination as follows:</p>
<p class="code">DEFINE PRINTER USERJIM WITH ROUTER=VM, ID=JIM, -
SCOPE=SYSTEM 
</p>
<p>
You can specify the following:</p>
<p class="code">USE USERJIM
BEGIN
CARS:  FIND ALL RECORDS
       END FIND
       FOR EACH RECORD IN CARS
  .
  .
  . 
</p>
<p>
Report A is produced</p>
<p class="code">  .
  .
  .
END MORE USE
  .
MORE
PRINT: FOR EACH RECORD IN CARS
  .
  .
  . 
</p>
<p>
Report B is produced</p>
<p class="code">  .
  .
  .
END 
</p>
<p>
In this example, reports A and B are sent to the <code>JIM</code> reader.</p>

====USE output name====
<p>
If the output name specified in the <var>USE</var> command does not match the name specified in the <var>DEFINE PRINTER</var> or <var>DEFINE PUNCH</var> definition, <var class="product">Model&nbsp;204</var> assumes that the name represents a sequential output data set of the kind described in [[USE command: To a sequential data set]]. </p>
<p>
The specified output name must be of the form <var>OUT<i>xxxxx</i></var>. If a data set definition statement for the <var>OUT<i>xxxxx</i></var> name cannot be found in the Job Control Language or EXEC procedure for the run and <var>OUT<i>xxxxx</i></var> is not the name of a <var>DEFINE DATASET</var> definition, <var class="product">Model&nbsp;204</var> displays a message that the data set does not exist.</p>
<p>
If <var class="product">Model&nbsp;204</var> is running with an external security interface, a <var>USE</var> command of the form <var>USE OUT<i>xxxxx</i></var> 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 <var>USE</var> command fails, the attempt is logged as a security violation, and a <var class="product">Model&nbsp;204</var> error message is displayed.</p>
<p>
For more information, refer to the [[:Category:Security interfaces|Security interfaces topics]].</p>

====Defining the destination in the USE command====
<p>
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.</p>
<p>
Suppose that you specify: </p>
<p class="code">USE PRINTER WITH ROUTER=VM, ID=JIM 
</p>
<p>
<var class="product">Model&nbsp;204</var> sends the output from this request to the virtual machine with the ID of <code>JIM</code>.</p>

====Dynamically allocating output====
<p>
The <var>USE</var> command (and the <var>DEFINE PRINTER</var> command) support the dynamic allocation parameter, <var>OUTPUT</var>, to allow you to use special formatting options that are not supported directly on these <var class="product">Model&nbsp;204</var> commands themselves. See the example and discussion in [[DEFINE PRINTER command#Dynamically allocating output|Dynamically allocating output]].</p>

[[Category: User commands]]
[[Category:Commands]]