Allocating and directing files dynamically: Difference between revisions

From m204wiki
Jump to navigation Jump to search
No edit summary
 
(4 intermediate revisions by the same user not shown)
Line 75: Line 75:
<p>
<p>
Large data sets are supported for <var class="product">Model&nbsp;204</var> database files and journal files, including CCAJLOG, GDG (z/OS only) and stream-based journals, and sequential data sets, including file dumps.</p>
Large data sets are supported for <var class="product">Model&nbsp;204</var> database files and journal files, including CCAJLOG, GDG (z/OS only) and stream-based journals, and sequential data sets, including file dumps.</p>
<p>Large checkpoint data sets are supported on z/OS in Model 204 version 7.7 and later.</p>
<p>
<p>
The <var class="product">Model&nbsp;204</var> <var>DEFINE DATASET</var> and <var>ALLOCATE DATASET</var> commands include the <var>LARGE</var> argument that indicates a data set may have more than 64K tracks.</p>
The <var class="product">Model&nbsp;204</var> <var>DEFINE DATASET</var> and <var>ALLOCATE DATASET</var> commands include the <var>LARGE</var> argument that indicates a data set may have more than 64K tracks.</p>
Line 113: Line 115:
</p></li>
</p></li>
</ul>
</ul>
 
===z/VM considerations===
===z/VM considerations===
<p>
<p>
Line 346: Line 348:
   
   
<p class="note"><b>Note:</b>
<p class="note"><b>Note:</b>
Server data sets are not supported when allocated above the 64K cylinder boundary. An attempt to open any server data set allocated above 64K cylinders results in issuing error [[M204.2917|message 2917]], which identifies the server data set name, and run termination.
Server data sets are not supported when allocated above the 64K cylinder boundary. An attempt to open any server data set allocated above 64K cylinders results in issuing error message M204.2917 (which identifies the server data set name) and run termination.
</p></li>
</p></li>
</ul>
</ul>
Line 768: Line 770:
Use the option to print separator pages in block character format in conjunction with the <var>SEP</var> and <var>HDR1</var>, <var>HDR2</var>, and <var>HDR3</var> parameters. </p>
Use the option to print separator pages in block character format in conjunction with the <var>SEP</var> and <var>HDR1</var>, <var>HDR2</var>, and <var>HDR3</var> parameters. </p>
<p>
<p>
To use this option, the IBM-supplied block character routine, IEFSD095, must reside in the system library SYS1.AOSB0 and must be linked in the ONLINE load module. For more information, see the [https://www.ibm.com/support/knowledgecenter/SSLTBW_1.13.0/com.ibm.zos.r13.hasc300/has2c32527.htm IBM Knowledge Center topic] on this routine.</p>
To use this option, the IBM-supplied block character routine, IEFSD095, must be [[Model 204 installation on IBM z/OS#Linking the Model 204 ONLINE load module|linked in the Online load module]].
</p>
   
   
[[Category:System management]]
[[Category:System management]]
[[Category:System-level capabilities of Model 204]]
[[Category:System-level capabilities of Model 204]]

Latest revision as of 21:07, 6 February 2017

Overview

You can allocate new or existing files in the Model 204 system and direct the output to particular destinations without using specific data set definitions in the startup JCL.

This page explains the use of the following commands:

  • DEFINE DATASET/PRINTER
  • ALLOCATE
  • FREE
  • USE PRINTER/PUNCH

Examples for each operating system are provided.

After the command summaries are sections that explain how to direct output using z/VSE/POWER and how to print separator pages in block format.

Dynamic file allocation

In z/OS and z/VM environments, you can perform dynamic file allocation in the following ways:

  • Create a data set template with the DEFINE DATASET command in the CCAIN input stream before User 0's parameter line:

    DEFINE DATASET name WITH SCOPE=SYSTEM other parameters

    Then dynamically issuing the following command sequence:

    ALLOCATE DATASET name WITH SCOPE=USER FREE DATASET name

  • Allocate data set units in the JCL for the run and then dynamically issue the allocation command sequence:

    ALLOCATE DATASET name WITH SCOPE=USER FREE DATASET name

In the z/OS environment, the actual data set allocation is performed by the standard SVC 99 routine provided by IBM. In the z/VM environment, the allocation service is performed by a Rocket Software-supplied SVC 99 emulation routine. For details on the SVC and the emulation SVC process, refer to the IBM z/OS Job Management Manual.

For z/VSE, files are allocated by complete data set definitions and ALLOCATE control statements in the JCL (see ALLOCATE control statement).

DEFINE DATASET command

The DEFINE command defines types of data structures, such as data sets, sequential I/O streams, program communication processes used by SOUL requests, and output destinations.

The DEFINE DATASET command enables a user with system manager privileges to specify the physical characteristics of dynamically created data sets. DEFINE DATASET creates a template, identified by a name, which is referenced by ALLOCATE and FREE commands.

z/OS considerations

The following considerations apply when using the DEFINE DATASET command in a z/OS environment:

  • The command can span more than one input line.

    A continuation character (-) after the last parameter on the line is required.

  • A newly issued DEFINE DATASET command replaces any previously defined duplicate names.
  • SCOPE=SYSTEM is a required parameter indicating that the definition applies to all users on the system. SCOPE=SYSTEM can be issued only by a user with system manager privileges.
  • The LABEL, POSITION, and DENSITY options of DEFINE DATASET apply only to dynamic allocation of tape data sets under z/OS. For examples, refer to the DEFINE DATASET command page.
  • Operator messages and interactions for dynamic tape allocations are the same as for standard tape allocation. The interaction is controlled by the operating system.
  • Parameters in a DEFINE DATASET command can be overridden by parameters specified in an ALLOCATE command. See ALLOCATE and FREE commands (z/OS and z/VM).
  • If you specify the STRNO parameter in the DD statement, you must give it the same value as the STRINGS parameter in the DEFINE DATASET statement. Preferably, do not specify STRNO in the DD statement.

Large data set support

Large data sets are supported for Model 204 database files and journal files, including CCAJLOG, GDG (z/OS only) and stream-based journals, and sequential data sets, including file dumps.

Large checkpoint data sets are supported on z/OS in Model 204 version 7.7 and later.

The Model 204 DEFINE DATASET and ALLOCATE DATASET commands include the LARGE argument that indicates a data set may have more than 64K tracks.

z/OS data sets may be SMS or non-SMS managed. A z/OS or z/VM data set must be sequential (defined with the PS option) to qualify as a large sequential data set.

Model 204 files may be dumped to or restored from large sequential data sets. Utilities for journal processing — UTILJ, MERGEJ, Audit204 — support large format journal files as input data sets. MERGEJ also supports large data sets as output.

All options of the M204UTIL z/VM utility can allocate and erase large format data sets and initialize, write and read non-indexed OS-format VTOCs on large volume DASD. See the Model 204 Installation Guide for IBM z/VM for information about preparing and using OS format disks under VM.

EXCP and IOS Branch Entry support is also provided.

z/OS examples

The following examples illustrate the use of the DEFINE DATASET command.

  • In this example, DEFINE DATASET creates a template. A user creates an output file that references the template with the ALLOCATE command:

    DEFINE DATASET SAMPLE WITH SCOPE=SYSTEM - LRECL=80 BLKSIZE=800 RECFM=FB SEQUENTIAL - PRIMARY=1 CYLINDER VOLUME=RPG001 ALLOCATE OUTFILE LIKE SAMPLE WITH SCOPE=USER - DSNAME=M204.VEHICLES.REPORT

    • LIKE assigns the attributes of a previously defined data set or template to the data set being defined.
    • WITH assigns the new attributes listed subsequent to it. WITH attributes override those specified in LIKE.
  • In this example, the ALLOCATE command performs the allocation using the allocation attributes included in the DEFINE DATASET command. In this circumstance, ALLOCATE cannot specify any options.

    DEFINE DATASET NAMEONE WITH SCOPE=SYSTEM - LRECL=80 BLKSIZE=1600 RECFM=FB SEQUENTIAL - PRIMARY=1 CYLINDER VOLUME=RPG000 - DSNAME=M204.VEHICLES.REPORT ALLOCATE NAMEONE (no attribute options)

z/VM considerations

The following considerations apply when using the DEFINE DATASET command in a z/VM environment:

  • The command can span more than one input line.

    A continuation character (-) after the last parameter on the line is required.

  • A newly issued DEFINE DATASET command replaces any previously defined duplicate names.
  • SCOPE=SYSTEM is a required parameter indicating that the definition applies to all users on the system. SCOPE=SYSTEM can be issued only by a user with system manager privileges.
  • Parameters in a DEFINE DATASET command can be overridden by parameters specified in an ALLOCATE command. (See ALLOCATE and FREE commands (z/OS and z/VM).)
  • You can specify SECONDARY under z/VM, but no secondary allocation occurs when running under z/VM. The secondary space information is stored in the Volume Table of Contents (VTOC) when allocation is done under z/VM.
  • The VOLUME option is required under z/VM when you create a new data set, or when you reference an existing data set that resides on an unaccessed-format or z/VSE-format minidisk. The VOLUME option is meaningful only during dynamic allocation.

Uses of DEFINE DATASET in the z/VSE environment

A DEFINE DATASET command in the z/VSE environment allows:

  • Translation of the Model 204 internal 8-character file name into a 7-character z/VSE file name acceptable for use on a DLBL or TLBL statement
  • Relating a Model 204 data set name to a logical unit number (useful when routing a data set to a file that cannot be referenced by a data set name)
  • Routing output from a USE command to a printer, punch, or tape device (see Directed output)
  • Specifying options (RECFM, LRECL) that cannot be coded in z/VSE JCL
  • RESTART recovery of a Model 204 file in which the internal file name is related to a 7-character z/VSE file name
  • Use of tape journals or checkpoint streams for RESTART recovery

z/VSE DEFINE DATASET options

The DEFINE DATASET options in a z/VSE environment are described in the following table:

DEFINE DATASET options in a z/VSE environment
Option Specifies...
name Internal name of either a sequential data set or a Model 204 file being defined.
DDNAME=ddname FILENAME=filename Symbolic file name (for disk files) or symbolic unit number (for tape or unit record devices) used in the Job Control Language stream by which the data set can be referenced. The keywords DDNAME and FILENAME are synonymous.
RECFM= { F|FA|FB|FBA|V|VA|VB|VBA|U|UA } Record format of the data set.
LRECL=logical-record-length Logical record length for the file. LRECL and BLKSIZE (below) are verified against each other when the data set is OPENed.
BLKSIZE=physical-block-size Size in bytes of a block of data for the file.
DATALEN=data-length True length of a data record. Record descriptor words for variable length records and/or carriage control characters are excluded.
DATALEN=0

Valid option for DEFINE DATASET.

If the record length cannot be determined when the data set is opened, DATALEN=0 causes an error to occur.

z/VSE considerations

The following considerations apply to DEFINE DATASET in the z/VSE environment:

  • The command can span more than one input line.

    A continuation character (-) after the last parameter on the line is required.

  • You can clear a data set definition by issuing another DEFINE DATASET command with the same name.
  • Values you specify on the DEFINE DATASET command override default values provided by Model 204.
  • Tapes used for sequential I/O must have a standard label and a TLBL JCL statement with a file name equal to the logical unit number. For example:

    // JOB ONLINE . . . // TLBL SYS006,'tape file id' // ASSGN SYS006,TAPE . . // EXEC ONLINE,SIZE=AUTO . . OPEN TEST DUMP TO SYS006

    or:

    DEFINE DATASET DMPTEST WITH SCOPE=SYSTEM - DDNAME=SYS006 OPEN TEST DUMP TO DMPTEST

Extended Task Input/Output Table support

The z/OS operating systems Task Input/Output Table (TIOT) places a limit of 3,273 data sets (allocated dynamically or with DD statements) in any, not just Model 204, job step. To bypass this limit, you can use the Extended Task Input/Output Table (XTIOT) instead of the TIOT for certain data set types. There is no effective limit to the number of data sets that you can allocate using the XTIOT.

Using TIOT and XTIOT with data sets

  • Every data set uses either TIOT or the XTIOT, never both.
  • You decide whether to use the TIOT or the XTIOT on a per data set basis.
  • The TIOT is always used for data sets:
    • Specified in the JCL through DD statements.
    • That are dynamically allocated as sequential or VSAM: that is, are not allocated as Model 204 files.
  • In a RESTART recovery run, each data set that was dynamically allocated in the original run is reallocated, unless NODYNAM was specified. Reallocation always uses the same table, either TIOT or XTIOT, that was used for that data set in the original run.

Using TIOT and XTIOT with dynamically allocated Model 204 files

  • Either the TIOT or the XTIOT can be used for dynamically allocated Model 204 files.
  • Options XTIOT and TIOT of the DEFINE and ALLOCATE commands determine which table to use.
  • The SYSOPT2 parameter setting, X'80', determines whether to use TIOT or XTIOT.
  • You can specify the TIOT and XTIOT only for Model 204 files with the OLD and DIRECT options on an ALLOCATE or DEFINE command, for example:

    ALLOCATE DATASET PAYROLL WITH SCOPE=SYSTEM DSN=A.B.C. OLD DIRECT XTIOT

    • If TIOT is specified on the ALLOCATE command, the TIOT is used.
    • If XTIOT is specified on the ALLOCATE command, the XTIOT is used.
  • If neither TIOT nor XTIOT is specified on the ALLOCATE command, SYSOPT2 determines whether the TIOT or XTIOT is used. If SYSOPT2=X'80' is set, then the XTIOT option is used, for only Model 204 file allocations, otherwise, the TIOT is used.
  • Use of the XTIOT requires use of IOS Branch Entry in the run, where XMEMOPT=X'02' is set in CCAIN. If IOS Branch Entry is not active and XTIOT is specified, the following error is generated when the allocation is attempted and fails.

    M204.2581 XMEMOPT=2 (IOS BRANCH) REQUIRED FOR XTIOT OPTION

Special considerations for obsolete form of ALLOCATE

Special considerations apply when the following obsolete form of the ALLOCATE command is used:

ALLOCATE ddname dsname

Where:

  • The TIOT and XTIOT options cannot be specified.
  • If the ddname starts with TAPE or OUT, sequential organization is assumed; the TIOT option is used.

    Otherwise, a Model 204 file is assumed; either the TIOT or the XTIOT is used, depending on the setting of SYSOPT2.

ALLOCATE and FREE commands (z/OS and z/VM)

The ALLOCATE command dynamically allocates new or existing Model 204 data sets or non-Model 204 data sets in z/OS or z/VM environments. For VSE, see ALLOCATE utility in z/VSE.

To release control of data sets allocated either with ALLOCATE or in the startup JCL, use the FREE command.

ALLOCATE command

When using the ALLOCATE command, the following considerations apply:

  • For dynamic allocation units:
    • You must specify dynamic allocation units in the JCL for the run.
    • To calculate the maximum number of concurrently allocated units, add the value of the DYNAMBR parameter and the DYNAM statements in the run. ALLOCATE does not apply to VSAM.
    • ALLOCATE does not apply to VSAM.
    • When ALLOCATE completes, the file DCB area used is released.
    • The ALOCPRIV parameter (restricted to a user with system manager privileges) designates the data sets users can allocate.

    The scope of the ALOCPRIV parameter is systemwide even when USER is the scope value.

  • For primary and secondary space allocation:
    • Specify the allocation of space (BLOCKS, TRACKS, or CYLINDERS) for a new data set on the PRIMARY option. The BLOCK option allocates space by the BLKSIZE of the actual data multiplied by the PRIMARY option value.
    • Under z/OS, the operating system allocates a maximum of 15 secondary amounts of the type of space specified.
    • Secondary space allocation is not performed under z/VM, unless you specify the SECONDARY option and then you subsequently use the data set under z/OS.
  • For Extended Address Volumes (EAV) allocation:
    • (z/OS version 1.12 and later) Extended Address Volumes (EAV) contain more than 64K cylinders. By specifying the EATTR parameter with the ALLOCATE or DEFINE DATASET command, you can allocate and use Model 204 database files and checkpoint, CCAJRNL, CCAJLOG, and USE data sets on EAV volumes above the 64K cylinder boundary. Both IOS Branch Entry (XMEMOPT=2) and EXCP I/O drivers can handle database files on EAV.
    • The EATTR parameter is effective only in z/OS version 1.12 and later; in all other environments it is ignored with no error message.

    Note: Server data sets are not supported when allocated above the 64K cylinder boundary. An attempt to open any server data set allocated above 64K cylinders results in issuing error message M204.2917 (which identifies the server data set name) and run termination.

Command options

Except for SCOPE, the options of the ALLOCATE command are identical to the options of the DEFINE DATASET command. You can omit ALLOCATE options, if you have specified them on a previous DEFINE DATASET command.

Use of the SCOPE=SYSTEM option is restricted to a user having system manager or administrator privileges. Other users must specify USER or allow SCOPE to default to USER.

Data set types are indicated by file name prefixes:

Prefix Data set type
OUT USE data set (sequential organization)
TAPE Deferred update data set (sequential organization)
DIRECT Direct organization Model 204 file
CCA Model 204 system data set (system manager privileges are required to allocate or free)

Options specified in the ALLOCATE command override DEFINE DATASET options.

Before performing an allocation, Model 204 verifies the NEW/OLD/COND, APPEND/NOAPPEND, and SHR/EXCL options.

The VOLUME option is required under z/VM when a new data set is created or when an existing data set that resides on an unaccessed z/OS-format or z/VSE-format minidisk is referenced.

Because no explicit file creation function exists in CMS, files on CMS disks do not require preallocation. However, you must preallocate files on variable-format disks with a primary allocation and optional secondary extents.

FREE command

The FREE command releases control of data sets allocated by the ALLOCATE command or by specifying the data set in the startup JCL. The freed data set disposition is controlled by the FREE/NOFREE and CATALOG/NOCATALOG options specified on the ALLOCATE command.

A data set cannot be freed if one of the following conditions exists:

  • Data set is currently in use.
  • Data set is a Model 204 system data set (identified by a CCA prefix).

System manager privileges are required to use FREE unless the ALOCPRIV parameters allow the privilege to other users.

Directed output

You can direct output from Model 204 User Language requests and DISPLAY commands to destinations other than the normal Model 204 output device (usually the user's terminal). Alternate destinations are:

  • Sequential data sets
  • Dynamically allocated printer or punch device (z/OS or z/VM)
  • Printer or punch device through the z/VM spooling system (guest operating system under z/VM)
  • Printer using CICS as routing method
  • Printer or punch device using z/VSE/POWER as a router
  • Dynamically allocated printer, punch, or internal reader (z/OS, z/VM, or a guest operating under z/VM)

Note: This functionality is obsolete and supplied only for compatibility.

Command overview

The following commands are required to direct output:

  • DEFINE PRINTER or DEFINE PUNCH to establish definitions (a template) for alternate output destinations

    DEFINE PRINTER/PUNCH commands can be issued only by a user with system manager privileges and can be overridden by another DEFINE PRINTER/PUNCH command for the same template name.

  • USE PRINTER or USE PUNCH to direct output to a dynamically allocated printer or punch device

    Any user can issue the USE command. Parameters specified on a DEFINE PRINTER/PUNCH command can be overridden by the USE command.

    If the output is directed to a sequential data set, a DD/ DLBL/ TLBL/ FILEDEF statement for this data set must be in the Model 204 JCL associated with the user. (Under z/OS or CMS, the sequential data set can also be dynamically allocated during the run using the ALLOCATE command.)

USE command (z/OS, CMS, guest under z/VM)

When you issue the USE command to direct output dynamically to a printer or punch under z/OS, CMS, or a guest operating system under z/VM, you can specify output options by the WITH keyword. Options specified by WITH override corresponding options specified in the DEFINE command.

You must specify the ROUTER option as z/OS, z/VM, or CICS in the USE command or in the DEFINE (PRINTER or PUNCH) command referenced by the USE command.

Parameters valid with the ROUTER=CICS option are:

  • HDR1
  • HDR2
  • SCOPE
  • SEP/NOSEP
  • TERMID (terminal identification of the printer)
  • TRANSID (transaction name of the printer transaction)

DEFINE PRINTER (z/OS, CMS, guest under z/VM)

The DEFINE PRINTER command creates a template that specifies the characteristics of printer output. The template is used for the life of the job unless it is overridden by another DEFINE PRINTER command for the same template name.

Use DEFINE PRINTER in conjunction with the USE command to direct output to a specified printer.

z/OS considerations

Under z/OS, directed output requires a JCL DD statement that associates a CCAPR data set with an alternate device (usually a printer). For example:

//CCAPR DD UNIT=device-unit-number

The device must be included in both the SYSGEN and the directory for the virtual machine is in use.

The following example relates each CCAPR to a virtual print device:

//CCAPR DD UNIT=015 //CCAPR1 DD UNIT=016 . . . //CCAPR7 DD UNIT=022

When you use the DEFINE PRINTER command to establish definitions for alternative output destinations, increase the amount of spare core to allow for the definitions.

CMS considerations

Under CMS, the M204SPL EXEC establishes the link to the z/VM spool for printed output. The EXEC can support all the options for the DEFINE PRINTER and USE PRINTER commands. For more information on the M204SPL, see the Rocket Model 204 Installation Guide for IBM z/VM.

DEFINE PUNCH (z/OS, CMS, guest under z/VM)

The DEFINE PUNCH command creates a template that specifies the characteristics of punch directed output. The template persists for the life of the job unless overridden by another DEFINE PUNCH command for the same template name.

Use DEFINE PUNCH in conjunction with the USE command to direct punch output.

The following considerations apply:

  • Punch output requires a JCL DD statement that associates a CCAPR data set with the address of a punch device.
  • A device is allocated to a user for the duration of the USE command.
  • You must associate each device name with a unique unit address by specifying CCAPU data sets (CCAPU through CCAPU99) in the JCL. You can use all the specified punch data sets concurrently.
  • You must include the device address in both the z/OS SYSGEN and, if running as a guest under z/VM, the z/VM directory for the VS1/SYS/z/OS virtual machine. Each CCAPU data set must be related to a virtual punch.

The following example associates each device name with a unique unit address.

//CCAPU DD UNIT=045 //CCAPU1 DD UNIT=046 . . . //CCAPU99 DD UNIT=145

z/VSE output data sets

The following requirements pertain to z/VSE output data sets:

  • Any data set routed to disk must be described with DLBL and EXTENT statements in the JCL stream executing the batch or online program.
  • Any data set routed to tape must be described with a TLBL statement in the JCL stream used to execute the batch or online program.
  • If a data set is directed to a printer or punch device, a DEFINE DATASET command must be issued prior to the USE command to set the logical record length, the block size, and the record format.
  • The record format must be F (fixed unblocked).

Example

In this example, the USE command directs output of one procedure to a disk file, and the output of a second procedure to a printer. The keyword PRINTER is omitted in the USE command for the second procedure:

// JOB ONLINE WITH USE COMMAND // DLBL OUTPRT,'USE.OUTPRT.FILE' // EXTENT SYS002,balance of extent information // ASSGN SYS002,X'cuu' // DLBL TEST,'M204.DATA.BASE.',,DA // EXTENT SYS005 // ASSGN SYS005,X'cuu' // ASSGN SYS010,PRINTER // UPSI 10010000 // EXEC ONLINE,SIZE=AUTO PAGESZ=6184 LOGIN system-manager-id password OPEN TEST USE OUTPRT <---- Directed output to a disk file INCLUDE ACCOUNT.REPORT . . DEFINE DATASET OUTFILE WITH SCOPE=SYSTEM FILENAME=SYS010 USE OUTFILE <---- Directed output to printer INCLUDE ACCOUNT.REPORT2 /* /&

USE PRINTER command (z/VSE under z/VM)

The following requirements apply to z/VSE running under z/VM:

  • Define print data sets (CCAPR) using the DEFINE DATASET command.
  • Associate the CCAPR file and the print device through a JCL ASSGN statement.
  • If a data set is directed to a printer or punch device, issue a DEFINE DATASET command prior to the USE command to indicate the logical record length, record format, and block size.
  • Define the print or punch device in the z/VSE supervisor and, under z/VM, the directory for the virtual machine.

Example using the JCL ASSGN statement

This example shows the association of the CCAPR data set with the device through a JCL ASSGN statement and a DEFINE DATASET command. The keyword PRINTER is omitted in the USE command:

// JOB ONLINE // ASSGN SYS021,X'06E' ---- Directed output printer // ASSGN SYS022,X'07E' ---- Directed output printer . . // EXEC ONLINE, SIZE=AUTO LOGIN system-manager-id password DEFINE DATASET CCAPR with SCOPE=SYSTEM FILENAME=SYS021 DEFINE DATASET CCAPR1 with SCOPE=SYSTEM FILENAME=SYS022 DEFINE PRINTER THIRDP with SCOPE=SYSTEM - ID=RSCS,TAG=THIRDP,ROUTER=VM . . USE THIRDP . . . /* /&

USE PUNCH command (z/VSE)

The following requirements apply to USE PUNCH in a z/VSE environment:

  • Define punch data sets (CCAPU through CCAPU7) using the DEFINE DATASET command.
  • Associate the CCAPU file and the punch device through a JCL ASSGN statement.

You must define the punch device, X'cuu', in both the z/VSE Supervisor and the z/VM directory for the z/VSE virtual machine.

Example 1: USE PUNCH in z/VSE

This example shows how to define punch-directed output in a z/VSE environment:

// ASSGN SYSxxx,X'cuu' . . . // EXEC ONLINE,SIZE=AUTO PAGESZ=6184,NUSERS= . . . LOGIN system-manager-id password DEFINE DATASET CCAPU WITH SCOPE=SYSTEM FILENAME=SYSxxx

Example 2: USE PUNCH in z/VSE running as guest under z/VM

This example illustrates how to define punch-directed output for z/VSE running as a guest under z/VM. The keyword PUNCH is omitted in the USE command:

//JOB ONLINE . . . //ASSGN SYS021,X'06E' DIRECTED OUTPUT PUNCH //ASSGN SYS022,X'07E' DIRECTED OUTPUT PUNCH . . . //EXEC ONLINE, SIZE=AUTO //CCAPU1 DD UNIT=046 . . . LOGIN system-manager-id password DEFINE DATASET CCAPU WITH SCOPE=SYSTEM FILENAME=SYS021 DEFINE DATASET CCAPU1 WITH SCOPE=SYSTEM FILENAME=SYS022 . . . DEFINE PUNCH THIRDP WITH SCOPE=SYSTEM - ID=RSCS,TAG=THIRDP,ROUTER-VM . . . USE THIRDP . . . /* /&

Using z/VSE/POWER

The implementation of directed output under z/VSE/POWER requires a DEFINE DATASET CCAPPRn/CCAPPUn command to specify a logical unit name that is used in a JCL ASSGN statement to define a POWER printer or punch device. Printers and punches used by z/VSE/POWER must be defined during IPL and started for each partition using the following specifications:

PRINTERS=cuu1 through cuu8

and

PUNCHES=cuu1 through cuu8

A device is allocated to a user for the duration of the USE command.

Printer and punch devices

Simultaneous directed output is supported by the use of CCAPPR and CCAPPR1 through CCAPPR7 for printers; CCAPPU and CCAPPU1 through CCAPPU7 for punches. Each CCAPPR and CCAPPU must be associated with a unique logical unit. The number of defined devices determines the number of simultaneous USE PRINT or USE PUNCH commands that can be directing output.

To identify printer and punch devices for z/VSE/POWER:

DEFINE DATASET powername WITH SCOPE=SYSTEM,- DDNAME=SYSxxx

where powername for printers is:

CCAPPR,CCAPPR1,...

and where powername for punches is:

CCAPPU,CCAPPU1,...

z/VSE/POWER JCL example

This example shows a z/VSE/POWER JCL:

* $$ JOB JNM=MODEL204,CLASS=2 // JOB MODEL204 ONLINE (EXECUTES IN PARTITION F2) . . . // ASSGN SYS011,X'02E' <---- POWER printer 02E // ASSGN SYS012,X'03E' <---- POWER printer 03E // ASSGN SYS013,X'04E' <---- POWER printer 04E // ASSGN SYS021,X'01D' <---- POWER punch // ASSGN SYS022,X'02D' <---- POWER punch // EXEC ONLINE,SIZE=AUTO DEFINE DATASET CCAPPR WITH SCOPE=SYSTEM,DDNAME=SYS011 DEFINE DATASET CCAPPR1 WITH SCOPE=SYSTEM,DDNAME=SYS012 DEFINE DATASET CCAPPR2 WITH SCOPE=SYSTEM,DDNAME=SYS013 DEFINE DATASET CCAPPU WITH SCOPE=SYSTEM,DDNAME=SYS021 DEFINE DATASET CCAPPU1 WITH SCOPE=SYSTEM,DDNAME=SYS022 LOGIN system-manager-id password DEFINE PRINTER PRT1 WITH SCOPE=SYSTEM,ROUTER=POWER, - CLASS=A,NOHOLD,HDR1=OUTFILE1 DEFINE PRINTER REMOTE WITH SCOPE=SYSTEM,ROUTER=POWER,CLASS=Y DEFINE PRINTER PRTX LIKE PRT1 WITH FORMS=3PRT DEFINE PUNCH CARD WITH SCOPE=SYSTEM,ROUTER=POWER,HOLD - DEFINE PUNCH INTERNAL WITH SCOPE=SYSTEM,ROUTER=POWER,INTRDR,CLASS=G DEFINE PUNCH REMCARD LIKE CARD WITH ID=015 USE PRT1 WITH NAME=MYOUTPUT . . USE MYJOB LIKE INTERNAL WITH NAME=MYJOB . . /* /& * $$ EOJ

z/VSE/POWER system requirements: the $$BSGMNT transient

The IBM-supplied $$BSGMNT transient must be available to Model 204 to perform directed output using z/VSE/POWER.

Information for printer and punch directed output (* $$LST statement and * $$PUN statement) is passed to the $$BSGMNT transient. Refer to the IBM z/VSE/POWER Installation and Operations Guide for a detailed description of the * $$LST and * $$PUN statements.

Options specifying default values are not passed to the $$BSGMNT transient.

z/VSE/POWER job stream

When using z/VSE/POWER, take note of the following considerations:

  • The DEFINE DATASET command can appear before User 0 input parameters.
  • DEFINE PRINTER and DEFINE PUNCH must appear after User 0 input parameters and are restricted to users with system manager or administrator privileges.
  • If G is a valid execution class for one of the z/VSE/POWER partitions, the punched output from USE PUNCH MYJOB is run by z/VSE whenever a class G partition is free.
  • The total length of the power statements cannot exceed 71 characters. This includes the 9 characters required for * $$ LST or * $$ PUN. Parameters and values on the DEFINE PRINTER/PUNCH or USE PRINTER/PUNCH commands, after translation to conform to the power statements, cannot exceed 62 characters.
  • If you define an option with a null value on a DEFINE PRINTER/PUNCH or USE PRINTER/PUNCH command, the parameter is not used. This is useful when you specify the LIKE option of these commands.
  • The keyword WITH denotes that specific directed output parameters follow.
  • Parameters can be separated by commas or blanks.
  • The LIKE keyword copies the attributes of some other template previously defined in a DEFINE PRINTER command.

    LIKE used by itself copies all the attributes of the previously defined template specified. WITH used in combination with LIKE causes the parameters specified after WITH to override the attributes of the template name specified in the LIKE phrase.

Tailoring the Model 204 separator page

Use the option to print separator pages in block character format in conjunction with the SEP and HDR1, HDR2, and HDR3 parameters.

To use this option, the IBM-supplied block character routine, IEFSD095, must be linked in the Online load module.