USE PRINTER / PUNCH command: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (→‎Syntax: add links)
 
(7 intermediate revisions by 2 users not shown)
Line 8: Line 8:
<table>
<table>
    
    
<tr> <th>
<tr class="head">  
<p>Operating system </p>
<th><p>Operating system </p></th>  
</th> <th>
<th><p>Directs out put to a...</p></th> </tr>
<p>Directs out put to a...</p>
</th> </tr>
    
    
<tr> <th>z/OS or z/VM </th> <td>Dynamically allocated printer or punch device</td> </tr>
<tr>  
<td>z/OS or z/VM </td>  
<td>Dynamically allocated printer or punch device</td> </tr>
   
   
<tr> <th>
<tr>  
<p>z/OS or z/VSE with the CICS terminal interface </p>
<td>z/OS or z/VSE with the CICS terminal interface</td>  
</th> <td>
<td>CICS printer</td> </tr>
<p>CICS printer</p>
</td> </tr>
   
   
<tr> <th>
<tr>  
<p>z/VSE/POWER</p>
<td>z/VSE/POWER</td>  
</th> <td>
<td>Printer or punch device</td> </tr>  
<p>Printer or punch device</p>
</td> </tr>
 
</table>
</table>
</dl>
</dl>
==Syntax==
==Syntax==
<p class="syntax"><b>U</b>SE [{PRINTER | PUNCH}] [<i>name</i>] [[WITH <i>option</i>]
<p class="syntax"><b>U</b>SE [{PRINTER | PUNCH}] [<i>name</i>] [[WITH <i>option</i>] [,<i>option</i>]...]  
      [,<i>option</i>]...]  
</p>
</p>
   
   
<b>Where:</b>
Where:
<p>name is the name of an output destination. Under z/OS and z/VM, the name can be 1 to 8 characters.</p>
<p>
<p>For the PRINTER and PUNCH forms of the USE command, options are defined in the sections on the DEFINE PRINTER and the DEFINE PUNCH commands.</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===
===Syntax notes===
<p>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.</p>
<p>
<p>Any number of USE output attributes can be specified. Options must be separated by commas or by one or more blanks.</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>Because PRINTER or PUNCH is a valid output name, the following command is valid:</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 class="code">USE PRINTER PRINTER  
</p>
</p>
<p>The ROUTER option must be specified in either the USE command or the DEFINE PRINTER or DEFINE PUNCH command referenced by the USE command.</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==
==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:  
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 class="code">USE PRINTER PAY3
</p>
</p>
<p>The following example performs the function of the previous command without specifying the PRINTER keyword: </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 class="code">USE PAY3
</p>
</p>
<p>The following command changes the TAG attribute of the template named THIRDP and directs the output to a punch device: </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 class="code">USE PUNCH THIRDP WITH TAG=SEVENTH
</p>
</p>
<p>In this example, the USE PRINTER command defines the output destination:</p>
<p>
In this example, the <var>USE PRINTER</var> command defines the output destination:</p>
<p class="code">USE PRINTER -  
<p class="code">USE PRINTER -  
   WITH ROUTER=MVS,CLASS=H, -
   WITH ROUTER=MVS,CLASS=H, -
Line 61: Line 67:
   HDR1=PAYROLL,HDR3=ROOM_12
   HDR1=PAYROLL,HDR3=ROOM_12
</p>
</p>
<p>The following examples illustrate the USE command under native z/VM: </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
<p class="code">USE PRINTER PAY3 WITH TAG=SIXTH
USE PUNCH THIRDP WITH NOHOLD
USE PUNCH THIRDP WITH NOHOLD
Line 70: Line 77:
   DIST=ROOM_12,NOSEP     
   DIST=ROOM_12,NOSEP     
</p>
</p>
==Usage notes==
==Usage notes==
<p>The USE PRINTER and USE PUNCH commands, under z/OS or z/VM, direct output to a dynamically allocated printer or punch device.</p>
<p>
<p>For a guest operating system under z/VM, USE PRINTER and USE PUNCH commands direct output to a printer or punch device.   </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>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 <var class="product">Model&nbsp;204</var> CICS terminal interfaces.</p>
<p>
<p>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.        </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><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 USE PRINTER request are:</p>
<p>
<table>
The modes of operation for a <var>USE PRINTER</var> request are:</p>
 
 
<tr> <th>
<table>  
<p>Mode of operation </p>
<tr class="head"> <th>Mode of operation</th>  
</th> <th>
<th>Action</th> </tr>
<p> Action</p>
</th> </tr>
    
    
<tr> <th><var>
<tr> <td><var>WAITTIME</var> greater than 0</td>  
<p>WAITTIME greater than 0 </p>
<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.
</var></th> <td>
<p>
<p>M204PSFS starts the printer transaction and waits a maximum of WAITTIME 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 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 &amp;PRTWAIT=YES in CICFG forces the terminal user to wait for the physical end of printing before releasing the terminal. </p>
<p>
<p>If the printer is not acquired, a warning message is displayed and no printing is attempted.</p>
If the printer is not acquired, a warning message is displayed and no printing is attempted.</p></td> </tr>
</td> </tr>
   
   
<tr> <th><var>
<tr> <td><var>WAITTIME</var>  less than or equal to 0</td>  
<p>WAITTIME less than or equal to 0 </p>
<td>Print data is placed in Temporary Storage and the printer task is queued, whether or not the printer is currently available.
</var></th> <td>
<p>
<p>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>
<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>
</table>
<p>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.</p>
 
