Most ACS variables are read-only. Read-only variables contain data set and system information, and they reflect what is known at the time of the allocation request. You can use read-only variables in comparison operations, but you cannot change their values.

All of the read-only variables appear in Table 1. The read-only variables are case sensitive. The following pages explain the uses of the read-only variables.

Name

Description

&ACCT_JOB

The accounting information from the JOB statement. (For a description of the indexing function for accounting information, see Special functions.)

Type: Literal

Max value: 142 characters

&ACCT_STEP

The accounting information from the EXEC statement. This information is refreshed for each step in the job. (For a description of the indexing function for accounting information, see Special functions.)

Type: Literal

Max value: 142 characters

&ACSENVIR

The environment in which the ACS routine was invoked, one of:

ALLOC

for new data set allocations (this is the default)

ALLOCTST

for a pre-allocation or allocation test environment.

CHANGE

OSREQ object change environment

CONVERT

for data set convert in place operations

CTRANS

OSMC object class transition environment

RECALL

for data set recall operations

RECOVER

for data set recover operations

RENAME

for data set alter rename operations

RMMPOOL

for DFSMSrmm requests for a storage group name

RMMVRS

for DFSMSrmm requests for a management class name

STORE

OSREQ object store environment

other

installation exit can set its own value before re-invoking ACS

Type: Literal

Max value: 8 characters

&ACSENVR2

The sub-environment in which the ACS routine was invoked. The valid values are the values for &ACSENVIR as well as FLASHCPY and blank.

Type: Literal

Max value: 8 characters

&ALLVOL

The volume serial numbers specified for data set allocations when &ACSENVIR is not recall or recover. When the environment is recall or recover, &ALLVOL is either the volume serial number on which the data set resided at the time it was migrated or backed up, or the volume serial number specified as the target volume of the recall or recover.

Exception: &ALLVOL is not available to the storage group ACS routine when the environment is recall or recover and when VOLCOUNT(ANY) is specified. See Special functions for usage information.

Type: Literal

Max value: 6 characters

The &ALLVOL ACS read-only variable contains the following values when you use VOL=REF:

• 'REF=SD' (the volume reference is to an SMS-managed DASD or VIO data set)
• 'REF=ST' (the volume reference is to an SMS-managed tape data set)
• 'REF=NS' (the volume reference is to a non-SMS-managed data set)

&ANYVOL

The volume serial numbers explicitly specified for the volumes if &ACSENVIR is not recall or recover. When the environment is recall or recover, &ANYVOL is either the serial number on which the data set resided at the time it was migrated or backed up, or the volume serial number specified as the target volume of the recall or recover.

Attention: &ANYVOL is not available to the storage group ACS routine when the environment is recall or recover and when VOLCOUNT(ANY) is specified. See Special functions for usage information.

Type: Literal

Max value: 6 characters

The &ANYVOL ACS read-only variable contains the following values when you use VOL=REF:

• 'REF=SD' (the volume is reference to an SMS-managed DASD data set)
• 'REF=ST' (the volume is reference to an SMS-managed tape data set)
• 'REF=NS' (the volume is reference to a Non-SMS-managed data set)

&APPLIC

The name of the application associated with the resource owner of the data set (which is set only if RACF® is installed and ACSDEFAULTS is YES in IGDSMSxx).

Type: Literal

Max value: 8 characters

&BLKSIZE

The numeric value for the block size specified on the DD statement, dynamic allocation, or TSO ALLOCATE, ranging from 0 - 2147483647 (KB).

Type: Numeric

Max value: 2147483647

&DD

DDNAME in the DD statement of the data set.

Type: Literal

Max value: 8 characters

&DEF_DATACLAS

The data class name associated with the resource owner of the data set (set only if RACF is installed and ACSDEFAULTS is YES in IGDSMSxx).

Type: Literal

Max value: 8 characters

&DEF_MGMTCLAS

The management class name associated with the resource owner of the data set (set only if RACF is installed and ACSDEFAULTS is YES in IGDSMSxx).

Type: Literal

Max value: 8 characters

&DEF_STORCLAS

The storage class name associated with the resource owner of the data set (set only if RACF is installed and ACSDEFAULTS is YES in IGDSMSxx).

Type: Literal

Max value: 8 characters

&DSN

The name of the data set or collection for which ACS processing is taking place. For VSAM data sets, only the cluster name is passed to the ACS routine; the component names are not.

If the data set has an absolute or relative generation number, it is stripped from &DSN The generation number is the low-level qualifier of the data set name. For the data set naming rules, see z/OS MVS JCL Reference.

Type: Literal

Max value: 44 characters

&DSNTYPE

The data set name type, one of:

BASIC

The data set is neither extended format nor large format.

EXC

Extended format data set is preferred. The data set allocation is attempted in nonextended format if the necessary system resources for extended are not available.

EXR

Extended format data set is required. The data set allocation fails if unable to allocate in extended format.

