DEFINE PUNCH command: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (misc formatting)
m (add missing table of router-specific options)
 
Line 41: Line 41:
<p>
<p>
The options in the table below are router-specific. The possible routers are listed in parentheses before the option definition.</p>
The options in the table below are router-specific. The possible routers are listed in parentheses before the option definition.</p>
<table>
<caption>Router-specific DEFINE PUNCH options</caption> 
<tr class="head"> <th>Option </th> <th>ROUTER=</th> <th>Specifies...</th> </tr>
 
<tr> <th><var>CLASS</var></th>
<td nowrap>MVS and VM</td>
<td>Spool class of the output device. The maximum length is one alphanumeric character. The default is <code>B</code>.</td> </tr>
<tr> <th><var>COPIES</var></th>
<td>MVS and VM</td>
<td>Number of copies to punch. The number must be in the range 1 to 255. The default is 1. </td></tr>
<tr> <th><var>DIST</var></th>
<td>VM</td>
<td>Distribution code for the output. The code is 1 to 8 characters. The default value is the first eight characters of the user's <var class="product">Model&nbsp;204</var> user ID. </td> </tr>
<tr> <th><var>FORM</var></th>
<td>POWER</td>
<td>Type of forms to be used for the output. FORM is specified by one to four alphanumeric characters, including hyphen (<tt>-</tt>), period (<tt>.</tt>), and slash (<tt>/</tt>). If FORM is not specified, it is assumed to be four blanks, representing the installation's standard type of forms. FORM is invalid if the output is directed to a 3741 device.
<p>
The z/VSE/POWER equivalent option name is FNO.</p>
</td> </tr>
<tr> <th><var>HOLD or<p>NOHOLD</p></var></th>
<td>MVS and VM</td>
<td>Whether or not data is sent to an output device when one becomes available or is put on hold. The HOLD option delays the sending of the output to a device. The output remains in a queue until it is released.
<p>
The NOHOLD option immediately sends the output to the device. The default is NOHOLD.</p>
</td> </tr>
<tr> <th><var>HOLD or<p>NOHOLD or</p><p>KEEP or</p><p>LEAVE</p></var></th>
<td>POWER</td>
<td>Disposition of the output after the USE file is closed:
<ul>
<li>HOLD and NOHOLD retain output in the punch queue. The z/VSE/POWER equivalent option names are DISP=H and DIDP=D. </li>
<li>KEEP writes output according to its class and priority. When the output has been sent, it is not deleted from the punch queue and the disposition becomes <code>L</code>.</li>
<li>LEAVE retains output in the punch queue. The output is not written out until the operator changes the disposition to <code>D</code> or <code>K</code> through the PALTER command or issues the PRELEASE command. If the output is released using the PRELEASE command, the output is written out, but a copy remains in the queue with a disposition of <code>L</code>. </td> </tr>
<tr> <th><var>ID</var></th>
<td>MVS and VM</td>
<td>Output destination. The identifier consists of 1 to 8 characters.
<p>For z/VM users, the default is the z/VM user ID.</p>
<p>Under z/OS, there is no default. In addition, you cannot specify ID if the WRITER option is indicated. </p></td> </tr>
<tr> <th><var>ID</var></th>
<td>POWER</td>
<td>Destination to which output is routed when networking is active. The ROUTE parameter is used to provide the node ID to use in conjunction with the destination.
<p>
The z/VSE/POWER equivalent option name is the <var class="term">userid</var> option of the DEST parameter.</p></td></tr>
<tr> <th><var>INTERPRET <p>NOINTERPRET</p></var></th>
<td>MVS</td>
<td>Whether a 3525 device type (a card punch with the interpret feature) is assigned to produce the output. INTERPRET assigns a device;
NOINTERPRET, the default, does not assign a device.</td></tr>
<tr> <th><var>INTRDR</var></th>
<td>MVS</td>
<td>INTRDR is equivalent to WRITER=INTRDR. INTRDR is invalid when COPIES or
WRITER is specified.</td></tr>
<tr> <th><var>INTRDR</var></th>
<td>POWER</td>
<td>Specifies that the output return to the input queue. INTRDR must be used if the USE command is used to produce a z/VSE job that you want to submit to the reader queue.
<p>
INTRDR is equivalent to specifying WRITER=INTRDR. INTRDR cannot be specified
when COPIES, SEGSIZE, or WRITER is specified. </p>
<p>
The z/VSE/POWER equivalent option name is DISP=I. </p></td></tr>
<tr> <th><var>JOBSEP</var></th>
<td>POWER</td>
<td>Number of separator pages to generate. JOBSEP must be a number in the range 0-9. If JOBSEP is not specified, the value defined during z/VSE/POWER generation by the JSEP parameter of the POWER macro is assumed. Refer to the <var class="book">z/VSE/POWER Installation and Operations Guide</var> for a description of separator pages and cards.
<p>
The z/VSE/POWER equivalent option name is JSEP.</p></td></tr>
<tr> <th><var>NAME</var></th>
<td>VM</td>
<td>Specifies further identification for the output. The NAME option corresponds to the NAME field in the CP CLOSE command.
<p>
The NAME value can be a z/VM-format file name and file type. The file name and file type must be one to eight alphanumeric characters in length and enclosed in single quotes. The file type defaults to blanks. For a z/OS-format or z/VSE-format file, NAME is a 1-to-24 character identifier (for example <code>M204.OUTPUT</code>).</p></td></tr>
<tr> <th><var>NAME</var></th>
<td>POWER</td>
<td>A one- to eight-character name that is given to the new output. If this option is omitted, the current POWER job name active on the task is used.
<p>
NAME is supplied to the $$BSGMNT transient in addition to the <code>* $$ PUN</code> statement. Therefore, specifying this option is not part of the restriction of the DEFINE PUNCH or USE PUNCH commands (see [[DEFINE PRINTER command]]). </p></td></tr>
<tr> <th><var>OUTLIM</var></th>
<td>MVS</td>
<td>Maximum number of lines of output allowed per request. The range of OUTLIM is 0 to 16777215. A default value of 0 places no limit on the number of lines.
<p>
Since z/OS terminates Online jobs with a S722 abend if the OUTLIM setting is exceeded, Rocket Software recommends setting OUTLIM only for BATCH204 jobs. See z/OS JCL documentation for information about writing an exit routine to circumvent this problem.</p>
</td> </tr>
<tr> <th><var>OUTLIM</var></th>
<td>POWER</td>
<td>Maximum number of lines of output allowed per request. OUTLIM must be a number in the range 0 to 999999. The default OUTLIM value for print output is the value defined during z/VSE/POWER generation in the first entry of the STDLINE parameter of the POWER macro.
<p>
The z/VSE/POWER equivalent option name is RBM.</p>
</td> </tr>
<tr> <th><var>PASSWORD</var></th>
<td>POWER</td>
<td>Password to be associated with the output. The password can consist of one to eight alphanumeric characters. If PASSWORD is not specified, the password obtained from the <code>* $$ JOB</code> statement for the <var class="product">Model&nbsp;204</var> job is used.
<p>
The z/VSE/POWER equivalent option name is PWD.</p>
</td> </tr>
<tr> <th><var>PRIORITY</var></th>
<td>POWER</td>
<td>Priority of the output. PRIORITY must be a number in the range 0 to 9. The default value is the priority of the job running <var class="product">Model&nbsp;204</var>.
<p>
The z/VSE/POWER equivalent option name is PRI.</p>
</td> </tr>
<tr> <th><var>ROUTE</var></th>
<td>MVS</td>
<td>Destination of the output. The maximum length is eight characters. The route must be a valid JES destination. The default is LOCAL. </td> </tr>
<tr> <th><var>ROUTE</var></th>
<td>POWER</td>
<td>Node ID to which output is routed when networking is active. The ID parameter provides the user ID at the node to which output is routed. The maximum length of this option is eight characters. 
<p>
The z/VSE/POWER equivalent option name is the <var class="term">nodeid</var> option of the DEST parameter.</p></td></tr>
<tr> <th><var>SEGSIZE</var></th>
<td>POWER</td>
<td>Number of lines punched before the output is segmented (that is, written out). The effect is as if SEGSIZE lines are written and a new USE command is issued for the same punch.
<p>
You cannot specify SEGSIZE and COPIES or INTRDR. </p>
<p>
SEGSIZE must be in the range 0 to 999999. A default value of zero means that no segmentation occurs.</p>
<p>
The z/VSE/POWER equivalent option name is RBS. </p></td></tr>
<tr> <th><var>SYSID</var></th>
<td>POWER</td>
<td>The system in a shared spooling configuration with which you want to associate the output. Possible values for SYSID are 1 to 9 or <code>N</code>:
<ul>
<li>If SYSID is omitted, the output is associated with the system on which the <var class="product">Model&nbsp;204</var> job is running. </li>
<li>If <code>N</code> is specified, the output is available to any system in the shared-spooling configuration. </li>
</ul>
<p>
The z/VSE/POWER equivalent option name is SYSID.</p></td></tr>
<tr> <th><var><p>TAG</p></var></th>
<td>VM</td>
<td>The description associated with the output. The maximum length is 50 characters. The text must be enclosed in single quotes, if blank characters are included in the text. For example:
<p class="code">TAG = 'BOSTON 5'</p></td></tr>
<tr> <th><var>UCS</var></th>
<td>POWER</td>
<td>The name of the phase under which a UCB (Universal Character Set Buffer) image is cataloged in a core image library available to $$BSGMNT. UCS can be as many as eight characters long.
<p>
The z/VSE/POWER equivalent option name is UCS.</p>
</td> </tr>
<tr> <th><var>USER</var></th>
<td>POWER</td>
<td>As many as 16 alphanumeric characters of user information. If the character string contains blanks or single quotes, the string must be enclosed in single quotation marks (for example, <code>'CORP.ACCTG'</code>). Each embedded single quote must be represented by two quotes. The information appears in the job separator, if JOBSEP is specified. 
<p>
The z/VSE/POWER equivalent option name is USER. </p></td></tr>
<tr> <th><var>WRITER</var></th>
<td>MVS</td>
<td>An external writer subroutine for supporting devices that the JES writers do not support. The subroutine is defined by the installation. The maximum length is eight characters.
<p>
You cannot specify this option if the ID or INTRDR option is used. </p></td></tr>
</table>