<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>The IBM-supplied sample DCT is modified as follows: </p>
<p class="code">MSGUSR DFHDCT TYPE=SDSCI,
<p class="code">MSGUSR DFHDCT TYPE=SDSCI,
Line 119: Line 127:
INDDEST=CSSL  
INDDEST=CSSL  
</p>
</p>
====Using CICS printers and z/VSE/POWER====
====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>
<p class="code">USE PRINTER name WITH ROUTER=CICS [,option ...]
The syntax for the form of the USE command that allows printed output on CICS printers is as follows: </p>
</p><p>where name is the name of an output destination. </p>
<p class="syntax">USE PRINTER <span class="term">name</span> WITH ROUTER=CICS [,<span class="term">option</span> ...]
<p>For example: </p>
</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 -   
<p class="code">USE PRINTER PROD1 WITH ROUTER=CICS -   
TERMID=L86A TRANSID=U204
TERMID=L86A TRANSID=U204
</p><p>The USE command supports directed output under z/VSE/POWER. The syntax for this form of the USE command is as follows: </p>
</p>
<p class="code">USE [{PRINTER | PUNCH}] [NAME] WITH ROUTER=POWER  
<p>
[,option...]
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><p>Where  </p>
<p class="code">USE [{PRINTER | PUNCH}] [<var class="term">name</var>] WITH ROUTER=POWER  
<p>name is the name of an output destination.</p>
[,<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====
====Referencing a previous definition====
<p>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. See "Defining the destination in the USE command" later in this topic.</p>
<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 DEFINE PRINTER or DEFINE PUNCH command. (See [[DEFINE PRINTER command|"DEFINE PRINTER: Defining the output destination"]] and [[DEFINE PUNCH command|"DEFINE PUNCH: Defining the output destination"]] for a discussion of these two commands.) </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>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.</p>
<p>
<p>For example, if you specify: </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 class="code">USE PRINTER USEREXT  
</p>
</p>
<p><var class="product">Model&nbsp;204</var> 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.</p>
<p>
<p>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: </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 class="code">USE PRINTER USEREXT WITH TAG=EXT02
</p>
</p>
<p><var class="product">Model&nbsp;204</var> 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.</p>
<p>
<p>WITH is not a valid output name.</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>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>
<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, -  
<p class="code">DEFINE PRINTER BOSTON1 WITH ROUTER=VM, ID=RSCS, -  
TAG=BOSTON1, SCOPE=SYSTEM  
TAG=BOSTON1, SCOPE=SYSTEM  
</p>
</p>
<p>You can then reference this definition as follows: </p>
<p>
You can then reference this definition as follows: </p>
<p class="code">USE BOSTON1
<p class="code">USE BOSTON1
BEGIN
BEGIN
Line 158: Line 187:
   .  
   .  
</p>
</p>
<p>Report A is produced</p>
<p>
Report A is produced</p>
<p class="code">  .
<p class="code">  .
   .
   .
Line 164: Line 194:
END  
END  
</p>
</p>
<p>In this example, report A is directed to the virtual machine RSCS with a tag of BOSTON1.</p>
<p>
<p>In the next example, the system manager defines the USERJIM destination as follows:</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, -
<p class="code">DEFINE PRINTER USERJIM WITH ROUTER=VM, ID=JIM, -
SCOPE=SYSTEM  
SCOPE=SYSTEM  
</p>
</p>
<p>You can specify the following:</p>
<p>
You can specify the following:</p>
<p class="code">USE USERJIM
<p class="code">USE USERJIM
BEGIN
BEGIN
Line 179: Line 212:
   .  
   .  
</p>
</p>
<p>Report A is produced</p>
<p>
Report A is produced</p>
<p class="code">  .
<p class="code">  .
   .
   .
Line 191: Line 225:
   .  
   .  
</p>
</p>
<p>Report B is produced</p>
<p>
Report B is produced</p>
<p class="code">  .
<p class="code">  .
   .
   .
Line 197: Line 232:
END  
END  
</p>
</p>
<p>In this example, reports A and B are sent to JIM's reader.</p>
<p>
In this example, reports A and B are sent to the <code>JIM</code> reader.</p>
 
====USE output name====
====USE output name====
<p>If the output name specified in the USE command does not match the name specified in the DEFINE PRINTER or DEFINE PUNCH 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|"USE command: To a sequential data set"]]. </p>
<p>
<p>The specified output name must be of the form OUT<var class="term">xxxxx</var>. If a data set definition statement for the OUT<var class="term">xxxxx</var> name cannot be found in the Job Control Language or EXEC procedure for the run and OUT<var class="term">xxxxx</var> is not the name of a DEFINE DATASET definition, <var class="product">Model&nbsp;204</var> displays a message that the data set does not exist.</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>If <var class="product">Model&nbsp;204</var> is running with an external security interface, a USE command of the form USE OUT<var class="term">xxxxx</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 USE 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>
<p>For more information, refer to the <var class="product">Model&nbsp;204</var> Security Interfaces Manual.</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====
====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>
<p>Suppose that you specify: </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 class="code">USE PRINTER WITH ROUTER=VM, ID=JIM  
</p>
</p>
<p><var class="product">Model&nbsp;204</var> sends the output from this request to the virtual machine with the ID of 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====
====Dynamically allocating output====
<p>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 <var class="product">Model&nbsp;204</var> commands themselves. See the example and discussion in "Dynamically allocating output" in [[DEFINE PRINTER command]].</p>
<p>
[[Category: General user commands]]
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]]
[[Category:Commands]]

Latest revision as of 23:05, 17 October 2017

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.