ACS routine input variables

Automatic class selection routines are used to implement your installation’s storage management policy. These routines must be written using the ACS programming language, a high-level language that uses relational statements to determine class and storage group assignments.

Related reading: The z/OS DFSMSdfp Storage Administration contains detailed information about the ACS programming language and the use of ISMF to define and to validate ACS routines.

The ACS routines use three values for the &ACSENVIR variable that are specific to objects. See Table 1 and Table 2 for a diagram of these variables. Using these values, you can distinguish object selection from data set selection. These values are as follows:

&ACSENVIR='STORE'

The storage class, management class, and perhaps the storage group routines are invoked because of an application’s request to store an object. Variable &DSN contains the collection name.

If variable &MEMN (object name) is null, the ACS routines are invoked to specify a storage class, management class, storage group for the collection named in &DSN. Therefore, you must supply ACS routines that select a storage class, management class, and Object storage group for the collection. The storage class and management class supplied by the ACS routines become the default classes for the collection. The storage group selected indicates in which Object storage group the collection is to be a member. All objects in the collection are stored in the storage group that you select.

If variable &MEMN is not null, this ACS invocation validates the storage class and management class specified by the application for the object named in variable &MEMN. ACS routines ensure that the stated class is acceptable for use with this object, and if not, should substitute an acceptable one. This does not affect the class specifications for the collection.

When neither storage class nor the management class is specified on a request to store an object into an existing collection, the object is assigned the default classes associated with that collection.

Attention: When an object is assigned the default classes associated with the collection, the ACS routines are not invoked, and it is possible to store an object with a name that does not conform to the requirements in the ACS CHANGE or CTRANS environments. Subsequent attempts to process that object will fail.

&ACSENVIR='CHANGE'

ACS is invoked to validate an application’s request to change the storage class or management class for the object named in variable &MEMN that is part of the collection named in variable &DSN. ACS routines should ensure that the stated class is acceptable for use. The appropriate ACS routine is invoked based on the combination of storage class (SC) and management class (MC) specifications included on the application request:

If only MC is specified, the management class ACS routine is invoked, using the requested MC and the existing SC.
If only SC is specified, both the storage class and management class ACS routines are invoked, using the requested SC and the existing MC.
If MC and SC are specified, management class and storage class ACS routines are invoked, using the requested MC and SC.

&ACSENVIR='CTRANS'

During a storage management cycle, ACS is invoked because a class transition event has occurred for the object named in variable &MEMN that is part of the collection named in variable &DSN. Variables &MGMTCLAS, and &STORCLAS have the names of the classes to which the object is assigned. ACS routines should select the new classes. These new classes can change the placement of the object in the hierarchy and can change the management of the object (including creation of a new transition event).

Table 1. Constructs verified or changed through ACS Routines Invoked by the &ACSENVIR variables—All OAM environments
ACS routines invoked (&ACSENVIR)	STORE	CHANGE	CTRANS	*ALLOC
DATA CLASS	NO	NO	NO	YES
STORAGE CLASS	**YES	***YES	YES	YES
MANAGEMENT CLASS	**YES	***YES	YES	NO
STORAGE GROUP	**YES	NO	NO	YES
Notes: ACS environment of ALLOC is invoked by MVS during allocation. When storing the first object into a new collection* through the STORE request, the ACS routines for storage class, management class, and perhaps the storage group are entered. **The ACS routines for management class and storage class are entered for objects* only when an explicit management class, storage class, or both are specified on a CHANGE request. (See the *CHANGE Environment Only* graphic for more information.)

Table 2. Constructs verified or changed through acs routines invoked by the &ACSENVIR variables—Change environment only
ACS routines invoked (OSREQ specifies)	Storage class only	Management class only	Storage class and management class
Storage class changed	YES	NO	YES
Management class changed	NO	YES	YES

In addition to &ACSENVIR, ACS routines might also use the following:

Read-Write Variables
- &MGMTCLAS
- &STORGRP
- &STORCLAS
- &SYSNAME
- &SYSPLEX
Read-Only Variables
- &DSN
- &HLQ
- &LLQ
- &MEMHLQ
- &MEMLLQ
- &MEMN
- &MEMNQUAL
- &NQUAL
- &RETPD
- &SIZE

Tip: &SIZE is valid only for STORE requests. &SIZE contains the object size converted to kilobytes (KB) and rounded up to the next highest 1 KB if the object size is not at a KB boundary (KB=1␠024 bytes).

Related reading: For detailed information about ACS variables, see the z/OS DFSMSdfp Storage Administration.