==Syntax notes==
==Syntax notes==

Latest revision as of 22:53, 17 October 2017

Summary

Privileges
User 0 or system manager
Function
Specifies an output definition that, together with the USE command, directs Model 204 punched output to a particular system or device. The definition remains in effect throughout the run unless it is overridden by another DEFINE PUNCH command specifying the same name.

Syntax

DEFINE PUNCH name [LIKE previousname] WITH SCOPE=SYSTEM [CLASS] [COPIES] [DIST] [HDR1 | HDR2 | HDR3] [HOLD | NOHOLD] [ID] [INTERPRET | NOINTERPRET] [INTRDR] [NAME] [OUTLIM] [ROUTE] [ROUTER={MVS | VM}] [TAG] [WRITER]

Where:

The options ROUTER, SEP/NOSEP, HDR1, HDR2, and HDR3 are common to all routers. The options common to all routers are described in the table below.

DEFINE PUNCH options (all routers)
Option Specifies...
HDR1

HDR2

HDR3

First, second, or third word of text on the Model 204 separator line. This option can have up to eight characters and is used with the SEP option.

The default for HDR1 is M204LIST.

For HDR2, the default under z/VM is the first eight characters of the Model 204 user ID if you do not indicate a NAME option.

HDR3 has no default.
ROUTER Method used in routing output. MVS and VM are the acceptable values for this option. The ROUTER option is required unless already specified in a template referred to by the LIKE phrase of the current DEFINE PUNCH command. This option has no default value.
SEP

