$ADD SUBMITLIB(`xxxxxxxxx`) - Add a new concatenation for $SUBMIT

Function

Defines a new SUBMITLIB(xxxxxxxx) data set concatenation to be used when submitting batch jobs by using the $SUBMIT command on this member. The concatenations can contain any combination of partitioned data sets (PDSs) or file system paths.

If a file system path is specified, files in the path with 1-8 character file names that conform to standard PDS member names can be accessed using the FILEDATA=TEXT allocation option.

Note: This command is not used to add an entry to an existing concatenation. To add a data set or path to an existing concatenation, use the $T SUBMITLIB command.

Syntax

Modification keywords

Data Set Specifications

Parameters

xxxxxxxx

Specifies the 1-8 character SUBMITLIB DD name that is being added. The SUBMITLIB DD name can be specified as DDNAME= on the $SUBMIT command or defaulted on the DD_DEFAULT= keyword on the SUBMITDEF statement.

DD(nnn)=

Specifies up to 255 data sets to be concatenated to this SUBMITLIB DD name. Data sets in this list are compacted after each initialization statement is processed. If you specify DD(1), DD(20), and DD(100) for a new SUBMITLIB concatenation, the resulting concatenation is renamed to DD(1), DD(2), and DD(3). Though up to 255 data sets can be specified, MVS rules limit any data set concatenation to 255 extents. If any data set has more than one extent, then the total number of data sets that can be supported are reduced.

DSName=jxxx...x

Specifies a 1-44 character data set name which JES2 includes in this SUBMITLIB concatenation. This data set must be a partitioned data set (PDS).

UNIT=hhhh|/hhhh|nnnn|cccccccc

If the SUBMITLIB data set to be used is not cataloged, then you must specify the unit information for the device containing the data set in one of the following ways:

hhhh | /hhhh

Specifies a 3 or 4 digit hexadecimal device number. Device numbers can be specified in one of the following formats:

UNIT=hhh
UNIT=/hhh
UNIT=/hhhh

Where, hhh and hhhh represent the device numbers. A slash (/) must precede a 4 digit device number.

nnnn

Specifies a device name.

cccccccc

Specifies a 1-8 character group name that is assigned to the device or group of devices that contained the noncataloged initialization data set to be included.

VOLser=xxxxxx

If the SUBMITLIB data set to be used is not cataloged, then this specifies a 1-6 character volume serial number on which the data set resides.

PATH=’xxxxxxxx’

Specifies a 1-88 character file system PATH which JES2 includes in this SUBMITLIB concatenation. Files in this path with a 1-8 character uppercase names that conform to standard PDS member names can be accessed by the $SUBMIT command. This path is allocated with the FILEDATA=TEXT allocation option. If the PATH= value is coded as null (no operand specified), then the DD(nnn) is deleted from an existing concatenation.

UNCONDitional|CONDitional

Specifies what action JES2 should take if one of the data sets or paths cannot be allocated. If CONDitional is specified (or defaulted), then if any data set or path cannot be allocated, the $ADD command fails. If UNCONDitional is specified, then an error allocating a single data set or path is ignored. The entry is not added to the concatenation but it remains assigned to the DD(nnn). If the concatenation is displayed, failed DD(nnn) displays the text 'ALLOCATION FAILED' before the data set name or path value. If all the data sets and paths in a concatenation fail to allocate, then the $ADD fails regardless of whether UNCONDitional was specified.

Authority Required

This command requires system authority. The description of the $T RDRnn command explains how to ensure that the authority of the appropriate MVS™ system command group is assigned.

This command requires control security access authority. For a description of assigning command input authority, see z/OS JES2 Initialization and Tuning Guide.

Processing Considerations

The $ADD SUBMITLIB command processing only ensures that the data sets that are specified can be allocated. It does not ensure that they actually exist or can be opened and used as a SUBMITLIB data set. That processing occurs when the SUBMITLIB is used by a $SUBMIT command.

Scope

Single member. The values that are supplied for this command is in effect for this member only.

Messages

The $HASP736 message displays the current SUBMITLIB concatenation.

The $HASP003 RC=56 indicates that you are trying to add a SUBMITLIB concatenation that already exists.

The $HASP003 RC=91 indicates that the command failed because there was an allocation failure. This is accompanied by the $HASP581 message with the allocation return, error, and information code. In this case, additional IKJ messages are issued to describe the allocation error.

Examples

 1 
$add submitlib(test),dd1=dsn=sys1.test.jcl       
          $HASP736 SUBMITLIB(TEST)                       
$HASP736 SUBMITLIB(TEST)                                 
$HASP736                     DD(1)=(DSNAME=SYS1.TEST.JCL,
$HASP736                     VOLSER=STORAG)

Add a new SUBMITLIB concatenation TEST with one data set SYS1.TEST.JCL

 2 
$add submitlib(prod),dd1=dsn=ibmuser.test.jcl,dd2=path='/u/ibmuser/jcl’
          $HASP736 SUBMITLIB(PROD)                           
$HASP736 SUBMITLIB(PROD)                                     
$HASP736                     DD(1)=(DSNAME=IBMUSER.TEST.JCL, 
$HASP736                     VOLSER=J2SHR2),                 
$HASP736                     DD(2)=(PATH=/u/ibmuser/jcl)

Add a new SUBMITLIB concatenation PROD with one data set IBMUSER.TEST.JCL and a path /u/ibmuser/jcl.

 3 
$add submitlib(error),dd(1)=(dsname=ibmuser.test.jcl),dd(2)=(dsname=sys1.prod.jcl)
       $HASP581 MEMBER IBM1 -- DYNAMIC ALLOCATE FAILED FOR ERROR  
      RC=4 S99ERROR=1708 S99INFO=0002                             
      IKJ56228I DATA SET SYS1.PROD.JCL NOT IN CATALOG OR CATALOG  
      CAN NOT BE ACCESSED                                         
       $HASP003 RC=(91),ADD SUBMITLIB(ERROR)  - ALLOCATION FAILURE

Attempt to add a new SUBMITLIB but the second data set, DD(2), does not exist. Therefore, the default for the add is CONDITIONAL and the $ADD fails because of the allocation error.

 4 
$add sublib(error),dd(1)=(dsname=ibmuser.test.jcl),
                             dd(2)=(dsname=sys1.prod.jcl), unconditional
          $HASP581 MEMBER IBM1 -- DYNAMIC ALLOCATE FAILED FOR ERROR
         RC=4 S99ERROR=1708 S99INFO=0002                           
         IKJ56228I DATA SET SYS1.PROD.JCL NOT IN CATALOG OR CATALOG
         CAN NOT BE ACCESSED                                       
          $HASP736 SUBMITLIB(ERROR)                                
$HASP736 SUBMITLIB(ERROR)                                          
$HASP736                     DD(1)=(DSNAME=IBMUSER.TEST.JCL,       
$HASP736                     VOLSER=J2SHR2),                       
$HASP736                     DD(2)=(ALLOCATION FAILED,             
$HASP736                     DSNAME=SYS1.PROD.JCL)

Unconditionally add a new SUBMITLIB concatenation ERROR even though the second data set SYS1.PROD.JCL does not exist.