PATH parameter - IBM-JCL

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. OSYNCSpecifies 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.


All rights reserved © 2018 Wisdom IT Services India Pvt. Ltd DMCA.com Protection Status

IBM-JCL Topics