NOSEP

Whether a separator is inserted in Model 204 output.

SEP indicates that there is a separator. Options HDR1, HDR2, and HDR3 form a single line with a blank space between each one.

NOSEP, the default, indicates that there is no separator.

The options in the table below are router-specific. The possible routers are listed in parentheses before the option definition.

Router-specific DEFINE PUNCH options
Option ROUTER= Specifies...
CLASS MVS and VM Spool class of the output device. The maximum length is one alphanumeric character. The default is B.
COPIES MVS and VM Number of copies to punch. The number must be in the range 1 to 255. The default is 1.
DIST VM Distribution code for the output. The code is 1 to 8 characters. The default value is the first eight characters of the user's Model 204 user ID.
FORM POWER Type of forms to be used for the output. FORM is specified by one to four alphanumeric characters, including hyphen (-), period (.), and slash (/). If FORM is not specified, it is assumed to be four blanks, representing the installation's standard type of forms. FORM is invalid if the output is directed to a 3741 device.

The z/VSE/POWER equivalent option name is FNO.

HOLD or

NOHOLD

MVS and VM Whether or not data is sent to an output device when one becomes available or is put on hold. The HOLD option delays the sending of the output to a device. The output remains in a queue until it is released.

The NOHOLD option immediately sends the output to the device. The default is NOHOLD.