HFS

Hierarchical file system data set

LARGE

Large format data set

LIBRARY

PDSE, partitioned data set extended

PDS

Partitioned data set

null

No value specified

Type: Literal

Max value: 7 characters

Note: Some values of the &DSNTYPE variable (BASIC, EXC, EXR, and LARGE) are set from values on the DD statement or dynamic allocation, as well as from the data class or the LIKE parameter.

&DSORG

The data set organization, one of:

PS

Physical sequential

PO

Partitioned

VS

VSAM organization

DA

BDAM organization

null

No value specified

Type: Literal

Max value: 2 characters

Restriction: When DIRECTORY blocks are specified on the SPACE parameter in the JCL, &DSORG is set to PO.

&DSOWNER

The name of the user or group that owns the data set (set only if RACF is installed).

Type: Literal

Max value: 8 characters

&DSTYPE

The data set type, one of:

GDS

One generation data set of a generation data group, or any data set allocated with a relative generation number (such as A.B.C(+1)) or an absolute generation number (such as A.B.C.G0000V00).

PERM

Standard permanent data sets

TEMP

Temporary data sets

null

None of the above.

Type: Literal

Max value: 8 characters

&EATTR

EATTR (extended attributes) value, one of:

OPT

Extended attributes are optional

NO

The data set cannot have extended attributes

blank

Not specified. This is the default.

Type: Literal

Max value: 4 characters

&EXPDT

The expiration date in the form of YYYYDDD where YYYY is a year from 1900 - 2155 and DDD is a day in a year from 1 - 366.

Exception: Expiration dates of 99365 and 99366 are considered "NEVER-SCRATCH" dates.

Type: Literal

Max value: 7 characters

&FILENUM

The value of the FILENUM ACS read-only variable. This variable corresponds to the data set sequence number on the JCL LABEL parameter. The default is 1. This field is optional.

Type: Numeric

Max value: 5 characters

&GROUP

The RACF-defined default group associated with the user, or the group specified in the GROUP keyword on the JCL JOB statement. If the environment is recall or recover, DFSMShsm sets &GROUP for both authorized and non-authorized users if it is available. Therefore, do not rely on a null value for &GROUP to determine if a user is a DFSMShsm Authorized User or not. When DFSMShsm invokes the ACS routines, &GROUP is the group associated with &USER.

Type: Literal

Max value: 8 characters

&HLQ

The high-level (first) qualifier of the data set or collection name.

Type: Literal

Max value: 8 characters

&JOB

The job name, the started task name, or the TSO/E userid from the JOB statement, depending on the execution mode (&XMODE). (See Determining Distributed FileManager/MVS data set creation requests for Distributed FileManager/MVS usage information.)

Type: Literal

Max value: 8 characters

&LABEL

The value of the LABEL ACS read-only variable. This variable corresponds to the label field of the JCL LABEL parameter. Allowable values are NL, AL, SL, NSL, SUL, AUL, BLP, LTM or blank. The default is IBM® Standard Label. This field is optional.

Type: Literal

Max value: 3 characters

&LIBNAME

The name for the LIBNAME ACS read-only variable, can contain a 1 to 8 character tape library name. This field is optional.

Type: Literal

Max value: 8 characters

&LLQ

The low-level (last) qualifier of the data set or collection name.

Type: Literal

Max value: 8 characters

&MAXSIZE

The maximum size (in KB or MB) of a new data set. For non-VSAM data sets, the value is &SIZE plus 15 extents. For VSAM data sets, the value is primary + (123 * secondary * volume count) if extent constraint removal is set to No. If extent constraint removal is set to Yes, the value is &SIZE plus 7257 extents. See Using read-only variables for more information about the values of &MAXSIZE and &SIZE for VSAM data sets. Also see Constraints when using read-only variables.

Type: Suffixed numeric

Max value: 2147483647 for KB, 2097151 for MB

&MEMHLQ

The high-level (first) qualifier of the object name.

Type: Literal

Max value: 8 characters

&MEMLLQ

The low-level (last) qualifier of the object name.

Type: Literal

Max value: 8 characters

&MEMN

The name of an object.

Type: Literal

Max value: 44 characters

&MEMNQUAL

The number of qualifiers in the object name.

Type: Numeric

Max value: 22

&MSPDEST

The destination, specified in data set name format, for a tape management system-driven tape allocation. This value is specified through the AMS pre-ACS installation exit. The data set name format lets you specify a sequence of destinations to be identified, where each qualifier is a specific destination. For example, a data set vaulted first at location OUTD and then sent to OLTS could have an MSPDEST of 'OUTD.OLTS'. The actual values depend on the support provided by your tape management system.

Type: Alphanumeric

Max value: 44 characters

&MSPARM

Additional information related to a tape management system-driven tape allocation. This is a variable length field that can be indexed. The value is specified through an external exit. For a description of the indexing function for virtual tape system parameters, see Virtual tape system parameter.

