registration
Ibm-jcl

Ibm-jcl

This course contains the basics of Ibm-jcl

Course introduction
Interview Questions
Pragnya Meter Exam

Ibm-jcl

DD statement

Purpose
Use the DD (data definition) statement to describe a data set and to specify the input and output resources needed for the data set. The parameters you can specify for data set definition are arranged alphabetically in the following pages.

Description

1.Syntax

// [ddname ] DD [positional-parameter][,keyword-parameter]...[comments]
   [procstepname.ddname]
// [ddname ] DD
   [procstepname.ddname]
  • The DD statement consists of the characters // in columns 1 and 2 and four fields: name, operation (DD), parameter, and comments. Do not code comments if the parameter field is blank.
  • A DD statement is required for each data set.
  • The maximum number of DD statements per job step is 3273, based on the number of single DD statements allowed for a TIOT (task input output table) control block size of 64K. This limit can be different depending on the installation-defined TIOT size. The IBM-supplied default TIOT size is 32K.In a JES3 system, the installation might further reduce the maximum number of DD statements per job.

2.Name Field

When specified, code a ddname as follows:

  • Each ddname should be unique within the job step. If duplicate ddnames appear in a job step, processing is as follows:
  • In a JES2 system: The system performs device and space allocation and disposition processing for both DD statements; however, it directs all references to the first DD statement in the step.
    In a JES3 system: If both DD statements request JES3 or jointly-managed devices, the system cancels the job during JES3 interpretation. If only one or neither DD statement requests a JES3 or jointly-managed device, the system performs device and space allocation processing for both DD statements; however, it directs all references to the first DD statement in the step

       

  • The ddname must begin in column 3.
  • The ddname is 1 through 8 alphanumeric or national ($, #, @) characters.
  • The first character must be alphabetic or national ($, #, @).
  • The ddname must be followed by at least one blank.

Omitting the ddname

Do not code a ddname in two cases:

  • The DD statement defines a data set that is concatenated to the data set of the preceding DD statement.
  • Note: Allocation processing does not fail an attempt to concatenate an HFS file to another HFS file, or an MVS data set, even though it is impossible to read from or write to concatenated HFS files. Do not request concatenation of HFS files.

  • The DD statement is the second or third consecutive DD statement for an indexed sequential data set.

Name Field when Overriding a Procedure DD Statement

Code the following in the name field of a DD statement that is to override a procedure DD statement:

  1. The name of the procedure step that contains the DD statement to be overridden
  2. Followed by a period
  3. Followed by the ddname of the procedure DD statement that is to be overridden.

Name Field when Adding a DD Statement to a Procedure

Code the following in the name field of a DD statement that is to be added to a procedure:

  1. The name of the procedure step to which the DD statement is to be added
  2. Followed by a period
  3. Followed by a ddname of your choosing.

For example:

//PROCSTP1.DDA DD parameters

Name Field when Adding a DD Statement to a Program

When you code a DD statement with a ddname of procstepname.ddname within a program step, the system:

  1. Checks the syntax of both the procstepname qualifier and the ddname qualifier
  2. Uses only the ddname qualifier as the statement ddname
  3. Adds the DD statement to the program step that contains the statement
  4. Issues an informational message because procstepname is coded outside of a procedure.

Special ddnames

Use the following special ddnames only when you want to use the facilities these names represent to the system.

JOBCAT       SYSCHK
JOBLIB       SYSCKEOV
STEPCAT      SYSIN
STEPLIB      SYSMDUMP
SYSABEND     SYSUDUMP

Do not use the following ddnames on a DD statement in a JES2 system. They have special meaning to JES2.

JESJCLIN     JESMSGLG 
JESJCL       JESYSMSG

The following ddnames have special meaning to JES3; do not use them on a DD statement in a JES3 system.

JCBIN        JS3CATLG
JCBLOCK      J3JBINFO
JCBTAB       J3SCINFO
JESJCLIN     J3STINFO
JESInnnn     STCINRDR

3.Operation Field
The operation field consists of the characters DD and must be preceded and followed by at least one blank. It can begin in any column.

4.Parameter Field
A DD statement has two kinds of parameters: positional and keyword. All parameters are optional.

Leave the parameter field blank only in the following case:

  • When SMS will provide the necessary DD description.

Positional Parameters
A DD statement can contain one positional parameter. If coded, this positional parameter must precede all keyword parameters.

Keyword Parameters
A DD statement can contain the following keyword parameters. You can code any of the keyword parameters in any order in the parameter field after a positional parameter, if coded. Do not use DD statement keywords as symbolic parameters in procedures to be started by a START command from the operator console.

5.Comments Field
The comments field follows the parameter field after at least one intervening blank. If you do not code any parameters on a DD statement, do not code any comments.

6.Location in the JCL
Most DD statements define data sets to be used in a job step, in a cataloged procedure step, or in an in-stream procedure step; these appear after the EXEC statement for the step. Some DD statements define data sets for the job, for example, the JOBLIB DD statement; these appear after the JOB statement and before the first EXEC statement.

When Overriding or Adding to Procedures

Place DD statements that override, nullify, or add parameters immediately following the EXEC statement that calls the procedure. Place overriding and nullifying DD statements first, followed by all added DD statements. Last in the calling step are any DD * or DD DATA statements with their in-stream data.

To override more than one DD statement in a procedure, place the overriding DD statements in the same order as the overridden DD statements in the procedure.

Concatenating Data Sets
You can logically connect or concatenate sequential or partitioned (PDSs or PDSEs) input data sets for the duration of a job step. Each of the concatenated data sets can reside on a different volume. Note that you cannot concatenate output data sets.

When data sets are concatenated, they are treated as having like attributes, and the system obtains these attributes, except for block size, from the first data set in the concatenation.

Coding a Concatenation
To concatenate data sets, omit the ddnames from all the DD statements except the first in the sequence. The data sets are processed in the same sequence as the DD statements defining them.

Devices for Concatenated Data Sets
Concatenated data sets can reside on different devices and different types of devices. (This may require internal DCB modifications.)

Block Sizes for Concatenated Data Sets
Concatenated data sets can have different block sizes. In a few cases, the data set with the largest block size must appear first in the concatenation. (Note that you can state a value equal to the largest block size for BLKSIZE on the first DD statement, regardless of what the actual block size of this data set is.) Certain data sets can be concatenated in any order of block size; these are:

  • Partitioned data sets (PDSs), and partitioned data sets extended (PDSEs) without member names coded on the DD statements.
  • Sequential data sets that are DASD-resident, tape-resident, or in-stream, and are accessed by QSAM and use system-created buffers.
  • Sequential data sets that are DASD-resident or in-stream, and are accessed by BSAM.

For these data sets, the BLKSIZE obtained is the largest in the concatenation. Note that this block size can cause invalid attribute combinations when combined with the attributes obtained from the first data set in the concatenation.

If you do not specify a block size, the system can, under certain conditions, determine an optimum block size.

Logical Record Lengths for Concatenated Data Sets
Concatenated data sets with format-V records can have different logical record lengths as long as the data set with the largest logical record length appears first in the concatenation. (Note that you can state a value equal to the largest logical record length for LRECL on the first DD statement, regardless of what the actual logical record length of this data set is.)

References to Concatenated Data Sets
If you make a backward reference to a concatenation (using *.), the system obtains information only from the first data set defined in the sequence of DD statements.

If you make a forward reference to a concatenation (using the DDNAME parameter), the forward reference resolves to the first data set in the concatenation.

If there are no DD statements between the forward reference and the concatenation, the rest of the data sets in the concatenation are appended to the first data set in the concatenation. The following example illustrates this.

//STEP1      EXEC    PGM=IEBGENER
//SYSPRINT   DD      SYSOUT=*
//SYSUT1     DD      DDNAME=INPUT
//INPUT      DD      DSN=TSTDATA1,DISP=SHR
//           DD      DSN=TSTDATA2,DISP=SHR
//SYSUT2     DD      SYSOUT=*
//SYSIN      DD      DUMMY

In this example, SYSUT1 will resolve to the first data set, TSTDATA1, defined by the DDNAME forward reference INPUT. TSTDATA2, the second data set in the DDNAME forward reference INPUT, will be appended to SYSUT1 as well. IEBGENER will recognize TSTDATA1 and TSTDATA2 as input.

If there are any DD statements between the forward reference and the concatenation, the rest of the data sets in the concatenation are appended to the last DD statement preceding the concatenation. For example:

//STEP1      EXEC    PGM=IEBGENER
//SYSUT1     DD      DDNAME=INPUT
//SYSPRINT   DD      SYSOUT=*
//SYSUT2     DD      SYSOUT=*
//INPUT      DD      DSN=TSTDATA1,DISP=SHR
//           DD      DSN=TSTDATA2,DISP=SHR
//SYSIN      DD      DUMMY

In the preceding example, SYSUT1 will resolve to the first data set, TSTDATA1, defined in the DDNAME forward reference INPUT. TSTDATA2 will be appended to SYSUT2, the last DD statement preceding the concatenation. In this example, IEBGENER will recognize only TSTDATA1 as input.

If a concatenated DD is added to a procedure, the remaining concatenated data sets will be concatenated to the last DD in the step named in an override or addition (or to the first step if no step was named in an override or addition). Note that this may result in these concatenated DDs being added to an unexpected DD. The following example illustrates this.

//TPROC     PROC
//S1        EXEC    PGM=IEFBR14
//DD1       DD      DDNAME=INPUT
//DD2       DD      DSN=MYDSN2,DISP=SHR
//DD3       DD      DSN=MYDSN3,DISP=SHR
//S2        EXEC    PGM=IEFBR14
//DDA       DD      DDNAME=INPUT
//DDB       DD      DSN=MINE2,DISP=SHR
//DDC       DD      DSN=MINE3,DISP=SHR
//          PEND
//STEP1     EXEC    TPROC
//INPUT     DD      DSN=MYDSN1,DISP=SHR
//          DD      DSN=MYDSN4,DISP=SHR
//S2.INPUT  DD      DSN=MINE1,DISP=SHR
//          DD      DSN=MINE4,DISP=SHR

In this example, the result of the DDNAME forward reference INPUT is:

  • In step S1, DD1 resolves to data set MYDSN1 and data set MYDSN4 is concatenated to data set MYDSN3.
  • In step S2, DDA resolves to data set MINE1 and data set MINE4 is concatenated to data set MINE3.

Do Not Concatenate Data Sets after a DUMMY Data Set
If you define a data set using the DUMMY parameter, do not concatenate other data sets after it. When the processing program asks to read a dummy data set, the system takes an end-of-data set exit immediately and ignores any data set that might be concatenated after the dummy.

Do Not Code Other Statements Between Concatenated DD Statements
Do not code other types of statements between two or more concatenated data definition (DD) statements. (Comments are the only exception; you can code them between DD statements.) For example, do not code a SET statement as follows:

//DD1     DD DSN=A
//        DD DSN=B
//        SET ...
//        * Wrong!!! SET statement not allowed (this comment IS allowed)
//        DD DSN=C

7.Examples of DD Statements and ddnames

Example 

//MYDS   DD  DSNAME=REPORT
//A      DD  DSNAME=FILE

Example 

//INPUT  DD  DSNAME=FGLIB,DISP=(OLD,PASS)
//       DD  DSNAME=GROUP2,DISP=SHR

In this example, because the ddname is missing from the second DD statement, the system concatenates the data sets defined in these statements.

Example 

//PAYROLL.DAY   DD   DSNAME=DESK,DISP=SHR

In this example, if procedure step PAYROLL contains a DD statement named DAY, this statement overrides parameters on DD statement DAY. If the step does not contain DD statement DAY, the system adds this statement to procedure step PAYROLL for the duration of the job step.

Example 

//STEPSIX.DD4   DD   DSNAME=TEXT,DISP=(NEW,PASS)
//              DD   DSNAME=ART,DISP=SHR

In this example, the second data set is concatenated to the first, and both are added to procedure step STEPSIX. The ddname is omitted from the second DD statement in order to concatenate data set ART to data set TEXT.

Because the system does not allow you to write to a concatenation of data, you need another data set with DISP=OLD in order to read from TEXT. Write to the new DD name before reading from DD4.

* Parameter

Parameter Type

Positional, optional

Purpose

Use the * (asterisk) parameter to begin an in-stream data set. The data records immediately follow the DD * statement; the records may be in any code such as EBCDIC. The data records end when one of the following is found:

/* in the input stream
// to indicate another JCL statement

The two-character delimiter specified by a DLM parameter on this DD statement The input stream runs out of card images.

Use a DATA parameter instead of the * parameter if any of the data records start with //.

Considerations for an APPC Scheduling Environment

The * parameter has no function in an APPC scheduling environment. If you code *, the system will check it for syntax and otherwise ignore it.

1.Syntax

//ddname DD *[,parameter]... [comments]

2.Defaults
When you do not code BLKSIZE and LRECL, JES uses installation defaults specified at initialization.

Note: If the input stream is from NJE (network job entry), JES uses the size specified at the sending node.

3.Relationship to Other Parameters
You may specify the following DD parameters with the DD * and DD DATA parameters. All other parameters are either ignored or result in a JCL error.

DCB=BLKSIZE   DSNAME
DCB=BUFNO     LIKE
DCB=LRECL     LRECL
DCB=DIAGNS    REFDD
DCB=MODE=C    VOLUME=SER
DLM           DSID

Restrictions When Coding LRECL

If you code LRECL with the * parameter, you cannot submit a data set to JES3 with a record length greater than 80 bytes.

You cannot use the TSO/E SUBMIT command to submit a data set to JES2 or JES3 with a record length greater than 80 bytes.

You can submit a data set to JES2 or JES3 with a record length greater than 80 bytes by submitting the following JCL:

//SUBMIT    JOB   ...
//S1        EXEC  PGM=IEBGENER
//SYSPRINT  DD    SYSOUT=*
//SYSIN     DD    DUMMY
//SYSUT2    DD    SYSOUT=(,INTRDR)
//SYSUT1    DD    DSN=IBMUSER.LONGDATA.JCL,DISP=SHR

In this example, IBMUSER.LONGDATA.JCL contains the data with a record length greater than 80 bytes.

In a JES3 system, the record length limit is the size of the installation-defined spool buffer, minus 44. (For example, if the buffer size is 4084, the record length limit is 4040.) JES3 fails any job that exceeds this limit.

If the records longer than 80 bytes include JCL to be transmitted to a remote system using JES3 // XMIT or //*ROUTE XEQ, or JES2 /*ROUTE XEQ or /*XMIT with JES3 in the network, the records are truncated to 80 bytes.

For JES3 SNA RJP Input

  • The only parameters you can specify for JES3 systems network architecture (SNA) remote job processing (RJP) input devices are BLKSIZE and LRECL.
  • Code DCB=LRECL=nnn, where nnn is 1 to 255 when SYSIN data records are greater than 80 bytes. (The default LRECL is 80 bytes.)

For 3540 Diskette Input/Output Units

VOLUME=SER, BUFNO, and DSID on a DD * statement are ignored except when they are detected by a diskette reader as a request for an associated data set. On a DD * or DD DATA statement processed by a diskette reader, you can specify DSID and VOLUME=SER parameters to indicate that a diskette data set is to be merged into the input stream following the DD statement.

4.Relationship to Other Control Statements
Do not refer to an earlier DD * statement in DCB, DSNAME, or VOLUME parameters on following DD statements.

5.Location in the JCL
A DD * statement begins an in-stream data set.

In-stream Data for Cataloged or In-stream Procedures

A cataloged or in-stream procedure cannot contain a DD * statement. When you call a procedure, you can add input stream data to a procedure step by placing in the calling step one or more DD * or DD DATA statements, each followed by data.

Multiple In-Stream Data Sets for a Step

You can code more than one DD * or DD DATA statement in a job step in order to include several distinct groups of data for the application program. Precede each group with a DD * or DD DATA statement and follow each group with a delimiter statement.

Omitted Data Delimiters

If you omit a DD statement before the input data, the system provides a DD * statement with the ddname of SYSIN. If you omit a delimiter statement after input data, the system ends the data when it reads a JCL statement or runs out of card images.

6.Unread Records
If the processing program does not read all the data in an in-stream data set, the system skips the remaining data without abnormally terminating the step.

7.Examples of the * Parameter
Example 

//INPUT1    DD   *
            . 
            .
            data
            .
//INPUT2    DD   *
            .
            .
            data
            .
/*

This example defines two groups of data in the input stream.

Example 

//INPUT3    DD   *,DSNAME=&&INP3
            .
            data 
            .
/*

This example defines an in-stream data set with INP3 as the last qualifier of the system-generated data set name. A name such as userid.jobname.jobid.Ddsnumber.INP3 is generated.

Example 

//STEP2         EXEC   PROC=FRESH
//SETUP.WORK    DD     UNIT=3400-6,LABEL=(,NSL)
//SETUP.INPUT1  DD     *
                .
                .
                data
                .
/*
//PRINT.FRM     DD     UNIT=180
//PRINT.INP     DD     *
                .
                .
                data
                .
/*

This example defines two groups of data in the input stream. The input data defined by DD statement SETUP.INPUT1 is to be used by the cataloged procedure step named SETUP. The input data defined by DD statement PRINT.INP is to be used by the cataloged procedure step named PRINT.

ACCODE parameter

Parameter Type

Keyword, optional

Purpose

Use the ACCODE parameter to specify or change an accessibility code for an ISO/ANSI/FIPS Version 3 or ISO/ANSI Version 4 tape output data set. An installation-written file-access exit routine verifies the code after the code is written to tape. If the code is authorized, the job step’s program can use the data set; if not, the system issues messages and may abnormally terminate the job step.

A data set protected by an accessibility code should reside only on a volume protected by RACF or a volume accessibility code. The volume should not contain any unprotected data sets.

Note: ACCODE is supported only for ISO/ANSI/FIPS Version 3 and ISO/ANSI Version 4 tape data sets. ACCODE is ignored for all label types except AL and AUL label tapes.

1.Syntax

ACCODE=access-code

2.Subparameter Definition

access-code
Specifies an accessibility code. The access code is 1 through 8 characters. In ISO/ANSI/FIPS Version 3 the first character must be an upper case letter from A through Z. In ISO/ANSI Version 4 the first character must be an upper case letter from A to Z, number from 0 to 9, or one of the special characters ! * ² % ’( ) + , - . / : ; < = > ? and _ .

Enclose the ACCODE in apostrophes if you specify special characters. For example, ACCODE=’AB/CD’. Specify two apostrophes if you include an apostrophe as a special character. For example, to specify DAY’SEND, use ACCODE=’DAY’’SEND’.

Note: ISO/ANSI/FIPS Version 3 and ISO/ANSI Version 4 use only the first character as the accessibility code; the installation can use the other seven characters. If the first character is other than those allowed, the installation does not give control to the file-access exit routine.

3.Defaults
If you do not specify an accessibility code on a DD statement that defines an ISO/ANSI/FIPS Version 3 or ISO/ANSI Version 4 tape data set, the system writes an ASCII blank character (X'20') in the tape label. A blank authorizes unlimited access to the tape’s data sets unless access is limited by RACF data set protection. If the installation does not supply a file-access exit routine, the system prevents access to any ISO/ANSI/FIPS Version 3 or ISO/ANSI Version 4 tape volume.

4.Overrides
If PASSWORD or NOPWREAD is coded on the DD statement LABEL parameter, password access overrides the ACCODE parameter.

5.Example of the ACCODE Parameter

//TAPE     DD    UNIT=2400,VOLUME=SER=T49850,DSNAME=TAPEDS,
//               LABEL=(,AL),ACCODE=Z

In this example, the DD statement ACCODE parameter specifies an accessibility code of Z for tape volume T49850. The volume has ISO/ANSI/FIPS Version 3 or ISO/ANSI Version 4 labels. The data set TAPEDS is first on the tape.

AMP Parameter

Parameter Type

Keyword, optional

Purpose
Use the AMP parameter to complete information in an access method control block (ACB) for a VSAM data set. The ACB is a control block for entry-sequenced, key-sequenced, and relative record data sets.

AMP is supported only for VSAM data sets.

Note: With SMS, you can create new VSAM data sets with JCL DD statements.

1.Syntax

AMP=(subparameter)
AMP=(’subparameter[,subparameter]...’)
AMP=’subparameter[,subparameter]...’

The subparameters are:

     AMORG
     BUFND=number
     BUFNI=number
     BUFSP=number
     CROPS= [NCK]
            [NRC]
            [NRE]
            [RCK]
     FRLOG= {NONE}
            {REDO}
     OPTCD= {I }
            {L }
            {IL}
     RECFM= [F ]
            [FB]
            [V ]
            [VB]
     STRNO=number
     SYNAD=module
     TRACE=(subparameter[,subparameter]...)
     ACCBIAS=[USER ]
             [SYSTEM]
             [DO ]
             [DW ]
             [SO ]
             [SW ]
     SMBDFR= {Y | N}
     SMBHWT= nn
     SMBVSP= {nnK | nnM}
     RMODE31=[ALL ]
             [BUFF]
             [CB ]
             [None]
     DD: AMP

Parentheses: Parentheses are required only when you are continuing the statement.

Multiple Subparameters:When a parameter contains more than one sub parameter, separate the sub parameters by commas and enclose the sub parameter list in apostrophes inside the parentheses. For example, AMP= ('AMORG,STRNO=4').

Null Positional Subparameters: Null positions in the AMP parameter are invalid. Special Characters: When a parameter contains only one subparameter and that subparameter contains special characters, enclose the subparameter in apostrophes inside the parentheses. For example, AMP=('STRNO=4').

Note: Do not enclose a subparameter in a subparameter list in apostrophes.

If you code a symbolic parameter on the AMP parameter, you can code the symbolic parameter in apostrophes.

Continuation onto Another Statement: Enclose the subparameter list in only one set of parentheses. Enclose all the subparameters on each statement in apostrophes. End each statement with a comma after a complete subparameter.For example:

//DS1   DD      DSNAME=VSAMDATA,AMP=(’BUFSP=200,OPTCD=IL,RECFM=FB’,
//              ’STRNO=6’)

2.Subparameter Definition

AMORG
Indicates that the DD statement describes a VSAM data set. Code AMORG when data set access is through an ISAM interface program and the DD statement contains VOLUME and UNIT parameters.

It is unnecessary to code AMP=AMORG for a data set that is SMS-managed. An SMS data set is cataloged at allocation; all information pertaining to the data set creation (such as RECORG) must be fully defined at allocation to ensure the success of the job.

BUFND=number
Specifies the number of I/O buffers that VSAM is to use for data records. The minimum is 1 plus the STRNO subparameter number. This value overrides the BUFND value specified in the ACB or GENCB macro, or provides a value if one is not specified. If you omit STRNO, BUFND must be at least 2. If you omit BUFND from AMP and from the ACB macro instruction, the system uses the STRNO number plus 1.

BUFNI=number
Specifies the number of I/O buffers that VSAM is to use for index records. This value overrides the BUFNI value specified in the ACB or GENCB macro, or provides a value if one is not specified. If you omit BUFNI from AMP and from the ACB macro instruction, VSAM uses as many index buffers as the STRNO subparameter number; if you omit both BUFNI and STRNO, VSAM uses 1 index buffer.

If data access is through the ISAM interface program, specify for the BUFNI number 1 more than the STRNO number, or specify 2 if you omit STRNO, to simulate having the highest level of an ISAM index resident. Specify a BUFNI number 2 or more greater than the STRNO number to simulate having intermediate levels of the index resident.

BUFSP=number
Specifies the maximum number of bytes for the data and index buffers in the user area. This value verrides the BUFSP value specified in the ACB or GENCB macro, or provides a value if one is not specified. If BUFSP specifies fewer bytes than the BUFFERSPACE parameter of the access method services DEFINE command, the BUFFERSPACE number overrides the BUFSP number.

CROPS=NCK
CROPS=NRC
CROPS=NRE
CROPS=RCK

Requests a checkpoint/restart option.

NCK
Requests no data set post-checkpoint modification tests.

NRC
Requests neither a data-erase test nor data set post-checkpoint modification tests.

NRE
Requests no data-erase test.

RCK
Requests a data-erase test and data set post-checkpoint modification tests. If the CROPS subparameter is omitted, RCK is the default.

If you request an inappropriate option, such as the data-erase test for an input data set, the system ignores the option.

FRLOG=NONE
FRLOG=REDO

Specifies if VSAM batch logging will be performed for your VSAM data set.

NONE
Disables the VSAM batch logging function for your VSAM data set. Changes made by applications will not be written to the MVS log stream indicated on the LOGSTREAMID parameter.

REDO
Enables the VSAM batch logging function for you VSAM data set. Changes made by applications will be written to the MVS log stream indicated on the LOGSTREAMID parameter.

Notes:

  1. If FRLOG=REDO is specified, the LOGSTREAMID parameter must be specified for the VSAM data set(s). If LOGSTREAMID is not specified, IEC161I is issued.
  2. There is no default JCL value for FRLOG. If FRLOG is omitted, the catalog value will be used.

OPTCD=I
OPTCD=L
OPTCD=IL

Indicates how the ISAM interface program is to process records that the step’s processing program flags for deletion.

I Requests, when the data control block (DCB) contains OPTCD=L, that the ISAM interface program is not to write into the data set records marked for deletion by the processing program. If AMP=('OPTCD=I') is specified without OPTCD=L in the DCB, the system ignores deletion flags on records.

L Requests that the ISAM interface program is to keep in the data set records marked for deletion by the processing program. If records marked for deletion are to be kept but OPTCD=L is not in the DCB, AMP=('OPTCD=L') is required.

Note: This parameter has the same meaning and restrictions for the ISAM interface as it has for ISAM. While it was not required in the ISAM job control language, you should code it in the AMP parameter.

IL Requests that the ISAM interface program is not to write into the data set records marked for deletion by the processing program. If the processing program had read the record for update, the ISAM interface program deletes the record from the data set.

AMP=('OPTCD=IL') has the same effect as AMP=('OPTCD=I') coded with OPTCD=L in the DCB.

RECFM=F
RECFM=FB
RECFM=V
RECFM=VB

Identifies the ISAM record format used by the processing program. You must code this RECFM subparameter when the record format is not specified in the DCB.

Note: This parameter has the same meaning and restrictions for the ISAM interface as it has for ISAM. While it was not required in the ISAM job control language, you should code it in the AMP parameter.

All VSAM requests are for unblocked records. If the processing program requests blocked records, the ISAM interface program sets the overflow-record indicator for each record to indicate that each is being passed to the program unblocked.

F Indicates fixed-length records.
FB Indicates blocked fixed-length records.
V Indicates variable-length records. If no RECFM is specified in the AMP parameter or in the DCB, V is the default.
VB Indicates blocked variable-length records.

STRNO=number
Indicates the number of request parameter lists the processing program uses concurrently. The number must at least equal the number of BISAM and QISAM requests that the program can issue concurrently. If the program creates subtasks, add together the number of requests for each subtask plus 1 for each subtask that sequentially processes the data set. This value overrides the STRNO value specified in the ACB or GENCB macro, or provides a value if one is not specified

SYNAD=module
Names a SYNAD exit routine. The ISAM interface program is to load and exit to this routine if a physical or logical error occurs when the processing program is gaining access to the data set.

The SYNAD parameter overrides a SYNAD exit routine specified in the EXLST or GENCB macro instruction that generates the exit list. The address of the intended exit list is specified in the access method control block that links this DD statement to the processing program. If no SYNAD exit is specified, the system ignores the AMP SYNAD parameter.

TRACE=(subparameter[,subparameter]...)
Indicates that the generalized trace facility (GTF) executes with your job to gather information about the opening, closing, and end-of-volume processing for the data set defined on this DD statement. You can use the interactive problem control system to print the trace output.

The TRACE subparameters are: HOOK, ECODE, KEY, PARM1, and PARM2. which you use to obtain diagnostic information during VSAM processing.

ACCBIAS=USER
ACCBIAS=SYSTEM
ACCBIAS=DO
ACCBIAS=DW
ACCBIAS=SO
ACCBIAS=SW

Specify one of these six values to override record access bias in the data class in order to use System-Managed Buffering (SMB) without changing the data class. See OFSMS/MVS Using Data Sets for details on System-Managed Buffering.

USER
Obtain buffers the same way the system would without SMB. This is the default if you code no specification for the ACCBIAS subparameter.

SYSTEM
Force SMB and let the system determine the buffering technique based on the ACB MACRF and storage class specification.

Note: USER and SYSTEM are the only values you may use to specify record access bias in the data class.

DO
SMB with direct optimization.

DW
SMB weighted for direct processing. This option provides the capability to use hiperspace.

SO
SMB with sequential optimization.

SW
SMB weighted for sequential processing.

SMBDFR=Y or SMBDFR=N
With direct optimization, use this subparameter to instruct VSAM whether to defer writing of changed buffers to the medium until either the data set is closed or the buffers are required for some other request. See OFSMS/MVS Using Data Sets for further details on using SMBDFR.

SMBHWT=nn
Specify a requirement for hiperspace where nn is an integer from 0 to 99. Use this parameter with direct optimization. The default value is 0, which means that the system does not obtain any hiperspace.

SMBVSP=nnK or SMBVSP=nnM
Specify the amount of virtual buffer space to acquire for direct optimized processing when opening the data set, where nn is 1 to 2048000 kilobytes or 1 to 2048 megabytes.

RMODE31=ALL
RMODE31=BUFF
RMODE31=CB
RMODE31=NONE

Designate the residency for buffers and control blocks. This subparameter allows you to specify whether or not to allocate the buffers and control blocks in 31-bit addressable storage. You can use this field independently of SMB. With SMB the default location is in 31-bit addressable storage (²above the 16-megabyte line²). Without SMB, the default is in 24-bit addressable storage (²below the line²).

The values you may specify for RMODE31 are:
ALL —Control blocks and buffers above the line.
BUFF —Buffers (only) above the line.
CB —Control blocks (only) above the line.
NONE —Control blocks and buffers below the line.

When you do not specify ACCBIAS, or when you specify ACCBIAS=USER, if you specify nothing for RMODE31 in either the JCL or the ACB, the system obtains the buffers and control blocks in virtual storage with a 24-bit address.

When ACCBIAS=SYSTEM, if you specify nothing for RMODE31 in either the JCL or the ACB, the system obtains the buffers in storage with an address greater than 16 million bytes.

When you specify CB or NONE for RMODE31, the system obtains the buffers in 24-bit addressable storage.

When you specify BUFF or NONE for RMODE31, the system obtains the control blocks in 24-bit addressable storage.

If your program runs in 24-bit mode and you use locate mode processing for the VSAM data set, you must obtain the buffers in 24-bit addressable storage.

Note: If your program runs with local or global shared resources (LSR/GSR) and uses journaling (JRNAD) or user processing (UPAD) exit routines, the exits must run in 31-bit mode if you obtained the control blocks above the line.

This capability to allocate above the line is necessary when either or both of the following conditions exists:

  • The number of data sets open to a job is quite large.
  • The number of buffers is such as to cause a storage shortage if kept in 24-bit addressable storage.

You may specify RMODE31 only with the JCL DD AMP parameter or in the ACB. The RMODE31 subparameter of AMP overrides any RMODE31 values specified in the ACB. The RMODE31 subparameter is available for all data set types.

3.Relationship to Other Parameters
Do not code the following parameters with the AMP parameter.

*          DDNAME     QNAME
BURST      DYNAM      RECFM
CHARS      FCB        SUBSYS
COPIES     FLASH      SYSOUT
DATA       FREE       TERM
DCB        MODIFY     UCS

Invalid ddnames
The following ddnames are invalid for VSAM data sets:

JOBLIB
STEPLIB
SYSABEND
SYSCHK
SYSCKEOV
SYSMDUMP
SYSUDUMP

Invalid DSNAMEs
When you code the AMP parameter, the DSNAME must not contain parentheses, a minus (hyphen), or a plus (+) sign. The forms of DSNAME valid for ISAM, partitioned access method (PAM), and generation data groups (GDG) are invalid with VSAM data sets.

4.Buffer Requirements
For a key-sequenced data set, the total minimum buffer requirement is three: two data buffers and one index buffer. For an entry-sequenced data set, two data buffers are required.

If the number of buffers specified in the BUFND and BU FNI subparameters causes the virtual storage requirements to exceed the BUFSP space, the number of buffers is reduced to fit in the BUFSP space. If BUFSP specifies more space than required by BUFND and BUFNI, the number of buffers is increased to fill the BUFSP space.

5.Examples of the AMP Parameter
Example 

//VSAMDS1    DD   DSNAME=DSM.CLASS,DISP=SHR,AMP=(’BUFSP=200,BUFND=2’,
//                ’BUFNI=3,STRNO=4,SYNAD=ERROR’)

In this example, the DD statement defines the size of the user area for data and index buffers, specifies the number of data and index buffers, specifies the number of requests that require concurrent data set positioning, and specifies an error exit routine named ERROR.

Example 

//VSAMDS2    DD   DSNAME=DSM.CLASS,DISP=SHR,AMP=(’BUFSP=23456,BUFND=5’,
//                ’BUFNI=10,STRNO=6,SYNAD=ERROR2,CROPS=NCK’,
//                ’TRACE=(PARM1=F00203000010,KEY=ABCDEF)’)

In this example, the DD statement defines the values for BUFSP, BUFNI, STRNO, and SYNAD, as in the previous example. It also specifies that a data set post-checkpoint modification test is not to be performed when restarting at a checkpoint and that GTF is to provide a trace of specified data areas.

AVGREC Parameter

Parameter Type

Keyword, optional — use this parameter only with SMS

Purpose
Use the AVGREC parameter when you define a new data set to specify that:

  • The units of allocation requested for storage space are records.
  • The primary and secondary space quantity specified on the SPACE parameter represents units, thousands, or millions of records.

When you use AVGREC with the SPACE parameter, the first subparameter (reclgth) on the SPACE parameter must specify the average record length of the records.

Code the AVGREC parameter when you want to (1) specify records as the units of allocation or (2) override the space allocation defined in the data class for the data set.

If SMS is not installed or is not active, the system checks the syntax and then otherwise ignores the AVGREC parameter.

1.Syntax

AVGREC= {U}
        {K}
        {M}

2.Subparameter Definition
U Specifies a record request and that the primary and secondary space quantity specified on the SPACE parameter represents the number of records in units (multiplier of 1).

K Specifies a record request and that the primary and secondary space quantity specified on the SPACE parameter represents the number of records in thousands (multiplier of 1024).

M Specifies a record request and that the primary and secondary space quantity specified on the SPACE parameter represents the number of records in millions (multiplier of 1048576).

3.Overrides
AVGREC overrides the space allocation defined in the DATACLAS parameter for the data set.

4.Relationship to Other Parameters
Do not code AVGREC with the TRK, CYL, or ABSTR subparameters of the SPACE parameter.Do not code the following DD parameters with the AVGREC parameter.

*        DYNAM
DATA     QNAME
DDNAME

5.Examples of the AVGREC Parameter
Example 

//SMSDS3   DD    DSNAME=MYDS3.PGM,DATACLAS=DCLAS03,DISP=(NEW,KEEP),
//               SPACE=(128,(5,2)),AVGREC=K

In the example, the space allocation defined in the DCLAS03 data class is overridden by the SPACE and AVGREC parameters, which indicate an average record length of 128 bytes, a primary quantity of 5K (5,120) records, and a secondary quantity of 2K (2,048) records.

Example 

//SMSDS3A  DD    DSNAME=MYDS3.PGM,DATACLAS=DCLAS03A,DISP=(NEW,KEEP),
//               AVGREC=K

In the example, the space allocation defined in the DCLAS03A data class is overridden by the AVGREC parameter, which indicates that the primary and secondary quantity represents thousands of records.

BLKSIZE parameter

Parameter Type

Keyword, optional

Purpose

Code the BLKSIZE parameter to specify the maximum length of a block. BLKSIZE= {value}

1.Syntax

BLKSIZE= {value}
         {valueK}
         {valueM}
         {valueG}

2.Subparameter Definition

value
Specifies the maximum length, in bytes, of a block.

The number of bytes that you specify for BLKSIZE depends on the device type and the record format for the data set. The maximum is 32,760 for DASD data sets and 2,147,483,648 for tape, except for data sets on magnetic tape with ISO/ANSI Version 3 labels, where the minimum value for BLKSIZE is 18 bytes and the maximum is 2048 bytes. To allow a block size greater than 2048, use installation exit routine IFG0193G.

valueK
Specifies the maximum length, in kilobytes, of a block. (1 kilobyte = 1024 bytes.) The maximum is 2097152. If you code 2097152K, the block size is the maximum: 2,147,483,648 bytes.

valueM
Specifies the maximum length, in megabytes, of a block. (1 megabyte = 1024 kilobytes.) The maximum is 2048. If you code 2048M, the block size is the maximum: 2,147,483,648 bytes.

valueG
Specifies the maximum length, in gigabytes, of a block. (1 gigabyte = 1024 megabytes.) The maximum is 2G. If you code 2G, the block size assigned is the maximum: 2,147,483,648 bytes.

3.Defaults
If you do not code BLKSIZE, the system can, under certain conditions, determine an optimum block size. For detailed information about system-determined block size.

4.Overrides
If you code a non-zero value for the BLKSIZE subparameter on a DCB or DCBE macro instruction or on a DD statement that defines an existing data set with standard labels, the DCB or DCBE BLKSIZE overrides the block size specified in the label.

5.Relationship to Other Control Statements
Do not code the BLKSIZE parameter with the DCB subparameter BUFSIZE. If you code BLKSIZE it will have no effect on EXCP processing unless the application takes special steps to use it.

6.Coexistence Considerations
Not all programs and operating systems prior to z/OS can read blocks longer than 32,760 bytes. For example, Version 2 Release 10 is the first release of OS/390 that can read such long blocks using standard access methods.

7.Examples of the BLKSIZE Parameter

//DD1B     DD     DSNAME=EVER,DISP=(NEW,KEEP),UNIT=3380,
//                RECFM=FB,LRECL=326,BLKSIZE=23472,
//                SPACE=(23472,(200,40))

DD statement DD1B defines a new data set named EVER on a 3380. The DD keywords RECFM, LRECL, and BLKSIZE contain the information necessary to complete the data control block.

//DD2B     DD    DSNAME=NEVER,DISP=(NEW,KEEP),UNIT=3590,
//               RECFM=FB,LRECL=256,BLKSIZE=204K

DD statement DD2B defines a new data set named NEVER on a 3590. The DD keywords RECFM, LRECL, and BLKSIZE contain the information necessary to complete the data control block. The block size, which in this example is 204 x 1024 = 208,896 bytes, must be divisible by the logical record length, and each program that reads or writes this data set must be capable of handling block sizes this large.

BLKSZLIM parameter

Parameter Type

Keyword, optional

Purpose

Use the BLKSZLIM parameter to specify an upper limit on a data set’s block size if BLKSIZE is omitted from all sources and the system determines the block size for the data set. If a BLKSIZE value is available from any source (such as the DD statement, data set label, or the program), then the block size limit has no effect. The BLKSZLIM parameter is useful mainly when writing new magnetic tape data sets with programs that can handle blocks longer than 32,760 bytes. Currently the maximum block size supported on any tape is 256 KB. You can safely code a larger value for BLKSZLIM. The BLKSZLIM value does not have to be a multiple of the LRECL value.

1.Syntax

BLKSZLIM= {value}
          {valueK}
          {valueM}
          {valueG}

2.Subparameter Definition

value
Specifies in bytes an upper limit on a data sets’s block size if BLKSIZE is omitted from all sources and the system determines the block size for the data set. The maximum value is 2,147,483,648 bytes (two gigabytes). The minimum value is 32K (32,768 bytes).

valueK
Specifies the block size limit in kilobytes (units of 1024). The maximum value is 2,097,152K (two gigabytes). The minimum value is 32K.

valueM
Specifies the block size limit in megabytes (units of 1024K). The maximum value is 2048M (two gigabytes). The minimum value is 1M.

valueG
Specifies the block size limit in gigabytes (units of 1024M). The maximum allowable value is 2G (two gigabytes). The minimum value is 1G.

3.Defaults
If you omit BLKSZLIM, the system determines the block size from one of the following sources, starting with the first:

  1. Data class
  2. DEVSUPxx value
  3. 32,768

4.Relationship to Other Parameters
The system ignores BLKSZLIM when you specify BLKSIZE.

5.Example of the BLKSZLIM Parameter

//DD1BB  DD  DSNAME=EVER,DISP=(NEW,KEEP),UNIT=3390,
//           RECFM=FB,LRECL=326,BLKSZLIM=32760,
//           SPACE=(23472,(200,40))

DD statement DD1B defines a new data set named EVER on a 3390 DASD. The DD keywords RECFM and LRECL contain the information necessary to complete the data control block. BLKSZLIM places an upper limit on the block size to be determined by the system.

//DD2B   DD  DSNAME=NEVER,DISP=(NEW,KEEP),UNIT=3590,
//           RECFM=FB,LRECL=80,BLKSZLIM=40K

DD statement DD2B defines a new data set named NEVER on a 3590 TAPE device. The DD keywords RECFM and LRECL contain the information necessary to complete the data control block. BLKSZLIM places an upper limit on the block size to be determined by the system.

BURST parameter

Parameter Type

Keyword, optional

Purpose

Use the BURST parameter to specify that the output for this sysout data set printed on a continuous-forms AFP printer is to go to:

  • The burster-trimmer-stacker, to be burst into separate sheets.
  • The continuous forms stacker, to be left in continuous fanfold.

If the specified stacker is different from the last stacker used, or if a stacker was not previously requested, JES issues a message to the operator to thread the paper into the required stacker.

Note: BURST applies only for an output data set printed on an AFP printer equipped with a burster-trimmer-stacker.

1.Syntax

BURST= {YES}
       {Y }
       {NO }
       {N }

2.Subparameter Definition

YES
Requests that the printed output is to be burst into separate sheets. This subparameter can also be coded as Y.

NO
Requests that the printed output is to be in a continuous fanfold. This subparameter can also be coded as N.

3.Defaults
If you do not code a BURST parameter, but you code a DD SYSOUT parameter and the sysout data set is printed on an AFP printer that has a burster-trimmer-stacker, JES uses an installation default specified at initialization. If you do not code a BURST parameter or a DD SYSOUT parameter, the default is NO.

4.Overrides
A BURST parameter on a sysout DD statement overrides an OUTPUT JCL BURST parameter.

5.Relationship to Other Parameters
Do not code the following parameters with the BURST parameter.

*        DISP       PROTECT
AMP      DSID       QNAME
DATA     DYNAM      VOLUME
DDNAME   LABEL

6.Relationship to Other Control Statements
The burster-trimmer-stacker can also be requested using the following:

  • The BURST parameter on the OUTPUT JCL statement.
  • The STACKER parameter on the JES3 //*FORMAT PR statement.
  • The BURST parameter on the JES2 /*OUTPUT statement.

7.Example of the BURST Parameter

//RECORD DD SYSOUT=A,BURST=Y

In this example, the DD statement requests that JES send the output to the burster-trimmer-stacker of the AFP printer. The stacker separates the printed output into separate sheets instead of stacking it in a continuous fanfold.

CCSID parameter

Parameter Type

Keyword, optional

Purpose

On systems with DFSMS/MVS Version 1 Release 5 or higher, and OS/390 Version 2 Release 5 or higher, you can request DFSMSdfp to convert data from/to the coded character set identifier (CCSID) specified on the JOB or EXEC statement to/from the CCSID specified on the DD statement. Data conversion is supported on access to ISO/ANSI Version 4 tapes using access methods BSAM or QSAM, but not using EXCP.

ISO/ANSI Version 4 tapes are identified by the LABEL=(,AL) or LABEL=(,AUL) keyword. The CCSID parameter does not apply to ISO/ANSI Version 1 or ISO/ANSI/FIPS Version 3 tapes or to tapes with labels other than AL or AUL.Using Data Sets for selecting ISO/ANSI Version 4 tapes. See the latter manual for list of supported CCSIDs.

The CCSID value of 65535 has a special meaning: it suppresses conversion.

When CCSID is not specified at the JOB, EXEC, or DD levels, data passed to BSAM and QSAM is converted to 7-bit ASCII when writing to ISO/ANSI Version 4 tapes. This may result in data loss on conversion. On READ operations the CCSID (if recorded) on the tape header label is used for conversion.

The CCSID is recorded in the tape header label if conversion is not defaulted.

1.Syntax

CCSID= nnnnn

2.Subparameter Definition

nnnnn
The CCSID as a decimal number from 1 through 65535.

3.Default
367.

4.Relationship to Other Parameters
Do not code the following parameters with the CCSID parameter:

*        DDNAME    QNAME
BURST DYNAM SYSOUT
CHARS FCB TERM
COPIES FLASH UCS
DATA MODIFY

5.Examples of the CCSID Parameter

Example 

//JOB1   JOB   (123456)
//S1     EXEC  PGM=MYPGM
//DD1    DD    DSN=A,DISP=NEW,UNIT=3590,
//             VOL=SER=T00001,LABEL=AL

In this example, the data on the new ISO/ANSI tape is converted from EBCDIC to 7-bit ASCII because CCSID was not specified at the JOB, EXEC, or DD levels. If the data passed to the access methods contain graphic or special characters there could be data loss on conversion to 7-bit ASCII. This is the default operation for ISO/ANSI/FIPS Version 3 and ISO/ANSI Version 4 tapes.

Example 

//JOB2   JOB   (123456)
//S1     EXEC  PGM=MYPGM
//DD1    DD    DSN=A,DISP=OLD,UNIT=3590,
//             VOL=SER=T00001,LABEL=AL

In this example the data on the ISO/ANSI tape is converted from 7-bit ASCII (default) to EBCDIC. This is the default operation for ISO/ANSI/FIPS Version 3 and ISO/ANSI Version 4 tapes.

Example 

//JOB3   JOB   (123456)
//S1     EXEC  PGM=MYPGM
//DD1    DD    DSN=A,DISP=NEW,UNIT=3590,
//             CCSID=65535,VOL=SER=T00003,LABEL=AL

In this example the data written to the ISO/ANSI Version 4 tape is not converted (CCSID=65535).

Example 

//JOB4   JOB   (123456)
//S1     EXEC  PGM=MYPGM
//DD1    DD    DSN=A,DISP=OLD,UNIT=3590,
//             CCSID=65535,VOL=SER=T00004,LABEL=AL

In this example the user did not want any conversion (CCSID=65535) on data read by the access methods.

Example 

//JOB5   JOB   (123456),CCSID=37
//S1     EXEC  PGM=MYPGM1
//DD1    DD    DSN=A,DISP=NEW,LABEL=(,AL),
//             VOL=SER=T00005,UNIT=3590,CCSID=437

In this example the user wants conversion from a CCSID of 37 (CECP: USA, Canada, Netherlands, Portugal, Brazil, Australia, New Zealand) to 437 (Base PC-data) for data written using BSAM or QSAM for ISO/ANSI Version 4 tape. The CCSID of 437 is recorded on the tape header label.

Example 

//JOB6   JOB   (123456),CCSID=37
//S1     EXEC   PGM=MYPGM2
//DD1    DD     DSN=A,DISP=OLD,UNIT=3590,
//              VOL=SER=T00006,CCSID=437

In this example the user wants data conversion from a CCSID of 437 to a CCSID of 37 for data read by the access method. Note that the CCSID does not have to be specified if it is recorded in the label.

Example 

//JOB7   JOB   (123456),CCSID=37
//S1     EXEC  PGM=MYPGM
//DD1    DD    DSN=A,DISP=OLD,UNIT=3590,
//             VOL=SER=T00007

In this example the ISO/ANSI labeled tape had a recorded CCSID of 437 and a CCSID was not specified on the DD statement. Data read from this tape by the access method is converted from a CCSID of 437 to a CCSID of 37.

Example 

//JOB8   JOB   (123456),CCSID=37
//S1     EXEC  PGM=MYPGM1
//DD1    DD    DSN=A,DISP=NEW,LABEL=(,AL),UNIT=3590,
//             VOL=SER=T00008,CCSID=437
//S2     EXEC  PGM=MYPGM2,CCSID=65535
//DD1    DD    DSN=B,DISP=NEW,LABEL=(,AL),UNIT=3590,
//             VOL=SER=T00009

This example illustrates overriding the CCSID specified on the JOB statement by the specification on the EXEC statement.

In this example, in step S1 the user wants conversion from a CCSID of 37 to 437 for data written using BSAM or QSAM for the ISO/ANSI Version 4 tape.

In step S2 the JOB level CCSID of 37 is overridden by the EXEC level CCSID of 65535. Since a CCSID of 65535 prevents conversion, the data written to tape is not converted. A CCSID of 65535 is recorded in the tape header label because no CCSID was specified on the DD statement.

CHARS parameter

Parameter Type

Keyword, optional

Purpose

Use the CHARS parameter to specify the name of one or more coded fonts for printing this sysout data set on an AFP printer.

Note: CHARS applies only for an output data set that is either printed on an AFP printer or processed by Infoprint Server.

1.Syntax

CHARS= {font-name }
{(font-name[,font-name]...)}
{DUMP }
{(DUMP[,font-name]...) }
  • You can omit the parentheses if you code only one font-name or only DUMP.
  • Null positions in the CHARS parameter are invalid. For example, you cannot code CHARS=(,font-name) or CHARS=(font-name,,font-name).

2.Subparameter Definition

font-name
Names a coded font or character-arrangement table. Each font-name is 1 through 4 alphanumeric or national ($, #, @) characters. Code from one to four names.

DUMP
Requests a high-density dump of 204-character print lines from a 3800. If more than one font-name is coded, DUMP must be first.

Note: Use DUMP on a SYSABEND or SYSUDUMP DD statement.

3.Defaults
If you do not code the DD CHARS parameter, JES uses the following, in order:

  1. The CHARS parameter on an OUTPUT JCL statement, if referenced by the DD statement.
  2. The DD UCS parameter value, if coded.
  3. The UCS parameter on an OUTPUT JCL statement, if referenced.
  4. If no character-arrangement table is specified on the DD or OUTPUT JCL statements, JES uses an installation default specified at initialization.

4.Overrides
A CHARS parameters on a sysout DD statement overrides the OUTPUT JCL CHARS parameter. For a data set scheduled to the Print Services Facility (PSF), PSF uses the following parameters, in override order, to select the font list:

  1. Font list in the library member specified by an OUTPUT JCL PAGEDEF parameter.
  2. DD CHARS parameter.
  3. OUTPUT JCL CHARS parameter.
  4. DD UCS parameter.
  5. OUTPUT JCL UCS parameter.
  6. JES installation default for the device.
  7. Font list on the PAGEDEF parameter in the PSF-cataloged procedure.

5.Relationship to Other Parameters
Do not code the following parameters with the CHARS parameter.

*         DISP     PROTECT
AMP       DSID     QNAME
DATA      DYNAM    VOLUME
DDNAME    LABEL

6.Relationship to Other Control Statements
CHARS can also be coded on the following:

  • The OUTPUT JCL statement.
  • The JES3 //*FORMAT PR statement.
  • The JES2 /*OUTPUT statement.

7.Requesting a High-Density Dump
You can request a high-density dump on the 3800 through two parameters on the DD statement for the dump data set or on an OUTPUT JCL statement referenced by the dump DD statement:

  • FCB=STD3. This parameter produces dump output at 8 lines per inch.
  • CHARS=DUMP. This parameter produces 204-character print lines.

You can code one or both of these parameters. You can place both on the same statement or one on each statement.

Examples of the CHARS Parameter

Example 

//DD1 DD SYSOUT=A,CHARS=(GT10,GB12)

In this example, the CHARS parameter specifies two fonts to be used when printing the data set: GT10 and GB12.

Example 

//SYSABEND DD UNIT=3800,CHARS=DUMP,FCB=STD3

The CHARS parameter on this SYSABEND DD statement specifies a high-density dump with 204 characters per line. The FCB parameter requests the dump output at 8 lines per inch.

Note: This example pertains only to 3800 printers.

CHKPT parameter

Parameter Type

Keyword, optional

Purpose

Use the CHKPT parameter to request that a checkpoint be written when each end-of-volume is reached on the multivolume data set defined by this DD statement. Checkpoints are written for all volumes except the last. Checkpoints can be requested for input or output data sets.

Note: CHKPT is supported only for multivolume QSAM or BSAM data sets. CHKPT is ignored for single-volume QSAM or BSAM data sets or for ISAM, BDAM, BPAM, or VSAM data sets. CHKPT is not supported for partitioned data sets extended (PDSEs).

1.Syntax

CHKPT=EOV

2.Subparameter Definition

EOV
Requests a checkpoint at each end-of-volume.

3.Overrides

  • The RD parameter values of NC and RNC on the JOB or EXEC statements override the CHKPT parameter.
  • The CHKPT parameter overrides cataloged procedure values or START command values for checkpoints at end-of-volume.

4.Relationship to Other Parameters
Do not code the following parameters with the CHKPT parameter.

*          DYNAM
DATA       QNAME
DDNAME     SYSOUT

5.Relationship to the SYSCKEOV DD Statement
If you specify CHKPT, you must also provide a SYSCKEOV DD statement in the job or step.

6.Checkpointing Concatenated Data Sets
For concatenated BSAM or QSAM data sets, CHKPT must be coded on each DD statement in the concatenation, if checkpointing is desired for each data set in the concatenation.

7.Examples of the CHKPT Parameter

Example 

//DS1   DD   DSNAME=INDS,DISP=OLD,CHKPT=EOV,
//           UNIT=SYSSQ,VOLUME=SER=(TAPE01,TAPE02,TAPE03)

In this example, the DD statement defines data set INDS, a multivolume QSAM or BSAM data set for which a checkpoint is to be written twice: once when end-of-volume is reached on TAPE01 and once when end-of-volume is reached on TAPE02

Example 

//DS2    DD   DSNAME=OUTDS,DISP=(NEW,KEEP),
//            CHKPT=EOV,UNIT=SYSDA,VOLUME=(,,,8)

In this example, OUTDS is a multivolume data set that is being created. The data set requires eight volumes. Seven checkpoints will be written: when the end-of-volume is reached on volumes one through seven.

CNTL parameter

Parameter Type

Keyword, optional

Purpose

Use the CNTL parameter to reference a CNTL statement that appears earlier in the job. The reference causes the subsystem to execute the program control statements within the referenced CNTL/ENDCNTL group.

The system searches for an earlier CNTL statement with a label that matches the label in the CNTL parameter. If the system finds no match, the system issues an error message.

1.Syntax

CNTL= {*.label }
      {*.stepname.label }
      {*.stepname.procstepname.label}

2.Subparameter Definition

*.label
Identifies an earlier CNTL statement, named label. The system searches for the CNTL statement first earlier in this step, then before the first EXEC statement of the job.

*.stepname.label
Identifies an earlier CNTL statement, named label, that appears in an earlier step, stepname, in the same job.

*.stepname.procstepname.label
Identifies a CNTL statement, named label, in a cataloged or in-stream procedure. Stepname is the name of the job step that calls the procedure; procstepname is the name of the procedure step that contains the CNTL statement named label.

3.Examples of the CNTL Parameter

Example 

//MONDAY    DD    CNTL=*.WKLYPGM

In this example, the DD statement requests that the system use the program control statements following the CNTL statement named WKLYPGM and located earlier in this step or preceding the first step.

Example 

//TUESDAY   DD    CNTL=*.SECOND.BLOCKS

In this example, the DD statement requests that the system use the program control statements following the CNTL statement named BLOCKS and located in a preceding step named SECOND.

Example 

//WEDNES    DD    CNTL=*.THIRD.PROCTWO.CANETTI

In this example, the DD statement requests that the system use the program control statements following the CNTL statement named CANETTI and located in the procedure step PROCTWO of the procedure called in the preceding job step THIRD.

COPIES parameter

Parameter Type

Keyword, optional

Purpose

Use the COPIES parameter to specify how many copies of this sysout data set are to be printed. The printed output is in page sequence for each copy.

For printing on an AFP printer, this parameter can instead specify how many copies of each page are to be printed before the next page is printed.

Note: For more information about the subparameters supported for AFP printers.

1.Syntax

COPIES= {nnn }
        {(nnn,(group-value[,group-value]...))}
        {(,(group-value[,group-value]...)) }
  • You can omit the parentheses if you code only COPIES=nnn.
  • The following are not valid:
  • – A null group-value, for example, COPIES=(5,(,)) or COPIES=(5,)
    – A zero group-value, for example, COPIES=(5,(1,0,4))
    – A null within a list of group-values, for example, COPIES=(5,(1,,4))

2.Subparameter Definition

nnn
A number (from 1 through 255 in a JES2 system, from 1 through 254 in a JES3 system) that specifies how many copies of the data set are to be printed.

For a data set printed on an AFP printer, JES ignores nnn if any group-values are specified.

group-value
Specifies how many copies of each page are to be printed before the next page is printed. Each group-value is a number from 1 through 255 in a JES2 system and from 1 through 254 in a JES3 system. You can code a maximum of eight group-values. Their sum must not exceed 255 or 254. The total copies of each page equals the sum of the group-values.

3.Defaults
On any of the following statements, if you do not code a COPIES parameter, code it incorrectly, or code COPIES=0, the system uses the DD COPIES parameter default of 1.

DD statement
OUTPUT JCL statement
For JES2, the /*OUTPUT statement

4.Overrides
A COPIES parameter on a sysout DD statement overrides an OUTPUT JCL COPIES parameter.

If this DD statement references an OUTPUT JCL statement and that OUTPUT JCL statement contains a FORMDEF parameter, which specifies a library member, the COPYGROUP parameter on a FORMDEF statement in that member overrides any group-value subparameters on the OUTPUT JCL COPIES parameter or the sysout DD COPIES parameter.

5.Relationship to Other Parameters
Do not code the following parameters with the COPIES parameter.

*         DDNAME     LABEL
AMP       DISP       QNAME
DATA      DYNAM      VOLUME

Relationship to FLASH Parameter

If this DD statement or a referenced OUTPUT JCL statement also contains a FLASH parameter, JES prints with the forms overlay the number of copies specified in one of the following:

  • COPIES=nnn, if the FLASH count is larger than nnn. For example, if COPIES=10 and FLASH=(LTHD,12) JES prints 10 copies, all with the forms overlay.
  • The sum of the group-values specified in the COPIES parameter, if the FLASH count is larger than the sum. For example, if COPIES=(,(2,3,4)) and FLASH=(LTHD,12) JES prints nine copies in groups, all with the forms overlay.
  • The count subparameter in the FLASH parameter, if the FLASH count is smaller than nnn or the sum from the COPIES parameter. For example, if COPIES=10 and FLASH=(LTHD,7) JES prints seven copies with the forms overlay and three copies without.

Restriction When Coding UNIT Parameter

The COPIES parameter is normally coded with the SYSOUT parameter. If, however, both COPIES and UNIT appear on a DD statement, JES handles the COPIES parameter as follows:

  • nnn defaults to 1.
  • Only the first group-value is used, if group-values are specified and printing is on a 3800.

6.Relationship to Other Control Statements
The number of copies can also be specified on the COPIES parameter of the following:

  • The OUTPUT JCL statement.
  • The JES2 /*OUTPUT statement.
  • The JES3 //*FORMAT PR statement.
  • The JES3 //*FORMAT PU statement.

For JES2, if you request copies of the entire job on the JES2 /*JOBPARM COPIES parameter and also copies of the data set on the DD COPIES or OUTPUT JCL COPIES parameter, and if this is a sysout data set, JES2 prints the number of copies equal to the product of the two requests.

Using OUTPUT JCL COPIES by Nullifying DD Copies
If both a DD statement and a referenced OUTPUT JCL statement contain COPIES parameters, the DD COPIES parameter normally overrides the OUTPUT JCL COPIES parameter. For example, four copies are printed of sysout data set DDA:

//OTA     OUTPUT    COPIES=3
//DDA     DD        SYSOUT=A,OUTPUT=*.OTA,COPIES=4

However, if the DD COPIES is a null parameter, the OUTPUT JCL COPIES parameter is used. For example, three copies are printed of sysout data set DDB:

//OTB     OUTPUT    COPIES=3
//DDB     DD        SYSOUT=A,OUTPUT=*.OTB,COPIES=

The following example shows a null COPIES parameter on an in-stream DD statement that overrides a procedure DD statement. The null COPIES parameter on DD statement PS.DDA nullifies the COPIES parameter on the procedure DD statement DDA, thereby allowing the COPIES parameter on OUTPUT JCL statement OT to be used. The system prints three copies of the DDA sysout data set.

//JEX      JOB      ACCT34,’PAUL BENNETT’
//INSTR    PROC
//PS       EXEC     PGM=ABC
//OT       OUTPUT   COPIES=3
//DDA      DD       SYSOUT=A,OUTPUT=*.OT,COPIES=2
//         PEND
//STEP1    EXEC     PROC=INSTR
//PS.DDA   DD       COPIES=
/*

Note: If a null COPIES parameter appears on a DD statement that either does not reference an OUTPUT JCL statement or references an OUTPUT JCL statement that does not contain a COPIES parameter, the system uses a default of 1.

7.Examples of the COPIES Parameter

Example 

//RECORD1   DD   SYSOUT=A,COPIES=32

This example requests 32 copies of the data set defined by DD statement RECORD1 when printing on an impact printer or an AFP printer.

Example 

//RECORD2   DD   SYSOUT=A,COPIES=(0,(1,2))

In this example, when printing on an AFP printer, three copies of the data set are printed in two groups. The first group contains one copy of each page. The second group contains two copies of each page. When printing on an impact printer, one copy (the default for nnn) is printed.

Example 

//RECORD3   DD   SYSOUT=A,COPIES=(8,(1,3,2))

In this example, when printing on an AFP printer, six copies of the data set are printed in three groups. The first group contains one copy of each page, the second group contains three copies of each page, and the last group contains two copies of each page. When the output device is not an AFP printer, the system prints eight collated copies.

Example 

//RECORD4   DD   UNIT=AFP1,COPIES=(1,(2,3))

Because the UNIT parameter is coded and the device is an AFP printer, the system prints only the first group-value: two copies of each page.

DATA parameter

Parameter Type

Positional, optional

Purpose

Use the DATA parameter to begin an in-stream data set that may contain statements with // in columns 1 and 2. The data records immediately follow the DD DATA statement; the records may be in any code, such as EBCDIC. The data records end when:

  • An EBCDIC /* or the two-character delimiter specified by a DLM parameter on this DD statement is found in the input stream, or
  • The input stream runs out of card images.

Note that, unlike a DD * statement, the data is not ended by the // that indicates another JCL statement.

Considerations for an APPC Scheduling Environment

The DATA parameter has no function in an APPC scheduling environment. If you code DATA, the system will check it for syntax and ignore it.

1.Syntax

//ddname DD DATA[,parameter]... [comments]

2.Defaults
When you do not code BLKSIZE and LRECL, JES uses installation defaults specified at initialization.

3.Relationship to Other Parameters
The following DD parameters may be specified with the DD * and DD DATA parameters. All other parameters are either ignored or result in a JCL error.

DCB=BLKSIZE     DSNAME
DCB=BUFNO       LIKE
DCB=LRECL       LRECL
DCB=DIAGNS      REFDD
DCB=MODE=C      VOLUME=SER
DLM             DSID

For JES3, when using the DCB=MODE=C subparameter with the DATA parameter, DCB=MODE=C must be the only parameter specified with the DATA parameter.

You cannot use the TSO/E SUBMIT command to submit a data set to JES2 or JES3 with a record length of greater than 80 bytes. The records are truncated to 80 bytes.

You can submit a data set to JES2 or JES3 with a record length of greater than 80 bytes by submitting JCL like the following. In this example JCL, IBMUSER. LONG DATA.JCL contains the data with a record length of greater than 80 bytes. In a JES3 system, the record length is limited to the installation-defined spool buffer size minus 44. (For example, if the buffer size is defined as 4084, the record length limit is 4040.) JES3 input service fails any job that exceeds this limit.

If the records longer than 80 bytes include JCL to be transmitted to a remote system using JES3 // XMIT or //*ROUTE XEQ, or JES2 /*ROUTE XEQ or /*XMIT with JES3 in the network, the records are truncated to 80 bytes.

//SUBMIT    JOB    ...
//S1        EXEC   PGM=IEBGENER
//SYSPRINT  DD     SYSOUT=*
//SYSIN     DD     DUMMY
//SYSUT2    DD     SYSOUT=(,INTRDR)
//SYSUT1    DD     DSN=IBMUSER.LONGDATA.JCL,DISP=SHR

For JES3 SNA RJP Input

  • The only parameters you can specify for JES3 systems network architecture (SNA) remote job processing (RJP) input devices are BLKSIZE and LRECL.
  • Code DCB=LRECL=nnn, where nnn is 1 to 255 when SYSIN data records are greater than 80 bytes. (The default LRECL is 80 bytes.)

For 3540 Diskette Input/Output Units

VOLUME=SER, BUFNO, and DSID on a DD DATA statement are ignored except when they are detected by a diskette reader as a request for an associated data set. On a DD * or DD DATA statement processed by a diskette reader, you can specify DSID and VOLUME=SER parameters to indicate that a diskette data set is to be merged into the input stream following the DD statement.

4.Relationship to Other Control Statements
Do not refer to an earlier DD DATA statement in DCB, DSNAME, or VOLUME parameters on following DD statements.

5.Location in the JCL
A DD DATA statement begins an in-stream data set.

In-stream Data for Cataloged or In-stream Procedures

A cataloged or in-stream procedure cannot contain a DD DATA statement. When you call a procedure, you can add input stream data to a procedure step by placing in the calling step one or more DD * or DD DATA statements, each followed by data.

Multiple In-Stream Data Sets for a Step

You can code more than one DD * or DD DATA statement in a job step in order to include several distinct groups of data for the processing program. Precede each group with a DD * or DD DATA statement and follow each group with a delimiter statement.

Omitted Data Delimiters

If you omit a DD statement before input data, the system provides a DD * statement with the ddname of SYSIN and ends the data when it reads a JCL statement or runs out of card images. If you omit a delimiter after input data, the system ends the data when it reads a JCL statement or runs out of card images.

6.Unread Records
If the processing program does not read all the data in an in-stream data set, the system skips the remaining data without abnormally terminating the step.

7.Examples of the DATA Parameter

Example 

//GROUP1  DD  DATA
          .
          .
          data
          .
/*
//GROUP2  DD  DATA
          .
          .
          data
          .
/*

This example defines two groups of data in the input stream.

Example 

//GROUP3  DD  DATA,DSNAME=&&GRP3
          .
          .
          data
          .
/*

This example defines an in-stream data set with GRP3 as the last qualifier of the system-generated data set name. A name such as
userid.jobname.jobid.Ddsnumber.GRP3 is generated.

Example 

//STEP2     EXEC  PROC=UPDATE
//PREP.DD4  DD    DSNAME=A.B.C,UNIT=3350,VOLUME=SER=D88230,
//                SPACE=(TRK,(10,5)),DISP=(,CATLG,DELETE)
//PREP.IN1  DD    DATA
            .
            .
            data
            .
/*
//ADD.IN2   DD    *
            .
            .
            data
            .
/*

This example defines two groups of data in the input stream. The input defined by DD statement PREP.IN1 is to be used by the cataloged procedure step named PREP. This data contains job control statements. The input data defined by DD statement ADD.IN2 is to be used by the cataloged procedure step named ADD. Because this data is defined by a DD * statement, it must not contain job control statements.

DATACLAS parameter

Parameter Type

Keyword, optional

This parameter is useful only if SMS is running. Without SMS, use the DCB parameter.

Purpose
Use the DATACLAS parameter to specify a data class for a new data set. The storage administrator at your installation defines the names of the data classes you can code on the DATACLAS parameter.

If SMS is not installed or is not active, the system syntax checks and then ignores the DATACLAS parameter.

SMS ignores the DATACLAS parameter if you specify it for (1) an existing data set or (2) a data set that SMS does not support.

You can use the DATACLAS parameter for both VSAM data sets and physical sequential (PS) or partitioned (PO) data sets.

A data class defines the following data set allocation attributes:

  • Data set organization
  • --Record organization (RECORG) or
    --Record format (RECFM)
  • Record length (LRECL)
  • Key length (KEYLEN)
  • Key offset (KEYOFF)
  • Type, PDS or PDSE (DSNTYPE)
  • Space allocation (AVGREC and SPACE)
  • Retention period (RETPD) or expiration date (EXPDT)
  • Volume-count (VOLUME)
  • Compaction
  • Media interchange type
  • Space constraint relief
  • Block size limit
  • For VSAM data sets (IMBED or REPLICATE, CISIZE, FREESPACE, SHAREOPTIONS, REUSE, INITIAL LOAD, SPANNED/NONSPANNED, BWO (backup while open), and LOGGING OPTIONS)

Note: The volume-count on the VOLUME parameter in the data class specifies the maximum number of SMS-managed volumes that a data set can span. The volume-count is ignored for data sets to which no storage class is assigned.

For tape data sets, only the following attributes apply:

  • EXPDT
  • LRECL
  • RECFM
  • RETPD

1.Syntax

DATACLAS=data-class-name

2.Subparameter Definition

data-class-name
Specifies the name of a data class to be used for allocating the data set. The name, one to eight characters, is defined by the storage administrator at your installation.

3.Defaults
If you do not specify DATACLAS for a new data set and the storage administrator has provided an installation-written automatic class selection (ACS) routine, the ACS routine may select a data class for the data set. Check with your storage administrator to determine if an ACS routine will select a data class for the new data set, in which case you do not need to specify DATACLAS.

When RECORG is not specified, data sets associated with a data class, either by JCL or assigned by an ACS routine, will have DSORG defaulted to either physical sequential or a partitioned organization

4.Overrides
Any attributes you specify on the same DD statement using parameters such as the following (not a complete list), override the corresponding attributes in the named data class for the data set:

RECORG (record organization) or RECFM (record format)

  • LRECL (record length)
  • KEYLEN (key length)
  • KEYOFF (key offset)
  • DSNTYPE (type, PDS or PDSE)
  • AVGREC (record request and spacequantity)
  • SPACE (average record length, primary, secondary, and directory quantity)
  • RETPD (retention period) or EXPDT (expiration date)
  • VOLUME (volume-count)
  • BLKSIZE (block size) and BLKSZLIM (block size limit). A block size from any source overrides BLKSZLIM from any source.
  • CICS (forward recovery log stream identifier)
  • DASD (space constraint)
  • VSAM (reuse, extended addressability, spanned records, logging control, record access bias, initial load formatting)

Explicit specification of SPACE on the DD statement overrides both the SPACE and the AVGREC values specified in the data class.

An ACS routine can override the data class that you specify on the DATACLAS parameter.

Attributes obtained with the LIKE and REFDD parameters override the corresponding attributes in the DATACLAS parameter.

5.Relationship to Other Parameters
Do not code the following DD parameters with the DATACLAS parameter.

*         DYNAM
DATA      QNAME
DDNAME

6.Examples of the DATACLAS Parameter

Example 

//SMSDS1   DD   DSNAME=MYDS1.PGM,DATACLAS=DCLAS01,DISP=(NEW,KEEP)

In the example, the attributes in the data class named DCLAS01 are used by SMS to handle the data set. Note that installation-written ACS routines may select a management class and storage class and can override the specified data class.

Example 

//SMSDS2   DD   DSNAME=MYDS2.PGM,DATACLAS=DCLAS02,DISP=(NEW,KEEP),
//              LRECL=256,EXPDT=1996/033

In the example, the logical record length of 256 and the expiration date of February 2, 1996, override the corresponding attributes defined in the data class for the data set. Note that installation-written ACS routines may select a management class and storage class and can override the specified data class.

DCB parameter

Parameter Type

Keyword, optional

Purpose
Use the DCB parameter to complete during execution the data set information in the data control block (DCB).

The data control block is constructed by the DCB macro instruction in assembler language programs or by file definition statements or language-defined defaults in programs in other languages.

Notes:

  1. With SMS, you do not need to use the DCB parameter to specify data set attributes.
  2. For JES3 SNA RJP, code DCB=LRECL=nnn; where nnn is 1 to 255 when SYSIN data records are greater than 80 bytes. (The default LRECL is 80 bytes.)

1.Syntax

[ DCB=(subparameter[,subparameter]...) ]
[ DCB= ( {dsname }[,subparameter]...) ]
[ ( {*.ddname } ) ]
[ ( {*.stepname.ddname } ) ]
[ ( {*.stepname.procstepname.ddname} ) ]

Parentheses: You can omit the parentheses if you code:

  • Only one keyword subparameter.
  • Only a data set name, dsname, without any subparameters.
  • Only a backward reference without any subparameters. A backward reference is a reference to an earlier DD statement in the job or in a cataloged or in-stream procedure called by a job step. A backward reference is in the form *.ddname or *.stepname.ddname or *.stepname.procstepname.ddname.

For example, DCB=RECFM=FB or DCB=WKDATA or DCB=*.STEP3.DD2

Multiple Subparameters: When the parameter contains more than one sub
parameter, separate the sub parameters by commas and enclose the sub
parameter list in parentheses. For example, DCB=(RECFM=FB,
LRECL=133,BLK SIZE=399) or DCB=(*.DD1,BUFNO=4)

Continuation onto Another Statement: Enclose the subparameter list in only one set of parentheses. End each statement with a comma after a complete subparameter. For example:

//INPUT   DD   DSNAME=WKDATA,DCB=(RECFM=FB,LRECL=80,BLKSIZE=800,
//             BUFL=800,BUFNO=4)

Alternate Syntax for DCB Keyword Subparameters

All of the DCB keyword subparameters can be specified without the need to code DCB =. For example, the following DD statement:

//DDEX   DD  DSNAME=WKDATA,DCB=(RECFM=FB,LRECL=80,BLKSIZE=800),DISP=MOD

can also be specified as:

//DDEX  DD  DSNAME=WKDATA,RECFM=FB,LRECL=80,BLKSIZE=800,DISP=MOD

Note that KEYLEN, LRECL, and RECFM are described as DD parameters.

Note:

  • If the BUFMAX subparameter is coded with or without the DCB parameter, it can have a null value only when coded on a DD which either:
  • – Overrides a DD in a procedure
    – Is added to a procedure

2.Subparameter Definition

subparameter
Specifies a DCB keyword subparameter needed to complete the data control block.

An alphabetic summary of the DCB keyword subparameters follows this parameter description.

You must supply DCB information through the DCB subparameters if your processing program, the data set label, or your language’s defined values do not complete the data control block.

dsname
Names a cataloged data set. The system is to copy DCB information from the data set’s label. The data set must reside on a direct access volume, and the volume must be mounted before the job step is executed.

If dsname represents a VSAM data set, and you are allocating a new data set, you must also supply the RECORG parameter. You can specify RECORG explicitly (through the RECORG parameter), or implicitly, through the DATACLAS or LIKE parameters.

A hyphen is a valid character in a catalogued data set name. A data set name that contains a hyphen must be enclosed in apostrophes if it is used as a DCB subparameter.

The dsname cannot contain special characters, except for periods used in qualifying the name. Do not specify a generation data group (GDG) base name, a GDG relative generation member name, or a member name of a non-GDG data set.

The system copies the following DCB information from the data set label:

DSORG (used in a backward reference)
RECFM
OPTCD
BLKSIZE
LRECL
KEYLEN
RKP

If you do not specify the expiration date of the cataloged data set, the system copies it from the data set label. The system also copies the system code.

If you code any DCB subparameters after the dsname, these subparameters override the corresponding subparameters in the data set label. The system copies from the referenced label only those subparameters not specified on the referencing DD statement.

*.ddname*.stepname.ddname*.stepname.procstepname.ddname

Specify a backward reference to an earlier DD statement. The system is to copy DCB  information from the DCB parameter specified on that DD statement. The DCB parameter of the referenced DD statement must contain subparameters, and it cannot name a cataloged data set or refer to another DD statement.

*.ddname specifies the ddname of an earlier DD statement in the same step. *.stepname.ddname specifies the ddname of a DD statement in an earlier step, stepname, in the same job. *.stepname.procstepname.ddname specifies the ddname of a DD statement in a cataloged or in-stream procedure called by an earlier job step. Stepname is the name of the job step that calls the procedure, and procstepname is the name of the procedure step that contains the DD statement.

If you code any DCB subparameters after the reference, these subparameters override the corresponding subparameters on the referenced DD statement. The system copies from the referenced DD statement only those subparameters not specified on the referencing DD statement. Do not reference a DD * or a DD DATA statement.

Note: The system also copies the UCS and FCB parameters from the referenced DD statement, unless you override them in the referencing DD statement.

3.Completing the Data Control Block
The system obtains data control block information from the following sources, in override order:

  • The processing program, that is, the DCB macro instruction in assembler language programs or file definition statements or language-defined defaults in programs in other languages.
  • The DCB subparameter of the DD statement.
  • The data set label.

Therefore, if you supply information for the same DCB field in your processing program and on a DD statement, the system ignores the DD DCB subparameter. If a DD statement and the data set label supply information for the same DCB field, the system ignores the data set label information.

Note: When concatenated data sets are involved, the DCB is completed based on the type of data set and how the processing program uses the data set. See z/OS DFSMS: Using Data Sets for more information.

4.Relationship to Other Parameters
See the descriptions of the individual DCB subparameters for the DD parameters and DCB subparameters that should not be coded with a specific DCB subparameter.

Do not code the following parameters with the DCB parameter.

AMP
DYNAM

With the DDNAME parameter, code only the BLKSIZE, BUFNO, and DIAGNS DCB subparameters.

With the QNAME parameter, code only the BLKSIZE, LRECL, OPTCD, and RECFM DCB subparameters.

The DD parameter KEYLEN and DCB subparameters KEYLEN, MODE, PRTSP, STACK, and TRTCH apply to specific device types. If you specify one of these subparameters on a DD statement for a device different from the type to which it applies, the system interprets the value incorrectly.

With the SPACE parameter, the value specified for BLKSIZE directly affects the amount of space obtained for data sets allocated in records, and for data sets allocated in blocks where the block length (blklgth) is zero.

For 3540 Diskette Input/Output Units

The VOLUME=SER, DCB=BUFNO, and DSID parameters on a DD * or DD DATA statement are ignored except when they are detected by a diskette reader as a request for an associated data set.

5.Examples of the DCB Parameter

Example 

//DD1    DD    DSNAME=ALP,DISP=(,KEEP),VOLUME=SER=44321,
//             UNIT=3400-6,DCB=(RECFM=FB,LRECL=240,BLKSIZE=960,
//             DEN=1,TRTCH=C)

DD statement DD1 defines a new data set named ALP. The DCB parameter contains the information necessary to complete the data control block.

Example 

//DD1A    DD    DSNAME=EVER,DISP=(NEW,KEEP),UNIT=3380,
//              DCB=(RECFM=FB,LRECL=326,BLKSIZE=23472),
//              SPACE=(23472,(200,40))

DD statement DD1A defines a new data set named EVER on a 3380. The DCB parameter contains the information necessary to complete the data control block.

//DD1B    DD    DSNAME=EVER,DISP=(NEW,KEEP),UNIT=3380,
//              RECFM=FB,LRECL=326,
//              SPACE=(23472,(200,40))

DD statement DD1B is the same as the DD1A statement except that it shows the alternate syntax for the DCB keyword subparameters. Also, because BLKSIZE is omitted, the system will select an optimum block size for the data.

Example 

//DD2     DD    DSNAME=BAL,DISP=OLD,DCB=(RECFM=F,LRECL=80,
//              BLKSIZE=80)
//DD3     DD    DSNAME=CNANN,DISP=(,CATLG,DELETE),UNIT=3400-6,
//              LABEL=(,NL),VOLUME=SER=663488,DCB=*.DD2

DD statement DD3 defines a new data set named CNANN and requests that the system copy the DCB subparameters from DD statement DD2, which is in the same job step.

Example 

//DD4     DD    DSNAME=JST,DISP=(NEW,KEEP),UNIT=SYSDA,
//              SPACE=(CYL,(12,2)),DCB=(A.B.C,KEYLEN=8)

DD statement DD4 defines a new data set named JST and requests that the system copy the DCB information from the data set label of the cataloged data set named A.B.C. If the data set label contains a key length specification, it is overridden by the KEYLEN coded on this DD statement.

Example 

//DD5     DD    DSNAME=SMAE,DISP=OLD,
//              DCB=(*.STEP1.PROCSTP5.DD8,BUFNO=5)

DD statement DD5 defines an existing, cataloged data set named SMAE and requests that the system copy DCB subparameters from DD statement DD8, which is contained in the procedure step named PROCSTP5. The cataloged procedure is called by EXEC statement STEP1. Any of the DCB subparameters coded on DD statement DD8 are ignored if they are specified in the program. If the DCB BUFNO subparameter is not specified in the program, five buffers are assigned.

DCB Subparameters

DDNAME parameter

Parameter Type

Keyword, optional

Purpose

Use the DDNAME parameter to postpone defining a data set until later in the same job step. A DDNAME parameter on a DD statement in a cataloged or in-stream procedure allows you to postpone defining the data set until a job step calls the procedure; the data set must be defined in the calling job step.

1.Syntax

DDNAME=ddname
  • The DDNAME parameter can have a null value only when coded on a DD which either:
  • – Overrides a DD in a procedure
    – Is added to a procedure.

2.Subparameter Definition

ddname
Refers to a later DD statement that defines the data set. ddname must match the ddname of the referenced DD statement. A job step or procedure step can contain up to five DD statements with DDNAME parameters. Each DDNAME parameter must refer to a different DD statement.

3.Overrides
If any DCB subparameter appears on both DD statements, the DCB subparameter on the referenced DD statement overrides the DCB subparameter on the DD statement that contains DDNAME.

4.Relationship to Other Parameters
The only DD parameters you can code with the DDNAME parameter are:

DCB=BLKSIZE      LIKE
DCB=BUFNO        REFDD
DCB=DIAGNS

Do not code the DDNAME parameter on a DD statement with a ddname of JOBLIB, JOBCAT, or STEPCAT.

5.Location in the JCL
Place a DD statement containing a DDNAME parameter in a job step or in a cataloged or in-stream procedure. The referenced DD statement must be later in the same job step, must be in the calling job step, or must be in a cataloged or in-stream procedure called by the job step. Do not use the name of a DDNAME statement more than once within the same step.

Location of DD Statements for Concatenated Data Sets

To concatenate data sets to a data set defined with a DDNAME parameter, the unnamed DD statements must follow the DD statement that contains the DDNAME parameter, not the referenced DD statement that defines the data set.

Errors in Location of Referenced DD Statement

The system treats a DDNAME parameter as though it were a DUMMY parameter and issues a warning message in the following cases:

  • If the job step or called procedure does not contain the referenced DD statement.
  • If the referenced DD statement appears earlier in the job step.

Location of DD Statement Requesting Unit Affinity

To use the same device, a DD statement can request unit affinity to an earlier DD statement by specifying UNIT=AFF=ddname. If a DD statement requests unit affinity to a DD statement containing a DDNAME parameter, the DD statement requesting unit affinity must be placed after the referenced DD statement. If the DD statement requesting unit affinity appears before, the system treats the DD statement requesting unit affinity as a DUMMY DD statement.

//STEP    EXEC    PGM=TKM
//DD1     DD      DDNAME=DD4
//DD2     DD      DSNAME=A,DISP=OLD
          .
          .
//DD4     DD      DSNAME=B,DISP=OLD
//DD5     DD      UNIT=AFF=DD1

DD1 postpones defining the data set until DD4. DD5 requests unit affinity to DD1. Because DD1 has been defined when DD5 is processed, the system assigns DD5 to the same device as DD1. Instead of specifying UNIT=AFF=ddname, both DD statements can specify the same devices in their UNIT parameters or the same volume serials in their VOLUME parameters.

6.Referenced DD Statement
If the DDNAME parameter appears in a procedure with multiple steps, the ddname on the referenced DD statement takes the form stepname.ddname. For example, if procedure step STEPCP1 contains:

//INDATA   DD  DDNAME=DD1

The referenced DD statement in the calling job step is:

//STEPCP1.DD1   DD   *

Parameters not Permitted on the Referenced DD Statement

The referenced DD statement must not contain a DYNAM or PATH parameter A DD statement that contains a DDNAME parameter must not override a procedure sysout DD statement that contains an OUTPUT parameter if the referenced DD statement also contains an OUTPUT parameter.

References to Concatenated Data Sets

If you make a forward reference to a concatenation, the forward reference resolves to the first data set in the concatenation. If there are no DD statements between the forward reference and the concatenation, the rest of the data sets in the concatenation are appended to the first data set in the concatenation. The following example illustrates this.

//STEP1      EXEC   PGM=IEBGENER
//SYSPRINT   DD     SYSOUT=*
//SYSUT1     DD     DDNAME=INPUT
//INPUT      DD     DSN=TSTDATA1,DISP=SHR
//           DD     DSN=TSTDATA2,DISP=SHR
//SYSUT2     DD     SYSOUT=*
//SYSIN      DD     DUMMY

In this example, SYSUT1 will resolve to the first data set TSTDATA1, defined by the DDNAME forward reference INPUT. TSTDATA2, the second data set in the DDNAME forward reference INPUT, will be appended to SYSUT1 as well. IEBGENER will recognize TSTDATA1 and TSTDATA2 as input.

If there are any DD statements between the forward reference and the concatenation, the rest of the data sets in the concatenation are appended to the last DD statement preceding the concatenation. For example:

//STEP1      EXEC   PGM=IEBGENER
//SYSUT1     DD     DDNAME=INPUT
//SYSPRINT   DD     SYSOUT=*
//SYSUT2     DD     SYSOUT=*
//INPUT      DD     DSN=TSTDATA1,DISP=SHR
//           DD     DSN=TSTDATA2,DISP=SHR
//SYSIN      DD     DUMMY

In the preceding example, SYSUT1 will resolve to the first data set, TSTDATA1, defined in the DDNAME forward reference INPUT. TSTDATA2 will be appended to SYSUT2, the last DD statement preceding the concatenation. In that example IEBGENER will only recognize TSTDATA1 as input.

If a concatenated DD is added to a procedure, the remaining concatenated data sets will be concatenated to the last DD in the step named in an override or addition (or to the first step if no step was named in an override or (addition). Note that this may result in these concatenated DDs being added to an unexpected DD. The following example illustrates this.

//TPROC      PROC
//S1         EXEC   PGM=IEFBR14
//DD1        DD     DDNAME=INPUT
//DD2        DD     DSN=MYDSN2,DISP=SHR
//DD3        DD     DSN=MYDSN3,DISP=SHR
//S2         EXEC   PGM=IEFBR14
//DDA        DD     DDNAME=INPUT
//DDB        DD     DSN=MINE2,DISP=SHR
//DDC        DD     DSN=MINE3,DISP=SHR
//           PEND
//STEP1      EXEC   TPROC
//INPUT      DD     DSN=MYDSN1,DISP=SHR
//           DD     DSN=MYDSN4,DISP=SHR
//S2.INPUT   DD     DSN=MINE1,DISP=SHR
//           DD     DSN=MINE4,DISP=SHR

In the preceding example, the result of the DDNAME forward reference INPUT is:

  • In step S1, DD1 resolves to data set MYDSN1 and data set MYDSN4 is concatenated to data set MYDSN3.
  • In step S2, DDA resolves to data set MINE1 and data set MINE4 is concatenated to data set MINE3.

7.Backward References
A backward reference is a reference to an earlier DD statement in the job or in a cataloged or in-stream procedure called by a job step. A backward reference is in the form *.ddname or *.stepname.ddname or *.stepname.procstepname.ddname. The ddname in the reference is the ddname of the earlier DD statement. If the earlier DD statement contains a DDNAME parameter, the reference is to the ddname in the name field of the earlier statement, not to the ddname in the DDNAME parameter.

The DD statement referenced in a DDNAME parameter cannot refer to a DD statement between the statement containing the DDNAME parameter and itself. For example:

//SHOW       EXEC   PGM=ABLE
//DD1        DD     DDNAME=INPUT
//DD2        DD     DSNAME=TEMPSPAC,SPACE=(TRK,1),UNIT=SYSDA
//DD3        DD     DSNAME=INCOPY,VOLUME=REF=*.DD1,
//                  DISP=(,KEEP),SPACE=(TRK,(5,2))
//DD4        DD     DSNAME=OUTLIST,DISP=OLD
//DD5        DD     DSNAME=MESSAGE,DISP=OLD,UNIT=3330,VOLUME=SER=333333
//INPUT      DD     DSNAME=NEWLIST,DISP=(OLD,KEEP),VOLUME=SER=333333,
//                  UNIT=3330

The DDNAME parameter on DD1 refers to DD statement INPUT. The VOLUME parameter of DD3 specifies a backward reference to DD1, which is the name field ddname.

DD statement INPUT identifies the volume 333333 in its VOLUME=SER=333333 parameter. DD statement INPUT cannot use a backward reference to the VOLUME parameter on DD5 because DD5 is between the referring DD1 and the referenced INPUT.

8.Examples of the DDNAME Parameter

Example 
The following procedure step is the only step in a cataloged procedure named CROWE:

//PROCSTEP   EXEC   PGM=RECPGM
//DD1        DD     DDNAME=WKREC
//POD        DD     DSNAME=OLDREC,DISP=OLD

DD statement DD1 is intended for weekly records in the input stream; these records are processed by this step. Because the * and DATA parameters cannot be used in cataloged procedures, the DDNAME parameter is coded to postpone defining the data set until the procedure is called by a job step. The step that calls the procedure is:

//STEPA      EXEC   PROC=CROWE
//WKREC      DD     *
             .
             .
             data
             .
/*

Example 
When the procedure contains multiple steps, use the form stepname.ddname for the ddname of the referenced DD statement. For example, the following procedure steps appear in a cataloged procedure named PRICE:

//STEP1      EXEC    PGM=SUGAR
//DD1        DD      DDNAME=QUOTES
             .
             .
             .
//STEP2      EXEC    PGM=MOLASS
//DD2        DD      DSNAME=WEEKB,DISP=OLD
             . 
             .
             .

The step that calls the procedure is:

//STEPA           EXEC   PROC=PRICE
//STEP1.QUOTES    DD    *
                  .
                  .
                  data
                  .
/*

Example 
When the referenced DD statement is to be a concatenation, the procedure must already contain the concatenation. (Such as when the referencing DD statement is to contain in-stream data.) For example, the following procedure step appears in cataloged procedure NEWONE.

//NEWONE     PROC
//STEP1      EXEC   PGM=TRYIT
//DD1        DD     DNAME=INSTUFF
//           DD     DSN=OLDSTUFF,DISP=OLD

.. The step that calls the procedure is:

//STEPA     EXEC   PROC=NEWONE
//STEP1.INSTUFF    DD *
            .
            data
             .
/*

The instream data (DDNAME=INSTUFF) is inserted before OLDSTUFF in the concatenation.

Example 
In the following example we create a DD concatenation in a procedure using multiple DDNAME forward references, INPUT1—INPUT5. In the example, INPUT1 resolves to data set FIRST, INPUT2 resolves to data set SECOND, and INPUT3 resolves to data set THIRD. INPUT4 and INPUT5 resolve to DUMMY.

//ABC      PROC
//SI       EXEC     PGM=IEFBR14
//DD1      DD       DDNAME=INPUT1
//         DD       DDNAME=INPUT2
//         DD       DDNAME=INPUT3
//         DD       DDNAME=INPUT4
//         DD       DDNAME=INPUT5
//STEP1    EXEC     ABC
//INPUT1   DD       DSN=FIRST,DISP=SHR
//INPUT2   DD       DSN=SECOND,DISP=SHR
//INPUT3   DD       DSN=THIRD,DISP=SHR

DEST parameter

Parameter Type

Keyword, optional

Purpose

Use the DEST parameter to specify a destination for a sysout data set. The DEST parameter can send a sysout data set to a remote or local terminal, a node, a node and remote workstation, a local device or group of devices, or a node and userid.

Note: Code the DEST parameter only on a DD statement with a SYSOUT parameter. Otherwise, the system checks the DEST parameter for syntax, then ignores it.

1.Syntax

DEST=destination

The destination subparameter for JES2 is one of the following:

LOCAL|ANYLOCAL
name
Nnnnnn
NnRmmmmm
NnnRmmmm
NnnnRmmm
NnnnnRmm
NnnnnnRm
(node,remote)
Rmmmmm
RMmmmmm
RMTmmmmm
Unnnnn
(node,userid)
userid

The destination subparameter for JES3 is one of the following:

ANYLOCAL
device-name
device-number
group-name
nodename
(nodename,userid)
(nodename,devicename)

2.Subparameter Definition for JES2 Systems

LOCAL|ANYLOCAL
Indicates the local node on a local device.

name
Identifies a destination by a symbolic name which is defined by the installation during JES2 initialization. The name can be, for example, a local device, remote device, or a userid. The name is 1 through 8 alphanumeric or national ($, #, @) characters.

Nnnnnn
Identifies a node. nnnnn is 1 through 5 decimal numbers from 1 through 32,767.

NnRmmmmm
NnnRmmmm
NnnnRmmm
NnnnnRmm
NnnnnRm
(node,remote)
Identifies a node and a remote work station connected to the node. The node number, indicated in the format by n, is 1 through 5 decimal numbers from 1 through 32,767. The remote work station number, indicated in the format by m, is 1 through 5 decimal numbers from 1 through 32,767. Do not code leading zeros in n or m. The maximum number of digits for n and m combined cannot exceed six.

Note: NnnR0 is equivalent to LOCAL specified at node Nn.

Rmmmmm
RMmmmmm
RMTmmmmm
Identifies a remote workstation. mmmmm is 1 through 5 decimal numbers from 1 through 32,767. Note that with remote pooling, the installation may translate this route code to another route code.

If you send a job to execute at a remote node and the job has a ROUTE PRINT RMTmmmm statement, JES2 returns the output to RMTmmmm at the node of origin. For JES2 to print the output at RMTmmmm at the executing node, code DEST=NnnnRmmm on an OUTPUT JCL statement or sysout DD statement.

Note: R0 indicates any local device.

Unnnnn
Identifies a local terminal with special routing. nnnnn is 1 through 5 decimal numbers from 1 through 32,767. If you send a job to execute and the job has a ROUTE PRINT Unnnnn statement, JES2 returns the output to Unnnnn at the node of origin.

(node,userid)
Identifies a node and a TSO/E or VM userid at that node. The node is a symbolic name defined by the installation during initialization; node is 1 through 8 alphanumeric or national ($, #, @) characters. The userid must be defined at the node; userid for TSO/E is 1 through 7 alphanumeric or national ($, #, @) characters and for VM is 1 through 8 alphanumeric or national ($, #, @) characters. The userid can also be a destination name defined in a JES2 DESTID initialization statement.

DEST=(node) is valid with a writer-name subparameter in the SYSOUT parameter; however, DEST=(node,userid) is not valid. Therefore, you can code

SYSOUT=(A,writer-name),DEST=(node), but not SYSOUT=(A,writername),
DEST=(node,userid).

Note: You can code DEST=(nodename,Unnnnn) here; this syntax is a valid subset of DEST=(node,userid).

userid
Identifies a userid at the local node. Userid for TSO/E is 1 through 7 alphanumeric or national ($, #, @) characters. The userid can also be a destination name definded in a JES2 DESTID initialization statement.

Note: JES2 initialization statements determine whether or not the node name is required when coding a userid. See your system programmer for information regarding how routings will be interpreted by JES2.

3.Subparameter Definition for JES3 Systems

ANYLOCAL
Indicates any local device that is attached to the global processor.

device-name
Identifies a local device by a symbolic name defined by the installation during JES3 initialization. device-name is 1 through 8 alphanumeric or national ($, #, @) characters.

device-number
Identifies a specific device by a 3-digit or 4-digit hexadecimal number. Precede a 4-digit number with a slash (/). A 3-digit number can be specified with or without a slash.

group-name
Identifies a group of local devices, an individual remote station, or a group of remote stations by a symbolic name defined by the installation during JES3 initialization. group-name is 1 through 8 alphanumeric or national ($, #, @) characters.

nodename
Identifies a node by a symbolic name defined by the installation during JES3 initialization. nodename is 1 through 8 alphanumeric or national ($, #, @) characters. If the nodename you specify is the same as the node you are working on, JES3 treats the output as though you specified ANYLOCAL.

(nodename,userid)
Identifies a nodename and a TSO/E or VM userid at that nodename. The nodename is a symbolic name defined by the installation during initialization; node is 1 through 8 alphanumeric or national ($, #, @) characters. The userid must be defined at the nodename; userid for TSO/E is 1 through 7 alphanumeric or national ($, #, @) characters and for VM is 1 through 8 alphanumeric or national ($, #, @) characters.

A userid requires a nodename; therefore, code DEST=(nodename,userid). You cannot code a userid without a node.

DEST=(nodename) is valid with a writer-name subparameter in the SYSOUT parameter: however, DEST=(nodename,userid) is not valid. Therefore, you can code SYSOUT=(A,writer-name),DEST=(nodename).

(nodename,devicename)
Identifies a node by a symbolic name defined by the installation during JES3 initialization. nodename and devicename are each 1 through 8 alphanumeric or national ($, #, @) characters. devicename identifies a device by a symbolic name defined to that node by the installation during JES3 initialization. devicename is 1 through 8 alphanumeric or national ($, #, @) characters. Use this form of the DEST parameter to override the ORG parameter.

4.Defaults
If you do not code a DEST parameter, JES directs the sysout data set to the default destination for the input device from which the job was submitted.

In a JES3 system, if you do not code a DEST parameter, the default destination is the submitting location. For jobs submitted through TSO/E and routed to NJE for execution, the default is the node from which the job was submitted, and the destination ANYLOCAL.

If a specified destination is invalid, the job fails.

If you’ve coded the ORG parameter but did not explicitly code a primary destination, the default primary destination is the node specified in the ORG parameter, not the submitting node.

5.Overrides
The DEST parameter on the sysout DD statement overrides an OUTPUT JCL DEST parameter.

6.Relationship to Other Parameters
Code the DEST parameter only on a DD statement with the SYSOUT parameter

7.Relationship to Other Control Statements
You can also code an output destination using:

  • The OUTPUT JCL statement.
  • The JES2 /*OUTPUT and /*ROUTE control statements.
  • The JES3 //*MAIN, //*FORMAT PR, and //*FORMAT PU control statements.

Because DEST=(node,userid) cannot be coded on JES2 or JES3 control statements, you must code it, if needed, on a DD or OUTPUT JCL statement.

8.Example of the DEST Parameter

//JOB01   JOB    ,’MAE BIRD’,MSGCLASS=B
//STEP1   EXEC   PGM=INTEREST
//DEBIT   DD     SYSOUT=A
//CALIF   DD     SYSOUT=A,DEST=R555
//FLOR    DD     SYSOUT=A,DEST=(BOCA,’9212U28’)

In this example, the system sends the sysout data set defined by DD statement DEBIT to the work station that submitted the job, the data set defined by DD statement CALIF to the remote terminal 555, and the data set defined by DD statement FLOR to VM userid 9212U28 at node BOCA.

DISP parameter

Parameter Type

Keyword, optional

Purpose
Use the DISP parameter to describe the status of a data set to the system and tell the system what to do with the data set after termination of the step or job. You can specify one disposition for normal termination and another for abnormal termination.

Note: Disposition of the data set is controlled solely by the DISP parameter; disposition of the volume(s) on which the data set resides is a function of the volume status when the volume is demounted. If the UNIT parameter specifies a device, such as a printer or telecommunications device, that does not involve a data set, do not code the DISP parameter.

If the system obtains unit and volume information for an OLD, MOD, or SHR status, the data set is treated as if it exists, whether or not it is physically on the device.

When any step of a job requests exclusive control of a data set, the system converts all requests for shared control of that data set within that job (DISP=SHR) to requests for exclusive control. One of two methods can be used to request exclusive control:

  • DISP=NEW, DISP=MOD, or DISP=OLD on a JCL request.
  • DISP=NEW, DISP=MOD, or DISP=OLD on a dynamic allocation request,

including dynamic allocation requests that result from the use of certain utility control statements. For example, utility control statements that delete/scratch a data set will result in exclusive use of that data set.

When any step of a job requests exclusive control of a data set (through DISP=NEW, DISP=MOD, or DISP=OLD), the system converts all requests for shared control of that data set within that job (DISP=SHR) to requests for exclusive control.

1.Syntax

{DISP=status }
{DISP=([status][,normal-termination-disp][,abnormal-termination-disp])}
DISP= ( [NEW] [,DELETE ] [,DELETE ] )
        [OLD] [,KEEP   ] [,KEEP   ]
        [SHR] [,PASS   ] [,CATLG  ]
        [MOD] [,CATLG  ] [,UNCATLG]
        [ , ] [,UNCATLG]
              [   ,    ]
  • You can omit the parentheses if you code only the status subparameter.
  • If you omit the status subparameter but code subparameters for normal or abnormal termination disposition, you must code a comma to indicate the absence of NEW. For example, DISP=(,KEEP) or DISP=(,CATLG,DELETE).
  • If you omit the second subparameter but code the third, you must code a comma to indicate the absence of the second subparameter. For example, DISP=(OLD,,DELETE) or DISP=(,,KEEP).

2.Subparameter Definition

Status Subparameter

NEW
Indicates that a new data set is to be created in this step.

Note: Initialize a new data set to ensure that it is empty.

OLD
Indicates that the data set exists before this step and that this step requires exclusive (unshared) use of the data set.

If you specify DISP=OLD for an output tape data set and (1) the data set is not protected by RACF or a password or (2) the data set has no expiration date, the system does not verify the data set name in the header label.

SHR
Indicates that the data set exists before this step and that other jobs can share it, that is, use it at the same time. This subparameter can also be coded as SHARE.

If you specify DISP=SHR for an output tape data set and (1) the data set is not protected by RACF or a password or (2) the data set has no expiration date, the system does not verify the data set name in the header label.

MOD
Indicates one of the following:

  • The data set exists and records are to be added to the end of it. The data set must be sequential.
  • A new data set is to be created.

In either case, MOD specifies exclusive (unshared) use of the data set.

When the data set is opened, the read/write mechanism is positioned after the last sequential record for an existing data set or at the beginning for a new data set. For subsequent OPENs within the same step, the read/write mechanism is positioned after the last sequential record.

Note: You cannot specify DISP=MOD to extend an ISO/ANSI/FIPS Version 3 tape data set unless the ISO/ANSI/FIPS Version 3 label validation installation exit allows the extension. For information on using ISO/ANSI/FIPS Version 3 installation exits, see z/OS DFSMS: Using Magnetic Tapes.

If the system cannot find volume information for the data set on the DD statement, in the catalog, or passed with the data set from a previous step, the system assumes that the data set is being created in this job step. For a new data set, MOD causes the read/write mechanism to be positioned at the beginning of the data set.

To use DISP=MOD to create a new data set, code one of the following:

  • No VOLUME=SER or VOLUME=REF parameter on the DD statement. The data set must not be cataloged or passed from another job step.
  • A VOLUME=REF parameter that refers to a DD statement that makes a nonspecific volume request. (A nonspecific volume request is a DD statement for a new data set that can be assigned to any volume or volumes.) One of the following must also be true:
  • – The DSNAME parameters in the two DD statements must be different.
    – The two DD statements must request different areas of the same ISAM data set.
  • In the case of tape, if you do not specify an explicit volume serial number on the DD statement, the system requests the operator to mount a ²scratch² tape.

For a new generation of a generation data group (GDG) data set (where (+n) is greater than 0), you may code VOLUME=REF or VOLUME=SER. For an SMS-managed data set the system ignores the volume.

After the system chooses a volume for a new data set, if the system finds another data set with the same name on that volume, the system will try to allocate a different volume. However, SMS-managed data sets require unique data set names. If a new data set is chosen to be SMS-managed and an existing SMS-managed data set has the same name, the request fails.

In a JES3 system, if you code DISP=MOD for a multivolume data set and any of the volumes are JES3-managed, JES3 will not execute the job until all volumes, including scratch volumes being added, are allocated. Such a job will wait on the queue until all volumes are allocated.

Normal Termination Disposition Subparameter

DELETE
Indicates that the data set is no longer needed if this step terminates normally.

For a DASD data set, DELETE means that the space occupied by that data set is available for use by other data sets. The system will physically erase the data set itself only if the erase option of a security product, such as RACF, is in effect for this data set. If the ease option is not in effect, the data will remain on the DASD until overwritten by another data set. For information on how to set the erase option, see the documentation for the security product.

For a tape data set, DELETE does not physically erase the data from the tape volume. The data will remain on the tape until overwritten by another data set. If the tape volume is a public volume, specifying DELETE allows the system to reuse the tape volume for other data sets that require a public volume; the system may overwrite the data set.

Existing data sets:

  • If you set a retention period on the DD RETPD parameter, an existing data set is deleted only if its retention period is passed; otherwise the data set is kept.
  • If you set an expiration date on the DD EXPDT parameter, an existing data set is deleted if the expiration date has passed.

If the storage administrator specified OVRD_EXPDT(YES) in the IGDSMSxx member of SYS1.PARMLIB, you can override the expiration date or retention period for SMS-managed data sets by specifying DELETE on the DD DISP parameter. In that case, the data set will be deleted whether or not the expiration date or the retention period has passed.

New data sets:
A new data set is deleted at the end of the step even though a retention period or expiration date is also specified. See the DD EXPDT or RETPD parameters.

If the system retrieves volume information from the catalog because the DD statement does not specify VOLUME=SER or VOLUME=REF, then DELETE implies UNCATLG: the system deletes the data set and removes its catalog entry.

KEEP
Indicates that the data set is to be kept on the volume if this step terminates normally. Without SMS, only KEEP is valid for VSAM data sets. VSAM data sets should not be passed, cataloged, uncataloged, or deleted. With SMS, all dispositions are valid for VSAM data sets; however, UNCATLG is ignored. For new SMS-managed data sets, KEEP implies CATLG.

PASS
Indicates that the data set is to be passed for use by a subsequent step in the same job.

With SMS, the system replaces PASS with KEEP for permanent VSAM and non-VSAM data sets. When you refer to the data set later in the job, the system obtains data set information from the catalog.

Notes:

  1. A data set can be passed only within a job.
  2. If you specify DISP=(NEW,PASS) but, at the end of the job, one or more data sets were not received by any job step, then the maximum number of DD statements you can specify decreases by one. (The size of the TIOT controls how many DD statements are allowed per job step.) For example, if the current limit is 1635 DD statements, you can specify DISP=(NEW,PASS), and up to 1634 DD statements.
  3. Coding PASS does not ensure that the operator will not unload the volume or that the system will not demount it to accommodate another job step allocation. Either can occur when the device on which the volume is mounted is not allocated to the job step that specified PASS or, for unlabaled tapes, when the volume requires verification. If the system does demount a volume for which RETAIN was requested, it will do so by issuing message IEF234E R (retain) for that volume. When the system reaches the next step requiring that volume, it will request the operator to remount the volume on an available device of the appropriate type.

CATLG
Indicates that, if the step terminates normally, the system is to place an entry pointing to the data set in the system or user catalog. For CVOL catalogs, the system creates any missing index levels. Note that the data set is kept.

An unopened tape data set is cataloged, unless the volume request is nonspecific or unless the data set is allocated to a dual-density tape drive but no density is specified. A nonspecific volume request is a DD statement for a new data set that can be assigned to any volume or volumes.

UNCATLG
Indicates that, if the step terminates normally, the system is to delete (1) the entry pointing to the data set in the system or user catalog and (2) unneeded indexes, except for the highest level entry. Note that the data set is kept.

With SMS, UNCATLG is ignored for SMS-managed data sets and VSAM data sets (KEEP is implied).

Abnormal Termination (Conditional) Disposition Subparameter

DELETE
Indicates that the data set’s space on the volume is to be released if this step terminates abnormally. The space can be used for other data sets; the data set is not erased from the space.

Existing data sets:

  • If you set a retention period on the DD RETPD parameter, an existing data set is deleted only if its retention period is passed; otherwise the data set is kept.
  • If you set an expiration date on the DD EXPDT parameter, an existing data set is deleted if the expiration date has passed.

You can override the expiration date or retention period for SMS-managed DASD data sets using the OVRD_EXPDT(YES) parameter in the IGDSMSxx SYS1.PARMLIB member. In that case, the data set will be deleted whether or not the data set has expired or the retention period has passed.

New data sets:
A new data set is deleted at the end of the step even though a retention period or expiration date is also specified. See the DD EXPDT or RETPD parameters.

If the system retrieves volume information from the catalog because the DD statement does not specify VOLUME=SER or VOLUME=REF, then DELETE implies UNCATLG: the system deletes the data set and removes its catalog entry.

For a cataloged, passed data set, the user catalog is not updated.

KEEP
Indicates that the data set is to be kept on the volume if this step terminates abnormally. Without SMS, only KEEP is valid for VSAM data sets. VSAM data sets should not be passed, cataloged, uncataloged, or deleted. With SMS, all dispositions are valid for VSAM data sets; however, UNCATLG is ignored. For new SMS-managed data sets, KEEP implies CATLG.

CATLG
Indicates that, if the step terminates abnormally, the system is to place an entry pointing to the data set in the system or user catalog. For CVOL catalogs, the system creates any missing index levels. Note that the data set is kept.

An unopened tape data set is cataloged, unless the volume request is nonspecific or unless the data set is allocated to a dual-density tape drive but no density is specified.

For a cataloged, passed data set, the user catalog is not updated. A passed, not received data set is not cataloged if the data set name has a first-level qualifier of a catalog name or alias.

UNCATLG
Indicates that, if this step terminates abnormally, the system is to delete (1) the entry pointing to the data set in the system or user catalog and (2) unneeded indexes, except for the highest level entry. Note that the data set is kept.

For a cataloged, passed data set, the user catalog is not updated. With SMS, UNCATLG is ignored for SMS-managed data sets and VSAM data sets (KEEP is implied).

3.Defaults

  • If you omit the status subparameter, the default is NEW.
  • If you omit the normal termination disposition subparameter, the default is DELETE for a NEW data set or KEEP for an existing data set.
  • If you omit the abnormal termination disposition subparameter, the default is the disposition specified or implied by the second subparameter. However, if the second subparameter specified PASS, the default abnormal termination disposition is DELETE for a NEW data set or KEEP for an existing data set.
  • If you omit the DISP parameter, the default is a NEW data set with a disposition of DELETE for both normal and abnormal termination disposition. Thus, you can omit the DISP parameter for a data set that is created and deleted during a step.

4.Relationship to Other Parameters
Do not code the following parameters with the DISP parameter.

*         DDNAME    SYSOUT
BURST     DYNAM
CHARS     FLASH
COPIES    MODIFY
DATA      QNAME

5.Disposition of QSAM Data Sets
Do not code DISP=MOD if the data control block (DCB) specifies RECFM=FBS and the data set is processed by QSAM. If you do and a block is shorter than the specified block size, QSAM assumes that the short block is the last block and starts end-of-file processing. By this action, QSAM can embed short blocks in your data set and so affect the number of records per track.

6.Disposition of Temporary Data Sets
Specify a normal termination disposition of PASS or DELETE for a temporary data set or for a data set with a system-generated name, that is, when a DSNAME parameter is omitted from the DD statement.

For a temporary data set name, the system ignores any abnormal termination disposition specified in the third subparameter and always PASSes the data set to subsequent steps.

7.Disposition of Partitioned Data Sets (PDSs and PDSEs)
When you specify DISP=MOD or DISP=NEW for a partitioned data set (PDS) or partitioned data set extended (PDSE), and you also specify a member name in the DSNAME parameter, the member name must not already exist. If the member name already exists, the system terminates the job.

When you specify DISP=OLD for a PDS or a PDSE, and you also specify a member name in the DSNAME parameter, the data set must already exist. If the member name already exists and the data set is opened for output, the system replaces the existing member with the new member. If the member name does not already exist and the data set is opened for output, the system adds the member to the data set.

When you specify DISP=MOD for a PDS or a PDSE, and you do not specify a member name, the system positions the read/write mechanism at the end of the data set. The system does not make an automatic entry into the directory.

When you specify DISP=MOD for a PDS or a PDSE, and you do specify a member name, the system positions the read/write mechanism at the end of the data set. If the member name already exists, the system terminates the job.

When you specify DISP=SHR for a partitioned data set extended (PDSE) and also specify a member name, then:

  • If the member name exists, the member can have one writer or be shared by multiple readers, or
  • If the member name does not exist, the member can be added to the data set. Thus, multiple jobs can access different members of the data set and add new members to the data set concurrently — but concurrent update access to a specific member (or update and read by other jobs) is not valid.

8.Adding a Volume to a Cataloged Data Set
If you want to add a volume to a cataloged data set and have it properly cataloged after it is kept or passed, code the volume count subparameter of the VOLUME parameter to make the system use the values in the system catalog to process the data set. The following DD statement shows how to keep and extend a cataloged data set using the system catalog. Assume that this data set was created with a volume count of 2.

//DDEX2   DD    DSNAME=OPER.DATA,DISP=(MOD,KEEP),
//              VOLUME=(,,,3),UNIT=(,P)

The VOLUME parameter references the system catalog for volume information about the data set and increases the maximum number of volumes for OPER.DATA. Because the UNIT parameter requests parallel mounting, the system must allocate the same number of units as the number of volumes in the VOLUME parameter; in this case, 3.

The following is an example of the messages in the job log after the job completes.

IEF285I    OPER.DATA                              KEPT
IEF285I    VOL SER NOS= 333001,333002,333003.
IEF285I    OPER.DATA                              RECATALOGED
IEF285I    VOL SER NOS= 333001,333002,333003.

Non-SMS-managed Data Sets
If you do not reference the catalog when adding a volume to a cataloged data set, the system does not update the catalog with the newly referenced volumes.

9.DISP=MOD for a Multivolume Data Set

Minimizing Tape Mounts
When you code DISP=MOD and the volume information is for a multivolume data set, normally the first volume(s) will be mounted on the devices(s) allocated. Then, if the data set is opened for output, OPEN starts with the last volume. If the number of tape volumes is more than the number of allocated devices, the system asks the operator to demount the first volume(s) and mount the last. To have the last tape volume mounted without first mounting and then demounting the earlier volume(s), code VOLUME=REF or DEFER in the UNIT parameter, or a volume sequence number in the VOLUME parameter.

Determining the Last Volume
If a data set that is not a striped data set resides on multiple volumes, you can code a volume sequence number to specify the volume on which reading or writing is to begin. If you do not code a volume sequence number and the data set is not striped, the system must identify the volume that contains the logical end of the data. Data might not have been written on all the volumes. After the system identifies the last volume, it positions the read/write mechanism on that volume.

In DASD and tape data set labels there is an indicator on the last volume containing user data. When you do not specify a volume sequence number, the system looks in the data set label for the indicator that identifies the last volume, and then selects the volume on which to begin writing as follows:

a.SMS-managed DASD
The system tests the data set label on the first volume in the list. If the label indicates it contains the end of the data set, the system selects that volume. Otherwise, it checks each subsequent volume until it finds one that has a last-volume indicator. (To begin writing, the system will not select later volumes that might also have the last-volume indicator by virtue of having previously contained parts of the data set.)

b.Non-SMS-managed DASD
The system tests the last volume in the list. If it contains a label for the data set, and the label indicates it is the last volume of the data set, the system selects that volume to begin writing. If that volume does not have a label for the data set or that label does not have the last-volume indicator, the system checks the first and subsequent volumes until it finds a last-volume indicator or until it tests the second-to-last volume. If the last volume in the list once had the end of the data set but now the data set requires fewer volumes, the system selects the wrong volume, and any data you add will not be retrievable by normal access.

c.Tape
For tapes with IBM standard or ANSI/ISO/FIPS labels, the system reads trailer labels on each volume starting with the first volume, and selects the first volume that ends with an end-of-file label instead of an end-of-volume label. For unlabeled tapes and those with the BLP option, the system selects the first volume.

Extending on a Volume Other Than the Last
When you code DISP=MOD for a multivolume data set, use the volume count and volume sequence number subparameters of the VOLUME parameter if you want to keep the system from positioning the read/write mechanism after the last record on the last volume. For example:

//DDEX1   DD   DSNAME=OPER.DATA,DISP=(MOD,KEEP),VOLUME=(,,1,2)

The volume sequence number of 1 specifies that you want to use the first volume, and the volume count of 2 specifies that the data set requires two volumes.

Effect of DCB=dsname Parameter
If the DCB parameter refers to a cataloged data set, the system obtains the volume sequence number from the label of the data set, unless the volume sequence number is coded on the DD statement.

Thus, for the following DD statement, even though DISP=MOD is specified, the system positions the read/write mechanism after the last record on the volume specified in the volume sequence number in the label; this volume may or may not be the last volume.

//DD1     DD    DSNAME=MULTI1,DISP=MOD,DCB=CATDD

To control which volume is processed, code a volume sequence number.

//DD2     DD    DSNAME=MULTI2,DISP=MOD,DCB=CATDD,VOLUME=(,,2)

10.Summary of Disposition Processing

Table: Summary of Disposition Processing

11.Examples of the DISP Parameter

Example 

//DD2     DD    DSNAME=FIX,UNIT=3420-1,VOLUME=SER=44889,
//              DISP=(OLD,,DELETE)

DD statement DD2 defines an existing data set and implies by the omitted second subparameter that the data set is to be kept if the step terminates normally. The statement requests that the system delete the data set if the step terminates abnormally.

Example 

//STEPA   EXEC   PGM=FILL
//DD1     DD     DSNAME=SWITCH.LEVEL18.GROUP12,UNIT=3350,
//        VOLUME=SER=LOCAT3,SPACE=(TRK,(80,15)),DISP=(,PASS)
//STEPB   EXEC   PGM=CHAR
//DD2     DD     DSNAME=XTRA,DISP=OLD
//DD3     DD     DSNAME=*.STEPA.DD1,DISP=(OLD,PASS,DELETE)
//STEPC   EXEC   PGM=TERM
//DD4     DD     DSNAME=*.STEPB.DD3,DISP=(OLD,CATLG,DELETE)

DD statement DD1 defines a new data set and requests that the data set be passed. If STEPA abnormally terminates, the data set is deleted because it is a new data set, the second subparameter is PASS, and an abnormal termination disposition is not coded.

DD statement DD3 in STEPB receives this passed data set and requests that the data set be passed. If STEPB abnormally terminates, the data set is deleted because of the third subparameter of DELETE.

DD statement DD4 in STEPC receives the passed data set and requests that the data set be cataloged at the end of the step. If STEPC abnormally terminates, the data set is deleted because of the abnormal termination disposition of DELETE.

DD statement DD2 defines an old data set named XTRA. When STEPB terminates, normally or abnormally, this data set is kept.

Example 

//SMSDD5   DD    DSNAME=MYDS5.PGM,DATACLAS=DCLAS05,STORCLAS=SCLAS05,
//               DISP=(NEW,KEEP)

DD statement SMSDD5 defines a new SMS-managed data set and requests that the data set be kept (which implies that it be cataloged).

Example 

//SMSDD7 DD DSNAME=MYDS7.PGM,DISP=(OLD,UNCATLG)

DD statement SMSDD7 defines an existing SMS-managed data set (the data set had been assigned a storage class when it was created) and requests that the data set be uncataloged. However, the data set is kept because UNCATLG is ignored for SMS-managed data sets.

DLM parameter

Parameter Type

Keyword, optional

Purpose
Use the DLM parameter to specify a delimiter to terminate this in-stream data set. When the DLM parameter assigns a different delimiter, the in-stream data records can include standard delimiters, such as /* and //, in the data.

In a JES2 system, when the DLM delimiter appears on a DD * statement, either the assigned delimiter or // ends the input data set. When the DLM delimiter appears on a DD DATA statement, only the assigned delimiter ends the input data set.

In a JES3 system, when the DLM delimiter appears on either a DD * or DD DATA statement, only the assigned delimiter ends the input data set.

Note: When the DLM delimiter overrides any implied delimiter, you must terminate the data with the DLM characters. Otherwise, the system keeps reading until the reader is empty.

Except for the JES2 /*SIGNON and /*SIGNOFF statements, the system does not recognize JES2 and JES3 statements in an input stream between the DLM parameter and the delimiter it assigns. The JES2 /*SIGNON and /*SIGNOFF statements are processed by the remote work station regardless of any DLM delimiter.

Considerations for an APPC Scheduling Environment
The DLM parameter has no function in an APPC scheduling environment. If you code DLM, the system will check it for syntax and ignore it.

1.Syntax

DLM=delimiter
  • If the specified delimiter contains any special characters, enclose it in apostrophes. In thiscase, a special character is any character that is neither alphanumeric nor national ($, #, @). Failing to code enclosing apostrophes produces unpredictable results.
  • If the delimiter contains an ampersand or an apostrophe, code each ampersand or apostrophe as two consecutive ampersands or apostrophes. Each pair of consecutive ampersands or apostrophes counts as one character.
  • The DLM parameter can have a null value only when coded on a DD which either:
  • – Overrides a DD in a procedure
    – Is added to a procedure.

2.Subparameter Definition

delimiter
Specifies two characters that indicate the end of this data set in the input stream.

3.Default
If you do not specify a DLM parameter, the default is the /* delimiter statement. If the system finds an error on the DD statement before the DLM parameter, it does not recognize the value assigned as a delimiter. The system reads records until it reads a record beginning with /* or //.

4.Relationship to Other Parameters
Code the DLM parameter only on a DD statement with the * or DATA parameter. The DLM parameter has meaning only on statements defining data in the input stream, that is, DD * and DD DATA statements. If DLM is specified on any other statement, a JCL error message is issued.

5.Invalid Delimiters
If the delimiter is not two characters:

  • For JES2, the delimiter is not recognized. The in-stream data set is terminated when a record starting with // or /* is read. The system fails the job due to the invalid delimiter.
  • For JES3, if an incorrect number of characters is coded, JES3 terminates the job.

6.Example of the DLM Parameter

//DD1   DD   *,DLM=AA
        .
        .
        data
        .
AA

The DLM parameter assigns the characters AA as the delimiter for the data defined in the input stream by DD statement DD1. For JES2, the characters // would also serve as valid delimiters since a DD * statement was used. JES3 accepts only the characters specified for the DLM parameter as a terminator for DD * or DD DATA.

DSID parameter

Parameter Type

Keyword, optional

Purpose
Use the DSID parameter to specify the data set identifier of an input or output data set on a diskette of the 3540 Diskette Input/Output Unit.

An input data set is read from a 3540 diskette by a diskette reader program, and an output data set is written on a 3540 diskette by a diskette writer, which is an external writer.

To read a data set from a 3540 diskette, the DD statement must contain:

  • A DSID parameter.
  • An * or DATA parameter, to begin the input stream data set.

To write a data set on a 3540 diskette, the DD statement must contain:

  • A DSID parameter.
  • A SYSOUT parameter that specifies the output class that the diskette writer processes and the name of the diskette writer.

Also, a system command, from the operator or in the input stream, must start the diskette writer before this DD statement is processed.

Note: The system ignores the DSID parameter on a DD *, DD DATA, or a DD statement with the SYSOUT parameter, except when a diskette reader or writer processes the JCL.

1..Syntax

DSID= {id }
      {(id,[V])}
  • You can omit the parentheses if you code only an id.
  • Null positions in the DSID parameter are invalid.

2.Subparameter Definition

id Specifies the data set identifier. The id is 1 through 8 characters. The characters must be alphanumeric, national ($, #, @), a hyphen, or a left bracket. The first character must be alphabetic or national ($, #, @).

V Indicates that the data set label must have been previously verified on a 3741 Data Station/Workstation. This subparameter is required only on a SYSIN DD statement.

3.Relationship to Other Parameters
Do not code the following parameters with the DSID parameter.

BURST    FLASH
CHARS    MODIFY
DDNAME   MVSGP
DYNAM    QNAME

For 3540 Diskette Input/Output Units
A DSID parameter on a DD *, DD DATA, or sysout DD statement is ignored except when detected by a diskette reader as a request for an associated data set. On a DD * or DD DATA statement processed by a diskette reader, you can specify DSID, VOLUME=SER, BUFNO, and LRECL to indicate that a diskette data set is to be merged into the input stream following the DD statement.

4.Example of the DSID Parameter

//JOB1       JOB    ,,MSGLEVEL=(1,1)
//STEP       EXEC   PGM=AION
//SYSIN      DD     *,DSID=(ABLE,V),VOLUME=SER=123456,
//                  DCB=LRECL=80
//SYSPRINT   DD    SYSOUT=E,DCB=LRECL=128,DSID=BAKER

In this example, the SYSIN DD statement indicates that the input is on diskette 123456 in data set ABLE and must have been verified. The output will be written on a diskette in data set BAKER.

DSNAME parameter 

Parameter Type

Keyword, optional

Purpose

Use the DSNAME parameter to specify the name of a data set. For a new data set, the specified name is assigned to the data set; for an existing data set, the system uses the name to locate the data set.

1.Syntax

{DSNAME} =name
DSN }

name for permanent data set:

dsname
dsname(member)
dsname(generation)
dsname(area)

name for temporary data set:

&&dsname&&dsname(member)&&dsname(area)

name for in-stream or sysout data set:

&&dsname

name copied from earlier DD statement:

*.ddname
*.stepname.ddname
*.stepname.procstepname.ddname

name for dummy data set:

NULLFILE
  • You can abbreviate DSNAME as DSN.
  • Avoid starting a data set name with JES or SYS1. The system uses these characters for system data sets.
  • If the data set name begins with a blank character, the system assigns the data set with a unique temporary data set name, and ignores the name specified on the DSNAME parameter
  • The system ignores blank characters at the end of a data set name.
  • Blanks can be included in a data set name if the name is enclosed in apostrophes, such as DSNAME='AB CD'. However, do not code blanks in the name for an in-stream or sysout data set; for example, SYSOUT=P,DSNAME='&&AB CD' is not valid.
  • If the data set is to be managed through SMS, you cannot enclose the data set name in apostrophes. However, the following exception applies: You can enclose the data set name on the DSNAME parameter in apostrophes if the data set is to be assigned to, or already resides on, an SMS-managed mountable tape volume. This exception applies only if DFSMS/MVS 1.1 or later is installed.
  • Any data set name enclosed in apostrophes on the DSNAME parameter will be treated as an unqualified name. Data sets with an unqualified name cannot be cataloged.
  • The system does not check data set names enclosed in apostrophes for valid characters or valid length. When SMS is not installed or active incorrect characters or length result in data set allocation, but the data set is not cataloged. When SMS is active, it will fail the job for incorrect characters or length.

Non-Significant Special Characters:strong> When a data set name contains special characters that are not significant to the system, other than hyphens, enclose it in apostrophes. For example, DSNAME='DS/29'.

Code each apostrophe that is part of the data set name as two consecutive apostrophes.For example, code DAYS'END as DSNAME='DAYS''END'.

The system ignores blank characters at the end of a data set name, even if the data set name is enclosed in apostrophes.

Significant Special Characters: The following special characters are significant to the system. Do not enclose them in apostrophes.

  • Periods to indicate a qualified data set name. However, you must enclose in apostrophes a period immediately before a right parenthesis, immediately after a left parenthesis, or immediately before a comma; for example, DSNAME='(.ABC)' and DSNAME='(ABC.)' and DSNAME='A.B.C.'.
  • Double ampersands to identify a temporary data set name. Note that if you use apostrophes, DSNAME='&&AB' and DSNAME='&AB' refer to the same data set.
  • Double ampersands to identify an in-stream or sysout data set name.
  • Parentheses to enclose the member name of a partitioned data set (PDS) or partitioned data set extended (PDSE), the area name of an indexed sequential data set, or thegeneration number of a generation data set.
  • Plus (+) or minus (-) sign to identify a generation of a generation data group.
  • The asterisk to indicate a backward reference.

On a DD statement in a cataloged or in-stream procedure, if the data set name is a symbolic parameter, do not enclose it in apostrophes. If it is enclosed in apostrophes, the system performs correct substitution only if the symbolic parameter enclosed in apostrophes is preceded by a symbolic parameter not enclosed in apostrophes.

The data set name should not contain the 44 special characters (X'04') created by the 12-4-9 multiple punch or any operation that converts the value of characters to X'04'.

2.Subparameter Definition
The data set names you specify on DSNAME are described in the following topics:

  • Data Set Name for Permanent Data Set
  • Data Set Name for Temporary Data Set
  • Data Set Name for In-Stream or Sysout Data Set
  • Data Set Name Copied from Earlier DD Statement
  • Data Set Name for Dummy Data Set

Data Set Name for Permanent Data Set
Assign a permanent data set either an unqualified or a qualified name:

Unqualified Name
1 through 8 alphanumeric or national ($, #, @) characters, a hyphen, or a character X'C0'. The first character must be alphabetic or national ($, #, @). For example, DSNAME=ALPHA is an unqualified data set name.

Qualified Name
Multiple unqualified names joined by periods. Each qualifier is coded like an unqualified name; therefore, the name must contain a period after every 8 characters or fewer. For example, DSNAME=ALPHA.PGM is a qualified data set name. The maximum length of a qualified data set name is:

  • 44 characters, including periods.
  • For a generation data group, 35 characters, including periods.
  • For an output tape data set, 17 characters, including periods. If longer than 17 characters, only the rightmost 17 characters, excluding trailing blanks, are written to the tape header label.

Name for RACF-Protected Data Set
The OS/390 Security Server, which includes RACF, expects the data set name to have a high-level qualifier that is defined to RACF. RACF uses the entire data set name, from 1 through 44 characters, when protecting a tape data set.

dsname
Specifies a data set name.

dsname(member)
Specifies the name of the permanent partitioned data set (PDS) or the partitioned data set extended (PDSE), and the name of a member within that data set. If the member does not exist and DISP=OLD or DISP=SHR is specified, the allocation will succeed, but the job will fail when the data set is opened for input. If the member does not exist and the data set is opened for output, the system will add the member to the data set.

member
1 to 8 alphanumeric or national characters, or a character X'C0'. The first character must be alphabetic, national, +, or −. If the first character is + or −, the member is a part of a generation data group.

dsname(generation)
Specifies the name of a generation data group (GDG) and the generation number (zero or a signed integer) of a generation data set within the GDG.

Note: A VSAM data set cannot be a generation data set.

generation

  • The first character of a relative generation number is +, −, or 0.
  • All characters of a relative generation number that follow the +, −, or 0 must be numeric (0 through 9).
  • The numeric portion (not + or −) of a relative generation number must be expressed in 1 to 3 numeric characters. For example, +100, −002, +4, −09, 000.
  • A relative generation number cannot exceed 255.

To retrieve all generations of a generation data group, omit the generation number.

dsname(area)
Specifies the name of a permanent indexed sequential data set and an area of the data set. The area-name is INDEX, PRIME, or OVFLOW. If you define an indexed sequential data set on only one DD statement, omit the area name or code it as PRIME. For example, DSNAME=dsname or DSNAME=dsname(PRIME).

To retrieve an indexed sequential data set, omit the area name.

Data Set Name for Temporary Data Set
A temporary data set is a data set that you create and delete within a job. (For information about coding data set names with the DD *, DATA, and SYSOUT parameters, see ²Data Set Name for In-Stream or Sysout Data Set.²)

Note: SMS manages a temporary data set if you specify a storage class (with the DD STORCLAS parameter) or if an installation-written automatic class selection (ACS) routine selects a storage class for the temporary data set.

When you define a temporary data set, you can code the DSNAME parameter or omit it; in either case, the system generates a qualified name for the temporary data set.

When you use DSNAME for a temporary data set, code the name as two ampersands (&&) followed by a character string 1 to 8 characters in length:

  • The first character following the ampersands must be alphabetic or national.
  • The remaining characters must be alphanumeric or national.

The format of the qualified name the system generates depends on whether or not you specified a data set name on the DSNAME parameter:

  • All temporary data set names begin as follows:
SYSyyddd.Thhmmss.RA000.jjobname

where:
yy indicates the year
ddd indicates the Julian day
hh indicates the hour
mm indicates the minute
ss indicates the second
jjobname indicates the name of the job

Date fields in the system-generated name reflect when the job containing the request (or the dynamic allocation request) was allocated. Time fields in the system-generated name reflect when the job started (or the time of a dynamic allocation request).

  • If you do not specify a data set name, the full format of the temporary data set name is:
SYSyyddd.Thhmmss.RA000.jjobname.Rggnnnnn

where:
gg 01 or, in a sysplex, the system identifier
nnnnn a number that is unique within a system

  • If you do specify a data set name, the full format of the temporary data set name is:
SYSyyddd.Thhmmss.RA000.jjobname.name.Hgg

where:
name the name you specified as &&name on the DSNAME parameter
gg 01 or, in a sysplex, the system identifier.

If you use DSNAME, note that the system-generated qualified name for the temporary data set will not be unique under the following conditions:

  • Multiple tasks or APPC transactions having identical jobnames execute at exactly the same time, and
  • The tasks or transactions contain DD statements with identical temporary data set names.

To ensure that a temporary data set name is unique, do not code a temporary data set name. Allow the system to assign one.

Only the job that creates a temporary data set has access to it to read and write data and to scratch the data set.

Note: In general, the system treats a single ampersand (&) followed by a character string of 1 to 8 characters as a symbolic parameter. However, if you code a data set name as a symbolic parameter (by coding DSNAME=&xxxxxxxx), and do not assign a value to or nullify the symbolic parameter, the system will process it as a temporary data set name.

&&dsname
Specifies the name of a temporary data set.

&&dsname(member)
Specifies the name of a temporary partitioned data set (PDS) or partitioned data set extended (PDSE) and a member within that data set.

member
1 - 8 alphanumeric or national characters, or a character X'C0'. The first character must be alphabetic or national.

&&dsname(area)
Specifies the name of a temporary indexed sequential data set and an area of the data set. The area name is INDEX, PRIME, or OVFLOW. If you define an indexed sequential data set on only one DD statement, omit the area name or code it as PRIME. For example, DSNAME=&&dsname or DSNAME=&&dsname(PRIME).

Data Set Name for In-Stream or Sysout Data Set
Use the DSNAME parameter to assign a data set name to an in-stream data set (defined with the DD * or DD DATA parameter) and to a sysout data set (defined with the DD SYSOUT parameter). When defining an in-stream or sysout data set, you can code the DSNAME parameter or omit it; if omitted, the system generates a name for the data set.

The data set name for in-stream and sysout data sets consists of two ampersands (&&) followed by one through eight 8 alphanumeric or national ($, #, @,) characters, a hyphen, or a character X'C0'. The first character following the ampersands must be alphabetic or national ($, #, @).

The system generates a qualified name for the in-stream or sysout data set. The qualified name contains:

  • The userid of the job
  • The jobname
  • The jobid
  • A system-assigned identifier
  • The data set name from the DSNAME parameter (if DSNAME is coded), or a question mark (?) if DSNAME is not coded.

The format of the name is:

userid.jobname.jobid.Ddsnumber.name

where name is the dsname or a question mark (?).

When the system checks a user’s authority to access a SYSOUT data set, the check is made against the JESSPOOL class using the fully qualified name, preceded by the node name and a period:

nodename.userid.jobname.jobid.Ddsnumber.name

Profiles of this format may be defined in your security system to allow other users access to your SYSOUT data sets. A profile is not necessary for you to access your own data sets.

Note: A single ampersand before a data set name in a cataloged or in-stream procedure signifies a symbolic parameter. However, if no value is assigned to the name on either the EXEC statement that calls the procedure, a PROC statement in the procedure, or a previous SET statement, the system treats the name as the last qualifier of the data set name for an in-stream or sysout data set.

&&dsname
Specifies the last qualifier of the system-generated data set name for an in-stream or sysout data set.

Data Set Name Copied from Earlier DD Statement
A backward reference is a reference to an earlier statement in the job or in a cataloged or in-stream procedure called by this or an earlier job step. A backward reference can be coded in the DSNAME parameter to copy a data set name from an earlier DD statement.

When copying the data set name, the system also copies the following from the DD statement:

  • Whether or not the data set is a PDS or a PDSE.
  • Whether or not the data set is a temporary data set.

*.ddname
Asks the system to copy the data set name from earlier DD statement ddname.

*.stepname.ddname
Asks the system to copy the data set name from DD statement, ddname, in an earlier step, stepname, in the same job.

*.stepname.procstepname.ddname
Asks the system to copy the data set name from a DD statement in a cataloged or in-stream procedure. Stepname is the name of this job step or an earlier job step that calls the procedure, procstepname is the name of the procedure step that contains the DD statement, and ddname is the name of the DD statement.

Data Set Name for Dummy Data Set

NULLFILE
Specifies a dummy data set. NULLFILE has the same effect as coding the DD DUMMY parameter. NULLFILE must be coded as a single-word parameter. For instance, IBM does not support the use of NULLFILE to obtain a dummy data set for these (or other) formats:

  • When followed by a member name
  • As a qualifier in a qualified data set name
  • As a temporary data set name.

3.Relationship to Other Parameters
Do not code the following parameters with the DSNAME parameter.

DDNAME
DYNAM
QNAME

Do not code the DCB IPLTXID subparameter with the DSNAME parameter.

Reserved Data Set Names

Do not code the following data set names on the DSNAME parameter with the *, DATA, or SYSOUT parameter (an in-stream or sysout data set); the names are reserved for system use.

JESJCL      JESMSGLG
JESJCLIN    JESYSMSG

With DD AMP Parameter
When you code an AMP parameter for a VSAM data set, do not code a DSNAME:

  • That contains parentheses, a minus (hyphen), or a plus (+) sign.
  • That is in the form for ISAM.
  • That is in the form for PAM (partitioned access method).
  • That names a generation data group.

With DD DISP Parameter
You can create a permanent data set by specifying a qualified or unqualified data set name, the disposition must be other than DELETE. The following example illustrates how to create a permanent data set:

//REPORT    DD    DSN=DEHART.APAR.REPORT,SPACE=(CYL,(5,5)),
//                DISP=(NEW,CATLG),UNIT=SYSALLDA,
//                DCB=(LRECL=121,RECFM=FBA,BLKSIZE=1210)

You can create a temporary data set by specifying a:

  • &&dsname or by omitting the DSNAME parameter
  • Qualified or unqualified data set name and specifying, either explicitly or implicitly, DISP=(NEW,DELETE).

The following two examples illustrate how to create a temporary data set:

//MYDD1      DD     DSN=TEMP1,UNIT=3480,DISP=(,DELETE),SPACE=(TRK,(1,1))
//DD2        DD     UNIT=SYSALLDA,SPACE=(TRK,1),DISP=(NEW,PASS)

Note: When you code a disposition of CATLG for a data set, do not code a DSNAME name in apostrophes.

4.Examples of the DSNAME Parameter

Example 

//DD1       DD      DSNAME=ALPHA,DISP=(,KEEP),
//                 UNIT=3420,VOLUME=SER=389984

DD statement DD1 defines a new data set and names it ALPHA. DD statements in later job steps or jobs may retrieve this data set by specifying ALPHA in the DSNAME parameter, unit information in the UNIT parameter, and volume information in the VOLUME parameter.

Example 

//DDSMS1    DD     DSNAME=ALPHA.PGM,DISP=(NEW,KEEP),DATACLAS=DCLAS1,
//                 MGMTCLAS=MCLAS1,STORCLAS=SCLAS1

DD statement DDSMS1 defines a new SMS-managed data set and names it ALPHA.PGM. DD statements in later job steps or jobs may retrieve this data set by specifying ALPHA.PGM in the DSNAME parameter.

Example 

//DD2    DD    DSNAME=LIB1(PROG12),DISP=(OLD,KEEP),UNIT=3350
//             VOLUME=SER=882234

DD statement DD2 retrieves member PROG12 from the partitioned data set named LIB1.

Example 

//DDIN DD DATA,DSNAME=&&PAYIN1
          .
          data
          .
/*

DD statement DDIN defines PAYIN1 as the last qualifier of the system-generated data set name for the in-stream data set. This generates a data set name such as userid.jobname.jobid.Ddsnumber.PAYIN1.

Example 

//DDOUT     DD      DSNAME=&&PAYOUT1,SYSOUT=P

DD statement DDOUT defines PAYOUT1 as the last qualifier of the system-generated data set name for the sysout data set. This generates a data set name such as userid.jobname.jobid.Ddsnumber.PAYOUT1.

Example 

//DD3       DD      DSNAME=&&WORK,UNIT=3420

DD statement DD3 defines a temporary data set. Because the data set is deleted at the end of the job step, the DSNAME parameter can be omitted. The following example shows why a temporary data set should be named.

Example 

//STEP1    EXEC     PGM=CREATE
//DD4      DD       DSNAME=&&ISDATA(PRIME),DISP=(,PASS),UNIT=(3350,2),
//         VOLUME=SER=334859,SPACE=(CYL,(10,,2),,CONTIG),DCB=DSORG=IS
//STEP2    EXEC     PGM=OPER
//DD5      DD       DSNAME=*.STEP1.DD4,DISP=(OLD,DELETE)

DD statement DD4 in STEP1 defines a temporary indexed sequential data set named ISDATA. This DD statement defines all of the areas of an indexed sequential data set. DD statement DD5 in STEP2 retrieves the data set by referring to the earlier DD statement that defines the data set. Because the temporary data set is passed when it is defined in STEP1, it is not deleted at the end of STEP1 and STEP2 can retrieve it.

DSNTYPE parameter

Parameter Type

Keyword, optional — use this parameter only with DFSMS/MVS

Purpose

Use the DSNTYPE parameter to specify:

  • A new partitioned data set (PDS)
  • A new partitioned data set extended (PDSE), which is also called a library
  • A new hierarchical file system (HFS) data set
  • A first-in first-out (FIFO) special file, which is also called a named pipe

Also use the DSNTYPE parameter to override the DSNTYPE attribute defined in the data class of the partitioned data set or PDSE.

Serialization of the data set can exist at both the data set (library) level and the member level. If you specify DISP=SHR on the DD statement for a PDSE, sharing of the data set applies to the data set and the individual member specified. Multiple jobs can access different members of the data set and create new members of the data set concurrently. However, concurrent update access to a specific member (or update and read by other jobs) is not allowed. Dispositions of DISP=OLD, NEW, or MOD result in exclusive use of the entire data set. A PDSE can be created through the BPAM, BSAM, and QSAM access methods.

If DFSMS is not installed or is not active, the system checks the syntax and then ignores the DSNTYPE parameter.

Before you define a PDSE, check with your storage administrator to ensure that SMS is able to manage the data set and assign the PDSE to a storage class.

An HFS data set is a data set used by z/OS UNIX System Services (z/OS UNIX) programs. It contains a mountable file system. It is a partitioned format data set, similar to a PDSE. A FIFO special file is a type of file with the property that data written to such a file is read on a first-in-first-out basis.

A FIFO special file defined in a DD statement provides a connection filled with data among programs. One or more programs can write data into the file; one or more programs can read the data.

1.Syntax

DSNTYPE= {LIBRARY}
         {HFS }
         {PDS }
         {PIPE }  

2.Subparameter Definition

LIBRARY
Specifies a DFSMS-managed partitioned data set extended (PDSE). A PDSE can contain data and problem object members.

HFS
Specifies an HFS data set. Specify HFS only when the DD statement also specifies a DSNAME parameter.

PDS
Specifies a partitioned data set (PDS). A PDS can contain data and load module members.

PIPE
Specifies a FIFO special file. Specify PIPE only when the DD statement also specifies a PATH parameter.

3.Defaults
If you do not specify DSNTYPE, the type of data set is determined by other data set attributes, the data class for the data set, or an installation default. DSNTYPE cannot default to HFS or PIPE. You must explicitly specify these attributes.

4.Overrides
DSNTYPE overrides the DSNTYPE attribute in the DATACLAS parameter for the data set.

5.Relationship to Other Parameters
Do not code the following DD parameters with the DSNTYPE parameter.

*       DDNAME
AMP     DYNAM
DATA    QNAME
RECORG

6.Examples of the DSNTYPE Parameter

Example 

//NEWPDSE      DD     DSNAME=FILEA.ABC(REC1),DISP=(NEW,KEEP)

In the example, the NEWPDSE DD statement defines member REC1 in the new PDSE named FILEA.ABC. Note that installation-written ACS routines select the data class (which specifies LIBRARY for DSNTYPE), management class, and storage class for the data set.

Example 

//NEWA      DD     DSNAME=REPORT.ONE(WEEK1),DISP=(NEW,KEEP),
//          DATACLAS=DCLAS09,DSNTYPE=LIBRARY

In the example, the NEWA DD statement defines member WEEK1 in the new PDSE named REPORT.ONE. DSNTYPE=LIBRARY overrides the DSNTYPE attribute in data class DCLAS09 but uses other data set attributes in DCLAS09. Note that installation-written ACS routines select the management class and storage class for the data set.

Example 

//NEWB     DD     DSNAME=REPORT.TWO(WEEK2),DISP=SHR,
//         DATACLAS=DCLAS09,DSNTYPE=LIBRARY

In the example, the NEWB DD statement adds a new member named WEEK2 to the existing PDSE named REPORT.ONE. DSNTYPE=LIBRARY overrides the DSNTYPE attribute in data class DCLAS09 but uses other data set attributes in DCLAS09. Other jobs can be concurrently processing existing members of PDSE named REPORT. Note that installation-written ACS routines select the management class and storage class for the data set.

Example 

//FILESYS   DD   DSNAME=OPENDS.USRJOE,DATACLAS=DCLAS05,DISP=(NEW,KEEP),
//          DSNTYPE=HFS,SPACE=(CYL,(100,100,1))

The FILESYS DD statement creates an HFS data set to contain an HFS file system. The DCLAS05 in DATACLAS specifies allocation characteristics. The number of directory blocks must be specified to indicate that this is an HFS data set but the value has no effect on allocation.

Example 

//PIPE    DD    PATH=’/u/payroll/buffer’,DSNTYPE=PIPE,
//        PATHOPTS=(OWRONLY,OEXCL,OCREAT),PATHMODE=(SIWUSR,SIRGRP),
//        PATHDISP=(KEEP,DELETE)

The PIPE DD statement creates a file named /u/payroll/buffer for use as a FIFO special file. The PATHOPTS parameter specifies that the user intends that the program open the FIFO special file for writing. The PATHMODE parameter specifies that the file owner can write in the FIFO special file and that users in the file group class can read from the FIFO special file. The PATHDISP parameter requests that the file be kept when the program ends normally and deleted when it ends abnormally.

Pathnames are case-sensitive. If you are specifying a pathname containing a special character, including a lowercase character, enclose it in apostrophes.

DUMMY parameter

Parameter Type

Positional, optional

Purpose

Use the DUMMY parameter to specify that:

  • No device or external storage space is to be allocated to the data set.
  • No disposition processing is to be performed on the data set.
  • For BSAM and QSAM, no input or output operations are to be performed on the data set.

One use of the DUMMY parameter is in testing a program. When testing is finished and you want input or output operations performed on the data set, replace the DD DUMMY statement with a DD statement that fully defines the data set.

Another use of the DUMMY parameter is in a cataloged or in-stream procedure. Code on the DD DUMMY statement all the required parameters. When the procedure is called, nullify the effects of the DUMMY parameter by coding on the DD statement that overrides the DD DUMMY statement a DSNAME parameter that matches the DSNAME parameter on the DD DUMMY statement. For example, procedure step PS contains the following:

//DS1    DD     DUMMY,DSNAME=A,DISP=OLD

Nullify the DUMMY parameter by coding:

//JS        EXEC   PROC=PROC1
//PS.DS1    DD     DSNAME=A

1.Syntax

//ddname DD DUMMY[,parameter]...

All parameters coded on a DD DUMMY statement must be syntactically correct. The system checks their syntax.

2.Parameters on DD DUMMY Statements

  • Code the DUMMY parameter by itself or follow it with all the parameters you would normally code when defining a data set, except the DDNAME parameter.
  • Code the DCB parameter, if needed. If the program does not supply all the data control block information, make sure that the DCB parameter supplies the missing information.
  • Code AMP=AMORG if you are using VSAM’s ISAM interface.
  • If you code either VOLUME=REF=dsname or DCB=dsname with DUMMY, the referenced dsname must be cataloged or passed; otherwise, the job is terminated.
  • Because no I/O is performed to the dummy data set, the system checks the SPACE and DISP parameters, if coded, for syntax, then ignores them. If you code UNIT with DUMMY, the system will ignore it if the specified unit name is syntactically correct and defined to the system. Otherwise the system terminates the job.

3.Relationship to Other Parameters
Do not code the following parameters with the DUMMY parameter.

*          DYNAM
DATA       QNAME
DDNAME

4.Relationship to Other Control Statements

Backward References
If a later DD statement in a job refers to a DD DUMMY statement when requesting unit affinity (UNIT=AFF=ddname) or volume affinity (VOLUME=REF=*.stepname .ddname), the system assigns a dummy status to the later DD statement.

Overriding a Procedure DD Statement
Coding DUMMY on a DD statement that overrides a DD statement in a procedure does not nullify symbolic parameters on the overridden DD statement. You must assign values to, or nullify, symbolic parameters on the overridden DD statement as described in “Using System Symbols and JCL Symbols”. If the overriding DD statement contains a DSNAME parameter other than NULLFILE, a PATH parameter other than /dev/null, or a SUBSYS, SYSOUT, *, or DATA parameter, the system nullifies a DUMMY parameter on the overridden DD statement.

Note: If you code SYSOUT= on an overriding statement, without specifying a subparameter value, the system does not nullify the DUMMY parameter. You must code a subparameter value for SYSOUT to nullify the DUMMY parameter.

Data Sets Concatenated to Dummy Data Sets
The system treats data sets concatenated to a DUMMY data set as dummy data sets in that I/O operations are bypassed. However, the system performs disposition processing and allocates devices and storage for any concatenated data sets.

5.Relationship to Access Methods
Use one of the following access methods with the DUMMY parameter:

  • Basic sequential access method (BSAM)
  • Virtual storage access method (VSAM)
  • Queued sequential access method (QSAM)
  • BDAM load mode (BSAM with MACRF=WL in the data control block)

If you use any other access method, the job is terminated.

Note: The ISAM/VSAM interface does not support the DUMMY parameter. Using Data Sets.

6.Examples of the DUMMY Parameter

Example 

//OUTDD1  DD  DUMMY,DSNAME=X.X.Z,UNIT=3380, 
//            SPACE=(TRK,(10,2)),DISP=(,CATLG)

DD statement OUTDD1 defines a dummy data set. The other parameters coded on the statement are checked for syntax but not used.

Example 

//IN1     DD   DUMMY,DCB=(BLKSIZE=800,LRECL=400,RECFM=FB)

DD statement IN1 defines a dummy data set. The DCB parameter supplies data control block information not supplied in the program. Without it, the step might be abnormally terminated.

Example 

//IN2    DD   DUMMY,DSNAME=ELLN,DISP=OLD,VOLUME=SER=11257,UNIT=3350

When calling a cataloged procedure that contains DD statement IN2 in procedure step STEP4, you can nullify the effects of the DUMMY parameter by coding:

//STEP4.IN2   DD   DSNAME=ELLN

Example 

//TAB     DD    DSNAME=APP.LEV12,DISP=OLD

If you call a cataloged procedure that contains DD statement TAB in procedure step STEP1, you can make this DD statement define a dummy data set by coding:

//STEP1.TAB  DD   DUMMY

Example 

//MSGS   DD   SYSOUT=A

If you call a cataloged procedure that contains the DD statement MSGS in procedure step LOCK, you can make this DD statement define a dummy data set by coding:

//LOCK.MSGS  DD  DUMMY

DYNAM parameter

Parameter Type

Positional, optional

Purpose
Use the DYNAM parameter to increase by one the control value for dynamically allocated resources held for reuse. Even when DYNAM is not coded, the system normally holds resources in anticipation of reuse. The DYNAM parameter is supported to provide compatibility with older systems.

A DD DYNAM statement is a dummy request.

1.Syntax

//ddname   DD   DYNAM   [comments]

2.Relationship to Other Parameters
Do not code any parameters with the DYNAM parameter.

Do not code on a DD DYNAM statement a ddname that is meaningful to the system; for example, JOBLIB, SYSCHK.

3.Relationship to Other Control Statements

  • Do not refer to a DD DYNAM statement in a DDNAME parameter.
  • To nullify the DYNAM parameter on a DD statement in a cataloged or in-stream procedure, code a SYSOUT or DSNAME parameter in the overriding DD statement. DSNAME=NULLFILE does not nullify a DYNAM parameter.
  • Do not code a backward reference to a DD DYNAM statement.
  • Do not code the DYNAM parameter on the first DD statement for a concatenation.

4.Example of the DYNAM Parameter

//INPUT   DD   DYNAM

This DD statement increases by one the control value for dynamically allocated resources held for reuse.

EXPDT parameter

Parameter Type

Keyword, optional

Purpose

Use the EXPDT parameter to specify the expiration date for a new data set. On and after the expiration date, the data set can be deleted or written over by another data set.

Note: You may specify a past date; this would not be an error condition.

If the DD statement contains DISP=(NEW,DELETE) or the DISP parameter is omitted and defaults to NEW and DELETE, the system deletes the data set when the step terminates, either normally or abnormally, even if you have specified an expiration date.

Do not specify EXPDT for a temporary data set. The EXPDT parameter achieves the same result as the RETPD parameter. Code the EXPDT parameter when you want to specify an expiration date for the data set, or, with SMS, override the expiration date defined in the data class for the data set.

1.Syntax

EXPDT= {yyddd }
       {yyyy/ddd}

The EXPDT parameter can have a null value only when coded on a DD statement that is either added to a procedure or overrides a DD statement in a procedure.

2.Subparameter Definition

EXPDT=yyddd
EXPDT=yyyy/ddd
Specifies an expiration date for the data set.

yyddd
This form of the expiration date specifies a two-digit year number yy (from 00 through 99) and a three-digit day number ddd (from 001 through 365 for a non-leap year date, from 001 through 366 for a leap year date). For example, code February 2, 1999 as EXPDT=99033, and code December 31, 1996 as EXPDT=96366.

Note: For expiration dates of January 1, 2000 and later, you MUST use the form EXPDT=yyyy/ddd.

Note: Expiration dates of 99365 and 99366 are considered “never-scratch” dates. Data sets with these expiration dates are not deleted or written over.

yyyy/ddd
This form of the expiration date specifies a four-digit year number yyyy (from 1900 through 2155) and a three-digit day number ddd (from 001 through 365 for a non-leap year date, from 001 through 366 for a leap year date). For example, code February 2, 1999 as EXPDT=1999/033, and code December 31, 2000 as EXPDT=2000/366.

Note: Expiration dates of 1999/365 and 1999/366 are considered “never-scratch” dates. Data sets with these expiration dates are not deleted or written over. You may specify the years from 1900. However, if you specify the current date or an earlier date, the data set is immediately eligible for replacement.

3.Overrides
With SMS, EXPDT overrides the expiration date defined in the DATACLAS parameter for the data set. With SMS, both the expiration date specified on EXPDT and defined in the data class for an SMS- managed data set can be limited by a maximum expiration date defined in the management class for the data set.

4.Relationship to Other Parameters
Do not code the following DD parameters with the EXPDT parameter.

*         DYNAM
DATA      RETPD
DDNAME    SYSOUT

5.Deleting a Data Set Before its Expiration Date
To delete a data set (and make the space occupied by the data set available for reallocation) before the expiration date has passed, use one of the following methods:

  • For data sets cataloged in an integrated catalog facility catalog, use the DELETE command, as described in z/OS DFSMS Access Method Services for Catalogs.
  • For data sets not cataloged in an integrated catalog facility catalog, use the IEHPROGM utility, as described in z/OS DFSMSdfp Utilities.
  • Use the SCRATCH macro with the OVRD parameter, as described in z/OS DFSMSdfp Advanced Services. If the data set is SMS-managed, this also uncatalogs the data set.
  • If the storage administrator specified OVRD_EXPDT(YES) in the IGDSMSxx member of SYS1.PARMLIB, you can override the expiration date for SMS-managed DASD data sets by specifying DELETE on the DD DISP parameter. The system will delete the data set whether or not it has expired.

6.Examples of the EXPDT Parameter

Example 

//DD7   DD    DSNAME=TOM1,DISP=(NEW,KEEP),EXPDT=2006/033,
//            UNIT=SYSDA,SPACE=(TRK,(1,1)),VOLUME=SER=663344

In this example, the data set is not eligible for being deleted or written over until February 2, 2006.

Example 

//SMSDS2   DD  DSNAME=MYDS2.PGM,DATACLAS=DCLAS02,DISP=(NEW,KEEP),
//             EXPDT=2001/033

In this example, the expiration date of February 2, 2001 overrides the expiration date defined in the data class for the data set.

FCB parameter

Parameter Type

Keyword, optional

Purpose

Use the FCB parameter to specify:

  • The forms control buffer (FCB) image JES is to use to guide printing of this sysout data set by a 1403 Printer, 3211 Printer, 3203 Printer Model 5, 3800 Printing Subsystem, 4245 Printer, 4248 Printer, or by a printer supported by systems network architecture (SNA) remote job entry (RJE).
  • The carriage control tape JES is to use to control printing of this sysout data set by a 1403 Printer or by a printer supported by SNA RJE.
  • The data-protection image JES is to use to control output of this sysout data set by a 3525 Card Punch.
  • The name of a page definition to be used by PSF in formatting a print data set.

The FCB image specifies how many lines are to be printed per inch and the length of the form. JES loads the image into the printer’s forms control buffer. The FCB image is stored in SYS1.IMAGELIB. IBM provides three standard FCB images:

  • STD1, which specifies 6 lines per inch on an 8.5-inch-long form. (3211 and 3203-2 only)
  • STD2, which specifies 6 lines per inch on an 11-inch-long form. (3211 and 3203-2 only)
  • STD3, which specifies 8 lines per inch for a dump on an 11-inch form. (3800 only)

1.Syntax

FCB= {fcb-name }
     {(fcb-name[,ALIGN|,VERIFY])}
  • You can omit the parentheses if you code only the fcb-name.
  • Code the fcb-name as STD1 or STD2 only to request the IBM-supplied images.
  • Code the fcb-name as STD3 for a high-density dump.
  • v Null positions in the FCB parameter are invalid.

2.Subparameter Definition

fcb-name
Identifies the FCB image. The name is 1 through 4 alphanumeric or national ($, #, @) characters and is the last characters of a SYS1.IMAGELIB member name:

  • FCB2xxxx member for a 3211, a 3203 model 5, or a printer supported by SNA.
  • FCB3xxxx member for a 3800.
  • FCB4xxxx member for a 4248.

ALIGN
Requests that the system ask the operator to check the alignment of the printer forms before the data set is printed.

Note:

  • ALIGN is ignored for a sysout data set.
  • ALIGN is ignored for a data set printed on an AFP printer. AFP printers do not use the ALIGN subparameter.

VERIFY
Requests that the system ask the operator to verify that the image displayed on the printer is for the desired FCB image. The operator can also take this opportunity to align the printer forms.

Note: VERIFY is ignored for a sysout data set.

3.Defaults
If you do not code the FCB parameter, the system checks the FCB image in the printer’s forms control buffer; if it is a default image, as indicated by its first byte, JES uses it. If it is not a default image, JES loads the FCB image that is the installation default specified at JES initialization.

4.Overrides
An FCB parameter on a sysout DD statement overrides an OUTPUT JCL FCB parameter. If both an FCB parameter and a PAGEDEF parameter are coded in your JCL, PSF ignores the FCB parameter.

5.Relationship to Other Parameters
Do not code the following parameters with the FCB parameter.

*          DYNAM
AMP        KEYOFF
DATA       PROTECT
DDNAME     QNAME

Do not code the following DCB subparameters with the FCB parameter.

CYLOFL  INTVL
RKP

For output to the 3525, do not code the SYSOUT parameter and the FCB parameter; the system ignores the FCB parameter.

6.Relationship to Other Control Statements
You can also code the FCB parameter on the following:

  • The OUTPUT JCL statement.
  • The JES2 /*OUTPUT statement.
  • The JES3 //*FORMAT PR statement.

7.Defining an FCB Image for a Work Station
When a work station uses a peripheral data set information record (PDIR), the FCB image is defined in the work station. The DD statement FCB fcb-name subparameter must match the FCB name defined in the PDIR work station.

When a work station does not use a PDIR, add an FCB member to SYS1.IMAGELIB. At setup time, JES3 translates the FCB into a set vertical format (SVF).

8.Requesting a High-Density Dump
You can request a high-density dump on the 3800 through two parameters on the DD statement for the dump data set or on an OUTPUT JCL statement referenced by the dump DD statement:

  • FCB=STD3. This parameter produces dump output at 8 lines per inch.
  • CHARS=DUMP. This parameter produces 204-character print lines.

You can code one or both of these parameters. You can place both on the same statement or one on each statement.

9.Examples of the FCB Parameter

Example 

//DD1   DD   UNIT=3211,FCB=(IMG1,VERIFY)

In this example, the DD statement defines an output data set to be printed by a 3211. The FCB parameter requests that the data set be printed under control of the FCB2IMG1 member in SYS1.IMAGELIB. Because VERIFY is coded, the system displays the FCB image on the printer before printing the data set.

Example 

//DD2   DD   SYSOUT=A,FCB=IMG2

This sysout DD statement specifies output class A. If output class A routes output to a printer having the forms control buffer feature, JES loads the FCB image IMG2 into the forms control buffer. If the printer does not have the forms control buffer feature, the operator receives a message to mount the carriage control tape IMG2 on the printer.

Example 

//OUTDDS   DD   UNIT=3211,FCB=(6,ALIGN)

In this example, the DD statement defines an output data set to be printed by a 3211. The FCB parameter requests that the data set be printed under control of the FCB image named 6. Because ALIGN is coded, the system issues a message to the operator requesting that the alignment of the printer forms be checked before the data set is printed.

Example 

//PUNCH    DD   UNIT=3525,FCB=DP2

In this example, the DD statement requests output on a 3525. Therefore, the FCB parameter defines the data protection image to be used for the 3525.

Example 

//SYSUDUMP   DD   SYSOUT=A,FCB=STD3

In this example, the DD statement requests that the 3800 print a dump at 8 lines per inch.

FILEDATA Parameter

Parameter Type

Keyword, optional

Purpose

Use the FILEDATA keyword to describe the organization of a hierarchical file so that the system can determine how to process the file. Use the FILEDATA keyword only on a system that includes DFSMS/MVS Version 1.3 or later.

If a job containing the FILEDATA parameter runs on a system without the required DFSMS/MVS support, the system checks the FILEDATA syntax and then ignores the parameter.

1.Syntax

FILEDATA= {BINARY}
          {TEXT }

2.Subparameter Definition

BINARY
The file described by the DD statement is a byte-stream file and does not contain record delimiters. The access method does not insert or delete record delimiters.

TEXT
The file described by the DD statement contains records delimited by the EBCDIC newline character (x’15’).

3.Defaults
If you do not code the FILEDATA parameter, the system assigns a default value of BINARY.

4.Overrides
The FILEDATA parameter does not override the specification of any other JCL keyword or system parameter.

5.Relationship to Other Parameters
You can code the FILEDATA parameter only on a DD statement that contains a PATH parameter. You can code the following parameters with the FILEDATA parameter.

BLKSIZE   LRECL      PATHMODE
BUFNO     NCP        PATHOPTS
DSNTYPE   PATH       RECFM
DUMMY     PATHDISP   TERM

6.Example of the FILEDATA Parameter

//DD1   DD   PATH=’/u/d89pek1/new’,FILEDATA=TEXT,
//           PATHMODE=(SIRWXU,SISUID),PATHOPTS=(ORDONLY,OCREAT)

In this example, the DD statement identifies a hierarchical file and informs the system that this file contains records delimited by the newline character.

FLASH Parameter

Parameter Type

Keyword, optional

Purpose

Use the FLASH parameter to identify the forms overlay to be used in printing this sysout data set on a 3800 Printing Subsystem and, optionally, to specify the number of copies on which the forms overlay is to be printed.

Note: FLASH applies only for a data set printed on a 3800.

1.Syntax

       {overlay-name }
FLASH= {(overlay-name[,count])}
       {NONE }

The count subparameter is optional. If you omit it, you can omit the parentheses. However, if you omit it, you must not code it as a null; for example, FLASH=(ABCD,) is invalid.

2.Subparameter Definition

overlay-name
Identifies the forms overlay frame that the operator is to insert into the printer before printing begins. The name is 1 through 4 alphanumeric or national ($, #, @) characters.

count
Specifies the number, 0 through 255, of copies that JES is to flash with the overlay, beginning with the first copy printed. Code a count of 0 to flash all copies.

NONE
Suppresses flashing for this sysout data set.

If FLASH=NONE is on a DD statement in a job to be executed at a remote node, JES3 sets the overlay-name to zero before sending the job to the node.

3.Defaults
If you do not code a FLASH parameter and an installation default was not specified at JES2 or JES3 initialization, forms are not flashed.

If you specify an overlay-name without specifying a count or with a count of 0, all copies are flashed. That is, the default for count is 255.

4.Overrides
A FLASH parameter on a sysout DD statement overrides an OUTPUT JCL FLASH Parameter

Note: A null first subparameter is invalid in a FLASH parameter on a DD statement, but is permitted on an OUTPUT JCL statement.

5.Relationship to Other Parameters
Do not code the following parameters with the FLASH parameter.

*        DISP     PROTECT
AMP      DSID     QNAME
DATA     DYNAM    VOLUME
DDNAME   LABEL

Relationship to COPIES Parameter

If this DD statement or a referenced OUTPUT JCL statement also contains a COPIES parameter, JES prints with the forms overlay the number of copies specified in one of the following:

  • COPIES=nnn, if the FLASH count is larger than nnn. For example, if COPIES=10 and FLASH=(LTHD,12) JES prints 10 copies, all with the forms overlay.
  • The sum of the group-values specified in the COPIES parameter, if the FLASH count is larger than the sum. For example, if COPIES=(,(2,3,4)) and FLASH=(LTHD,12) JES prints nine copies in groups, all with the forms overlay.
  • The count subparameter in the FLASH parameter, if the FLASH count is smaller than nnn or the sum from the COPIES parameter. For example, if COPIES=10 and FLASH=(LTHD,7) JES prints seven copies with the forms overlay and three copies without.

6.Relationship to Other Control Statements
FLASH can also be coded on the following:

  • The OUTPUT JCL statement.
  • The JES3 //*FORMAT PR statement.
  • The JES2 /*OUTPUT statement.

7.Verification of Forms Overlay Frame
Before printing starts, the system requests the operator to load the specified forms overlay frame in the printer. A frame must be loaded, but the system cannot verify that it is the correct frame.

8.Printing without Flashing
To print without flashing, specify one of the following:

  • FLASH=NONE on the DD or OUTPUT JCL statement.
  • Omit the FLASH parameter on all of the statements for the data set and on all JES initialization statements.
  • For a sysout data set, omit the FLASH parameter on the DD statement and specify FLASH=(,0) on a referenced OUTPUT JCL statement.

9.Example of the FLASH Parameter

//DD1     DD    SYSOUT=A,COPIES=10,FLASH=(ABCD,5)

In this example, JES issues a message to the operator requesting that the forms-overlay frame named ABCD be inserted into the printer. Then JES prints the first five copies of the data set with the forms-overlay and the last five copies without.

FREE parameter

Parameter Type

Keyword, optional

Purpose

Use the FREE parameter to specify when the system is to unallocate the resources used for this DD statement’s data set. The resources can be devices, volumes, or exclusive use of a data set.

Note: Specifying FREE will not release the enqueue on the data set until the last step that requires the data set completes processing.

1.Syntax

FREE= {END }
      {CLOSE}

2.Subparameter Definition

END
Requests that the system unallocate the data set at the end of the last step that references the data set.

CLOSE
Requests that the system unallocate the data set when it is closed.

3.Defaults
If no FREE parameter is specified, the default is END. Also, if the FREE parameter is incorrectly coded, the system substitutes END and issues a warning message.

4.Overrides
FREE=CLOSE is ignored when:

  • The data set is a member of a concatenated group.
  • The task using the data set abnormally terminates.

If you specify FREE=CLOSE and the job step abnormally terminates before the data set is closed, the system uses the abnormal termination disposition from the DISP parameter to process the data set. If a recovery routine, such as an ESTAE routine, gets control and closes the data set, then the system uses the normal termination disposition. If the job step abnormally terminates after the data set is closed, then the system has already processed the data set using the normal termination disposition.

  • The data set is referenced by another DD statement in the same or subsequent step.
  • The data set is a VSAM data set.
  • The DDname on the DD statement is JOBCAT, JOBLIB, STEPCAT, or STEPLIB.

5.Relationship to Other Parameters
Do not code the following parameters with the FREE parameter.

*         DDNAME     QNAME 
AMP       DYNAM      RECORG
DATA      KEYOFF     RLS

If the DD statement specifies FREE=END and a DISP subparameter of PASS, the data set is not unallocated until the end of the job or until used for a later DD statement with a disposition of other than PASS.

Do not specify FREE=CLOSE on a DD statement with a ddname of JOBCAT, JOBLIB, STEPCAT, or STEPLIB; CLOSE is ignored.

If you specify SPIN=NO with FREE=CLOSE, the sysout data set will be unallocated, but not printed until the end of the job.

When you specify SPIN=UNALLOC with FREE=CLOSE, the sysout data set is available for printing immediately when you explicitly close or dynamically unallocate the data set. If you do not explicitly close or dynamically unallocate the data set, it will be available for printing at the end of the step.

If you specify SPIN=UNALLOC with FREE=END, the sysout data set is unallocated at the end of the step, and is made available for printing then. If you dynamically unallocate the sysout data set, the system makes it available for printing immediately.

If you specify SPIN=NO with FREE=END, the system makes the sysout data set available for printing at the end of the job, regardless of when the data set is unallocated or closed.

6.Relationship to Other Control Statements
If a DD statement requests unit affinity in a UNIT=AFF parameter or volume affinity in a VOLUME=REF parameter with an earlier DD statement, do not code FREE=CLOSE on the earlier statement.

If you code FREE=CLOSE on a sysout DD statement that references an OUTPUT JCL statement containing a GROUPID parameter, JES2 will not group the data sets into one output group. Instead, JES2 produces one copy of the sysout data set for each OUTPUT JCL statement that the DD statement references.

7.Relationship to the CLOSE Macro Instruction
When FREE=CLOSE is specified for a data set that is opened and closed more than once during a job step:

  • The data set is unallocated after it is closed if the assembler CLOSE macro instruction specifies DISP, REWIND, or FREE. If the data set is reopened after the system has unallocated it, the job step abnormally terminates, unless the data set is dynamically allocated in the interval.

The data set is not unallocated until the end of the job if the assembler CLOSE macro instruction specifies LEAVE or REREAD. Then the data set can be reopened

8.Examples of the FREE Parameter

Example 

//EA33   DD   SYSOUT=D,FREE=CLOSE

In this example, the FREE=CLOSE parameter makes JES unallocate this output class D data set when it is closed, rather than at the end of the job step. JES schedules the data set for printing.

Example 

//EA33    DD    DSNAME=SYBIL,DISP=OLD,FREE=CLOSE

In this example, the FREE=CLOSE parameter makes JES unallocate the data set, dequeue it, and make it available to other jobs as soon as it is closed.

Example 

//STEP1    EXEC   PGM=ABLE1
//DD1 DD DSNAME=A,DISP=(,PASS),FREE=END //STEP2 EXEC PGM=ABLE2 //DD2 DD DSNAME=A,DISP=(OLD,CATLG),FREE=END

In this example, data set A is passed by STEP1 to STEP2. FREE=END on DD statement DD1 is ignored because the disposition is PASS. FREE=END on DD statement DD2 causes data set A to be unallocated at the end of STEP2, when it is also cataloged.

Example 

//STEP1    EXEC   PGM=BAKER1
//DD       DD     DSNAME=A,DISP=(NEW,PASS),FREE=END
//STEP2    EXEC   PGM=BAKER2

In this example, data set A is a new data set. Because PASS is specified, FREE=END is ignored and the data set remains allocated.

HOLD parameter

Parameter Type

Keyword, optional

Purpose

Use the HOLD parameter to tell the system to hold a sysout data set until it is released by the system operator. When the data set is ready for processing, notify the system operator to release it via a TSO/E NOTIFY parameter, a JES2 /*MESSAGE statement, or a JES3 //*OPERATOR statement.

A TSO/E user can specify HOLD=YES to retrieve a sysout data set and display it on a terminal. For JES3, the TSO/E user can process only work on the hold queue.

Notes:

  1. HOLD is supported only for sysout data sets. If HOLD appears on a DD statement that does not contain a SYSOUT parameter, it is ignored.
  2. HOLD allows the sysout data set to be the internal reader. If the sysout data set is the internal reader, the job being submitted will be held.

1.Syntax

HOLD= {YES}
      {Y }
      {NO }
      {N }

2.Subparameter Definition

YES
Requests that the system hold the sysout data set until the data set is released by the system operator. You can also code this subparameter as Y.

NJE Notes:

  • In a JES2 NJE environment, the system does not hold the data set until it reaches its ultimate destination node.
  • If the destination node is a JES3 node, the system may still not hold the data set if the class of output being transmitted is not defined as a hold class. If the sending node is JES3, the system holds the output data set at that node on the BDT queue (when transmitting to an SNA-attached node) or the WTR queue (when transmitting to a BSC-attached node) if all of the following are true:
  • – The ²// DD SYSOUT=² JCL statement does not contain a DEST=(node,userid) parameter.
    – The SYSOUT= parameter does not contain the WRITER-NAME subparameter and the output class is not defined as a hold class.
    – No WRITER= parameter is coded on the OUTPUT JCL statement.

Example.

The following job executes on NODE1 and results in the SYSUT2 output data set being held on the BDT queue on NODE1. (NODE5 is attached to NODE1 via SNA and output class A is not defined as a hold class.)

//S1          EXEC    PGM=IEBGENER
//SYSPRINT    DD      SYSOUT=A
//SYSIN       DD      DUMMY
//SYSUT1      DD      DSN=SYS1.PROCLIB(JES3),DISP=SHR
//SYSUT2      DD      SYSOUT=A,HOLD=YES,DEST=NODES

Example.

The following job executes on NODE1 and results in the SYSUT2 output data set being held on the WTR queue on NODE1. (NODE5 is attached to NODE1 via BSC and output class A is not defined as a hold class.)

//S1         EXEC     PGM=IEBGENER
//O1         OUTPUT   CLASS=A,DEST=NODE2.MYWRITR
//SYSPRINT   DD       SYSOUT=A
//SYSIN      DD       DUMMY
//SYSUT1     DD       DSN=SYS1.PROCLIB(JES3),DISP=SHR
//SYSUT2     DD       SYSOUT=(,),HOLD=YES,OUTPUT=(*.O1)

NO
Requests that the system perform installation-defined processing for the sysout data set’s output class. You can also code this subparameter as N.

3.Defaults
If no HOLD parameter is specified, the default is NO. If the HOLD parameter is incorrectly coded, the system assumes the default of NO and issues a warning message; the job continues.

4.Overrides
HOLD=NO is overridden by the unallocation verb of dynamic allocation or the TSO/E FREE command.

HOLD=YES on the DD statement overrides the sysout data set disposition specified on the OUTDISP parameter of the OUTPUT JCL statement.

5.Relationship to Other Parameters
Code the HOLD parameter only on a DD statement with the SYSOUT parameter. JES3 ignores HOLD=YES when

  • DEST=(node,userid) is coded on the SYSOUT= DD statement. Example 1 shows this case. (JES3 does not ignore the HOLD=YES when DEST= is coded on the OUTPUT DD statement. Example 2 shows this case.) or
  • the sysout data set is placed on the hold queue, for example, if SYSOUT=(,writer-name) is coded.

Ignored but permitted DD parameter:

If you specify the SUBSYS DD parameter, the system checks it for syntax and then ignores it.

6.Relationship to Other Control Statements
Code a NOTIFY parameter on the JOB statement to ask the system to send a message to your TSO/E userid when job processing is complete.

JES2 users can use the /*NOTIFY control statement to direct job notification messages and to override a JOB NOTIFY parameter.

7.Examples of the HOLD Parameter

Example 

//JOB01    JOB     ,’HAROLD DUQUETTE’,MSGLEVEL=1
//STEP1    EXEC    PGM=MJCOSCO
//DD1      DD      SYSOUT=B,DEST=RMT6,HOLD=YES

In this example, sysout data set DD1 from JOB01 is held on a queue until the TSO/E user at RMT6 asks the system operator to release the data set.

Example 

//$JOBxx    JOB      ,’OSWALD CHALMERS’,MSGLEVEL=1
//OUT1      OUTPUT   DEST=NODE2.printer,CLASS=A,...
//STEP1     EXEC     PGM=IEBGENER
//SYSPRINT  DD       SYSOUT=*
//SYSUT1    DD       DISP=SHR,DSN=A.DATA.SET
//SYSUT2    DD       SYSOUT=(,),OUTPUT=(*.OUT1),HOLD=YES

In this example, if the job is submitted on NODE1, JES3 does not ignore the HOLD=YES. The SYSOUT data set is held at NODE1 and is not transmitted to NODE2 to be held there.

KEYLEN parameter

Parameter Type

Keyword, optional

Purpose
Use the KEYLEN parameter to specify the length of the keys used in a newdata set.

Code the KEYLEN parameter when you want to:

  • Specify a key length for the data set or
  • With SMS, override the key length defined in the data class of the data set.

The key length can be supplied from the data set label (or data class with SMS). If a key length is not specified or supplied, input or output requests must not require keys.

KEYLEN applies to data sets with the BDAM, BPAM, BSAM, EXCP, QISAM, and TCAM access methods, and, with SMS, to VSAM data sets.

1.Syntax

KEYLEN=bytes

2.Subparameter Definition

bytes
Specifies the length, in bytes, of the keys used in the data set. The number of bytes is:

  • 0 to 255 for non-VSAM data sets. The key length must be less than or equal to the record length.

Note: Use only 0 for a member of a partitioned data set extended (PDSE). Use 0 or 8 to perform input operations on the directory of a PDSE.

  • 1 to 255 for VSAM key-sequenced (RECORG=KS) data sets. A key length must be specified, either explicitly with the KEYLEN or LIKE parameter, or in the data class for the data set. The key length must be less than the record length.

3.Overrides
KEYLEN overrides the key length specified in the data set label, and with SMS, KEYLEN overrides the key length defined in the DATACLAS parameter for the data set.

4.Relationship to Other Parameters
Do not code the following DD parameters with the KEYLEN parameter.

*              DCB=STACK
DATA DCB=TRTCH
DCB=KEYLEN DDNAME
DCB=MODE DYNAM
DCB=PRTSP

5.Examples of the KEYLEN Parameter

Example 

//DD4   DD   DSNAME=JST,DISP=(NEW,KEEP),UNIT=3350,
// SPACE=(CYL,(12,2)),DCB=(A.B.C),KEYLEN=8

DD statement DD4 defines a new data set named JST and requests that the system copy the DCB information from the data set label of the cataloged data set named A.B.C. If the data set label contains a key length specification, it is overridden by the KEYLEN coded on this DD statement.

Example 

//SMSDS3   DD   DSNAME=MYDS3.PGM,DATACLAS=VSAM1,DISP=(NEW,KEEP),
//              KEYLEN=6

In the example, where the data class VSAM1 defines a key-sequenced VSAM data set, the key length of 6 overrides the key length defined in the data class.

KEYOFF parameter

Parameter Type

Keyword, optional — use this parameter only with SMS Without SMS, use the RKP subparameter of the DCB parameter.

Purpose

Use the KEYOFF parameter to specify the key offset, the position of the first byte of the record key in each logical record of a new VSAM data set. The first byte of a logical record is position 0.

If SMS is not installed or is not active, the system syntax checks and then ignores the KEYOFF parameter. Code the KEYOFF parameter only for a VSAM key-sequenced data set (RECORG=KS).

Code the KEYOFF parameter when you want to (1) specify a key offset for the data set or (2) override the key offset defined in the data class of the data set.

1.Syntax

KEYOFF=offset-to-key

offset-to-key
Specifies the position (offset), in bytes, of the first byte of the key in each record. The offset is 0 to the difference between the record length (LRECL) and key length (KEYLEN), in the range 0 to 32,760.

3.Overrides
KEYOFF overrides the key offset defined in the DATACLAS parameter for the data set.

4.Relationship to Other Parameters
Do not code the following DD parameters with the KEYOFF parameter.

*                DYNAM
DATA             FCB
DCB=RESERVE      FREE=CLOSE
DCB=RKP          UCS
DDNAME

5.Example of the KEYOFF Parameter

//SMSDS3   DD   DSNAME=MYDS3.PGM,DATACLAS=VSAM1,DISP=(NEW,KEEP),
// KEYOFF=2

In the example, the data class VSAM1 defines a key-sequenced VSAM data set. The key offset of 2 overrides the key offset defined in the data class and specifies that the first byte of the key is in the third position of each record.

LABEL parameter

Parameter Type

Keyword, optional

Purpose

Use the LABEL parameter to specify for a tape or direct access data set:

  • The type and contents of the label or labels for the data set.
  • If a password is required to access the data set.
  • If the system is to open the data set only for input or output.
  • The expiration date or retention period for the data set.

Although subparameters RETPD and EXPDT are shown in the syntax of the LABEL parameter, you should use the RETPD or EXPDT DD parameter to specify a retention period or expiration date for the data set.

For a tape data set, this parameter can also specify the relative position of the data set on the volume.

1.Syntax

LABEL=([data-set-sequence-number][,label] [,PASSWORD][,IN ]
                                                     [,RETPD=nnnn    ])
                                 [   ,  ] [,NOPWREAD][,OUT]
                                                     [,EXPDT={yyddd }]
                                          [    ,    ]      
                                                     [   {yyyy/ddd}  ]

label is one of the following:

  AL
  AUL
  BLP
  LTM
  NL
  NSL
  SL
  SUL

The first four sub parameters are positional; the last sub parameter is keyword. If you omit any positional sub parameters but code a following positional sub parameter, indicate each omitted sub parameter by a comma. If the following sub parameter is one of the keyword subparameters (EXPDT or RETPD), you do not need commas to indicate omitted sub parameters. For example:

LABEL=(0001,SUL,PASSWORD,IN)
LABEL=(,SUL,PASSWORD)
LABEL=(,SUL,,IN,EXPDT=97033)
LABEL=(,,PASSWORD,EXPDT=1997/033)
LABEL=(,SUL,EXPDT=1997/033)
LABEL=(0001,,,IN)
LABEL=(0001,EXPDT=1997/033)

If you specify only the data-set-sequence-number or only the retention period or only the expiration date, you can omit the parentheses. For example, code LABEL=data-setsequence- number, LABEL=RETPD=nnnn, LABEL=EXPDT=yyddd, or LABEL=EXPDT=yyyy/ddd.

Alternate Syntax for RETPD and EXPDT

RETPD and EXPDT should be specified as DD parameters rather than sub
parameters of the LABEL parameter. This allows you to specify a retention period or expiration date without the need to code LABEL.

For example, code RETPD and EXPDT on the DD statement as:

RETPD=366 or EXPDT=2006/033

2.Subparameter Definition

Data-Set-Sequence-Number
Identifies the relative position of a data set on a tape volume. The data-set-sequence-number is 1 through 4 decimal digits. Omit this subparameter or code 0 or 1 to indicate the first data set on the tape volume.

Omit this subparameter for the following:

  • Cataloged data sets. The system obtains the data-set-sequence-number from the catalog.
  • A DD DSNAME parameter that requests all members of a generation data group (GDG). The system retrieves the data-set-sequence-number from the catalog.
  • A data set passed from a preceding step. The system obtains the data-set-sequence-number from the passing step.

Label
The system does not retain label type information for cataloged data sets; if the label type is not coded in the LABEL parameter for a cataloged data set, the system assumes SL. For a data set on a direct access device, the system obtains the label type from the DD statement; the label type is not obtained from any other source referred to in the DD statement. Only two label types are valid for direct access devices: SL and SUL.

SL
Indicates that a data set has IBM standard labels. If this subparameter is omitted, SL is the default. Code only SL or SUL for data sets on direct access devices. If the LABEL parameter is coded on a SYSCKEOV DD statement, code LABEL=(,SL).

SUL
Indicates that a data set has both IBM standard and user labels. Code only SL or SUL for data sets on direct access devices. Do not code SUL for partitioned or indexed sequential data sets.

AL
Indicates that a tape data set has ISO/ANSI Version 1 or ISO/ANSI/FIPS Version 3 labels. If you specify AL for a tape generation data set for output, the ending .GnnnnVnn (where n=0 through 9) will not appear as part of the file identifier (data set name field) of the HDR1 label. Instead, the data is placed in the generation and version number fields of the HDR1 label.

AUL
Indicates that a tape data set has user labels and ISO/ANSI Version 1 or ISO/ANSI/FIPS Version 3 labels.

NSL
Indicates that a tape data set has nonstandard labels. Before you code NSL, ensure that your installation has created and installed non-standard label processing routines, described in z/OS DFSMS Installation Exits.

NL
Indicates that a tape data set has no labels. When retrieving two or more data sets from several NL or BLP tape volumes, concatenate the DD statements and repeat the LABEL parameter on each DD statement. If you are processing ASCII data on unlabeled tapes, the data control block must specify OPTCD=Q.

BLP
Requests that the system bypass label processing for a tape data set.

If the installation did not specify the BLP feature in the reader cataloged procedure, BLP has the same effect as NL.

If you code BLP and the tape volume has labels, a tapemark delimits the data set. To let the system position a tape with labels to the proper data set, code the data-set-sequence-number subparameter; the number must reflect all labels and data sets that precede the desired data set.

Do not specify BLP when the DD DSNAME parameter requests all members of a generation data group (GDG); the system obtains the data-set-sequencenumber from the catalog. Therefore, coding BLP might result in incorrect tape positioning.

When retrieving two or more data sets from several NL or BLP tape volumes, or when retrieving a data set from several BLP tape volumes and those volumes have labels, concatenate the DD statements and repeat the LABEL parameter on each DD statement.

LTM
Indicates that the data set has a leading tapemark.

Notes:

  1. You may use the LABEL parameter when allocating a system-managed tape volume, but you cannot use the NSL or LTM subparameters. If the ACS routine does not exclude these subparameters, the job will fail with JCL errors. System-managed tape volumes must be IBM standard label or ANSI standard tapes.
  2. LABEL=(,,,IN) is the system-managed tape library equivalent of either
    UNIT=SYS3480R or UNIT=SYS348XR, which represent overriding esoteric unit names.

Password Protection
For an SMS-managed data set (one with an assigned storage class), SMS sets the password indicators in the VTOC and catalog but ignores the indicators and does not use password protection for the data set. Password protecting data sets requires the following:

  • Data set names no longer than 17 characters. MVS retains in the tape label only the rightmost 17 characters of the data set name. Consequently, longer names could be identical in password checks.
  • Volumes with IBM standard labels or ISO/ANSI/FIPS Version 3 labels.
  • A password assigned in the PASSWORD data set. If a password is not assigned, the system will abnormally terminate a job step when it attempts to open the data set for output, if NOPWREAD is coded, or for input or output, if PASSWORD is coded.

To create a password-protected data set following an existing password-protected data set, code the password of the existing data set. The password must be the same in both the existing and the new data set.

To password-protect a data set on a tape volume containing other data sets, you must password-protect all the data sets on the volume and the passwords must be the same for all data sets.

To password-protect an existing data set using PASSWORD or NOPWREAD, open the data set for output the first time it is used during the job step.

PASSWORD
Indicates that a data set cannot be read, changed, deleted, or written to unless the system operator or TSO/E user supplies the correct password.

NOPWREAD
Indicates that a data set cannot be changed, deleted, or written to unless the system operator or TSO/E user supplies the correct password. No password is necessary for reading the data set.

Input or Output Processing

IN
Indicates that a BSAM data set opened for INOUT or a BDAM data set opened for UPDAT is to be read only. The IN subparameter overrides the processing option in the assembler OPEN macro instruction. Any attempt by the processing program to write in the data set makes the system give control to the error analysis (SYNAD) routine.

OUT
Indicates that a BSAM data set opened for OUTIN or OUTINX is to be written in only. The OUT subparameter overrides the processing option in the assembler OPEN macro instruction. Any attempt by the processing program to read the data set makes the system give control to the error analysis (SYNAD) routine.

Retention Period or Expiration Date for Data Set
You should avoid using the RETPD and EXPDT subparameters on the LABEL parameter to specify a retention period or expiration date for the data set.

Use the DD RETPD parameter or the DD EXPDT Parameter, which do the same function. This allows you to specify a retention period or expiration date without the need to code the LABEL parameter.

3.Defaults

  • If no data-set-sequence-number subparameter is specified or if the number is coded as 0 or 1, the default is the first data set on the tape volume, unless the data set is passed or cataloged.
  • If no label type subparameter is specified, the default is only IBM standard labels (SL).

4.Relationship to Other Parameters
Do not code the following parameters with the LABEL parameter.

*         DATA       MODIFY
BURST     DDNAME     QNAME
CHARS     DYNAM      SYSOUT 
COPIES    FLASH

Do not specify the LABEL parameter with the FUNC subparameter of the DCB parameter. The results are unpredictable.

ISO/ANSI/FIPS Version 3 tape data sets can be protected by use of the ACCODE parameter. If you specify a LABEL parameter on a SYSCKEOV DD statement, code LABEL=(,SL).

5.Relationship to Other Control Statements
When a VOLUME=REF subparameter refers to an earlier DD statement to use the same volume(s):

  • For tape, the system copies the LABEL label type subparameter from the referenced DD statement; the copied label type overrides the label type on the referencing DD statement.
  • For direct access, the system uses a LABEL=(,SL) or LABEL=(,SUL) subparameter from the referencing DD statement. If the referencing DD statement specifies any other label type, the system copies the LABEL label type subparameter from the referenced DD statement; the copied label type overrides the label type on the referencing DD statement.
  • You do not need to provide a data set sequence number when the DD DSNAME parameter references all the members of a GDG or a single member through a relative generation number; the system obtains the data from the catalog. For all other data set names, however, you must provide the data set sequence number on the LABEL parameter.

6.Data Conversion
AL or AUL in the LABEL parameter requests conversion between EBCDIC and ASCII. You can also request conversion by specifying OPTCD=Q in the data control block. If the tape is not labeled, LABEL=(,NL), you must specify OPTCD=Q for conversion to occur.

7.Examples of the LABEL Parameter

Example 

//DD1   DD   DSNAME=HERBI,DISP=(NEW,KEEP),UNIT=TAPE,
//           VOLUME=SER=T2,LABEL=(3,NSL,RETPD=188)

DD statement DD1 defines a new data set. The LABEL parameter tells the system:

  • This data set is to be the third data set on the tape volume.
  • This tape volume has nonstandard labels.
  • This data set is to be kept for 188 days.

Although LABEL=(3,NSL,RETPD=188) is valid, it is better practice to use the DD RETPD parameter as follows:

//DD1   DD   DSNAME=HERBI,DISP=(NEW,KEEP),UNIT=TAPE,
//           VOLUME=SER=T2,LABEL=(3,NSL),RETPD=188

Example 

//DD2   DD   DSNAME=A.B.C,DISP=(,CATLG,DELETE),UNIT=3400-5,LABEL=(,NL)

DD statement DD2 defines a new data set, requests that the system catalog it, and indicates that the data set has no labels. Each time this data set is used by a program, the DD statement must include LABEL=(,NL).

Example 

//DD3   DD   DSNAME=SPECS,UNIT=3400-5,VOLUME=SER=10222,
//           DISP=OLD,LABEL=4

DD statement DD3 indicates an existing data set. The LABEL parameter indicates that the data set is fourth on the tape volume.

Example 

//STEP1   EXEC   PGM=FIV
//DDX DD DSNAME=CLEAR,DISP=(OLD,PASS),UNIT=3400-5, // VOLUME=SER=1257,LABEL=(,NSL) //STEP2 EXEC PGM=BOS //DDY DD DSNAME=*.STEP1.DDX,DISP=OLD,LABEL=(,NSL)

DD statement DDX in STEP1 indicates an existing data set with nonstandard labels and requests that the system pass the data set. DD statement DDY in STEP2 receives the data set. DDY contains the label type, because the system does not obtain the label type through the backward reference in the DSNAME parameter.

Example 

//DDZ   DD    DSNAME=CATDS,DISP=OLD,LABEL=(,SUL)

DD statement DDZ indicates an existing, cataloged data set on direct access. The data set has IBM standard labels and user labels. The LABEL parameter is required; otherwise, if the DD statement does not contain a LABEL parameter, the system assumes that a direct access data set has SL labels.

Example 

//DD7   DD   DSNAME=TOM1,DISP=(NEW,KEEP),LABEL=EXPDT=2006/033,
//           UNIT=3350,SPACE=(TRK,(1,1)),VOLUME=SER=663344

DD statement DD7 defines a new data set, requests the system to keep the data set, and indicates that the data set cannot be deleted or written over until the expiration date of February 2, 2006. Although LABEL=EXPDT=2006/033 is valid, it is better practice to use the DD EXPDT parameter as follows:

//DD7   DD   DSNAME=TOM1,DISP=(NEW,KEEP),EXPDT=2006/033,
//           UNIT=3350,SPACE=(TRK,(1,1)),VOLUME=SER=663344

LIKE parameter

Parameter Type

Keyword, optional

Purpose

Use the LGSTREAM parameter to specify the prefix of the name of the log stream for an SMS-managed VSAM data set. Use it only:

  • For allocating SMS-managed VSAM data sets that will be accessed using record level sharing (RLS).
  • On a system that includes DFSMS/MVS Version 1 Release 4 or later. (The system ignores the LGSTREAM parameter when operating with DFSMS 1.3 and earlier releases.)

1.Syntax

LGSTREAM=name

The name, up to a maximum of twenty-six characters, consists of one or more segments. Each segment may contain one to eight characters, which may be alphabetic, numeric, or national ($, #, @) characters. Segments are joined by periods, with periods being counted as characters towards the limit of twenty-six. The first character of each segment must be non-numeric.

2.Subparameter Definition

name
Specifies the name of the prefix the system logger uses for the forward recovery log stream for recording changes made to the data set when accessed in the RLS mode. The system logger adds other qualifiers to the end of the LGSTREAM name to generate the data set name where it keeps the forward recovery logs.

3.Defaults
If you do not code a LGSTREAM parameter the system will assign the value specified in the SMS data class assigned to the data set, if applicable.

4.Overrides
The system ignores LGSTREAM specifications for non-SMS-managed and non-VSAM data sets and for VSAM linear data sets. The LGSTREAM name on a DD statement can override the LOGSTREAMID name specified in the SMS data class.

5.Relationship to Other Parameters
Code a disposition of NEW or of MOD treated as NEW. (The system ignores the LGSTREAM parameter for existing data sets.) Do not code the following DD parameters with the LGSTREAM parameter.

*            DLM          PATHDISP
BURST        DSNTYPE      QNAME
CHARS        DYNAM        SEGMENT
COPIES       FLASH        SPIN
DATA         MODIFY       SYSOUT
DCB=DSORG    OUTPUT       TERM
DCB=RECFM    PATHOPTS     UCS
DDNAME       PATHMODE

6.Example of the LGSTREAM Parameter

//FRED   DD   DSN=VSAM.DATASET,LGSTREAM=SSAB1234.NEW,RECORG=KS,
//            KEYLEN=8,KEYOFF=0,DISP=(,KEEP)

In this example, the system will create an SMS-managed VSAM key-sequenced data set if the storage administrator assigns a data class that provides other parameters such as SPACE and LOG=ALL, and assigns a POOL storage group. The system logger will use the name SSAB1234.NEW as the prefix to generate the data set name where it will keep the forward recovery logs.

LGSTREAM parameter

Parameter Type

Keyword, optional — use this parameter only with SMS

Without SMS, use the DCB=dsname form of the DCB parameter.

Purpose

Use the LIKE parameter to specify the allocation attributes of a new data set by copying the attributes of a model data set, which must be an existing cataloged data set and reside on a direct access volume.

The following attributes are copied from the model data set to the new data set:

  • Data set organization
  • – Record organization (RECORG) or
    – Record format (RECFM)
  • Record length (LRECL)
  • Key length (KEYLEN)
  • Key offset (KEYOFF)
  • Type, PDS or PDSE (DSNTYPE)
  • Space allocation (AVGREC and SPACE)

Unless you explicitly code the SPACE parameter for the new data set, the system determines the space to be allocated for the new data set by adding up the space allocated in the first three extents of the model data set. Therefore, the space allocated for the new data set will generally not match the space that was specified for the model data set. Note that if the model data set was allocated in blocks (that is, BLKLGTH or RECLGTH was specified rather than TRK or CYL), then the system will allocate space for the new data set in tracks.

Note: Directory quantity is picked up as part of the space allocation attribute except when the model data set is a PDSE. When you create a PDS, the directory blocks must be specified directly on the JCL by using the SPACE parameter.

There is no requirement that either the new data set or the model data set must be SMS-managed. If the new data set is to reside on tape:

  • The model data set must be a sequential DASD data set
  • Only the record format (RECFM) and the record length (LRECL) attributes are copied to the new data set.

For VSAM data set compression, the LIKE parameter copies existing data set attributes. That is, LIKE processing on a model data set that is compressed will pass the attribute to the new data set. This means that specifying compaction in DATACLAS is not the only way compression can be achieved.

When you specify the LIKE parameter on a JCL DD statement, the SMS read-only variable values that correspond to the attributes copied from the model data set are not available as input to the ACS routines.

If SMS is not installed or is not active, the system syntax checks and hen ignores the LIKE parameter.

The retention period (RETPD) or expiration date (EXPDT) is not copied to the new data set.

Note: Do not use the LIKE parameter to copy attributes from a temporary data set (&&dsname), partitioned data set if a member name is included, and relative generation number for a GDG.

1.Syntax

LIKE=data-set-name

2.Subparameter Definition

data-set-name
Specifies the data set name (dsname) of the model data set whose attributes are to be used as the attributes of the new data set.

3.Overrides
Any attributes obtained using the LIKE parameter override the corresponding attributes in the DATACLAS parameter. Any attributes you specify on the same DD statement with the following parameters override the corresponding attributes obtained from the model data set.

AVGREC (record request and space quantity)
DSNTYPE (type, PDS or PDSE)
KEYLEN (key length)
KEYOFF (key offset)
LRECL (record length)
RECORG (record organization) or RECFM (record format)
SPACE (average record length, primary, secondary, and directory quantity)

4.Relationship to Other Parameters

Do not code the following DD parameters with the LIKE parameter.

DYNAM
REFDD
SYSOUT

5.Examples of the LIKE Parameter

Example 

//SMSDS6   DD   DSNAME=MYDS6.PGM,LIKE=MYDSCAT.PGM,DISP=(NEW,KEEP)

In the example, the data set attributes used for MYDS6.PGM are obtained from the cataloged model data set MYDSCAT.PGM.

Example 

//SMSDS7   DD   DSNAME=MYDS7.PGM,LIKE=MYDSCAT.PGM,DISP=(NEW,KEEP),
//              LRECL=1024

In the example, the data set attributes used for MYDS7.PGM are obtained from the cataloged model data set MYDSCAT.PGM. Also, the logical record length of 1024 overrides the logical record length obtained from the model data set.

LRECL parameter

Parameter Type

Keyword, optional

Purpose

Use the LRECL parameter to specify the length of the records in a new data set.

Code the LRECL parameter when you want to

  • Specify the logical record length for the data set, or
  • With SMS, override the record length defined in the data class of the data set. LRECL applies to data sets with the BPAM, BSAM, EXCP, QISAM, QSAM, and TCAM access methods, and with SMS, to VSAM data sets.

1.Syntax

LRECL=bytes

2.Subparameter Definition

bytes
Specifies (1) the length, in bytes, for fixed length records or (2) the maximum length, in bytes, for variable-length records. The value of bytes is:

  • 1 to 32,760 for non-VSAM data sets.
  • 1 to 32,761 for VSAM key-sequenced (KS), entry-sequenced (ES), or relative record (RR) data sets. (LRECL does not apply to VSAM linear space, RECORG=LS, data sets.)

For VSAM key-sequenced (KS) data sets, a record length must be specified, either explicitly with the LRECL or LIKE parameter, or in the data class for the data set. The record length must be greater than the key length.

Note: When RECFM is F or U, the length must not exceed DCB BLKSIZE. For RECFM=D or V, the length must not exceed BLKSIZE minus 4. For RECFM=VS, the length can exceed BLKSIZE. For unblocked records when DCB RKP=0, the length is for only the data portion of the record. LRECL=0 is valid only for RECFM=U.

Additional Syntax for LRECL=bytes

LRECL=nnnnnK
Specifies the length in kilobytes for variable-length spanned records in ISO/ANSI/FIPS Version 3 tape data sets that are processed by the Data Facility Product using the extended logical record interface (XLRI). nnnnn is from 1 through 16,383 and indicates multiples of 1024 bytes. The value in the DCB macro must already be coded as LRECL=0K or LRECL=nnnnnK. If a K is coded for any other type of data set, only the numeric value of LRECL is recognized.

LRECL=X
For QSAM only, specifies that the logical record length exceeds 32,760 bytes for variable-length spanned records. This option is not valid for ISO/ANSI/FIPS Version 3 variable-length records.

3.Overrides
LRECL overrides the record length specified in the data set label, and with SMS, LRECL overrides the record length defined in the DATACLAS parameter for the data set.
4.Relationship to Other Parameters
Do not code the following DD parameters with the LRECL parameter.

DCB=LRECL
DDNAME
DYNAM

5.Examples of the LRECL Parameter

Example 

//DD1B   DD   DSNAME=EVER,DISP=(NEW,KEEP),UNIT=3380,
//            RECFM=FB,LRECL=326,SPACE=(23472,(200,40))

In the example, the logical record length of 326 is used for the new data set EVER.

Example 

//SMSDS2    DD    DSNAME=MYDS2.PGM,DATACLAS=DCLAS02,DISP=(NEW,KEEP),
//                LRECL=256

In the example, the logical record length of 256 overrides the logical record length defined in the data class for the data set.

MGMTCLAS parameter

Parameter Type

Keyword, optional

Use this parameter only with SMS and for SMS-managed data sets.

Without SMS, there are no DD parameters that provide this function.

Purpose

Use the MGMTCLAS parameter to specify a management class for a new SMS-managed data set. The storage administrator at your installation defines the names of the management classes you can code on the MGMTCLAS parameter.

After the data set is allocated, the attributes in the management class control:

  • Migration of the data set, including migration from primary storage to DFSMShsm-owned storage to archival storage
  • Backup of the data set, including frequency of backup, number of versions, and retention criteria for backup versions
  • Automatic deletion of data sets
  • Automatic release of unused space in data sets

The Hierarchical Storage Manager (DFSMShsm) or a functionally equivalent program performs these functions.

If SMS is not installed or is not active, the system syntax checks and then ignores the MGMTCLAS parameter.

SMS ignores the MGMTCLAS parameter if you specify it for an existing data set. The use of a management class can be protected by RACF.

1.Syntax

MGMTCLAS=management-class-name

2.Subparameter Definition

management-class-name
Specifies the name of a management class to be used for management of the SMS-managed data set after the data set is allocated. The name, one to eight alphanumeric or national ($ # @) characters, is defined by the storage administrator at your installation.

3.Defaults
If you do not specify MGMTCLAS for a new data set and the storage administrator has provided an installation-written automatic class selection (ACS) routine, the ACS routine may select a management class for the data set. Check with your storage administrator to determine if an ACS routine will select a management class for the new data set, in which case you do not need to specify MGMTCLAS. You cannot override management class attributes via JCL parameters. With SMS, MGMTCLAS.

4. overrides
overrides the attributes defined in the DATACLAS parameter for the data set. The management class for a data set defines a maximum value for the expiration date or retention period of the data set. This maximum limits the values that are specified on the EXPDT or RETPD parameter, or defined in the data class for the data set. An ACS routine can override the management class that you specify on the MGMTCLAS parameter.

5.Relationship to Other Parameters
Do not code the following DD parameters with the MGMTCLAS parameter.

* DYNAM DATA QNAME
  DDNAME

Code MGMTCLAS only when you specify a storage class for the data set (via the STORCLAS parameter) or an ACS routine selects a storage class.

6.Example of the MGMTCLAS Parameter

//SMSDS1   DD   DSNAME=MYDS1.PGM,DATACLAS=DCLAS1,STORCLAS=SCLAS1,
//              MGMTCLAS=MCLAS01,DISP=(NEW,KEEP)

In the example, SMS uses the attributes in the management class named MCLAS01 to handle the migration and backup of the SMS-managed data set. Note that installation-written ACS routines may override the specified management class, storage class, and data class.

MODIFY parameter

Parameter Type

Keyword, optional

Purpose

Use the MODIFY parameter to specify a copy-modification module that tells JES how to print this sysout data set on a 3800 Printing Subsystem. The module can specify the following:

  • Legends.
  • Column headings.
  • Where and on which copies the data is to be printed.

The module is defined and stored in SYS1.IMAGELIB using the IEBIMAGE utility program.

Note: MODIFY applies only for the 3800 Printing Subsystem Models 1 and 2 and the 3800 Printing Subsystem Models 3, 6, and 8 in compatibility mode.

1.Syntax

MODIFY= {module-name }
        {(module-name[,trc])}
  • You must code the module-name.
  • The trc subparameter is optional. If you omit it, you can omit the parentheses. However, if you omit it, you must not code it as a null; for example, MODIFY=(TAB1,) is invalid.

2.Subparameter Definition

module-name
Identifies a copy-modification module in SYS1.IMAGELIB. The module-name is 1 through 4 alphanumeric or national ($, #, @) characters.

trc
Identifies which table-name in the CHARS parameter is to be used. This table reference character is 0 for the first table-name specified, 1 for the second, 2 for the third, or 3 for the fourth. The CHARS parameter is on the following, in override order:

  1. This DD statement.
  2. A referenced OUTPUT JCL statement.
  3. A statement in the library member specified on the OUTPUT JCL PAGEDEF parameter.
  4. A statement in the SYS1.IMAGELIB member obtained by default.
  5. A JES3 initialization statement.

3.Defaults
If no MODIFY parameter is specified, JES3 uses an installation default specified at initialization. JES2 provides no installation default at initialization. If you do not specify trc or if the trc value is greater than the number of table-names in the CHARS parameter, JES2 uses the first table named in the CHARS parameter and JES3 uses the default character arrangement table.

4.Overrides
A MODIFY parameter on a sysout DD statement overrides an OUTPUT JCL MODIFY parameter.

Note: A null first subparameter is invalid in a MODIFY parameter on a DD statement, but is permitted on an OUTPUT JCL statement.

5.Relationship to Other Parameters
Do not code the following parameters with the MODIFY parameter.

*         DISP       PROTECT
AMP       DSID       QNAME
DATA      DYNAM      SUBSYS
DDNAME    LABEL      VOLUME

6.Relationship to Other Control Statements
MODIFY can also be coded on the following:

  • The OUTPUT JCL statement.
  • The JES3 //*FORMAT PR statement.
  • The JES2 /*OUTPUT statement.

The second character of each logical record can be a TRC code, so that each record can be printed in a different font. This way of specifying fonts is indicated by the OUTPUT JCL TRC parameter.

7.Example of the MODIFY Parameter

//DD1    DD    UNIT=3800,MODIFY=(A,0),CHARS=(GS15,GS10)

In this example, the MODIFY parameter requests that the data in the copy-modification module named A replace variable data in the data set to be printed by the 3800. Module A defines which positions are to be replaced and which copies are to be modified. The second subparameter in MODIFY specifies that the first character arrangement table in the CHARS parameter, GS15, be used.

OUTLIM parameter

Parameter Type

Keyword, optional

Purpose

Use the OUTLIM parameter to limit the number of logical records in the sysout data set defined by this DD statement. When the limit is reached, the system exits to the SYSOUT limit exit routine. If the installation supplies an installation-written routine, the routine can determine whether to terminate the job or increase the limit. If the installation does not supply a routine, the system terminates the job.

Note: OUTLIM is valid only on a DD statement with a SYSOUT parameter.

1.Syntax

OUTLIM=number

2.Subparameter Definition

number
Specifies the maximum number of logical records. The number is 1 through 8 decimal digits from 1 through 16777215.

3.Default
(1) If no OUTLIM parameter is specified or OUTLIM=0 is coded and (2) if output is not limited by JES control statements, JES3 uses an installation default specified at initialization; JES2 provides no installation default at initialization.

4.Relationship to Other Parameters
Code the OUTLIM parameter only on a DD statement with the SYSOUT parameter. Do not code the OUTLIM parameter with the DCB subparameters CPRI or THRESH; these subparameters can alter the OUTLIM value.

On Dump DD Statements

On a SYSABEND or SYSUDUMP DD statement:

  • JES3 ignores the OUTLIM parameter.
  • JES2 limits the output as specified on the OUTLIM parameter.

Not only can JECL statement limit output, but the OUTLIM parameter is applied independently of other limits.

5.Relationship to Other Control Statements

Output can also be limited by the following:

  • The LINES, BYTES, PAGES, or CARDS parameter of the JES2 /*JOBPARM statement.
  • The LINES, BYTES, PAGES, or CARDS parameter of the JES3 //*MAIN statement.
  • The LINES, BYTES, PAGES, or CARDS parameter of the JOB statement.

6.Example of the OUTLIM Parameter

//OUTDD   DD   SYSOUT=F,OUTLIM=1000

The limit for the number of logical records is 1000.

OUTPUT parameter

Parameter Type

Keyword, optional

Purpose

Use the OUTPUT parameter with the SYSOUT parameter to associate a sysout data set explicitly with an OUTPUT JCL statement. JES processes the sysout data set using the options from this DD statement combined with the options from the referenced OUTPUT JCL statement.

When the OUTPUT parameter references more than one OUTPUT JCL statement, the system produces separate output for each  OUTPUT JCL statement.

Note: Code the OUTPUT parameter only on a DD statement with either a SYSOUT or SUBSYS parameter. If you code the OUTPUT parameter without SYSOUT, the system checks the OUTPUT parameter for syntax and ignores it, unless you also code the SUBSYS parameter. If you code the SUBSYS parameter, the system passes the OUTPUT parameter to the subsystem identified in the SUBSYS parameter. The subsystem might support the OUTPUT parameter or might ignore it. The Infoprint Server subsystem, for example, uses the OUTPUT parameter to process a sysout data set.

1.Syntax

OUTPUT= {reference }
        {(reference[,reference]...)}

A reference is one of the following:

          *.name
          *.stepname.name
          *.stepname.procstepname.name
  • You can omit the parentheses if you code only one reference.
  • You must not code a null in an OUTPUT parameter. For example, OUTPUT=(,*.name) is invalid.
  • You can reference a maximum of 128 OUTPUT JCL statements on one OUTPUT parameter.
  • You can code references in any combination. For example, the following are valid:
  •   //EXA    DD   SYSOUT=A,OUTPUT=(*.name,*.name,*.stepname.name)
      //EXB    DD   SYSOUT=A,OUTPUT=(*.stepname.name,
      //            *.stepname.procstepname.name,*.name)
  • You can code the references to OUTPUT JCL statement

2.Subparameter Definition

*.name
Refers to an earlier OUTPUT JCL statement with name in its name field. The system searches for the OUTPUT JCL statement first in the same step, then before the first EXEC statement of the job.

*.stepname.name
Refers to an earlier OUTPUT JCL statement, name, in this step or an earlier step, stepname, in the same job.

*.stepname.procstepname.name
Refers to an OUTPUT JCL statement in a cataloged or in-stream procedure. Stepname is the name of this job step or an earlier job step that calls the procedure, procstepname is the name of the procedure step that contains the OUTPUT JCL statement, and name is the name field of the OUTPUT JCL statement.

3.Defaults
If you do not code an OUTPUT parameter on a sysout DD statement, JES obtains processing options for the sysout data set in the following order:

  1. From each OUTPUT JCL statement containing DEFAULT=YES in the same step.
  2. From each OUTPUT JCL statement containing DEFAULT=YES before the first EXEC statement in the job, provided that the step contains no OUTPUT JCL statements with DEFAULT=YES.
  3. Only from the sysout DD statement, provided that neither the step nor job contains any OUTPUT JCL statements with DEFAULT=YES.

If you do not specify a SYSOUT class on the DD statement, JES3 uses the truncation value associated with the first referenced (or defaulted) OUTPUT statement that does specify a class. If this DD statement specifies an OUTPUT class, JES3 accepts that class and its associated truncation value.

4.Overrides
When an OUTPUT JCL statement is used with the sysout DD statement to specify processing, JES handles parameters as follows:

  • If a parameter appears on the DD statement, JES uses the parameter.
  • If a parameter appears only on the OUTPUT JCL statement, JES uses the parameter.
  • If the same parameter appears on both statements, JES uses the DD parameter.

JES uses the whole overriding parameter, ignoring the whole overridden parameter. If a subparameter is left off the overriding parameter, the system does not pick up that subparameter from the overridden parameter. For example:

//EXAMP2   OUTPUT   FLASH=(ABCD,3)
//FVZ2     DD       SYSOUT=F,OUTPUT=*.EXAMP2,FLASH=(EFGH)

Only EFGH is used. The system ignores all of the FLASH parameter on the OUTPUT JCL statement, including the second parameter.

5.Relationship to Other Parameters
Code the OUTPUT parameter only on a DD statement with the SYSOUT or SUBSYS parameter.

With INTRDR Subparameter in SYSOUT Parameter

Do not code an OUTPUT parameter when the SYSOUT parameter specifies a JES2 internal reader by an INTRDR parameter.

Null Subparameters

A null first subparameter is invalid in a FLASH or MODIFY parameter on a DD statement, but is permitted on an OUTPUT JCL statement. For example, MODIFY=(,3) is valid only on an OUTPUT JCL statement.

SYSOUT Third Subparameter

You cannot reference a JES2 /*OUTPUT statement using the third subparameter of the SYSOUT parameter if either of the following is also coded:

  • The OUTPUT parameter on the same DD statement.
  • An OUTPUT JCL statement containing DEFAULT=YES in the same step or before the EXEC statement of the job, when the DD statement does not contain an OUTPUT parameter.

DEFAULT Parameter on OUTPUT JCL Statement

If you code DEFAULT=YES on an OUTPUT JCL statement, you can still refer to that OUTPUT JCL statement in the OUTPUT parameter of a sysout DD statement.

6.Location in the JCL
All referenced OUTPUT JCL statements must precede the DD statement that refers to them. If the referencing DD statement appears in an in-stream or cataloged procedure, the referenced OUTPUT JCL statement must precede the DD statement in the procedure. A sysout DD statement in a procedure cannot refer to an OUTPUT JCL statement in the calling step.

7.No Match for OUTPUT Name
If the system finds no match for the name coded in the OUTPUT parameter, the system issues a JCL error message and fails the job.

8.Processing Options in Multiple References
A sysout DD statement can refer to more than one OUTPUT JCL statement, either explicitly in an OUTPUT parameter containing more than one reference or implicitly when several default OUTPUT JCL statements apply. The processing options for a sysout data set come from one sysout DD statement and one OUTPUT JCL statement. In multiple references, each combination of sysout DD statement and one of the referenced OUTPUT JCL statements produces a separate set of printed or punched output.

Processing options are not cumulative across a group of OUTPUT JCL statements.

Note that in JES3, when TYPE=DSISO and/or TRUNC=YES|NO are specified on the SYSOUT initialization statement, and a sysout DD statement that does not specify a class references multiple OUTPUT statements, the data set DSISO/TRUNC characteristics are derived from the first class specification encountered in the OUTPUT statements. If the DD statement does specify a class, the DSISO/TRUNC characteristics are derived from that class.

9.Examples of the OUTPUT Parameter

Example 

//J1     JOB      ,’MARY LUDWIG’
//JOUT   OUTPUT   CLASS=C,FORMS=RECP,INDEX=6
//STEP1  EXEC     PGM=XYZ
//SOUT   OUTPUT   CLASS=H,BURST=YES,CHARS=GT12,FLASH=BLHD
//ALL    DD       SYSOUT=(,),OUTPUT=(*.JOUT,*.SOUT),COPIES=5
//IN     DD       *
         .
        (data)
         .
/*

The OUTPUT parameter references two OUTPUT JCL statements. Therefore, the system prints the single sysout data set twice:

  • For DD ALL combined with OUTPUT JOUT, the sysout data set is printed in class C. In the installation, output class C is printed on a 3211 Printer. Combining the parameters from the DD and OUTPUT JCL statements, the system prints 5 copies of the data set on form RECP and indents the left margin 5 spaces.
  • For DD ALL combined with OUTPUT SOUT, the sysout data set is printed in class H. In the installation, output class H is printed on a 3800 Printing Subsystem. Combining the parameters from the DD and OUTPUT JCL statements, the system prints 5 copies of the data set with the forms-overlay frame named BLHD using character-arrangement table GT12 and bursts the output.

Example 

//J6      JOB       ,’SUE THACKER’
//OUTA    OUTPUT    DEST=HQ
//STEP1   EXEC      PGM=RDR
//OUTB    OUTPUT    CONTROL=DOUBLE
//DS1     DD        SYSOUT=A,OUTPUT=(*.OUTA,*.OUTB)
//STEP2   EXEC      PGM=WRT
//OUTC    OUTPUT    DEST=ID2742
//DS2     DD        SYSOUT=A,OUTPUT=(*.OUTC,*.STEP1.OUTB)

The OUTPUT parameter on DS1 references:

  • The job-level OUTPUT JCL statement OUTA to send the sysout data set to HQ.
  • The step-level OUTPUT JCL statement OUTB to print the sysout data set double-spaced on the local 3800 Printing Subsystem used for output class A. The OUTPUT parameter on DS2 references:
  • OUTPUT JCL statement OUTB in the first step to print the sysout data set double-spaced on the local 3800 Printing Subsystem used for output class A.
  • OUTPUT JCL statement OUTC in the same step to send the sysout data set to userid ID2742, which is attached to the local system.

Note: The references to OUTPUT JCL statements are in no particular order.

PATH parameter

Parameter Type

Keyword, optional — use this parameter only with an HFS file

Purpose

Use the PATH parameter to specify the name of the HFS file.

1.Syntax

PATH=pathname
  • Enclose the pathname value in single quotes if it contains a character other than:
  •   Uppercase letters
      Numbers
      National characters
      Slash (/)
      Asterisk (*)
      Plus (+)
      Hyphen (-)
      Period (.)
      Ampersand (&)
  • Enclose the pathname value in single quotes if you continue it on another statement. For example:
//EXA   DD   PATH=’/u/payroll/directory171/DEPT64directory/account
//           ingDIR/personhoursfile’

2.Subparameter Definition

pathname
Identifies a file in a hierarchical file system (HFS). The pathname consists of the names of the directories from the root to the file being identified, and then the name of the file.

Each directory or filename:

  • Is preceded by a slash (/). The system treats any consecutive slashes as a single slash.
  • Can contain symbolic parameters.
  • Has a length of 1 through 254 characters, not including the slash.
  • Consists of printable characters from X’40’ through X’FE’. These printable characters include all the characters that can be used in a portable filename, plus additional characters. For a portable filename, use only the portable filename character set. A filename can contain characters outside this range, but it cannot be specified in JCL.
  • Is subject to symbolic substitution. An ampersand (&) (X'50'), followed by a character string that matches a valid symbolic parameter in the JCL, causes a substitution to occur, based on the syntax rules for symbolic parameters.
  • Is case-sensitive. Thus, /u/joe and /u/JOE and /u/Joe define three different files.

The pathname:

  • Has the form:
  • /name1/name2/name3/.../namen
  • Begins with a slash.
  • Has a length of 1 through 255 characters. The system checks the length after substituting for any symbols and before compressing any consecutive slashes.

3.Defaults
Defaults for a DD statement with a PATH parameter are:

  • If the PATHDISP parameter is not specified, the normal and abnormal disposition is KEEP.
  • If the PATHOPTS parameter is not specified, the status is OLD.

4.Relationship to Other Parameters
You can code the following parameters with the PATH parameter:

BLKSIZE
BUFNO
DSNTYPE
DUMMY
FILEDATA
LRECL
NCP
PATHDISP
PATHMODE
PATHOPTS
RECFM
TERM

Do not code PATHDISP, PATHMODE, or PATHOPTS on a DD statement without a PATH parameter.

Do not code a PATH parameter on the following DD statements:

JOBCAT
JOBLIB
STEPCAT
STEPLIB
SYSABEND
SYSMDUMP
SYSUDUMP

Coding the PATH parameter is useful only when one of the following is true:

  • The job runs on a system with both MVS SP5.2.2 or later and DFSMS/MVS 1.3. At this level, programs can use standard MVS access methods to work with hierarchical files.
  • The program being run has been coded to recognize and process the PATH specification. Programs designed to use such DD statements must either:
  • – Use dynamic allocation information retrieval to obtain the information specified for PATH, PATHOPTS, and PATHMODE, and pass it to the open() callable service.
    – Use the C/370 fopen(//dd: ) function. fopen() handles the differences between DD statements with PATH and DSN specified.

If:

  • You specify either:
  • – OCREAT alone

    or:
    – Both OCREAT and OEXCL

    on the PATHOPTS parameter

    And if:

  • The file does not exist,

Then MVS performs an open() function. The options from PATHOPTS, the pathname from the PATH parameter, and the options from PATHMODE (if specified) are used in the open(). MVS uses the close() function to close the file before the application program receives control.

For status group options other than OCREAT and OEXCL, the description in this,assumes that the application passes the subparameters to the open() function without modification. That is, this application uses dynamic allocation information retrieval (the DYNALLOC macro) to retrieve the values specified for PATHOPTS and passes the values to the open() function. The application program can ignore or modify the information specified in the JCL.

5.Relationship to Other Statements
A PATH parameter other than /dev/null on a DD statement that overrides a procedure statement nullifies the DUMMY parameter on the overridden statement.

Backward and forward references to a DD statement containing a PATH parameter are not permitted. For backward references, the referring DD statement is treated as an error. For forward references, the DD statement referred to is treated as an error.

6.Dummy HFS Files
The following DD statements define a dummy HFS file. The statements are equivalent; for DUMMY3, the extra slashes (/) are compressed to single slashes.

//DUMMY1   DD    PATH=’/dev/null’
//DUMMY2   DD    DUMMY,PATH=/ANYNAME
//DUMMY3   DD    PATH=’//dev///null’

The system checks the syntax of pathnames specified with DUMMY. In the DD statement DUMMY2, the pathname must be a valid name.

7.Example of the PATH Parameter

//DD1      DD     PATH=’/usr/applics/pay.time’,PATHOPTS=ORDONLY

The DD statement specifies the HFS file pay.time that is listed in the directory applics. The directory applics is listed in the directory usr. The PATHOPTS parameter specifies that the program can only read the file.

The effects of the missing PATH parameters are:

  • The file must already exist, because the statement does not specify PATHOPTS=OCREAT.
  • The system will keep the file for both normal and abnormal step terminations, because the statement does not contain a PATHDISP parameter.
  • The access permissions were set with a PATHMODE parameter when the file was created.

PATHDISP parameter

Parameter Type

Keyword, optional — use this parameter only with an HFS file

Purpose

Use the PATHDISP parameter to specify the disposition of an HFS file when the job step ends normally or abnormally.

1.Syntax

PATHDISP={normal-termination-disposition }
        ={(normal-termination-disposition,
abnormal-termination-disposition)}
PATHDISP=([KEEP ][,KEEP ]) =([DELETE][,DELETE])

A normal-termination-disposition or abnormal-termination-disposition is one of the following:

             KEEP
             DELETE
  • If you omit the normal-termination-disposition parameter, you must code a comma to indicate its absence. For example: PATHDISP=(,DELETE)
  • If you code only the normal-termination-disposition parameter, you may omit the enclosing parentheses.

2.Subparameter Definition

KEEP
Specifies that the file should be kept:

  • When the step ends normally, KEEP is the first subparameter.
  • When the step ends abnormally, KEEP is the second subparameter.

DELETE
Specifies that the file should be deleted:

  • When the step ends normally, DELETE is the first subparameter.
  • When the step ends abnormally, DELETE is the second subparameter.

Deleting a file deletes the name for the file. If the file has other names created by link() functions, DELETE does not delete the file itself. The file persists until all of its names are deleted.

3.Defaults
The system uses KEEP for both the normal and abnormal dispositions:

  • If you do not code a value on the PATHDISP parameter — for example, PATHDISP=(,)
  • If you do not code a PATHDISP on a DD statement with a PATH parameter If you code only a normal-termination-disp, such as PATHDISP=DELETE, the abnormal disposition is the same as the normal disposition.

If you code only an abnormal-termination-disp, such as PATHDISP=(,DELETE), the system uses KEEP for the normal disposition.

4.Relationship to Other Parameters
Code the PATHDISP parameter only on a DD statement that contains a PATH parameter. You can code the following parameters with the PATHDISP parameter:

BLKSIZE
BUFNO
DSNTYPE
DUMMY
FILEDATA
LRECL
NCP
PATH
PATHMODE
PATHOPTS
RECFM
TERM

5.Example of the PATHDISP Parameter

//DD1     DD     PATH=’/usr/applics/pay.time’,PATHDISP=(KEEP,DELETE)

The DD statement identifies a file that already exists. The DD statement requests that the system keep the file, if the step ends normally. If the step ends abnormally, the system deletes the filename and, if no other names were set using link(), deletes the file itself.

PATHMODE parameter

Parameter Type

Keyword, optional — use this parameter only with an HFS file

Purpose

Use the PATHMODE parameter to specify the file access attributes when the system is creating the HFS file named on the PATH parameter. Creating the file is specified by a PATHOPTS=OCREAT parameter.

1.Syntax

PATHMODE={file-access-attribute }
  {(file-access-attribute[,file-access-attribute]...)}

A file-access-attribute is one of the following:

For file owner class:      SIRUSR
                           SIWUSR
                           SIXUSR
                           SIRWXU
For file group class: SIRGRP SIWGRP SIXGRP SIRWXG
For file other class: SIROTH SIWOTH SIXOTH SIRWXO
To set user and group IDs: SISUID SISGID
  • You can specify up to 14 file-access-attributes.
  • The file-access-attributes can be in any order.
  • Duplicate file-access-attributes are treated as one specification.
  • Do not code null positions. For example, do not code PATHMODE=(,file-access-attribute) or PATHMODE=(file-access-attribute,,file-access-attribute).

2.Subparameter Definition

For File Owner Class
The file owner class consists of the user who created the file or who currently owns the file. The user is identified by an OMVS user ID (UID).
SIRUSR
Specifies permission for the file owner to read the file.
SIWUSR
Specifies permission for the file owner to write the file.
SIXUSR
Specifies permission for the file owner either:

  • To search, if the file is a directory
  • To execute the program in the file, for a file other than a directory

SIRWXU
Specifies permission for the file owner either:

  • To read, write, and search, if the file is a directory
  • To read, write, and execute, for a file other than a directory

This value has the same effect as specifying all three parameters (SIRUSR, SIWUSR, and SIXUSR).

For File Group Class
The file group class contains the users who are in the same group as the file. The group is identified by an OMVS group ID (GID).

SIRGRP

Specifies permission for users in the file group class to read the file.

SIWGRP
Specifies permission for users in the file group class to write the file.

SIXGRP
Specifies permission for users in the file group class either:

  • To search, if the file is a directory
  • To execute the program in the file, for a file other than a directory

SIRWXG
Specifies permission for users in the file group class either:

  • To read, write, and search, if the file is a directory
  • To read, write, and execute, for a file other than a directory

This value has the same effect as specifying all three parameters (SIRGRP, SIWGRP, and SIXGRP).

For File Other Class
The file other class consists of all users other than the file owner or the members of the file’s group who can access z/OS UNIX resources on the MVS system.

SIROTH
Specifies permission for users in the file other class to read the file.

SIWOTH
Specifies permission for users in the file other class to write the file.

SIXOTH
Specifies permission for users in the file other class either:

  • To search, if the file is a directory
  • To execute the program in the file, for a file other than a directory

SIRWXO
Specifies permission for users in the file other class either:

  • To read, write, and search, if the file is a directory
  • To read, write, and execute, for a file other than a directory

This value has the same effect as specifying all three parameters (SIROTH, SIWOTH, and SIXOTH).

To Set User and Group IDs in a Program
These controls allow users to run a program with the user ID of the file owner or the group ID of the file owner of the program file. They control access authorization a particular program is running. The file owner can set the controls any time, not just in the DD statement. Do not specify these controls in JCL, because they will be reset when the file is written. The system overrides the SISUID and SISGID parameters and sets the controls so that no users can run the program when either:

  • The DD statement creates the file
  • A user writes in the file, thus changing the program

Then, for the program to be run, the file owner must reset the controls.

SISUID
Specifies that the system set the user ID of the process to be the same as the user ID of the file owner when the file is run as a program.

SISGID
Specifies that the system set the group ID of the process to be the same as the group ID of the file owner when the file is run as a program. The group ID is taken from the directory in which the file resides.

3.Defaults
When creating a new HFS file, if you do not code a PATHMODE on a DD statement with a PATH parameter, the system sets the permissions to 0, which prevents access by all users. If the HFS file already exists, PATHMODE is checked for syntax but ignored. The permission bits are left as they are set.

4.Relationship to Other Parameters
Code the PATHMODE parameter only on a DD statement that contains both a PATH parameter and a PATHOPTS parameter with OCREAT. If OCREAT is not on the statement, the PATHMODE parameter is checked for syntax and then ignored. You can code the following parameters with the PATHMODE parameter:

BLKSIZE
BUFNO
DSNTYPE
DUMMY
FILEDATA
LRECL
NCP
PATH
PATHMODE
PATHOPTS
RECFM
TERM

If:

  • You specify either:
  • – OCREAT alone 

    or:
    – Both OCREAT and OEXCL on the PATHOPTS parameter,

    And if:
  • The file does not exist, Then MVS performs an open() function. The options from PATHOPTS, the pathname from the PATH parameter, and the options from PATHMODE (if specified) are used in the open(). MVS uses the close() function to close the file before the application program receives control. 

For status group options other than OCREAT and OEXCL, the description in this book assumes that the application passes the subparameters to the open() function without modification. That is, this application uses dynamic allocation information retrieval (the DYNALLOC macro) to retrieve the values specified for PATHOPTS and passes the values to the open() function. The application program can ignore or modify the information specified in the JCL.

5.Example of the PATHMODE Parameter

//DD1   DD   PATH=’/usr/applics/pay.time’,PATHDISP=(KEEP,DELETE),
//           PATHOPTS=(OWRONLY,OCREAT,OEXCL),PATHMODE=(SIRWXU,SIRGRP)

The DD statement requests that the file named in the PATH parameter be created. The PATHMODE parameter specifies that the file owner can read, write, and search or execute the file and that users in the file group can read the file.

PATHOPTS parameter

Parameter Type

Keyword, optional — use this parameter only with an HFS file

Purpose

Use the PATHOPTS parameter to specify the access and status for the HFS file named in the PATH parameter.

1.Syntax

PATHOPTS={file-option }
         {(file-option[,file-option]...)}

A file-option can be in the access or status group and is one of the following:

Access group: ORDONLY
              OWRONLY
              ORDWR
Status group: OAPPEND
OCREAT OEXCL ONOCTTY ONONBLOCK OSYNC OTRUNC
  • You can specify up to 7 file-options.
  • The file-options can be in any order.
  • Code only one file-option from the access group. If you specify more than one file-option from the access group, the system uses ORDWR as the access.
  • Code any combination of file-options from the status group.
  • Duplicate file-options are treated as one specification.
  • Do not code null positions. For example, do not code PATHOPTS=(,file-option) or PATHOPTS=(file-option,,file-option).

2.Subparameter Definition

Access Group

ORDONLY
Specifies that the program should open the file for reading.
OWRONLY
Specifies that the program should open the file for writing.
ORDWR
Specifies that the program should open the file for reading and writing. Do not use this option for a FIFO special file.

Status Group

OAPPEND
Specifies that MVS sets the file offset to the end of the file before each write, so that data is written at the end of the file.
OCREAT
Specifies that:

  • If the file does not exist, the system is to create it. If a directory specified in the pathname does not exist, one is not created, and the new file is not created.
  • If the file already exists and OEXCL was not specified, the system allows the program to use the existing file.
  • If the file already exists and OEXCL was specified, the system fails the allocation and the job step.

OEXCL
Specifies that:

  • If the file does not exist, the system is to create it.
  • If the file already exists, the system fails the allocation and the job step. The system ignores OEXCL if OCREAT is not also specified.

ONOCTTY
Specifies that if the PATH parameter identifies a terminal device, opening of the file does not make the terminal device the controlling terminal for the process.
ONONBLOCK
Specifies the following, depending on the type of file:

  • For a FIFO special file:
  • – With ONONBLOCK specified and ORDONLY access: An open() function for reading-only returns without delay.
    – With ONONBLOCK not specified and ORDONLY access: An open() function for reading-only blocks (waits) until a process opens the file for writing.
    – With ONONBLOCK specified and OWRONLY access: An open() function for writing-only returns an error if no process currently has the file open for reading.
    – With ONONBLOCK not specified and OWRONLY access: An open() function for writing-only blocks (waits) until a process opens the file for reading.
  • For a character special file that supports nonblocking open:
  • – If ONONBLOCK is specified: An open() function returns without blocking (waiting) until the device is ready or available. Device response depends on the type of device.
    – If ONONBLOCK is not specified: An open() function blocks (waits) until the device is ready or available.

Specification of ONONBLOCK has no effect on other file types. OSYNC Specifies that the system is to move data from buffer storage to permanent storage before returning control from a callable service that performs a write.
OTRUNC
Specifies that the system is to truncate the file length to zero if all the following are true:

  • The file specified on the PATH parameter exists.
  • The file is a regular file.
  • The file successfully opened with ORDWR or OWRONLY.

The system does not change the mode and owner. OTRUNC has no effect on FIFO special files or character special files.

3.Defaults
If you do not code a value on the PATHOPTS parameter or if you do not code a PATHOPTS on a DD statement with a PATH parameter, the system assumes that the pathname exists, searches for it, and issues a message if the pathname does not exist.

If the file exists and you specify PATHOPTS without a file-option for the access group, the allocation succeeds. If the file does not exist and you specify PATHOPTS without a file-option from the access group, the system fails to open the file and issues a message.

4.Relationship to Other Parameters
Code the PATHOPTS parameter only on a DD statement that contains a PATH parameter.

You can code the following parameters with the PATHOPTS parameter:

BLKSIZE
BUFNO
DSNTYPE
DUMMY
FILEDATA
LRECL
NCP
PATH
PATHMODE
PATHOPTS
RECFM
TERM

If:

  • You specify either:
  • – OCREAT alone 

    or:
    – Both OCREAT and OEXCL on the PATHOPTS parameter,

    And if:
  • The file does not exist,

Then MVS performs an open() function. The options from PATHOPTS, the pathname from the PATH parameter, and the options from PATHMODE (if specified) are used in the open(). MVS uses the close() function to close the file before the application program receives control.

For status group options other than OCREAT and OEXCL, the description in this, assumes that the application passes the subparameters to the open() function without modification. That is, this application uses dynamic allocation information retrieval (the DYNALLOC macro) to retrieve the values specified for PATHOPTS and passes the values to the open() function. The application program can ignore or modify the information specified in the JCL.

5.File Status
The MVS system uses the PATHOPTS parameter to determine the status for the file, as follows:

  • OLD status:
  • -PATHOPTS is not on the DD statement.
    -PATHOPTS does not contain a file option.
    -PATHOPTS does not contain OCREAT.
  • MOD status: PATHOPTS contains OCREAT but not OEXCL.
  • NEW status: PATHOPTS contains both OCREAT and OEXCL.

Note: The DISP parameter cannot appear on a DD statement containing the PATH parameter.

6.Example of the PATHOPTS Parameter

//DD1    DD    PATH=’/usr/applics/pay.time’,PATHDISP=(KEEP,DELETE),
//             PATHOPTS=(OWRONLY,OCREAT,OEXCL),PATHMODE=(SIRWXU,SIRGRP)

OCREAT in the PATHOPTS parameter specifies that the file named in the PATH parameter be created. OWRONLY requests that the system open the file only for writing. OEXCL specifies that, if the file already exists, the system will not create a file and the job step will fail.

PROTECT parameter

Parameter Type

Keyword, optional

Use the PROTECT parameter only if RACF is installed and active. With SMS, use the SECMODEL parameter to protect data sets;

Purpose
Use the PROTECT parameter to tell the z/OS Security Server, which includes RACF, to protect:

  • One data set on a direct access volume.
  • One data set on a tape volume with one of the following types of labels:
  • – IBM standard labels, LABEL=(,SL) or LABEL=(,SUL)
    – ISO/ANSI/FIPS Version 3 labels, LABEL=(,AL) or LABEL=(,AUL)
    – Nonstandard labels, LABEL=(,NSL), if the installation provides support
  • An entire tape volume with one of the following:
  • – IBM standard labels, LABEL=(,SL) or LABEL=(,SUL)
    – ISO/ANSI/FIPS Version 3 labels, LABEL=(,AL) or LABEL=(,AUL)
    – Nonstandard labels, LABEL=(,NSL), if the installation provides support
    – No labels, LABEL=(,NL)
    – Bypassed label processing, LABEL=(,BLP)
    – Leading tapemarks, LABEL=(,LTM)

1.Syntax

PROTECT= {YES}
         {Y }

2.Subparameter Definition

YES
Requests RACF to protect a direct access data set, tape data set, or tape volume. This parameter can also be coded as Y.

3.Overrides
With SMS, the DD SECMODEL parameter overrides the PROTECT=YES parameter.

4.Relationship to Other Parameters
Do not code the following parameters with the PROTECT parameter.

*        DLM       QNAME
BURST    DYNAM     SYSOUT
CHARS    FCB       TERM
DATA     FLASH     UCS
DDNAME   MODIFY

DSNAME Parameter for RACF-Protected Data Sets

RACF expects the data set name specified in the DSNAME parameter to have a high-level qualifier that is defined to RACF.

5.Requirements for Protecting a Tape Data Set
A DD statement that contains a PROTECT parameter to establish RACF protection for a tape data set must:

  • Specify or imply VOLUME=PRIVATE.
  • Specify or imply DISP=NEW, DISP=OLD, or DISP=SHR; it must not specify or imply DISP=MOD.
  • Specify in the LABEL parameter a label type of:
  • – SL or SUL for IBM standard labels.
    – AL or AUL for ISO/ANSI Version 1 or ISO/ANSI/FIPS Version 3 tape labels.
    – NSL for nonstandard labels. In this case, the NSL installation exit routine must issue a RACDEF or RACROUTE TYPE=DEFINE macro instruction.
  • If the data set is not the first on the volume, specify a data-set-sequence-number in the LABEL parameter, which requires that the RACF TAPEDSN option be active.

6.Requirements for Protecting a Tape Volume
A DD statement that contains a PROTECT parameter to establish RACF protection for a tape volume must:

  • Specify or imply VOLUME=PRIVATE.
  • Specify or imply DISP=NEW.
  • Specify in the LABEL parameter a label type of:
  • – SL or SUL for IBM standard labels.
    – AL or AUL for ISO/ANSI Version 1 or ISO/ANSI/FIPS Version 3 tape labels.
    –  NSL for nonstandard labels. In this case, the NSL installation exit routine must issue a RACDEF or RACROUTE TYPE=DEFINE macro instruction.
    – NL for no labels.
    – BLP for bypass label processing.
    – LTM for leading tapemark.

Note that RACF cannot fully protect unlabeled tapes because RACF cannot verify the volume serial number directly; the operator must verify the volume serial number when mounting the tape volume.

7.Requirements for Protecting a Direct Access Data Set
A DD statement that contains a PROTECT parameter to establish RACF protection for a direct access data set must:

  • Name a permanent data set in the DSNAME parameter.
  • Specify a status of DISP=NEW or MOD treated as NEW. RACF can establish protection only when the data set is being created.

8.Examples of the PROTECT Parameter

Example 

//DASD   DD   DSNAME=USER37.MYDATA,DISP=(,CATLG),
//            VOLUME=SER=333000,UNIT=3330,SPACE=(TRK,2),PROTECT=YES

This DD statement requests RACF protection for the new direct access data set USER37.MYDATA.

Example 

//TAPEVOL   DD   DSNAME=MHB1.TAPEDS,DISP=(NEW,KEEP),LABEL=(,NL),
//               VOLUME=SER=T49850,UNIT=3400-5,PROTECT=YES

This DD statement requests RACF protection for tape volume T49850. Because a specific tape volume is requested, it automatically has the PRIVATE attribute. The volume has no labels.

Example 

//TAPEDS   DD   DSNAME=INST7.NEWDS,DISP=(NEW,CATLG),LABEL=(2,SUL),
//              VOLUME=SER=223344,UNIT=3400-5,PROTECT=YES

This DD statement requests RACF protection for INST7.NEWDS, which is the second data set on tape volume 223344. Because a specific tape volume is requested, it automatically has the PRIVATE attribute. The volume has IBM standard and user labels; the RACF TAPEDSN option must be active.

QNAME parameter

Parameter Type
Keyword, optional

Purpose
Use the QNAME parameter to indicate that this DD statement defines a data set of telecommunications access method (TCAM) messages. The QNAME parameter refers to a TPROCESS macro instruction that defines a destination queue for the messages. Optionally, the QNAME parameter can also name a TCAM job to process the messages.

1.Syntax

QNAME=procname[.tcamname]

2.Subparameter Definition

procname
Identifies a TPROCESS macro instruction; procname must be identical to the procname in the name field of the TPROCESS macro instruction.

tcamname
Names a TCAM job: tcamname must be identical to the jobname. The TCAM job can be a task started by an operator START command.

3.Relationship to Other Parameters
The only DD parameters that you can code with the QNAME parameter are DCB, LIKE, LRECL, RECFM, and REFDD. The only DCB subparameters that you can code with the QNAME parameter are: BLKSIZE, BUFL, LRECL, OPTCD, and RECFM.

4.Examples of the QNAME Parameter

Example 

//DYD   DD   QNAME=FIRST,DCB=(RECFM=FB,LRECL=80,BLKSIZE=320)

This DD statement defines a data set of TCAM messages. FIRST is the name of the TPROCESS macro instruction that specifies the destination queue to which the messages are routed. The DCB parameter supplies information not supplied in the program’s DCB macro instruction for the data control block.

Example 

//DXD   DD   QNAME=SECOND.TCAM01

This DD statement defines a data set of TCAM messages. SECOND is the name of the TPROCESS macro instruction that specifies the destination queue to which the messages are routed. TCAM program TCAM01 will process the messages.

RECFM parameter

Parameter Type

Keyword, optional

Purpose

Use the RECFM parameter to specify the format and characteristics of the records in a new data set. All the format and characteristics must be completely described in one source, that is, in the data set label of an existing data set, in the DCB macro, in the DD DCB parameter, or in the DD RECFM parameter. However, the processing program can modify the RECFM field in the DCB.

Code the RECFM parameter when you want to (1) specify the record format for the data set or (2) with SMS, override the record format defined in the data class of the data set.

The syntax of the RECFM parameter is described in the following topics:

  • Coding RECFM for BDAM Access Method
  • Coding RECFM for BPAM Access Method
  • Coding RECFM for BSAM, EXCP, and QSAM Access Methods
  • Coding RECFM for QISAM Access Method
  • Coding RECFM for TCAM Access Method

1.Coding RECFM for BDAM Access Method

Syntax: BDAM Access Method

2.Coding RECFM for BPAM Access Method

Syntax: BPAM Access Method

3.Coding RECFM for BSAM, EXCP, and QSAM Access Methods

Syntax: BSAM, EXCP, and QSAM Access Methods

4.Syntax: QISAM Access Method

Coding RECFM for TCAM Access Method
Syntax: TCAM Access Method

5.Overrides
RECFM overrides the record format specified in the data set label, and with SMS, RECFM overrides the record format defined in the DATACLAS parameter for the data set.

6.Relationship to Other Parameters
Do not code the following DD parameters with the RECFM parameter.

*              DDNAME
AMP            DYNAM
DATA           RECORG
DCB=DSORG
DCB=RECFM

7.Examples of the RECFM Parameter

Example 

//DD1B   DD   DSNAME=EVER,DISP=(NEW,KEEP),UNIT=3380,
//            RECFM=FB,LRECL=326,SPACE=(23472,(200,40))

In the example, the record format of fixed block (FB) is used for the new data set EVER.

Example 

//SMSDS6    DD    DSNAME=MYDS6.PGM,DATACLAS=DCLAS06,DISP=(NEW,KEEP),
//                RECFM=FB

In the example, the record format of fixed block (FB) overrides the record format defined in the data class for the data set.

RECORG Parameter

Parameter Type

Keyword, optional — use this parameter only with SMS

Without SMS, see the AMP parameter described.

Purpose
Use the RECORG parameter to specify the organization of the records in a new VSAM data set.

Code the RECORG parameter when you want to (1) specify the record organization for the data set or (2) override the record organization defined in the data class of the data set.

If SMS is not installed or is not active, the system syntax checks and then ignores the RECORG parameter.

1.Syntax

        {KS}
RECORG= {ES}
        {RR}
        {LS}

2.Subparameter Definition

KS
Specifies a VSAM key-sequenced data set.
ES
Specifies a VSAM entry-sequenced data set.
RR
Specifies a VSAM relative record data set.
LS
Specifies a VSAM linear space data set.

3.Defaults
If you do not specify RECORG, SMS assumes a physical sequential (PS) or
partitioned (PO) data set.

4.Overrides
The RECORG parameter overrides the record organization defined in the DATACLAS parameter for the data set.

5.Relationship to Other Parameters
Do not code the following DD parameters with the RECORG parameter.

*             DDNAME
DATA          DSNTYPE           
DCB=DSORG     DYNAM     
DCB=RECFM     RECFM      
FREE=CLOSE     

6.Example of the RECORG parameter

//SMSDS3   DD   DSNAME=MYDS3.PGM,DATACLAS=VSAM1,DISP=(NEW,KEEP),
//              RECORG=KS

In the example, the record organization of key-sequenced (KS) overrides the record organization defined in the data class.

REFDD parameter

Parameter Type

Keyword, optional — use this parameter only with SMS

Without SMS, use the DCB=*.ddname form of the DCB parameter described.

Purpose

Use the REFDD parameter to specify attributes for a new data set by copying attributes of a data set defined on an earlier DD statement in the same job.

The following attributes are copied to the new data set from (1) the attributes specified on the referenced DD statement, and (2) for attributes not specified on the referenced DD statement, from the data class of the data set specified by the referenced DD statement:

  • Data set organization
  • – Record organization (RECORG) or
    – Record format (RECFM)
  • Record length (LRECL)
  • Key length (KEYLEN)
  • Key offset (KEYOFF)
  • Type, PDS or PDSE (DSNTYPE)
  • Space allocation (AVGREC and SPACE)

Only RECFM and LRECL apply to tape data sets. REFDD does not copy DCB attributes from the data set label.

If SMS is not installed or is not active, the system checks the syntax and then ignores the REFDD parameter. The retention period (RETPD) or expiration date (EXPDT) is not copied to the new data set.

Note: Do not use the REFDD parameter to copy attributes from a temporary data set (&&dsname), partitioned data set if a member name is included, and relative generation number for a GDG.

1.Syntax

       {*.ddname }
REFDD= {*.stepname.ddname }
       {*.stepname.procstepname.ddname}

2.Subparameter Definition

*.ddname
*.stepname.ddname
*.stepname.procstepname.ddname
Specify a backward reference to an earlier DD statement. The referenced DD statement cannot name a cataloged data set or refer to another DD statement.

*.ddname
Specifies the ddname of an earlier DD statement in the same step.

*.stepname.ddname
Specifies the ddname of a DD statement in an earlier step, stepname, in the same job.

*.stepname.procstepname.ddname
Specifies the ddname of a DD statement in a cataloged or in-stream procedure called by an earlier job step. Stepname is the name of the job step that calls the procedure and procstepname is the name of the procedure step that contains the DD statement.

Do not reference a DD * or a DD DATA statement.

3.Overrides
Any attributes specified on the referenced DD statement override the
corresponding data class attributes of the referenced data set.

Any attributes you specify on the referencing DD statement with the following parameters override the corresponding attributes obtained from the referenced DD statement and the data class attributes of the referenced data set.

RECORG (record organization) or RECFM (record format)
LRECL (record length)
KEYLEN (key length)
KEYOFF (key offset)
DSNTYPE (type, PDS or PDSE)
AVGREC (record request and space quantity)
SPACE (average record length, primary, secondary, and directory quantity)

4.Relationship to Other Parameters

Do not code the following DD parameters with the REFDD parameter.

DYNAM
LIKE

5.Examples of the REFDD Parameter

Example 

//SMSDS6   DD   DSNAME=MYDS6.PGM,DATACLAS=DCLAS01,DISP=(NEW,KEEP),
//              LRECL=512,RECFM=FB
//SMSDS7   DD   DSNAME=MYDS7.PGM,REFDD=*.SMSDS6,DISP=(NEW,KEEP)

In the example, the data set attributes used for MYDS7.PGM are obtained from the referenced data set MYDS6.PGM.

Example 

//SMSDS6  DD   DSNAME=MYDS6.PGM,DATACLAS=DCLAS01,DISP=(NEW,KEEP),
//              LRECL=512,RECFM=FB
//SMSDS8   DD   DSNAME=MYDS8.PGM,REFDD=*.SMSDS6,DISP=(NEW,KEEP),
//              LRECL=1024

In the example, the data set attributes used for MYDS8.PGM are obtained from the referenced data set MYDS6.PGM. Also, the logical record length of 1024 overrides the logical record length obtained from the referenced data set.

RETPD Parameter

Parameter Type

Keyword, optional

Purpose
Use the RETPD parameter to specify the retention period for a new data set to help reduce the chance of later accidental deletion. After the retention period, the data set can be deleted or written over by another data set.

If the DD statement contains DISP=(NEW,DELETE) or the DISP parameter is omitted to default to NEW and DELETE, the system deletes the data set when the step terminates normally or abnormally, even though a retention period is also specified.

Do not specify RETPD for a temporary data set. The RETPD parameter achieves the same result as the EXPDT parameter.

Code the RETPD parameter when you want to (1) specify a retention period for the data set or (2) with SMS, override the retention period defined in the data class for the data set.

1.Syntax

RETPD=nnnn
  • The RETPD parameter can have a null value only when coded on a DD which either:
  • – Overrides a DD in a procedure
    – Is added to a procedure.

2.Subparameter Definition
nnnn
Specifies the retention period, in days, for the data set. The nnnn is one through four decimal digits (0 - 9999). The system adds nnnn to the current date to produce an expiration date. For SMS data sets, the system adds nnnn to the data set creation date to produce an expiration date. The calculated expiration date uses 365-day years and 366-day leap years.

Note: If you code RETPD and the calculated expiration date is December 31, 1999, the expiration date is set to January 1, 2000.

3.Overrides
With SMS, RETPD overrides the retention period defined in the DATACLAS parameter for the data set. With SMS, both the retention period specified on RETPD and defined in the data class for an SMS-managed data set can be limited by a maximum retention period defined in the management class for the data set.

4.Relationship to Other Parameters
Do not code the following DD parameters with the RETPD parameter.

*         DYNAM
DATA      EXPDT
DDNAME    SYSOUT

5.Deleting a Data Set Before its Retention Period Passes
To delete a data set before the retention period has passed, use one of the following:

  • For data sets cataloged in an integrated catalog facility catalog, use the DELETE command, as described in z/OS DFSMS Access Method Services for Catalogs.
  • For data sets not cataloged in an integrated catalog facility catalog, use the IEHPROGM utility, as described in z/OS DFSMSdfp Utilities.
  • For a non-VSAM data set, use the SCRATCH macro with the OVRD parameter, as described in z/OS DFSMSdfp Advanced Services.
  • The system operator can reply ²u² to the IEC507D message prompt to delete unexpired data sets.
  • You can override the retention period for SMS-managed DASD data sets by specifying OVRD_EXPDT(YES) in the IGDSMSxx SYS1.PARMLIB member and specifying DELETE on the DD DISP statement. The data set will be deleted whether or not the retention period has passed.

6.Examples of the RETPD Parameter

Example 

//DD1   DD   DSNAME=HERBI,DISP=(NEW,KEEP),UNIT=TAPE,
//           VOLUME=SER=T2,LABEL=(3,NSL),RETPD=188

In the example, the data set is not eligible for being deleted or written over for 188 days.

Example 

//SMSDS2   DD   DSNAME=MYDS2.PGM,DATACLAS=DCLAS02,DISP=(NEW,KEEP),
//              RETPD=732

In the example, the retention period of 732 days overrides the retention period defined in the data class for the data set.

RLS parameter

Parameter Type

Keyword, optional

Purpose

You can, on a system that includes MVS/DFSMS Version 1 Release 3 or higher, use the RLS parameter to specify the level of record sharing, or sharing protocol, for a VSAM data set containing records that must be shared.

Note: RLS is most useful for an existing application. For a new or heavily-modified application, you can request record-level sharing in application code and do not need to specify RLS on the DD statement.

1.Syntax

RLS= {NRI}
     {CR }

2.Subparameter Definition

NRI
Specifies ²no read integrity² (NRI). The application can read all records. Use this subparameter if the application can read uncommitted changes made to a data set by another application. NRI provides better performance than the CR subparameter because it avoids the overhead of obtaining a lock when reading a record from the data set.

CR
Specifies ²consistent read² (CR). This subparameter requests VSAM to obtain a SHARE lock on each record the application reads. This ensures the application will not read uncommitted changes made to a data set by another application. VSAM obtains the lock while processing a GET NUP request, and releases the lock before completing the GET request. An application that processes a data set allocated with RLS=CR may require modification if it tries to read changes to the data set.

3.Overrides
Specifying RLS does not override any other JCL parameter.

4.Relationship to Other Parameters
Do not code the following DD parameters with the RLS parameter:

*                   DSNTYPE         PATHDISP
AMP                 DYNAM           QNAME
BURST               FLASH           SEGMENT
CHARS               FREE            SPIN
COPIES              MODIFY          SYSOUT
DATA                OUTPUT          TERM
DCB (see Note)      PATH            UCS
DDNAME              PATHOPTS
DLM                 PATHMODE

Note: You can code RLS with DCB as long as the only DCB subparameters you specify are KEYLEN and LRECL.

5.Examples of the RLS Parameter

Example 

//       EXEC PGM=BATCHPRG
//DD1    DD DSN=A,RLS=NRI,DISP=SHR

When the program BATCHPRG opens DD1, the data set is to be processed as a shared resource. NRI specifies that an application can read uncommitted changes made by other applications.

Example 

//      EXEC PGM=BATCHPRG
//DD2   DD DSN=B,RLS=CR,DISP=SHR

When the program BATCHPRG opens DD2, the data set is to be processed as a shared resource. CR specifies that an application can read only committed changes made by other applications.

SECMODEL parameter

Parameter Type

Keyword, optional — use this parameter only with SMS Without SMS, use the DD PROTECT parameter described.

Purpose

Use the SECMODEL parameter to specify the name of an existing RACF data set profile that is copied to the discrete data set profile that RACF builds for the new data set.

The following information from the RACF data set profile, which RACF uses to control access to the data set, is copied to the discrete data set profile of the new data set:

  • OWNER - indicates the user or group assigned as the owner of the data set profile.
  • ID - indicates the access list of users or groups authorized to access the data set.
  • UACC - indicates the universal access authority associated with the data set.
  • AUDIT/GLOBALAUDIT - indicates which access attempts are logged.
  • ERASE - indicates that the data set is to be erased when it is deleted (scratched).
  • LEVEL - indicates the installation-defined level indicator.
  • DATA - indicates installation-defined information.
  • WARNING - indicates that an unauthorized access causes RACF to issue a warning message but allow access to the data set.
  • SECLEVEL - indicates the name of an installation-defined security level.

Use the SECMODEL parameter (1) when you want a different RACF data set profile than the default profile selected by RACF or (2) when there is no default profile.

If SMS is not installed or is not active, the system syntax checks and then ignores the SECMODEL parameter.

1.Syntax

SECMODEL=(profile-name[,GENERIC])

2.Subparameter Definition

profile-name
Specifies the name of a RACF model profile, discrete data set profile, or generic data set profile. The named profile is copied to the discrete data set profile of the new data set. If a generic data set profile is named, GENERIC must also be coded.

GENERIC
Identifies that the profile-name refers to a generic data set profile.

3.Overrides
The SECMODEL parameter overrides the PROTECT=YES parameter.

4.Relationship to Other Parameters
Do not code the following DD parameters with the SECMODEL parameter.

*       DDNAME
DATA    DYNAM

5.Examples of the SECMODEL Parameter

Example 

//SMSDS4   DD   DSNAME=MYDS4.PGM,SECMODEL=(GROUP4.DEPT1.DATA),
//              DISP=(NEW,KEEP)

In the example, RACF uses the previously defined model data set profile named GROUP4.DEPT1.DATA to control access to the new data set.

Example 

//SMSDS5   DD   DSNAME=MYDS5.PGM,SECMODEL=(GROUP5.*,GENERIC),
//              DISP=(NEW,KEEP)

In the example, RACF uses the previously defined generic data set profile named GROUP5.* to control access to the new data set.

SEGMENT parameter

Parameter Type

Keyword, optional

Purpose

In a JES2 system, use the SEGMENT parameter to allow part of a job’s output to be printed while the job is still executing, or to allow multiple segments of a job’s output to be printed simultaneously on multiple printers. With SEGMENT, portions of a data set are spun, one segment at a time. You determine the size of the portion with the SEGMENT parameter. SEGMENT allows you to specify the number of pages produced for a sysout data set before the system processes the segment of the data set. To count pages, JES2 uses the carriage control characters in the data that skip to channel 1.

SEGMENT is supported by JES2 only. The SEGMENT parameter applies only to line mode data sets with RECFM=A or RECFM=M.

1.Syntax

SEGMENT=page-count

2.Subparameter Definition

page-count
Indicates the number of pages produced for the sysout data set for the current segment. When the number is reached, the system spins-off the data segment for output processing.

3.Overrides
The system spins the sysout regardless of SPIN, FREE, and OUTDISP specifications.

4.Relationship to Other Parameters
Do not code the following parameters with the SEGMENT parameter.

*       DDNAME   EXPDT      QNAME
AMP     DISP     LABEL      RETPD
CHKPT   DSNAME   LIKE       SUBSYS
DATA    DYNAM    PROTECT    VOLUME

Page mode data is not counted for segmentation. The system might suspend segmentation if it reaches the threshold for segmentation allowed by JES.

5.Example of the Segment Parameter

//DD1   DD   SYSOUT=A,SEGMENT=100

In this example, if the sysout data set produced 400 pages, then four separate segments, 100 pages in each, are produced for output processing.

SPACE parameter

Parameter Type

Keyword, optional

Note: With SMS, code the SPACE parameter when you want to

  • Request space for a new data set, or
  • Override the space allocation defined in the DATACLAS parameter for the data set.

Purpose

Use the SPACE parameter to request space for a new data set on a direct access volume. You can request space in two ways:

  • Tell the system how much space you want and let the system assign specific tracks.
  • Tell the system the specific tracks to be allocated to the data set.

Letting the system assign the specific tracks is most frequently used. You specify only how space is to be measured in tracks, cylinders, blocks, or records — and how many of those tracks, cylinders, blocks, or records are required.

The SPACE parameter has no meaning for tape volumes; however, if you assign a data set to a device class that contains both direct access devices and tape devices, for example, UNIT=SYSSQ, you should code the SPACE parameter.

If you code the SPACE parameter on a DD statement that defines an existing data set, the SPACE value you specify temporarily overrides the SPACE value used to create the data set. For example, a data set created with SPACE=(CYL,(5,1)) causes 5 cylinders to be allocated to the data set, and, if it needs more space, it can obtain 1 additional cylinder.

Suppose, though, that there is one particular job that specifies DISP=MOD and will write many records to this data set. JCL for this job can define, for example, SPACE=(CYL,(5,10)) to obtain an additional 10 cylinders instead of just 1 cylinder. The override, however, is in effect only for this job. Any other job that requires a secondary extent and does not have a SPACE parameter override gets just the 1 additional cylinder specified in the JCL that created the job.

Notes

  • When creating VSAM data sets, be aware that there is no direct one-to-one correspondence between ‘define cluster’ parameters and JCL keyword parameters.
  • The average value in the SPACE keyword is meant to be an average block length value for space calculations and is not meant to represent an LRECL value.
  • The AVGREC keyword is only to be used as a multiplier in determining how much space is to be allocated.
  • When defining VIO data sets, be aware that a SPACE parameter in the JCL or the SPACE value defined for a data class will override the system default space value.
  • The size of a data set is limited to 65,536 tracks per volume except for the following types of data sets:
  • – Hierarchical File System (HFS)
    – Extended format sequential
    – Partitioned data set extended (PDSE)
    – VSAM

1.Syntax

  • All the subparameters are positional. Code a comma to indicate an omitted subparameter if any others follow. Thus:
  • – If you code primary and directory or index quantities and omit a secondary quantity, code a comma inside the inner parentheses to indicate the omission. For example, SPACE=(TRK,(20,,2)).
    – If you omit RLSE but code a following subparameter, code a comma to indicate the omission. For example, SPACE=(TRK,(20,10),,CONTIG) or SPACE=(TRK,20,,CONTIG).
    – If you omit CONTIG, MXIG, or ALX and ROUND follows, code a comma to indicate the omission. For example, SPACE=(400,30,RLSE,,ROUND). If you also omit RLSE, this example becomes SPACE=(400,30,,,ROUND).

2.Subparameter Definition

System Assignment of Space

TRK
Requests that space be allocated in tracks.
CYL
Requests that space be allocated in cylinders.

blklgth — (only if AVGREC is not coded)
Specifies the average block length of the data, in bytes. The blklgth is a decimal number from 0 through 65535. This parameter indicates that the values specified for primary-qty and second-qty are block quantities, and directs the system to compute the number of tracks to allocate using a block length. The value specified for block size uses block length in this computation, with the exception of the value zero. See primary-qty and second-qty descriptions for how a zero block size is handled.

reclgth — (only if AVGREC is coded and SMS is active)
With SMS, specifies the average record length of the data, in bytes. The reclgthis a decimal number from 0 through 65535. This parameter indicates that the values specified for primary-qty and second-qty are record quantities, whose average record length is reclgth. If you specify zero, no space will be allocated. The system allocates DASD space in whole tracks. The number of tracks required depends on how the records are blocked. The system uses one of the following as the block length to compute the number of tracks to allocate, in the order indicated:

  1. The block size from the DCB parameter, if specified
  2. The system determined block size, if available
  3. A default value of 4096.

primary-qty
Specifies one of the following:

  • For TRK, the number of tracks to be allocated.
  • For CYL, the number of cylinders to be allocated.
  • For a block length, the number of data blocks in the data set.
  • For a record length, the number of records in the new data set. Use the AVGREC parameter to specify that the primary quantity represents units, thousands, or millions of records.

Note: When you specify TRK or CYL for a partitioned data set (PDS or PDSE), the primary quantity includes the space for the directory. When you specify a block length or record length for a partitioned data set (PDS or PDSE), the primary quantity does not include the directory space; the system assigns the directory to space outside the primary space assignment.

If the data set does not have the space constraint relief option, one volume must have enough available space for the primary quantity. If you request a particular volume and it does not have enough space available for your request, the system terminates the job step. In order for a data set to have the space constraint relief option, it must be SMS-managed and the data class must specify the option.

If you specify a blklgth of zero for the first subparameter, the system uses one of the following as the block length to compute the number of tracks to allocate, in the order indicated:

  1. The block size from the DCB parameter, if specified
  2. The block size determined from RECFM and LRECL on the DD statement or data class, if available
  3. A default value of 4096.

To request an entire volume, either code the ALX parameter or specify in the primary quantity the number of tracks or cylinders on the volume minus the number used by the volume table of contents (VTOC), volume label track, VTOC index, and VVDS (if any). The volume must not contain other data sets.

second-qty
Specifies the number of additional tracks, cylinders, blocks, or records to be allocated, if more space is needed. The system does not allocate additional space until it is needed. With SMS, use the AVGREC parameter to specify that the secondary quantity represents units, thousands, or millions of records. The system computes the number of tracks to allocate using a block length as indicated in the following order:

  1. The block size from the DCB parameter, if specified
  2. The system determined block size, if available
  3. A default value of 4096.

If the first subparameter specifies the average block length, the system computes the number of tracks for the secondary quantity from the second-qty number and one of the following, in order:

  1. The blklgth subparameter of the SPACE parameter.
  2. The saved average block length value specified when the data set was created, if no SPACE parameter was specified for an existing data set.
  3. The block length in the BLKSIZE field of the data control block.

When you specify a secondary quantity and the data set requires additional space, the system allocates the specified quantity:

  • In contiguous tracks or cylinders, if available.
  • If not available:
  • – If the data set does not have the space constraint relief option, in up to five extents.
    – With the space constraint relief option, the system might have to allocate more than five new extents. A data set has this option only if it is SMS-managed and the data class specifies the option.

The system can allocate up to 123 extents for a data set on a volume if it is a PDSE, an HFS data set, an extended format data set, or a VSAM data set in an ICF catalog. For other types of data sets the system can allocate up to 16 extents for each data set on each volume. An extent is space that may or may not be contiguous to other space allocated to the data set. The extents for a data set include the primary quantity space and user-label space.

Note: BDAM data sets cannot be extended.

When your program has filled a sequential data set’s allocated space on a volume, the system determines where the following data is written as follows:

  • If the disposition of the data set is NEW or MOD and the limit on the number of extents on a volume has not been reached, the system attempts to allocate the secondary quantity on the same volume.
  • If the disposition of the data set is OLD or SHR, the system examines the next volume specified for the data set.
  • – If space has been allocated on the next volume for the data set, the next volume is used for the data set.
    – If space has not been allocated on the next volume for the data set, secondary space is allocated on the next volume for the data set.

If there is not another volume specified for the data set, the system attempts to allocate the secondary quantity on the current volume.

Note that your program should not write with a disposition of DISP=SHR unless you take precautions to prevent other programs from writing at the same time.

If the requested volumes have no more available space and if at least one volume is demountable, the system asks the operator to mount scratch (nonspecific) volumes until the secondary allocation is complete. If none of the volumes are demountable, the system abnormally terminates the job step.

directory
Specifies the number of 256-byte records needed in the directory of a partitioned data set (PDS).

Note: When creating a partitioned data set (PDS), you must request space for a directory. When creating a partitioned data set extended (PDSE), the size of the directory grows dynamically as needed. SMS uses the size requested for a PDSE directory only if you later convert the PDSE to a PDS.

The PDS directory must fit in the first extent of the data set. If the primary quantity is too small for the directory, or if the system has allocated the primary quantity over multiple extents and the first extent is too small for the directory, then the allocation fails.

With SMS, you can specify the number of directory records on the SPACE parameter without specifying any other subparameters. For example:

//DD12   DD   DSNAME=PDS.EXMP,DATACLAS=DCLAS12,SPACE=(,(,,20)),
//            DISP=(NEW,KEEP)

specifies 20 directory records for the data set. In this example, the number of specified directory records (20) overrides the number of directory records defined in the data class of the data set. (SMS uses all other space allocation attributes defined in the data class of the data set.)

index
For the index of an indexed sequential data set, specifies one of the following:

  • For TRK, the number of tracks needed. The number of tracks must equal one or more cylinders.
  • For CYL, the number of cylinders needed.

RLSE (Partial Release)
Requests that space allocated to an output data set, but not used, is to be released when the data set is closed. This partial release parameter causes the close function to release unused space only if the data set is open to allow writing and the last operation was not a read or a POINT macro.

For a multi-volume sequential data set, only unused space on the current volume is released when the data set is closed; allocated space on any subsequent volume is not affected.

If you specify RLSE and an abnormal termination occurs, the system does not release unused space even though the data set is open. RLSE is supported only for sequential, partitioned, and VSAM extended format data sets.

Coding RLSE for primary allocation does not prohibit use of secondary allocation. The secondary request for space is still in effect.

The system ignores a request to release unused space when closing a data set if it cannot immediately obtain exclusive control of the data set. Circumstances that would preclude obtaining exclusive control include:

  • Another job is sharing the data set.
  • Another task in the same multitasking job is processing an OPEN, CLOSE, EOV, or FEOV request for the data set.
  • Another data control block is open for the data set.

The RLSE subparameter is ignored when TYPE=T is coded in the CLOSE macro instruction.

When coding RLSE for an existing data set, code the unit of measurement and primary quantity as they appeared in the original request. For example, if the original request was:

SPACE=(TRK,(100,50))

you can release unused tracks when you retrieve the data set by coding:

SPACE=(TRK,(100),RLSE)

You can release space in the following additional ways other than by deleting the data set:

  • Partial release option in the management class
  • DFSMShsm space management cycle
  • PARTREL macro issued by an authorized program.

CONTIG
Requests that space allocated to the data set must be contiguous. This subparameter affects only primary space allocation.

If CONTIG is specified and contiguous space is not available, the system terminates the job step.

MXIG
Requests that space allocated to the data set must be (1) the largest area of available contiguous space on the volume and (2) equal to or greater than the primary quantity. This subparameter affects only primary space allocation.

Caution: IBM recommends that you use extreme care when coding this parameter. Large amounts of storage could be allocated, depending on how much free space is available at the time the request is made. If you code this parameter, IBM recommends that you also code the RLSE parameter to release any unused space.

Note: Do not code a MXIG subparameter for an indexed sequential data set.

ALX
Requests that space allocated to the data set is to be up to 5 of the largest areas of available contiguous space on the volume, and each area must be equal to or greater than the primary quantity. The system allocates fewer than 5 areas only when 5 areas of sufficient size are not available. ALX affects only primary space allocation.

For example, assume the following space extents (in tracks) are available: 910,435, 201, 102, 14, 12, and 8.

If your job requests 14 tracks as its primary allocation, and ALX is in effect, the job receives the following 5 extents: 910, 435, 201, 102, and 14.

However, if the job requests 15 tracks as its primary allocation, it would receive 4 extents: 910, 435, 201, and 102. The job does not receive the 14-track extent because it is less than the primary space allocation.

Caution: IBM recommends that you use extreme care when coding this parameter. Large amounts of storage could be allocated, depending on how much free space is available at the time the request is made. If you code this parameter, IBM recommends that you also code the RLSE parameter to release any unused space.

Note: Do not code an ALX subparameter for an indexed sequential data set.

ROUND
When the first subparameter specifies the average block length, requests that space allocated to the data set must be equal to an integral number of cylinders. If the first subparameter specifies TRK, or CYL, the system ignores ROUND.

Request for Specific Tracks
For an SMS-managed data set (one with an assigned storage class), do not code ABSTR.

ABSTR
Requests that the data set be allocated at the specified location on the volume.

primary-qty
Specifies the number of tracks to be allocated to the data set. The volume must have enough available space for the primary quantity. If it does not, the system terminates the job step.

address
Specifies the track number of the first track to be allocated. Count the first track of the first cylinder on the volume as 0. Count through the tracks on each cylinder until you reach the track on which you want the data set to start. The absolute track address must be a decimal number equal to or less than 65535.

Note: Do not request track 0.

directory
Specifies the number of 256-byte records needed in the directory of a partitioned data set.

Note: When creating a partitioned data set, you must request space for a directory.

index
Specifies the number of tracks needed for the index of an indexed sequential data set. The number of tracks must equal one or more cylinders.

3.Overrides
With SMS, the SPACE parameter overrides the space allocation attributes defined in the data class for the data set.

Explicit specification of SPACE on the DD statement overrides both the SPACE and the AVGREC values specified in the data class.

4.Relationship to Other Parameters
Do not code the following parameters with the SPACE parameter.

*         DYNAM
DATA      QNAME
DDNAME    SUBSYS

With KEYLEN for Block Requests
If space is requested in blocks and the blocks have keys, code the DD parameter KEYLEN (or the DCB subparameter KEYLEN) on the DD statement and specify the key length.

5.SPACE for New Data Sets with SMS
With SMS, code the SPACE parameter with or without the AVGREC parameter when you want to (1) request space for the data set or (2) override the space allocation attributes defined in the data class for the data set.

6.Examples of the SPACE Parameter

Example 

//DD1   DD   DSNAME=&&TEMP,UNIT=MIXED,SPACE=(CYL,10)

The DD statement defines a temporary data set. The UNIT parameter requests any available tape or direct access volume; MIXED is the installation’s name for a group of tape and direct access devices. If a tape volume is assigned, the SPACE parameter is ignored; if a direct access volume is assigned, the SPACE parameter is used to allocate space to the data set. The SPACE parameter specifies only the required subparameters: the type of allocation and a primary quantity. It requests that the system allocate 10 cylinders.

Example 

//DD2   DD   DSNAME=PDS12,DISP=(,KEEP),UNIT=3350,
//           VOLUME=SER=25143,SPACE=(CYL,(10,,10),,CONTIG)

The DD statement defines a new partitioned data set. The system allocates 10 cylinders to the data set, of which ten 256-byte records are for a directory. Since the CONTIG subparameter is coded, the system allocates 10 contiguous cylinders on the volume.

Example 

//REQUEST1   DD   DSNAME=EXM,DISP=NEW,UNIT=3330,VOLUME=SER=606674,
//                SPACE=(1024,75),DCB=KEYLEN=8
//REQUESTA   DD   DSNAME=EXQ,DISP=NEW,UNIT=3380,
//                SPACE=(1024,75),DCB=KEYLEN=8

These DD statements request space in block lengths. The average block length of the data is 1024 bytes. 75 blocks of data are expected as output. Each block is preceded by a key eight bytes long. The system computes how many tracks are needed, depending on the device requested in the UNIT parameter.

Example 

//REQUEST2   DD   DSNAME=PET,DISP=NEW,UNIT=3330,VOLUME=SER=606674,
//                SPACE=(ABSTR,(5,1))

In this example, the SPACE parameter asks the system to allocate 5 tracks, beginning on the second track of the volume.

Example 

//DD3   DD   DSNAME=MULTIVOL,UNIT=3350,DISP=(,CATLG),
//           VOLUME=SER=(223344,223345),SPACE=(CYL,(554,554))

This example shows how to create a multivolume data set on two complete volumes. The two volumes do not contain other data sets. A volume on 3350 Direct Access Storage contains 555 cylinders. The unrequested cylinder contains the volume table of contents (VTOC).

Example 

//SMSDS3   DD   DSNAME=MYDS3.PGM,DATACLAS=DCLAS03,DISP=(NEW,KEEP),
//              SPACE=(128,(5,2)),AVGREC=K

In this example, the space allocation defined in the DCLAS03 data class is overridden by the SPACE and AVGREC parameters, which indicate an average record length of 128 bytes, a primary quantity of 5K (5,120) records, and a secondary quantity of 2K (2,048) records.

SPIN parameter

Parameter type

Keyword, optional

Purpose

Use the SPIN parameter to specify that the output for the sysout data set is to be made available for processing

  • Immediately upon unallocation
  • At the end of the job.

1.Syntax

SPIN= {UNALLOC}
      {NO }

2.Subparameter Definition

UNALLOC
Indicates that the system makes the data set available for processing immediately when the data set is unallocated. If you dynamically unallocate the sysout data set, either explicitly or by specifying FREE=CLOSE, the system makes the data set available for processing immediately. If you do not dynamically unallocate it, the sysout data set is unallocated at the end of the step, and the system will make it available for processing then.

NO
Indicates that the system makes the sysout data set available for processing as a part of the output at the end of the job, regardless of when the data set is unallocated.

3.Defaults
If you dynamically unallocate the sysout data set, the default is that the data set is immediately available for processing. If you unallocate the sysout data set at the end of the step, the default is that the data set is available for processing. at the end of the job.

If you specify FREE=CLOSE, the following defaults apply:

  • A data set that is closed by the application program is available for processing immediately.
  • A data set that is closed as part of the end-of-step cleanup, such as for a program abend, is available for processing at the end of the job.

If you specify FREE=END, the default is that the data set is available for processing at the end of the job.

4.Overrides
The SEGMENT parameter overrides the SPIN parameter.

Note: Another way for a program to control when the sysout data set becomes available for processing is to issue a SETPRT macro.

5.Relationship to Other Parameters
Do not code the following parameters with the SPIN parameter.

*       DDNAME    LABEL        RETPD
AMP     DISP      LIKE         SUBSYS
CHKPT   DYNAM     PROTECT      VOLUME
DATA    EXPDT     QNAME

6.Examples of the SPIN Parameter

Example 

//DD1   DD   SYSOUT=A,FREE=CLOSE,SPIN=UNALLOC

In this example, if you explicitly close or dynamically unallocate the sysout data set, the system makes it available for printing immediately. If you do not explicitly close or dynamically unallocate the sysout data set, the system makes it available for printin at the end of the step.

Example 

//DD2   DD   SYSOUT=A,FREE=CLOSE,SPIN=NO

In this example, the system makes the sysout data set available for printing at the end of the job, regardless of when it is unallocated or closed.

Example 

//DD3   DD   SYSOUT=A,FREE=END,SPIN=UNALLOC

In this example, the sysout data set is unallocated at the end of the step, and made available for printing then. If you dynamically unallocate the sysout data set, the system makes it available for printing immediately.

Example 

//DD4   DD   SYSOUT=A,FREE=END,SPIN=NO

In this example, the system makes the sysout data set available for printing at the end of the job, regardless of whether the data set is unallocated or closed.

STORCLAS parameter

Parameter Type
Keyword, optional — use this parameter only with SMS and for SMS-managed data sets

Without SMS or for non-SMS-managed data sets, use the UNIT parameter and the VOLUME parameter.

Purpose

Use the STORCLAS parameter to specify a storage class for a new SMS-managed data set. The storage administrator at your installation defines the names of the storage classes you can code on the STORCLAS parameter.

The storage class contains the attributes that identify a storage service level to be used by SMS for storage of the data set. It replaces the storage attributes that are specified on the UNIT and VOLUME parameters for non-SMS-managed data sets.

An SMS-managed data set is defined as a data set that has a storage class assigned. A storage class is assigned when either (1) you specify the STORCLAS parameter or (2) an installation-written automatic class selection (ACS) routine selects a storage class for a new data set.

If SMS is not installed or is not active, the system syntax checks and then ignores the STORCLAS parameter. SMS ignores the STORCLAS parameter if you specify it for an existing data set. The use of a storage class can be protected by RACF.

1.Syntax

STORCLAS=storage-class-name

2.Subparameter Definition

storage-class-name
Specifies the name of a storage class to be used for storage of the data set. The name, one to eight characters, is defined by the storage administrator at your installation.

3.Defaults
If you do not specify STORCLAS for a new data set and the storage administrator has provided an installation-written automatic class selection(ACS) routine, the ACS routine may select a storage class for the data set. Check with your storage administrator to determine if an ACS routine will select a storage class for the new data set, in which case you do not need to specify STORCLAS.

4.Overrides
No attributes in the storage class can be overridden by JCL parameters.

An ACS routine can override the storage class that you specify on the STORCLAS parameter.

5.Relationship to Other Parameters
If the storage administrator has specified GUARANTEED_SPACE=YES in the storage class, then volume serial numbers you specify on the VOLUME=SER parameter override the volume serial numbers used by SMS. Otherwise, volume serial numbers are ignored.

Do not code the following DD parameters with the STORCLAS parameter.

*         DYNAM     UNIT=AFF
DATA      QNAME     VOLUME=REF
DDNAME

6.Examples of the STORCLAS Parameter

Example 

//SMSDS1   DD   DSNAME=MYDS1.PGM,STORCLAS=SCLAS01,DISP=(NEW,KEEP)

In the example, SMS uses the attributes in the storage class named SCLAS01 for the storage service level of the data set. Note that installation-written ACS routines may select a management class and data class and can override the specified storage class.

Example 

//SMSDS2   DD   DSNAME=MYDS2.PGM,STORCLAS=SCLAS02,DISP=(NEW,KEEP),
//              VOLUME=SER=(223344,224444)

In the example, SMS uses the attributes in the storage class named SCLAS02 for the storage service level of the data set. Also, if the storage administrator has specified GUARANTEED_SPACE=YES in the storage class, VOLUME=SER can be coded and the data set will reside on the specified volumes. (However, if space is not available on the volumes, the job step fails.) Note that installation-written ACS routines may select a management class and data class and can override the specified storage class.

SUBSYS parameter

Parameter Type

Keyword, optional

Purpose

Use the SUBSYS parameter to request a subsystem to process this data set and, optionally, to specify parameters defined by the subsystem.

Do not use the SUBSYS parameter for an SMS-managed data set (one with an assigned storage class).

In a loosely-coupled multiprocessing environment, the requested subsystem must be defined on all processors that could interpret this DD statement.

Considerations for an APPC Scheduling Environment
In an APPC scheduling environment, avoid coding the system symbolic SYSUID on the SUBSYS parameter. Symbolic substitution is inconsistent when you code SYSUID as a subparameter of SUBSYS parameter.

1.Syntax

SUBSYS= {subsystem-name }
        {(subsystem-name[,subsystem-subparameter]...)}

Single Subparameter: You can omit the parentheses if you code only the
subsystem-name.

Number of Subparameters: If needed, you can code up to 254 subsystem-
subparameters on a JES2 system, or up to 1020 bytes of data on a JES3 system.

Multiple Subparameters: When the parameter contains more than the subsystem-name, separate the subparameters by commas and enclose the subparameter list in parentheses. For example, SUBSYS=(XYZ,1724,DT25).

Positional Subparameters: If you omit a subparameter that the subsystem considers positional, code a comma in its place.

Special Characters: When a subparameter contains special characters, enclose the subparameter in apostrophes. For example, SUBSYS=(XYZ,1724,'KEY=Y').

Code each apostrophe that is part of a subparameter as two consecutive apostrophes. For example, code O’Day as SUBSYS=(XYX,1724,'NAME=O''DAY').

If you code a symbolic parameter on the SUBSYS parameter, you can code the symbolic parameter in apostrophes.

Continuation onto Another Statement: Enclose the subparameter list in only one set of parentheses. End each statement with a comma after a complete
subparameter. For example:

//DS1   DD   DSNAME=DATA1,SUBSYS=(XYZ,1724,’KEY=Y’,
//           DT25,’NAME=O’’DAY’)

Note: The SUBSYS parameter can have a null value only when coded on a DD which either:

  • Overrides a DD in a procedure
  • Is added to a procedure.

2.Subparameter Definition

subsystem-name
Identifies the subsystem. The subsystem name is 1 through 4 alphanumeric or national ($, #, @) characters; the first character must be alphabetic or national ($, #, @). The subsystem must be available in the installation.

subsystem-subparameter
Specifies information needed by the subsystem. A subparameter consists of alphanumeric, national ($, #, @), or special characters.

3.Relationship to Other Parameters
Do not code the following DD parameters with the SUBSYS parameter:

*       DDNAME      QNAME
AMP     DYNAM       SEGMENT
DATA    MODIFY      SYSOUT

The specified subsystem can define other parameters that you must not code with the SUBSYS parameter:

Ignored but Permitted DD Parameters
If you specify any of the following DD parameters, the system checks them for syntax and then ignores them:

HOLD UNIT

If you specify the SPACE parameter, the system checks its syntax and then ignores it, but the subsystem designated on the SUBSYS parameter may use this information when it allocates the DD.

DISP Parameter
The system checks the DISP status subparameter for syntax, but always indicates a status of MOD to the subsystem. If the DISP normal or abnormal termination subparameter is CATLG or UNCATLG, the system allocates the appropriate catalog to the subsystem.

DUMMY Parameter
If DUMMY is specified with SUBSYS, the subsystem checks the syntax of the subsystem subparameters. If they are acceptable, the system treats the data set as a dummy data set.

When This Statement Overrides a Procedure Statement
If SUBSYS appears on a DD statement that overrides a DD statement in a cataloged or in-stream procedure, the following occurs:

  • The system ignores a UNIT parameter, if specified, on the overridden DD
    statement.
  • The system nullifies a DUMMY parameter, if specified, on the overridden DD
    statement.

4.Subsystem Support for JCL Parameters
The specified subsystem might not support all parameters on the DD and OUTPUT JCL statements.

5.Examples of the SUBSYS Parameter

Example 

//DD1   DD   DSNAME=ANYDS,DISP=OLD,SUBSYS=ABC

The DD statement asks subsystem ABC to process data set ANYDS.

Example 

//DD1   DD   DSNAME=ANYDS,DISP=OLD,SUBSYS=(XYZ2,
//           ’KEYWORD=DATA VALUE1’)

The DD statement asks subsystem XYZ2 to process data set ANYDS. The system passes the subparameter KEYWORD=DATA VALUE1 to the subsystem. The parameter is enclosed in apostrophes because it contains an equal sign and a blank, which are special characters.

Example 

//DD1   DD   DSNAME=ANYDS,DISP=OLD,SUBSYS=(XYZ2,IKJ2,
//           ’NAME=’’MODULE1’’’,’DATE=4/11/86’)

The DD statement asks subsystem XYZ2 to process the data set ANYDS. The system passes three subparameters to the subsystem: IKJ2, NAME='MODULE1' and DATE=4/11/86. Note that the character string MODULE1 is passed to the subsystem enclosed in apostrophes.

Example 

//DD1   DD  SUBSYS=(AOP1,’MyPrinter’)

The DD statement asks the Infoprint Server subsystem named AOP1 to process a sysout data set. The system passes the subparameter MyPrinter to the Infoprint Server subsystem. The subparameter is enclosed in apostrophes because it contains lowercase letters.

SYSOUT parameter

Parameter Type

Keyword, optional

Purpose

Use the SYSOUT parameter to identify this data set as a system output data set, usually called a sysout data set. Do not use the SYSOUT parameter for an SMS-managed data set (one with an assigned storage class). The SYSOUT parameter also:

  • Assigns this sysout data set to an output class. The attributes of each output class are defined during JES initialization.
  • Optionally requests an external writer to process the sysout data set rather than JES. An external writer is an IBM- or installation-written program.
  • Optionally identifies the forms on which the data set is to be printed or punched.
  • Optionally refers to a JES2 /*OUTPUT statement for processing parameters.

The sysout data set is processed according to the following processing options, in override order:

  1. The options specified on this sysout DD statement.
  2. The options specified on a referenced OUTPUT JCL statement.
  3. The options specified on a referenced JES2 /*OUTPUT statement or on a JES3 //*FORMAT statement.
  4. The installation default options for the requested output class.

Notes:

  1. If a sysout data set has the same class as the JOB statement MSGCLASS parameter, the job log appears on the same output listing as this sysout data set.
  2. An installation should maintain a list of available output classes and their attributes. Some classes should be used for most printing and punching, but others should be reserved for special processing. Each class is processed by an output writer. The system operator starts the output writers for the commonly used output classes. If you plan to specify a special output class, ask the operator to start the output writer for that class. If the writer is not started before the job produces the sysout data set, the data set is retained until the writer is started.
  3. If the automatic restart manager (ARM) restarts a job, JES discards all non-spin sysout data sets created during the previous execution. (You can avoid losing that output by adding SPIN=UNALLOC to the DD statement for the SYSOUT data set.)

1.Syntax

SYSOUT= { class }
        { * }
        { ([class] [,writer-name] [,form-name]) }
                   [   ,INTRDR  ] [,code-name]
SYSOUT= (,)
  • You can omit the parentheses if you code only a class.
  • All of the subparameters are positional. Code a comma to indicate an omitted subparameter as follows:
  • – If you omit the class, code a comma to indicate the omission. For example, when other subparameters follow, code SYSOUT=(,INTRDR,FM26). When other subparameters do not follow, code a null class as SYSOUT=(,).
    – If you omit a writer-name but code a form-name or code-name, code a comma to indicate the omission. For example, SYSOUT=(A,,FM26).
    – Omission of the third subparameter does not require a comma. For example, SYSOUT=A or SYSOUT=(A,INTRDR).

2.Subparameter Definition

Class
Identifies the output class for the data set. The class is one character: A through Z or 0 through 9, which you may optionally include in quotation marks. The attributes of each output class are defined during JES initialization; specify the class with the desired attributes.

*: Requests the output class in the MSGCLASS parameter on the JOB statement. In a JES2 system you can also use the dollar-sign ($) to request the output class in the MSGCLASS parameter on the JOB statement.

(,): Specifies a null class. A null class must be coded to use the CLASS parameter on a referenced OUTPUT JCL statement.

writer-name
Identifies the member name (1 to 8 alphanumeric characters) of an installation-written program.

An external writer is a started task used to process output. Because the external writer is a started task, it has a userid associated with it. Process output with an external writer by naming the writer on the DD statement that defines the output:

//MYOUTPUT   DD    SYSOUT=(A,XTWTR)

In order for the writer to process that output, the writer’s userid must be in a RACF access list. The access list permits the writer’s userid to the SYSOUT data set. The writer’s userid is the userid specified in the started procedure table for the writer task. If your installation’s policy requires security labels, the security label associated with the external writer must be equal to or greater than the security label associated with the SYSOUT.

Do not code STDWTR as a writer-name.STDWTR is reserved for JES and used as a parameter in the MVS operator’s MODIFY command.

In a JES3 system, do not code NJERDR as a writer-name. NJERDR is reserved for JES3.

INTRDR
Tells JES that this sysout data set is to be sent to the internal reader as an input job stream.

form-name
Identifies the print or punch forms. form-name is 1 through 4 alphanumeric or national ($, #, @) characters.

code-name
Identifies an earlier JES2 /*OUTPUT statement from which JES2 is to obtain processing characteristics. The code-name must be the same as the code parameter on the JES2 /*OUTPUT statement.

Note:

  • code-name is supported only on JES2 systems.
  • Do not specify the code-name subparameter when the job or job step contains a default OUTPUT JCL statement.

3.Defaults
In a JES2 system, if you do not specify a class on this DD statement or a referenced OUTPUT JCL statement, JES2 assigns the sysout data set to the output class defined by the MSGCLASS value of the JOB statement. See the override order shown under ²Purpose² for how this default is established. If you do not code a writer-name subparameter on this DD statement or a referenced OUTPUT JCL statement, the installation’s job entry subsystem processes the sysout data set. If you do not code a form-name subparameter on this DD statement or a referenced OUTPUT JCL statement, JES uses an installation default specified at initialization.

4.Overrides
The class subparameter of the DD statement SYSOUT parameter overrides an OUTPUT JCL CLASS parameter. On the DD statement, you must code a null class in order to use the OUTPUT JCL CLASS parameter; for example:

//OUTDS   DD   SYSOUT=(,),OUTPUT=*.OUT1

The writer-name subparameter of the DD statement SYSOUT parameter overrides an OUTPUT JCL WRITER parameter. The form-name subparameter of the DD statement SYSOUT parameter overrides an OUTPUT JCL FORMS parameter. Note that the SYSOUT form-name subparameter can be only four characters maximum while both the OUTPUT JCL FORMS form-name and the JES initialization default form names can be eight characters maximum.

5.Relationship to Other Parameters
Do not code the following DD parameters with the SYSOUT parameter.

*           DDNAME     LIKE
AMP         DISP       PROTECT
CHKPT       DYNAM      QNAME
DATA        EXPDT      RETPD
DATACLAS    LABEL      SUBSYS
VOLUME

Ignored Parameters

Because JES allocates sysout data sets, the UNIT and SPACE parameters are ignored, if coded on a sysout DD statement.

Parameters on Procedure DD Statements that are Overridden

When an overriding DD statement contains a SYSOUT parameter, the system ignores a UNIT parameter on the overridden DD statement in the cataloged or in-stream procedure.

Naming a Sysout Data Set

Code the DSNAME parameter with the SYSOUT parameter if you wish to assign the last qualifier of the system-generated name to a sysout data set.

SYSOUT and DEST Subparameters

Do not code the SYSOUT writer-name subparameter when coding a DEST userid subparameter. These subparameters are mutually exclusive. You can code:

//VALID1   DD   SYSOUT=D,DEST=(node,userid)
//VALID2   DD   SYSOUT=(D,writer-name),DEST=(node)

With DCB Subparameters

JES2 ignores DCB=PRTSP=2 on a DD statement that also contains a SYSOUT parameter. For JES, it is not necessary to select a specific BLKSIZE on the DCB parameter for performance reasons because the subsystem selects its own blocking.

INTRDR with OUTPUT Parameter

Do not code an OUTPUT parameter when the writer-name subparameter is INTRDR.

6.Relationship to Other Control Statements
A sysout DD statement can directly or indirectly reference an OUTPUT JCL
statement. The parameters on the referenced OUTPUT JCL statement combine with the parameters on the sysout DD statement to control the processing of the sysout data set.

SYSOUT cannot specify a code-name subparameter in a job or job step that contains an OUTPUT JCL statement; in this case, JES2 treats the third
subparameter as a form-name, instead of a reference to a JES2 /*OUTPUT statement.

Backward References

Do not refer to an earlier DD statement that contains a SYSOUT parameter.

7.Starting an External Writer when Requested
When a statement supplying processing options for a sysout data set specifies an external writer, the writer must be started before it can print or punch the data set. The writer is started by a system command from the operator or in the input stream. If the writer is not started before the job produces the sysout data set, the data set is retained until the writer is started.

8.Held Classes in a JES2 System
A sysout data set is held if the sysout DD statement contains HOLD=YES or the OUTPUT JCL statement specifies OUTDISP=HOLD.

9.Held Classes in a JES3 System
If CLASS specifies a class-name that is defined to JES3 as a held class for the output service hold queue (Q=HOLD), all of the new output characteristics might not be included in the data set on the writer queue when (1) the data set is moved from the hold queue to the output service writer queue (Q=WTR), (2) the data setincludes an OUTPUT JCL statement, and (3) the NQ= or NCL= keyword is used.

10.Significance of Output Classes
To print this sysout data set and the messages from your job on the same output listing, code one of the following:

  • The same output class in the DD SYSOUT parameter as in the JOB MSGCLASS parameter.
  • DD SYSOUT=* to default to the JOB MSGCLASS output class.
  • DD SYSOUT=(,) to default to one of the following:
    1. The CLASS parameter in an explicitly or implicitly referenced OUTPUT JCL statement. In this case, the OUTPUT JCL CLASS parameter should specify the same output class as the JOB MSGCLASS parameter.
    2. The JOB MSGCLASS output class, if no OUTPUT JCL statement is referenced or if the referenced OUTPUT JCL statement contains either CLASS= or CLASS=*.

11.Examples of the SYSOUT Parameter

Example 

//DD1   DD   SYSOUT=P

In this example, the DD statement specifies that JES is to write the sysout data set to the device handling class P output.

Example 

//DD2   DD   DSNAME=&&PAYOUT1,SYSOUT=P

In this example, DD statement DD2 defines PAYOUT1 as the last qualifier of the system-generated name for the sysout data set. The system generates a name such as serid.jobname.jobid.Ddsnumber.PAYOUT1. The DD statement specifies that JES is to write the data set to the device handling class P output.

Example 

//JOB50   JOB    ,’C. BROWN’,MSGCLASS=C
//STEP1   EXEC   PGM=SET
//DDX     DD     SYSOUT=C

In this example, DD statement DDX specifies that JES is to write the sysout data set to the device handling class C output. Because the SYSOUT parameter and the MSGCLASS parameter specify the same class, the messages from his job and the sysout data set can be written to the same device.

Example 

//STEP1   EXEC      PGM=ANS
//OT1     OUTPUT    DEST=NYC
//OT2     OUTPUT    DEST=LAX
//OT3     OUTPUT    COPIES=5
//DSA     DD        SYSOUT=H,OUTPUT=(*.OT2,*.OT1,*.OT3)

In this example, the DD statement combines with the three referenced OUTPUT JCL statements to create three separate sets of output:

  1. DSA combines with OT1 to send the sysout data set to NYC.
  2. DSA combines with OT2 to send the sysout data set to LAX.
  3. DSA combines with OT3 to print five copies of the data set locally on the printer used for output class H.

Note that the output references can be in any order.

Example 

//DD5   DD   SYSOUT=(F,,2PRT)

In this example, the DD statement specifies that JES is to write the sysout data set to the device handling class F output. The data set is to be printed or punched on forms named 2PRT.

TERM parameter

Parameter Type

Keyword, optional

Do not use the TERM parameter for an SMS-managed data set (one with an assigned storage class).

Purpose

Use the TERM parameter to indicate to the system that a data set is coming from or going to a terminal for a TSO/E user.

Considerations for an APPC Scheduling Environment

The TERM parameter has no function in an APPC scheduling environment. If you code TERM, the system will check it for syntax and ignore it.

1.Syntax

TERM=TS

2.Subparameter Definition

TS
In a foreground job submitted by a TSO/E user, indicates that the input or output data set is coming from or going to a TSO/E userid.

In a background or batch job, the system either:

  • Ignores the TERM=TS parameter, when it appears with other parameters.
  • Fails the TERM=TS parameter with an allocation error, when the parameter appears by itself. (The system bypasses this error if SYSOUT=* is coded with TERM=TS.)

3.Relationship to Other Parameters
Do not code the following DD parameters with the TERM parameter.

*         DYNAM
AMP       PROTECT
DATA      QNAME
DDNAME

Code only the DCB and SYSOUT parameters with the TERM parameter. The system ignores any other DD parameters.

4.Location in the JCL
To ensure that the system uses the desired OUTPUT JCL statement, code all referenced OUTPUT JCL statements in the input stream before the DD statement that refers to them. For example, if the referencing DD statement appears in an in-stream or cataloged procedure, the referenced OUTPUT JCL statement should precede the DD statement in the procedure.

In a foreground TSO/E job, a DD statement containing TERM=TS and a SYSOUT parameter begins an in-stream data set. When concatenating DD statements, the DD statement that contains TERM=TS must be the last DD statement in a job step.

5.Examples of the TERM Parameter

Example 

//DD1   DD   TERM=TS

In a foreground job submitted from a TSO/E userid, this DD statement defines a data set coming from or going to the TSO/E userid.

Example 

//DD1   DD   TERM=TS,SYSOUT=*

In a background or batch job, the system ignores TERM=TS and recognizes a sysout data set. (An allocation error occurs if SYSOUT=* is not coded with TERM=TS.)

Example 

//DD3   DD   UNIT=3400-5,DISP=(MOD,PASS),TERM=TS,LABEL=(,NL),
//           DCB=(LRECL=80,BLKSIZE=80)

In a foreground job, the system ignores all of the parameters in this example except TERM and DCB. In a batch job, the system ignores only the TERM parameter.

UCS parameter

Parameter Type

Keyword, optional

Purpose

Use the UCS (universal character set) parameter to identify:

  • The UCS image JES is to use in printing this sysout data set.
  • A print train (print chain or print band) JES is to use in printing this sysout data set on an impact printer.
  • A font for this sysout data set printed on an AFP printer in a JES2 system. In this use, the UCS parameter acts like a CHARS parameter.

The UCS image specifies the special character set to be used. JES loads the image into the printer’s buffer. The UCS image is stored in SYS1.IMAGELIB. IBM provides the special character set codes.

1.Syntax

UCS= {character-set-code                     }
     {(character-set-code [,FOLD] [,VERIFY]) }
                          [  ,  ]
  • You can omit the parentheses if you code only a character-set-code.
  • All of the subparameters are positional. If you omit FOLD but code VERIFY, code a comma to indicate the omission. For example, UCS=(AN,,VERIFY).
  • Null positions in the UCS parameter are invalid.

2.Subparameter Definition

character-set-code
Identifies a universal character set. The character-set-code is 1 through 4 alphanumeric or national ($, #, @) characters. See Table for IBM standard special character set codes.

Table: Special Character Sets for the 1403, 3203 Model 5, and 3211 Printers

FOLD
Requests that the chain or train for the universal character set be loaded in fold mode. Fold mode is described in 2821 Component Description. Fold mode is most often used when upper- and lower-case data is to be printed only in uppercase.

Note: JES2 and JES3 do not support the FOLD subparameter. For JES2, the FOLD option is specified in the UCS image for JES2-controlled printers.

VERIFY
Requests that, before the data set is printed, the operator verify visually that the character set image is for the correct chain or train. The character set image is displayed on the printer before the data set is printed.

3.Defaults
If you do not code the UCS parameter, the system checks the UCS image in the printer’s buffer; if it is a default image, as indicated by its first byte, JES uses it. If it is not a default image, JES loads the UCS image that is the installation default specified at JES initialization.

On an impact printer, if the chain or train does not contain a valid character set, JES asks the operator to specify a character set and to mount the corresponding chain or train.

4.Overrides
For printing on a printer with the UCS feature, the UCS parameter on a sysout DD statement overrides an OUTPUT JCL UCS parameter. For printing on a 3800 Model 1, a CHARS parameter on the sysout DD statement or the OUTPUT JCL statement overrides all UCS parameters.

For a data set scheduled to the Print Services Facility (PSF), the PSF uses the following parameters, in override order, to select the font list:

  1. Font list in the library member specified by an OUTPUT JCL PAGEDEF parameter.
  2. DD CHARS parameter.
  3. OUTPUT JCL CHARS parameter.
  4. DD UCS parameter.
  5. OUTPUT JCL UCS parameter.
  6. JES installation default for the device.
  7. Font list on the PAGEDEF parameter in the PSF cataloged procedure.

5.Relationship to Other Parameters
Do not code the following DD parameters with the UCS parameter.

*          DYNAM
AMP        KEYOFF
DATA       PROTECT
DDNAME     QNAME

Do not code the UCS parameter with the DCB subparameters CYLOFL, INTVL, RESERVE, and RKP.

The FOLD and VERIFY subparameters are meaningful only when you specify a printing device directly on a DD statement, for example, UNIT=00E, thus bypassing JES sysout processing.

6.Using Special Character Sets
To use a special character set, SYS1.IMAGELIB must contain an image of the character set, and the chain or train for the character set must be available. IBM provides standard special character sets, and the installation may provide user-designed special character sets.

7.Examples of the UCS Parameter

Example 

//DD1   DD   UNIT=1403,UCS=(YN,,VERIFY)

In this example, the DD statement requests a 1403 Printer. The UCS parameter requests the chain or train for special character set code YN. Because VERIFY is coded, the system will display the character set image on the printer before the data set is printed.

Example 

//DD2   DD   SYSOUT=G,UCS=PN

In this example, the DD statement requests the device for output class G. If the device is a printer with the UCS feature, the system loads the UCS image for code PN. If the device is an impact printer, the system asks the operator to mount the chain or train for PN, if it is not already mounted. If the device is a 3800, the system uses the UCS subparameter to select the character-arrangement table. Otherwise, the system ignores the UCS parameter.

UNIT parameter

Parameter Type

Keyword, optional

Note: With SMS, you do not need to use the UNIT parameter to specify a device for an SMS-managed data set. Use the STORCLAS parameter or let an installation-written automatic class selection (ACS) routine select a storage class for the data set.

Also with SMS, for a non-SMS-managed data setyou’re your storage administrator has set a system default unit under SMS, you do not need to specify UNIT. Check with your storage administrator.

Purpose
Use the UNIT parameter to ask the system to place the data set on:

  • A specific device.
  • A certain type or group of devices.
  • The same device as another data set.

The UNIT parameter can also tell the system how many devices to assign and request that the system defer mounting the volume until the data set is opened.

1.Syntax

{UNIT=([ddd        ] [,unit-count] [,DEFER]) }
       [/ddd       ] [    ,P     ]
       [/dddd      ] [    ,      ]
       [device-type
       [group-name
{UNIT= AFF=ddname                             }
  • You can omit the parentheses if you code only the first subparameter.
  • All of the subparameters are positional. If you omit unit-count or P but code DEFER, code a comma to indicate the omission; one device is assigned to the data set. For example, UNIT=(3490,,DEFER).

2.Subparameter Definition

device-number
Identifies a specific device by a 3-digit or 4-digit hexadecimal number. Precede a 4-digit number with a slash (/). A 3-digit number can be specified with or without a slash.

Attention: Specify a device number only when necessary. When you specify a device number, the system can assign only that specific device. If the device is already being used, the job must be delayed or canceled.

However, for a permanently mounted direct access device, such as a 3390 Direct Access Storage, specifying a device type (UNIT=3390) and a volume serial number in the VOLUME=SER parameter has the same result as specifying a device number in the UNIT parameter.

In a JES3 system, if any DD UNIT parameter in a job specifies a device-number for a device that is JES3-managed or jointly JES3/MVS managed, the JES3 //*MAIN statement must contain a SYSTEM parameter. SMS ignores a device number, if specified for SMS-managed DASD.

device-type
Requests a device by its generic name, which is an IBM-supplied name that identifies a device by its machine type and model. For example, UNIT=3390. When a device-type name contains a hyphen, do not enclose it in apostrophes, for example, UNIT=3400-5. Obtain the list of device types you can specify from your installation. If you specify the device-type subparameter, SMS ignores it. For a 3480 Magnetic Tape Subsystem in compatibility mode, code UNIT=3400-9 or a group-name.

group-name
Requests a group of devices by a symbolic name. The installation must have assigned the name to the device(s) during system initialization or IBM must have assigned the name. The group-name is 1 through 8 alphanumeric characters. If you specify the group-name subparameter, SMS ignores it.

Group Names: A group-name can identify a single device or a group of devices. A group can consist of devices of the same or different types. For example, a group can contain both direct access and tape devices.

Note: A group name is called an esoteric name in Hardware Configuration Definition (HCD) terminology.

Allocation from Groups: The system assigns a device from the group. If a group consists of only one device, the system assigns that device. If the group consists of more than one device type, the units requested are allocated from the same device type. For example, if GPDA contains 3380 Disk Storage and 3390 Direct Access Storage devices, a request for two units would be allocated to two 3380s or to two 3390s.

Extending Data Set: If a data set that was created using the group-name subparameter is to be extended, the system allocates additional devices of the same type as the original devices. However, the additional devices may not necessarily be from the same group.

SYSALLDA: IBM assigned group-names include SYSALLDA, which contains all direct access devices defined to the system.

SYS3480R and SYS348XR: SYS3480R and SYS348XR are IBM-assigned group names. SYS3480R contains 3480, 3480X, and 3490 Magnetic Tape Subsystems. SYS348XR contains 3480X and 3490 Magnetic Tape Subsystems.

Use these group names to override the device type eligibility retrieved by the system when referencing existing 3480- or 3480 XF-formatted data sets.
Specifically, use SYS3480R when you want to read 3480-formatted data sets and use SYS348XR when you want to read 3480 XF-formatted data sets.

Note: LABEL=(n,,,IN) is the system-managed tape library equivalent of either UNIT=SYS3480R or UNIT=SYS348XR.

unit-count
Specifies the number of devices for the data set. ²Unit-count² is a decimal number from 1 through 59.

Number of Devices Allocated: The system uses the unit-count to determine how many devices to allocate. For tapes, the system uses the unit-count subparameter to allocate the specified number of system-managed or non-system-managed units. If you also specify P (for parallel mount) in the UNIT parameter, and for SMS-managed DASD, the system uses the highest of the following numbers to determine how many devices and volumes to allocate:

  • unit-count specified in the UNIT parameter
  • volume-count specified in the VOLUME parameter
  • number of volume serial numbers implicitly or explicitly specified

You may receive more devices than the unit-count requests if you specify VOLUME=REF or a permanently resident or reserved volume. And, if two DD statements in a step request the same volume and either DD statement requests any other volume(s), the system assigns an additional device.

Unit Count for Received or VOLUME=REF Data Sets: The system assigns one device when the DD statement receives a passed data set or refers in a
VOLUME=REF subparameter to a cataloged data set or earlier DD statement for volume and unit information. Code a unit-count subparameter if the data set needs more than one device.

Unit Count when Device Number Specified: When the first subparameter
requests a specific device, the unit count must be 1 or omitted. Only when the device is a communication device can the unit count be higher than 1.

P Asks the system to allocate the same number of devices as requested in the VOLUME volume-count or SER subparameter, whichever is higher. Thus, all volumes for the data set are mounted in parallel. If you specify the P subparameter for system-managed DASD, the system ignores it. If you specify the P subparameter for system-managed tape libraries, the system honors it.

DEFER
Asks the system to assign the data set to device(s) but requests that the volume(s) not be mounted until the data set is opened. To defer mounting, DEFER must be specified or implied for all DD statements that reference the volume.

If you specify the DEFER subparameter for system-managed DASD, the system
ignores it. If you specify the DEFER subparameter for system-managed tape libraries, the system honors it.

DEFER when Data Set is Never Opened: If you request deferred mounting of a volume and the data set on that volume is never opened by the processing
program, the volume is never mounted during the job step.

Restrictions on DEFER: Do not code DEFER:

  • For a new data set on direct access. The system ignores DEFER.
  • On a SYSCKEOV DD statement.

AFF=ddname
Requests that the system allocate different data sets residing on different,
removable volumes to the same device during execution of the step. This request is called unit affinity, where ²ddname² is the ddname of an earlier DD statement in the same step. Use unit affinity to reduce the number of devices used in a job step; request that an existing data set be assigned to the same device(s) as another existing data set. If you specify the UNIT=AFF subparameter for system-managed DASD, the system ignores it.

If you specify the UNIT=AFF subparameter for system-managed tape libraries, the system attempts to honor it. Under certain conditions the system ignores unit affinity.

Restrictions on UNIT=AFF: Do not code UNIT=AFF=ddname:

  • With DISP=NEW if the data set referenced in the AFF subparameter resides on a direct access device. This restriction applies only to non-SMS-managed DASD. If coded, the system terminates the job. If the referenced data set can be allocated to either tape or DASD, the system allocates both requests to tape devices.
  • On a DD * or DD DATA statement or on a DD statement containing a SUBSYS parameter. The system ignores the UNIT=AFF and defaults the device to
    SYSALLDA.
  • When the DD statement referenced in the AFF subparameter contain
    FREE=CLOSE.
  • With the STORCLAS parameter.
  • With an affinity specification to an earlier DD statement that requests SYS3480R or SYS348XR on the group-name subparameter, unless volume affinity also exists. Volume affinity exists when two DD statements both reference a data set on the same volume. Do not also specify DISP=OLD or DISP=MOD; attempting to write 3480 data to a 3490 drive, or 3490 data to a 3480 drive, will fail during OPEN processing with ABEND 813-04 accompanied by message IEC149I.

3.Overrides
If you code SYSOUT and UNIT on the same statement, the SYSOUT parameter overrides the UNIT parameter.

The system also obtains device information when the system obtains volume serial information from:

  • A VOLUME=REF=dsname reference to an earlier data set.
  • A VOLUME=REF=ddname reference to an earlier DD statement.
  • The volume(s) for a passed data set.
  • The catalog for a cataloged data set.

However, you can override the retrieved device information if the device you specify is a subset of the retrieved device information; otherwise the system ignores the overriding device information. For example, if the retrieved unit grouping is 3350, and the specified unit subparameter is 3350A (a subset of 3350), then the system allocates from the devices contained in 3350A.

If you have 3490 Magnetic Tape Subsystem models A10 and A20 defined to your system and you use one of the IBM-generated group names SYS3480R or SYS348XR, the system overrides the device type retrieved from the catalog with a device from the esoteric device group.

Note: LABEL=(n,,,IN) is the system-managed tape library equivalent of either UNIT=SYS3480R or UNIT=SYS348XR. You can mount 3480-formatted or 3480X-formatted (18-track formatted) tape volumes, that are not extended, on a 3490 tape device (36-track write, 18-track or 36-track read).

4.Relationship of the UNIT Parameter to Other Parameters
Do not code the following DD parameters with the UNIT parameter.

*         DYNAM
DATA      QNAME
DDNAME

Do not code the UNIT DEFER subparameter on a SYSCKEOV DD statement. To allocate a device, such as a printer or telecommunications device, that does not involve a data set, do not code the DISP parameter.

5.Location in the JCL
When a DD statement contains a UNIT=AFF=ddname parameter, the DD statement referenced in the AFF subparameter must be defined earlier in the job step; otherwise, the system treats the DD statement containing UNIT=AFF as a DD DUMMY statement.

The following example illustrates a case where the system treats the DD statement containing the UNIT=AFF as a DD DUMMY statement:

//STEP   EXEC   PGM=TKM
//DD1    DD     DDNAME=DD5
//DD2    DD     DSNAME=A,DISP=OLD
//DD3    DD     DSNAME=C,DISP=SHR,UNIT=AFF=DD1
//DD5    DD     DSNAME=B,DISP=SHR

DD3 requests unit affinity to DD1. Although DD1 occurs earlier in the job step than DD3, it refers to DD5 that is located after DD3. Because DD1 is not completely defined, the system treats DD3 as a dummy statement.

6.Examples of the UNIT Parameter

Example 

//STEP2  EXEC PGM=POINT
//DDX    DD DSNAME=EST,DISP=MOD,VOLUME=SER=(42569,42570),
//       UNIT=(3480,2)
//DDY    DD DSNAME=ERAS,DISP=OLD,UNIT=3480
//DDZ    DD DSNAME=RECK,DISP=OLD,
//       VOLUME=SER=(40653,13262),UNIT=AFF=DDX

DD statement DDX requests two 3480 tape devices, DD statement DDZ requests the same two devices as DDX. Note that the operator will have to change volumes on the two 3480 devices during execution of the job step. DD statement DDY requests one 3480 tape device.

Example 

//DD1   DD   DSNAME=AAG3,DISP=(,KEEP),
//           VOLUME=SER=13230,UNIT=3400-5

This DD statement defines a new data set and requests that the system assign any 3420 Magnetic Tape Unit that can operate in 6250 BPI NRZI nine-track format.

Example 

//DD2   DD   DSNAME=X.Y.Z,DISP=OLD,UNIT=(,2)

This DD statement defines a cataloged data set and requests that the system assign two devices to the data set. The system obtains the device type from the catalog.

Example 

//DD3   DD   DSNAME=COLLECT,DISP=OLD,
//           VOLUME=SER=1095,UNIT=(3490,,DEFER)

This DD statement defines an existing data set that resides on a tape volume and requests that the system assign a 3490 tape device. Because DEFER is coded, the volume will not be mounted until the data set is opened.

Example 

//STEPA   DD   DSNAME=FALL,DISP=OLD,UNIT=237

For this data set, the system retrieves the volume and device type from the catalog. The UNIT parameter, by specifying device 237, overrides the catalog device type; however, device 237 must be the same type as the device stated in the catalog.

Example 
This example shows the use of the ALLOCxx UNITAFF default. This example
assumes the following environment:

  • UNITAFF(3490) was specified in parmlib member ALLOC05, defining a 3490 as the default unit-affinity-ignored unit name. This default is used when unit affinity is ignored, the referenced DD is an SMS-managed request and the referencing DD is a NEW non-SMS-managed request, and the system is unable to obtain a unit from the primary DD in the unit affinity chain.
  • The SMS ACS routines are defined so that:
  • – Data set L is to be redirected from tape to an SMS-managed DASD volume, SD3.
    – Data set M is not to be redirected and is, therefore, still intended to go to a non-SMS managed tape volume.

//JOB2    JOB    ......
//STEP1   EXEC   ......
//DD11    DD     DSN=L,DISP=(NEW),UNIT=3480,.....
//STEP2   EXEC   ......
//DD21    DD     DSN=L,DISP=OLD,......
//DD22    DD     DSN=M,DISP=(NEW,CATLG),UNIT=AFF=DD21

In STEP1, DD11, data set L is created and cataloged on SD3, SMS-managed DASD (redirected using SMS ACS routines).

In STEP2, DD21, data set L is an existing data set and is cataloged on SD3, SMS-managed DASD. DD21 is both the referenced DD (referenced by the UNIT=AFF on DD22) and the primary DD.

In STEP2, DD22 is the referencing DD, which requests unit affinity to DD21. Because data set L is on SMS-managed DASD, the system cannot honor the unit affinity for DD22 which is intended to go to tape. With the unit affinity ignored, the system must determine a unit to be used for DD22.

The system is not able to rely on the unit information in the catalog for data set L, because the catalog reflects a DASD unit (as a result of being redirected). Because data set L was created in a prior step and there is no unit specified on DD21, the system is not able to use the JCL for DD21 as a source of unit information. The system will, therefore, use the unit-affinity-ignored unit name of 3490 for DD22.

VOLUME parameter

Parameter Type

Keyword, optional

Terminology

Data sets on system-managed tape volumes exhibit both SMS and non-SMS
characteristics. When necessary, data sets on a system-managed tape volume are distinguished from system-managed DASD data sets. Otherwise, the term
system-managed data sets refers to both data sets on a system-managed tape volume and system-managed DASD data sets.

With SMS, consider the following:

  • All volumes in a multi-volume data set should reside in the same system-managed tape library and must belong to the same tape storage group. If all of the volumes do not reside in the same tape library, the installation can enter the volumes through the DFSMS installation exit, CBRUXVNL.
  • You cannot make a specific volume reference to a scratch volume.
  • You do not need to use the VOLUME parameter to specify volumes for new data sets. See the DATACLAS parameter and the STORCLAS parameter.
  • You cannot override the volume count for an existing system-managed DASD data set (but you can specify a volume count when you create a new system-managed DASD data set).
  • If the storage administrator has specified a system default unit name and you do not code a UNIT name for non-system-managed data sets, then the system uses the volumes associated with the default unit name. In this case, you do not need to code the VOLUME parameter. Check with your storage administrator to determine whether a default unit name has been specified.

Purpose
Use the VOLUME parameter to identify the volume or volumes on which a data set resides or will reside. You can request:

  • A private volume
  • Retention of the volume
  • A specific volume by serial number
  • The same volume that another data set uses

You can also specify which volume of a multivolume data set is to be processed first and, for an output data set, the number of volumes required.

A nonspecific volume request is a DD statement for a new data set that can be assigned to any volume or volumes. To make a nonspecific volume request for a new data set, either:

  • Omit the VOLUME parameter.
  • Code a VOLUME parameter but omit a SER or REF subparameter.

1.Syntax

{VOLUME} = ([PRIVATE] [,RETAIN] [,volume-sequence-number] [,volume-count]
{VOL   }              [   ,   ] [,                      ]
                      [SER=serial-number ]
                      [SER=(serial-number[,serial-number]...)]
                  [,] [REF=dsname ]
                     [REF=*.ddname ]
                     [REF=*.stepname.ddname ]
                     [REF=*.stepname.procstepname.ddname ]

Single Subparameter: You can omit the parentheses if you code only PRIVATE or only a keyword subparameter. For example,

VOLUME=PRIVATE or VOLUME=SER=222001 or VOLUME=REF=DS1.

Null REF Subparameter: The REF subparameter of the VOLUME parameter can
have a null value only when coded on a DD that either overrides a DD in a
procedure or is added to a procedure.

Null Positional Subparameters: Null positions in the VOLUME=SER parameter are invalid.

Positional Subparameters: The first four subparameters are positional. The last subparameter, SER or REF, is a keyword subparameter and must follow all
positional subparameters. Code a comma to indicate an omitted positional
subparameter as follows:

  • If you omit PRIVATE and code RETAIN, code a comma before RETAIN. For
    example,
    VOLUME=(,RETAIN,2,3,SER=(222001,222002,222003)).
  • Code a comma when RETAIN is omitted and the volume sequence number and volume count subparameters follow. For example,
    VOLUME=(PRIVATE,,2,3,SER=(222001,222002,222003)),

    and if PRIVATE is also omitted,

    VOLUME=(,,2,3,SER=(222001,222002,222003)).
  • Code a comma when the volume sequence number is omitted and the volume count subparameter follows. For example,
    VOLUME=(,RETAIN,,3,SER=(222001,222002,222003)), and
    VOLUME=(PRIVATE,,,3,SER=(222001,222002,222003)), and
    VOLUME=(,,,3,SER=(222001,222002,222003)).
  • Code a comma when the volume count is omitted, at least one other subparameter precedes it, and a keyword subparameter follows. For example,
    VOLUME=(,RETAIN,2,,SER=(222001,222002,222003)), and
    VOLUME=(,,2,,SER=(222001,222002,222003)), and
    VOLUME=(,RETAIN,REF=*.stepname.ddname)

Single SER Subparameter: You can omit the parentheses in the SER subparameter if you code only one serial number. For example,

VOLUME=SER=222001.

Special Characters: When a serial number in the SER subparameter contains special characters, other than hyphens, enclose it in apostrophes. For example,

VOLUME=SER=(222001,222-02,'222/03').

When the dsname in the REF subparameter contains special characters, other than the periods used in a qualified name, enclose it in apostrophes. For example,

VOLUME=REF='DS/284'.

Code each apostrophe that is part of the serial number or data set name as two consecutive apostrophes. For example,

VOLUME=SER='O''HARE' or VOLUME=REF='DS''371'.

2.Subparameter Definition

PRIVATE
Requests a private volume. Private means that:

  • The system is not to allocate an output data set to the volume unless the volume is specifically requested, such as in a VOLUME=SER subparameter.
  • If tape, the volume is to be demounted after the data set is closed, unless RETAIN is also coded or the DD DISP parameter specifies PASS.
  • If a demountable direct access volume, the volume is to be demounted after the data set is closed.

RETAIN
For a private tape volume, RETAIN requests that this volume is not to be
demounted or rewound after the data set is closed or at the end of the step. For a public tape volume, RETAIN requests that this volume is to be retained at the device if it is demounted during the job.

RETAIN Support: RETAIN is supported only for tape volumes managed by the basic control program and by JES2. If coded on a DD statement for a tape data set on a JES3-managed device, JES3 ignores the parameter when issuing KEEP/RETAIN messages and when performing unallocation at the end of the job. However, if RETAIN is coded for a tape data set on a JES3-managed device and the tape volume is to be shared with a later step, JES3 designates the volume as retained.

RETAIN has no effect on the handling of direct access volumes.

Demounting Despite RETAIN: Coding RETAIN does not ensure that the operator will not unload the volume or that the system will not demount it for another job step allocation. Either can occur when the device on which the volume is mounted is not allocated to the job step that specified RETAIN or, for unlabeled tapes, when the volume requires verification. If the system does demount a volume for which RETAIN was requested, it will do so by issuing message IEF234E R (retain) for that volume. When the system reaches the next step requiring that volume, it will request the operator to remount the volume on an available device of the
appropriate type.

volume-sequence-number
Identifies the volume of an existing multivolume data set to be used to begin processing the data set. The volume sequence number is a decimal number from 1 through 255; the first volume is identified as 1. The volume sequence number must be less than or equal to the number of volumes on which the data set exists; otherwise, the job fails.

If the volume sequence number is not specified the system will process the first volume. For new data sets, the system ignores the volume sequence number.

volume-count
Specifies the maximum number of volumes that an output data set requires. The volume count is a decimal number from 1 through 255 for a tape data set and from 1 through 59 for a DASD data set. The total volume count for all DD statements in one job step cannot exceed 4095.

Note: The system uses the unit count to determine how many devices to allocate. However, if you also specify P (for parallel mount) in the UNIT parameter, the system might use the value specified for the volume count to determine how many devices and volumes to allocate.

Volume Count for Tape Data Sets: Code a volume count when a new data set will reside on 6 or more volumes. If you omit the volume count or if you specify 1 through 5, the system allows up to five volumes; if you specify 6 through 20, the system allows 20 volumes; if you specify a count greater than 20, the system allows 5 plus a multiple of 15 volumes.

Volume Count and Serial Numbers: When the volume count is greater than:

  • The number of volume serials coded in the SER subparameter
  • The number of volume serials the system retrieved from the catalog
  • The number of volume serials the system retrieved from VOL=REF
  • The number of volume serials the system retrieved from a passed data set, the system assigns other volumes to the remaining devices. If the volume count is smaller than the number of volume serials, the system ignores the volume count.

If a data set may need more volumes than the number of volume serials coded, specify a volume count equal to the total number of volumes that might be used. Requesting more volumes in the volume count will make sure that the data set can be written on more volumes if it exceeds the requested volumes.

If you do not code a volume count and volume serial number, the system can extend an existing cataloged data set that resides on a removable volume up to 20 volumes.

Volume Count for Nonspecific Requests: If the request is for a nonspecific, public volume on a direct access device, the system ignores the volume count and
allocates the number of volumes in the UNIT unit count subparameter.

If the request is for a nonspecific, private volume, the system treats it like a specific request if the volume count is more than one and allocates the number of volumes in the volume count.

Volume Count for System-Managed DASD Data Sets: You cannot specify a volume count for an existing system-managed DASD data set. (If you do, the system will ignore it.) When you create a new system-managed DASD data set, however, you can override the volume count defined in the data class by using the volume-count subparameter.

Volume Count for System-Managed Tape Data Sets: If you specify a volume count and DISP=PASS on a DD statement, the system will pass the volume count to subsequent receiving steps within the job. This may cause the system to allocate more devices than expected to the receiving DD. Coding UNIT=AFF in the receiving step’s DD will result in the optimum number of devices being allocated to the receiving DD.

SER=serial-number
SER=(serial-number[,serial-number]...)
Identifies by serial number the volume(s) on which the data set resides or will reside. A volume serial number is 1 through 6 alphanumeric, national ($, #, @), or special characters; enclose a serial number that contains special characters, other than hyphens, in apostrophes. If the number is shorter than 6 characters, it is padded with trailing blanks.

You can code a maximum of 255 volume serial numbers on a DD statement. Do not specify duplicate volume serial numbers in a SER subparameter. Each volume must have a unique volume serial number, regardless of whether it is a tape or disk volume. Do not code a volume serial number as SCRTCH, PRIVAT, or Lnnnnn (L with five numbers); these are used in messages to ask the operator to mount a volume.

Do not code a volume serial number as MIGRAT, which is used by the Hierarchical Storage Manager DFSMShsm for migrated data sets. When using some typewriter heads or printer chains, a volume serial number may be unrecognizable if you code certain special characters.

For a permanently mounted direct access device, such as a 3390 Direct Access Storage, specifying a volume serial number and UNIT=3390 has the same result as specifying a device number in the UNIT parameter.

For new SMS-managed data sets:
For an SMS-managed data set, code the SER subparameter only if the storage administrator has specified GUARANTEED_SPACE=YES in the storage class of the data set. In this case, SMS uses the volumes you explicitly specify. If it is unable to do so, the allocation fails. The volume serial numbers must be assigned to the same storage group. If GUARANTEED_SPACE=YES is not in effect, SMS ignores any volume serial numbers you specify for new SMS-managed data sets.

For existing data sets:

  • If you do not specify a volume serial number and you specify an SMS-
    managed or cataloged data set:
    the system will allocate the data set to the volume on which it resides.
  • If you specify a non-SMS-managed volume serial number: the system will
    allocate the data set on the volume specified, regardless of whether there is a cataloged or SMS-managed data set of the same name elsewhere. If there is no data set with the specified name on the volume specified, the request will fail.
  • If you specify an SMS-managed volume serial number: the system will find and allocate the data set to the volume on which it resides, even if that is different from the volume specified. If there is no SMS-managed data set with the specified name, the request will fail.
  • When multiple DD statements in the same step for the same SMS-managed DASD data set are specified: if DISP=MOD is specified, or the OPEN or OPENJ macro is issued with the EXTEND or OUTINX option, a data integrity exposure occurs when the data set is extended on additional volume(s). This new volume information is not available to the other DD statements in the job step for the same data set. The data on the new volume(s) will be overlayed if the data set is opened for output processing using one of the other DD statements in the same job step and the data set is again extended.
  • Recommendation: Have only one DD statement per step for a data set that may need to extend to a new volume.
  • When two data sets, one that is SMS-managed and one that is not, share the same data set name:
  • – If you specify the non-SMS-managed volume, the system will allocate the non-SMS-managed data set.
    – If you do not specify the volume information, or you specify an SMSmanaged volume, the system will allocate the SMS-managed data set.

REF=dsname
REF=*.ddname
REF=*.stepname.ddname
REF=*.stepname.procstepname.ddname
Tells the system to obtain volume serial numbers from another data set or an earlier DD statement.

Note: VOL=REF obtains ONLY the volume serial numbers from the referenced data set or earlier DD statement. In particular it does not obtain the volume sequence number, volume count, label type, or data set sequence number.

dsname
Names a cataloged or passed data set. The system assigns this data set to the same volumes containing the cataloged or passed data set. When dsname names a passed data set, the reference must appear on a DD statement before the receiving DD statement. (After a passed data set is received, the passed data set information is no longer available.)

The dsname can be an alias name or a catalog name. The dsname cannot be a generation data group (GDG) base name, a GDG relative generation member, or a member name of a non-GDG data set. When the dsname contains special
characters, other than the periods used in a qualified name, enclose it in
apostrophes.

*.ddname
Asks the system to obtain the volume serial numbers from earlier DD statement ddname in the same job step.

*.stepname.ddname
Asks the system to obtain the volume serial numbers from DD statement, ddname, in an earlier step, stepname, in the same job.

*.stepname.procstepname.ddname
Asks the system to obtain the volume serial numbers from a DD statement in a cataloged or in-stream procedure. Stepname is the name of the job step that calls the procedure, procstepname is the name of the procedure step that contains the DD statement, and ddname is the name of the DD statement.

Referenced Data Set Not Opened: When REF refers to a DD statement in a previous step and the data set was not opened, the system allocates a device that has the widest range of eligibility to meet both DD statement requests. Thus, the system might allocate a device for which the referring data set is not eligible. To prevent this problem for tape data sets, always code the DCB DEN subparameter or the DCB TRTCH subparameter on a DD statement that you plan to reference.

References to Multivolume Tape Data Sets: When REF refers to a data set residing on more than one tape volume, the system allocates all volumes to the referencing DD when it represents an OLD data set, that is, a data set that existed prior to the current job step. For a NEW tape data set the system allocates only the last volume of a referenced multivolume tape data set.

If an earlier job step extends the referenced data set to more volumes, or adds or extends an earlier data set so that the referenced data set resides on a later volume, the new volume information is available to the referencing DD statement.

If the current job step extends the referenced data set to more volumes, or adds or extends an earlier data set so that the referenced data set resides on a later volume, the new volume information is available to the referencing DD statement ONLY when the referenced data set is a new data set with no volume serial numbers explicitly or implicitly specified, which means only if the entire collection of data sets on the volumes was created in the current step. In other words, if the current job step extends the referenced data set to more volumes, or adds or extends an earlier data set so that the referenced data set resides on a later volume, the new volume information is not available to the referencing DD statement when either of the following conditions is true:

  • The data set that is referenced (directly or through a chain of references) existed before the start of the step containing the reference.
  • The data set that is referenced (directly or through a chain of references) is a new data set requested with specific volume serial numbers.

If the referenced data set already exists and has volume serial numbers explicitly specified, then the last listed volume serial is used even if the earlier data set actually exists on or is written to fewer volumes.

If the referenced data set is new and has specific volume serials, then the last listed volume serial is used even if the data set is written with fewer volumes. In either of these cases, the allocation of the referencing data set is likely to fail.

References to Multivolume Direct Access Data Sets: When REF refers to a data set that resides on more than one direct access volume, the system allocates all of the volumes. If a DD statement that is requesting a new data set has a unit count and volume count greater than one but specifies no volume serial numbers, one volume is allocated.

If a second DD statement within the same step requests the same data set, the same volume is allocated to it. If this job step extends the data set to more volumes, this new volume information is not available to the second DD statement.

Two or more DD statements in the same step can request the same data set. However, if the data set is extended to additional volumes in that step, the additional volume information is not available to the second or succeeding DD statements within the step.

References to DD Statements with UNIT Group Names: When REF refers to a DD statement containing a UNIT group-name subparameter, the system allocates a device of the same type actually used for the referenced data set, but not necessarily a device in the referenced group-name.

References to VSAM Data Sets: When REF refers to a multivolume VSAM data set, the system allocates a device of the same type as the first device type used for the referenced VSAM data set.

References to SMS-Managed Data Sets: When REF refers to an SMS-managed data set, SMS manages the new data set using the storage class of the referenced data set, if it is available, and applies these rules:

  • If the reference is to a data set on one or more SMS-managed tape volumes, then the two data sets must be assigned to the same storage group. If the automatic class selection (ACS) routine does not assign the same storage group to the referenced and referencing data sets, the allocation fails with message IGD304I.
  • For references to data sets on SMS-managed media other than tape, the two data sets must be assigned to compatible types of storage groups. This ensures the consistency for locate requests. For example, if the referenced data set is on DASD, allocating the referencing data set to be allocated on tape could result in potential locate request errors. If the ACS routine does not assign compatible types of storage group

References to Non-SMS-Managed Data Sets: When REF refers to a non-SMS-managed data set, the ACS routine receives control and can do one of two things:

  • Allow the allocation to proceed as a non-SMS-managed data set.
  • Fail the allocation by exiting with a non-zero return code.

If the ACS routine attempts to make the referencing data set SMS-managed, SMS fails the allocation with message IGD305I.

Do Not Refer to In-Stream Data Sets: Do not refer to a DD *, DD DATA, or DD SYSOUT statement. The system ignores the reference and defaults the device name to SYSALLDA, which is the group name for all direct access devices defined to the system.

References to DUMMY Data Sets: If ddname refers to a DD DUMMY statement, the data set for this DD statement is also assigned a dummy status.

Label Type Picked up from Referenced Statement: When REF is coded, the system also copies the LABEL label type subparameter from the referenced DD statement.

3.Overrides
The volume sequence number overrides a DISP=MOD parameter. Thus, instead of starting at the end of the data set on the last volume, according to the MOD subparameter, processing of the data set begins with the volume indicated by the volume sequence number.

4.Relationship to Other Parameters
Do not code the following parameters with the VOLUME parameter.

BURST    DDNAME    MODIFY
CHARS    DYNAM     QNAME
COPIES   FLASH     SYSOUT

Do not code VOLUME=REF with the STORCLAS parameter.

Other DD Parameter Picked up from Referenced Statement
When REF is coded, the system also copies the LABEL label type subparameter from the referenced DD statement.

For 3540 Diskette Input/Output Units
The VOLUME=SER, DCB=BUFNO, and DSID parameters on a DD * or DD DATA statement are ignored except when they are detected by a diskette reader as a request for an associated data set. See the 3540 Programmer’s Reference.

5.VOLUME Parameter in a JES3 System
When you do not code a volume serial number, code PRIVATE if you want JES3 to manage the allocation. Otherwise, MVS manages the allocation. RETAIN is ignored in a JES3 system.

6.VOLUME Parameter for Optical Readers
For optical readers, if no volume serial number is specified, the system assumes VOLUME=SER=OCRINP.

7.VOLUME Parameter for Nonspecific Volume Requests
A nonspecific volume request can appear on a DD statement for a new data set; the data set is assigned to any volume or volumes. The nonspecific request is made through a VOLUME parameter that does not contain a SER or REF subparameter. The parameter can contain the following subparameters:

VOLUME=(PRIVATE,RETAIN,,volume-count)

Note: The use of PRIVATE on nonspecific requests eligible to permanently resident DASD devices is not recommended. Operator intervention is required to allow the system to allocate such a request to a private volume.

8.VOLUME parameter for Specific Multi-Volume Tape Requests
When allocating a specific, multi-volume tape data set, if the data set resides on multiple tape volumes that are:

  • System-managed, then all volumes should reside in the same system-managed tape library and the same tape storage group. (If all of the volumes do not reside in the same tape library, the installation can enter the volumes through the DFSMS installation exit, CBRUXVNL.) These volumes must also be part of the same SMS storage group.
  • Non-system-managed, then all volumes must be outside of any system-managed tap library.

9.Examples of the VOLUME Parameter

Example 

//DD1   DD   DSNAME=DATA3,UNIT=SYSDA,DISP=OLD,
//           VOLUME=(PRIVATE,SER=548863)

The DD statement requests an existing data set, which resides on the direct access volume, serial number 548863. Since PRIVATE is coded, the system will not assign to the volume another data set for which a nonspecific volume request is made and will demount the volume at the end of the job.

Example 

//DD2   DD   DSNAME=QUET,DISP=(MOD,KEEP),UNIT=(3400-5,2),
//           VOLUME=(,,,4,SER=(96341,96342))

The DD statement requests an existing data set, which resides on two volumes, serial numbers 96341 and 96342. The VOLUME volume count subparameter requests four volumes, if required. Thus, if more space is required, the system can assign a third and fourth volume.

Example 

//DD3   DD   DSNAME=QOUT,UNIT=3400-5

The DD statement defines a data set that is created and deleted in the job step. By omission of the VOLUME parameter, the statement makes a nonspecific volume request, thereby asking the system to assign a suitable volume to the data set.

Example 

//DD4   DD   DSNAME=NEWDASD,DISP=(,CATLG,DELETE),UNIT=3350,
//           VOLUME=SER=335006,SPACE=(CYL,(10,5))

This new data set is assigned to volume serial number 335006, which is a permanently mounted volume on a particular 3350 Direct Access Storage. You can obtain the same space on the same volume in another way: instead of specifying the volume serial number and UNIT=3350, you can specify the device number of the particular 3350 device in the UNIT parameter.

Example 

//OUTDD   DD   DSNAME=TEST.TWO,DISP=(NEW,CATLG),
//             VOLUME=(,,,3,SER=(333001,333002,333003)),
//             SPACE=(TRK,(9,10)),UNIT=(3330,P)
//NEXT    DD   DSNAME=TEST.TWO,DISP=(OLD,DELETE)

DD statement OUTDD creates a multivolume data set and catalogs it. If the data set does not require three volumes, it will reside on fewer volumes. DD statement NEXT then deletes the data set. If the data set resides on fewer volumes than the number of volumes on which it is cataloged, the following messages appear in the job log when the system deletes the data set:

IEF285I   TEST.TWO                             DELETED
IEF285I   VOL SER NOS=333001,333003.
IEF283I   TEST.TWO                             NOT DELETED
IEF283I   VOL SER NOS=333002 1.
IEF283I   TEST.TWO                             UNCATALOGED
IEF283I   VOL SER NOS=333001,333002,333003.

If the data set resides on all specified volumes, the following messages appear in the job log when the system deletes the data set:

IEF285I TEST.TWO                               DELETED
IEF285I   VOL SER NOS=333001,333002,333003.

Example 

//SMSDS2   DD   DSNAME=MYDS2.PGM,STORCLAS=SCLAS02,DISP=(NEW,KEEP),
//              VOLUME=SER=(223344,224444)

For new system-managed DASD data sets or data sets on a system-managed tape volume, the system uses the attributes in the storage class named SCLAS02 for the storage service level of the data set. Also, if the storage administrator has specified GUARANTEED_SPACE=YES in the storage class for DASD VOLUME=SER can be coded and the data set will reside on the specified volumes. (However, if space is not available on the volumes, the job step fails. Allocation also fails if the requested volumes aren’t in any of the possible storage groups for the data set. For tape requests, the system always gets the tape request specified with a specific volume serial.) Installation-written automatic class selection (ACS) routines select the data class and management class.

Example 

//STEP1   EXEC PGM=....
//DD1     DD DSN=OLD.SMS.DATASET,DISP=SHR
//DD2     DD DSN=FIRST,DISP=(NEW,CATLG,DELETE),VOL=REF=*.DD1
//STEP2   EXEC PGM=...
//DD3 DD DSN=SECOND,DISP=(NEW,CATLG,DELETE),VOL=REF=*.STEP1.DD1

DD1 in STEP1 identifies the original SMS-managed data set OLD.SMS.DATASET. DD2 in STEP1 and DD3 in STEP2 each create an SMS-managed data set using the attributes in the storage class associated with the original data set OLD.SMS.DATASET in DD1

Searches relevant to you
Top