HOLD or

NOHOLD or

KEEP or

LEAVE

POWER Disposition of the output after the USE file is closed:
  • HOLD and NOHOLD retain output in the punch queue. The z/VSE/POWER equivalent option names are DISP=H and DIDP=D.
  • KEEP writes output according to its class and priority. When the output has been sent, it is not deleted from the punch queue and the disposition becomes L.
  • LEAVE retains output in the punch queue. The output is not written out until the operator changes the disposition to D or K through the PALTER command or issues the PRELEASE command. If the output is released using the PRELEASE command, the output is written out, but a copy remains in the queue with a disposition of L.
ID MVS and VM Output destination. The identifier consists of 1 to 8 characters.

For z/VM users, the default is the z/VM user ID.

Under z/OS, there is no default. In addition, you cannot specify ID if the WRITER option is indicated.

ID POWER Destination to which output is routed when networking is active. The ROUTE parameter is used to provide the node ID to use in conjunction with the destination.

The z/VSE/POWER equivalent option name is the userid option of the DEST parameter.

INTERPRET

NOINTERPRET

MVS Whether a 3525 device type (a card punch with the interpret feature) is assigned to produce the output. INTERPRET assigns a device; NOINTERPRET, the default, does not assign a device.
INTRDR MVS INTRDR is equivalent to WRITER=INTRDR. INTRDR is invalid when COPIES or WRITER is specified.
INTRDR POWER Specifies that the output return to the input queue. INTRDR must be used if the USE command is used to produce a z/VSE job that you want to submit to the reader queue.

INTRDR is equivalent to specifying WRITER=INTRDR. INTRDR cannot be specified when COPIES, SEGSIZE, or WRITER is specified.

The z/VSE/POWER equivalent option name is DISP=I.

JOBSEP POWER Number of separator pages to generate. JOBSEP must be a number in the range 0-9. If JOBSEP is not specified, the value defined during z/VSE/POWER generation by the JSEP parameter of the POWER macro is assumed. Refer to the z/VSE/POWER Installation and Operations Guide for a description of separator pages and cards.

The z/VSE/POWER equivalent option name is JSEP.

NAME VM Specifies further identification for the output. The NAME option corresponds to the NAME field in the CP CLOSE command.

The NAME value can be a z/VM-format file name and file type. The file name and file type must be one to eight alphanumeric characters in length and enclosed in single quotes. The file type defaults to blanks. For a z/OS-format or z/VSE-format file, NAME is a 1-to-24 character identifier (for example M204.OUTPUT).

NAME POWER A one- to eight-character name that is given to the new output. If this option is omitted, the current POWER job name active on the task is used.

NAME is supplied to the $$BSGMNT transient in addition to the * $$ PUN statement. Therefore, specifying this option is not part of the restriction of the DEFINE PUNCH or USE PUNCH commands (see DEFINE PRINTER command).

OUTLIM MVS Maximum number of lines of output allowed per request. The range of OUTLIM is 0 to 16777215. A default value of 0 places no limit on the number of lines.

Since z/OS terminates Online jobs with a S722 abend if the OUTLIM setting is exceeded, Rocket Software recommends setting OUTLIM only for BATCH204 jobs. See z/OS JCL documentation for information about writing an exit routine to circumvent this problem.

OUTLIM POWER Maximum number of lines of output allowed per request. OUTLIM must be a number in the range 0 to 999999. The default OUTLIM value for print output is the value defined during z/VSE/POWER generation in the first entry of the STDLINE parameter of the POWER macro.

The z/VSE/POWER equivalent option name is RBM.

PASSWORD POWER Password to be associated with the output. The password can consist of one to eight alphanumeric characters. If PASSWORD is not specified, the password obtained from the * $$ JOB statement for the Model 204 job is used.

The z/VSE/POWER equivalent option name is PWD.

PRIORITY POWER Priority of the output. PRIORITY must be a number in the range 0 to 9. The default value is the priority of the job running Model 204.

The z/VSE/POWER equivalent option name is PRI.

ROUTE MVS Destination of the output. The maximum length is eight characters. The route must be a valid JES destination. The default is LOCAL.
ROUTE POWER Node ID to which output is routed when networking is active. The ID parameter provides the user ID at the node to which output is routed. The maximum length of this option is eight characters.