Type: Alphanumeric

Max value: 142 characters

&MSPOLICY

The name of a management policy associated with tape data for a tape management system-driven allocation. You can use the DFSMSrmm EDGUX100 installation exit to set MSPOLICY to a VRS management value name. You can also set the value of this variable using the SMS pre-ACS installation exit or allow your tape management system to set it using the pre-ACS installation exit.

Type: Alphanumeric

Max value: 8 characters

&MSPOOL

A tape pool name associated with the data set being allocated. In a system-managed tape environment with scratch pool support, you can use this variable to specify a default storage group, where the tape storage group is equivalent to the tape pool specified in the variable. If you use the DFSMSrmm EDGUX100 installation exit, you can set this variable to the pool name or prefix determined by the DFSMSrmm scratch pool processing. This variable can also be set through the pre-ACS installation exit.

Type: Alphanumeric

Max value: 8 characters

&NQUAL

The number of qualifiers in the data set or collection name.

Type: Numeric

Max value: 22

&NVOL

The maximum of the volume count, UNIT count, and number of explicit VOL=SER specifications.

Type: Numeric

Max value: 2147483647

&PGM

The name of the program the system is running. (See Determining Distributed FileManager/MVS data set creation requests for Distributed FileManager/MVS usage information.)

Type: Literal

Max value: 8 characters

&RECORG

The data set record organization, one of:

KS

VSAM key sequenced (KSDS)

ES

VSAM entry sequenced (ESDS)

RR

VSAM relative record (RRDS)

LS

VSAM linear

null

No value specified

Type: Literal

Max value: 2 characters

&RETPD

The retention period of NNNN days where NNNN is from 0 - 9999 (JCL maximum). The &RETPD value is calculated from the specified &EXPDT value. If 99365 or 99366, the two "NEVER EXPIRED" dates, is specified after 01 January 2000, the calculated value for &RETPD is set to 0. &EXPDT, however, contains the true value of 1999365 or 1999366.

Type: Numeric

Max value: 2147483647

&SECLABL

Specifies the default security label in the RACF profile of the user or data set if the SECLABEL class is active. Otherwise, the read- only variable will contain a null value.

Type: Literal. The first character must be alphabetic, $, #, or @.

Max value: 1 - 8 alphanumeric or national ($, #, @) characters.

&SECOND_QTY

Specifies a secondary allocation quantity from JCL or AMS control cards. It has meaning only when the &SPACE_TYPE variable is defined. In conjunction with &SPACE_TYPE, &SECOND_QTY allows the DATACLAS ACS routine to make the appropriate DATACLAS assignment. You must modify your existing ACS routines if you wish to use these two variables.

&SIZE

The primary amount of space (in KB or MB) requested for a new data set or the amount of space actually used in an existing data set on a DASD volume (see Constants). See Using read-only variables for more information about the values of &MAXSIZE and &SIZE for VSAM data sets.

Type: Suffixed numeric

Max value: 2147483647 for KB; 2097151 for MB

&SPACE_TYPE

Specifies the allocation unit from JCL or AMS control cards to be used in conjunction with the secondary space allocation amount. In conjunction with the &SECOND_QTY variable, &SPACE_TYPE allows the DATACLAS ACS routine to make the appropriate DATACLAS assignment. You must modify your existing ACS routines if you wish to use these two variables.

Valid values: TRK, CYL, K, M, U, BLK, and blank

&SYSNAME

Specifies the system name of the system on which the ACS routine is executing. This field is optional. See Using read-only variables for usage information.

Type: Literal

Max value: 8 characters

&SYSPLEX

Specifies the Parallel Sysplex® name of the system on which the ACS routine is executing. This field is optional. See Using read-only variables for usage information.

Type: Literal

Max value: 8 characters

&UNIT

IBM-supplied or installation defined generic name for a device type (for example, 3380, SYSDA). For additional possible settings for the &UNIT variable, see ACS routine environments.

Type: Literal

Max value: 8 characters

A slash (/) preceding a four digit number represents a unit address (for example, /3380).

When you allocate a tape data set with DISP=MOD and no unit information is specified in the JCL, this variable is blank and SMS might attempt to manage the tape data set as a DASD-resident data set.

&USER

The user ID of the person allocating the data set. When DFSMShsm invokes the ACS routines, &USER is either the requestor of the recall or recover, or the user ID of the DFSMShsm address space. If the environment is recall or recover, DFSMShsm sets &USER for both authorized and non-authorized users if it is available. Therefore, do not rely on a null value for &USER to determine if a user is a DFSMShsm authorized user or not. (Refer to Determining Distributed FileManager/MVS data set creation requests for Distributed FileManager/MVS usage information.)

Type: Literal

Max value: 8 characters

&XMODE

The execution mode in which the data set is being allocated, one of:

BATCH

Batch execution mode

TSO

TSO execution mode

TASK

A started address space

Type: Literal

Max value: 8 characters