The z/VSE/POWER equivalent option name is the nodeid option of the DEST parameter.

SEGSIZE POWER Number of lines punched before the output is segmented (that is, written out). The effect is as if SEGSIZE lines are written and a new USE command is issued for the same punch.

You cannot specify SEGSIZE and COPIES or INTRDR.

SEGSIZE must be in the range 0 to 999999. A default value of zero means that no segmentation occurs.

The z/VSE/POWER equivalent option name is RBS.

SYSID POWER The system in a shared spooling configuration with which you want to associate the output. Possible values for SYSID are 1 to 9 or N:
  • If SYSID is omitted, the output is associated with the system on which the Model 204 job is running.
  • If N is specified, the output is available to any system in the shared-spooling configuration.

The z/VSE/POWER equivalent option name is SYSID.

TAG

VM The description associated with the output. The maximum length is 50 characters. The text must be enclosed in single quotes, if blank characters are included in the text. For example:

TAG = 'BOSTON 5'

UCS POWER The name of the phase under which a UCB (Universal Character Set Buffer) image is cataloged in a core image library available to $$BSGMNT. UCS can be as many as eight characters long.

The z/VSE/POWER equivalent option name is UCS.

USER POWER As many as 16 alphanumeric characters of user information. If the character string contains blanks or single quotes, the string must be enclosed in single quotation marks (for example, 'CORP.ACCTG'). Each embedded single quote must be represented by two quotes. The information appears in the job separator, if JOBSEP is specified.

The z/VSE/POWER equivalent option name is USER.

WRITER MVS An external writer subroutine for supporting devices that the JES writers do not support. The subroutine is defined by the installation. The maximum length is eight characters.

You cannot specify this option if the ID or INTRDR option is used.

Syntax notes

You can specify any number of DEFINE PUNCH output options. Options must be separated by commas or by one or more blanks.

For general syntax and usage notes that apply to all forms of the DEFINE command, see DEFINE command.

Examples

The following examples show DEFINE PUNCH commands for a system running under native z/OS. The first example uses the WITH phrase to define the attributes of an output destination:

DEFINE PUNCH THIRDP - WITH SCOPE=SYSTEM,ROUTER=MVS, - ROUTE=THIRD,NOSEP

The following example creates an output definition by using the LIKE phrase to refer to most of the attributes of the definition created in the first example. The WITH phrase is used to redefine the ROUTE option.

DEFINE PUNCH FOURTHP LIKE THIRDP - WITH SCOPE=SYSTEM,ROUTE=FOURTH

The following examples show DEFINE PUNCH commands for a system running under native z/VM or a guest operating system under z/VM:

DEFINE PUNCH THIRDP - WITH SCOPE=SYSTEM,ROUTER=VM, - ID=RSCS,TAG=THIRD,NOSEP,HOLD DEFINE PUNCH FOURTHP LIKE THIRDP - WITH TAG=FOURTH,NOHOLD

Usage notes

The DEFINE PUNCH command specifies a destination for Model 204 punched output and describes the characteristics of output that is to be sent to that destination. The options for this command give you more control over output and tailor the Model 204 separator page. The destination might be another system or an alternate device. Any number of different definitions can be specified. These definitions exist for the duration of the Model 204 run and are available to all users. Once a particular definition has been specified, it can be changed only with another DEFINE PUNCH command or USE command for that destination.

The DEFINE PUNCH command is optional. The information supplied in this command can be specified instead in the USE command that actually directs the output to the alternate device.

The DEFINE PUNCH command can be issued when Model 204 is running under native z/OS, native z/VM, or a guest operating system under z/VM, or z/VSE/POWER. The guest operating system can be any z/OS or z/VSE operating system supported by Model 204. This command is not available under z/OS if the Preferred Machine Assist feature is used.

Whenever you issue a USE command to direct output to a destination other than your terminal, Model 204 determines whether an output definition has been specified for that alternate destination in a DEFINE PUNCH command. The characteristics-for example, output identifiers, number of copies, separator format-specified in the DEFINE PUNCH definition are used to produce the output. These characteristics can be overridden by any options specified in the USE command itself. (See USE: Directing output.) In addition, certain characteristics are determined by the device selection made by the system manager in the Job Control Language or EXEC procedure for the run.