Linnea Nichols

Systems Programming Branch Manager

Department of Information Technology
Fairfax County Government
12000 Govt Cntr Pkwy Ste 361

The ABCs Fairfax, VA 22035-0043

Voice: (703)324-2708

of FAX: (703)324-3958
Email: [email protected]

C ACS

A B
Linnea Nichols
Fairfax County Government
[email protected]
703/324-2708
 Presentation Objectives

Provide guidance in writing ACS routines in the following areas

Agenda - Design methodology
- Documentation standards
- Coding standards and techniques
• Presentation objectives - Structure for ACS routines
- Testing methodology
• Introduction - Maintenance considerations

– The DFSMS environment

– ACS routines and the allocation
process
– ACS language
• ACS invocation and ACS variables
• Designing ACS routines
• ACS coding standard and consideration
• Testing and maintaining ACS routines
• Summary

The syntax of ACS will not be discussed

Smsacs.prs 2
 The DFSMS Environment
Introduction DFSMS is IBM's strategic approach to improve the efficiency of storage
The DFSMS Environment management. The goals of DFSMS are to:

- Allow the system to manage as much storage as possible

- Centralize control of storage management functions
- Isolate users from details of space, availability, performance, and device
management
Hardware Software People - Use ACS routines to assign classes that reflect service requirements

ES/9000 DFSMS/MVS
Policies,
3990
Practices, DFSMS is an interaction between many products. DFSMS/MVS lies at the heart.
3390 hsm rmm
dfp dss Procedures It's function is to simplify the management and use of external storage media by
3590
RAMAC sort racf providing a device independent means of requesting data services at the data set
level. SMS achieves this by assigning through the ACS routines a series of classes
IBM IBM IBM and groups that reflect the service requirements of a data set. These definitions
Storage are stored in the SMS control data sets.
Storage DFSMS Management
Offerings Library

• Allow the system to manage as much storage as

possible
• Centralize control of storage management functions
• Isolate users from details of space, availability,
performance, and device management
• Use ACS routines to assign classes that reflect
service requirements

Smsacs.prs 3
 This foil describes where the ACS routines fit in the allocation process of a data
set.

ACS Routines When allocating a new data set, the ACS routines are invoked in the following

The Allocation Process order:

- Data class (DC) ACS routine

- Storage class (SC) ACS routine
Convert - Management class (MC) ACS routine
Recover
Recall - Storage group (SG) ACS routine

DATACLAS STORCLAS MGMTCLAS STORGRP

Alloc ACS ACS ACS ACS The code within each ACS routine determines which classes and group(s) are
Routine Routine Routine Routine chosen for the new data set. For example, the storage class ACS routine assigns
the storage class for the data set.
SC=xx
SC=‘ ‘
When the ACS routines have completed, RACF is called to check whether the
assigned storage class and management class may be used in the allocation of
the data set. If these requirements are met, RACF will permit the allocation.

The allocation process consists of:

1. Selecting volume(s) for allocation

1 Automatic Class Selection (ACS) 2. Allocating the data set on the volume
routines determine if a data set is to be 3. Cataloging the data set
managed and, if so, its services
The decision that determines whether a data set will be system-managed is made
2 A volume(s) is selected for allocation in the storage class ACS routine. If a data set is assigned a storage class, it will be
managed. Certain data sets cannot be system-managed. However, system-
3 The data set is allocated and cataloged managed and non-system-managed data sets can exist in the same installation.

Smsacs.prs 4
 The ACS language referenced is contained in the DFSMS/MVS Storage
Administration Reference Manual

ACS Language PROC Start of an ACS routine

FILTLIST Definition of filter criteria

DO Start of a statement group

SELECT Define a set of conditional execution statements

Available statements in
ACS language IF Conditional execution statements

SET Assign a value to a read/write variable

WRITE Send message to end user

• PROC • SET EXIT Immediate exit of ACS routine (nonzero return code abends
the allocation)
• FILTLIST • WRITE
END End of statement group
• DO • EXIT
Comments Just that, comments to make it easier to understand what the
• SELECT • END routine is doing

• IF • Comments

Smsacs.prs 5
 Each routine is invoked separately based on three criteria - the current ACS
environment, the program being executed, and the parameters being supplied. Not
all routines are invoked all the time. In fact, in some cases none of the routines are
invoked. It is important to be aware of this while coding ACS routines.
ACS Routine Invocation
The following two foils illustrate this point.

Each routine is invoked separately based on:

1 The current ACS environment (&ACSENVIR)

– ALLOC
– CONVERT
– RECALL
– RECOVER

2 The program being executed

– JCL DD DISP=NEW
– TSO/E RECEIVE
– DFSMShsm Recall
– DFSMSdss Copy

3 The parameters supplied

– BYPASSACS (DFSMSdss)
– FORCENONSMS (DFSMShsm)

Smsacs.prs 6
 ACS Routine When &ACSENVIR=ALLOC
This chart shows which ACS routine is invoked when the ACS variable &ACSENVIR
Invocation Examples equals "ALLOC". Notice that the type of processing determines which ACS routine is
invoked.

Initial Allocation
When &ACSENVIR is ‘ALLOC’ For new allocations, the data class and storage class ACS routines are always
invoked. If a storage class is assigned, the data set will be system-managed and
SC MC SG the management class and storage group ACS routine will be invoked. If a storage
Type of processing DC ACS class is NOT assigned, the data set will not be system-managed and the
ACS ACS ACS management class and storage group ACS routines will be bypassed.
Initial allocation Y Y C C Temporary data sets are considered new allocations. The difference between
temporary and permanent data set allocation is the management class ACS routine
IDCAMS IMPORT N Y C C will not be invoked for temporary data sets.
DFDSS COPY N Y C C
DFDSS COPY IDCAMS IMPORT
N N N C The IDCAMS IMPORT command moves or restores a VSAM cluster. The data class
BYPASSACS
ACS routine is bypassed for this command. The storage class and management
class ACS routines are invoked and provided with class names exported with the
original data set or class names provided in the IMPORT command.
• DC ACS routine only invoked for initial allocation
• MC and SG ACS routines are only invoked if a SC is DFDSS COPY
assigned The DFDSS COPY command has a &ACSENVIR equal to "ALLOC". The data class
• SG ACS routine will be invoked when STORCLAS ACS routine is bypassed for this command. The storage class and management
class ACS routines are invoked and provided with class names copied with the
keyword is used with the DFDSS COPY original data set or class names provided in the DFDSS COPY command.
BYPASSACS command
Y - routine is invoked DFDSS COPY BYPASSACS
N - routine is not invoked Using the DFDSS COPY command keyword BYPASSACS, the system will not
C - routine is invoked if SC is assigned invoke the ACS routines to determine the target data set class names. One can
specify the DFDSS COPY keywords STORCLAS and MGMTCLAS to assign the
class names. Note the combination of BYPASSACS and NULLSTORCLAS forces
the selected data set to not be system-managed.
Smsacs.prs 7
 ACSENVIR=RECALL/RECOVER/CONVERT
The three other standard ACS environments are RECALL, RECOVER, and CONVERT. Each
environment causes a different type of processing to occur.
ACS Routine DFDSS RESTORE

Invocation Examples The original class names (storage and management) are passed to the ACS routines as they
were when the data set was dumped. These classes can be accepted "as is" by the ACS
routines, or new ones can be assigned, depending on the ACS logic. (If the data set is being
restored from another site, you may want to re-drive the allocation through the ACS routines.)

&ACSENVIR=RECALL/RECOVER/CONVERT DFDSS RESTORE BYPASSACS

Using the DFDSS RESTORE command keyword BYPASSACS, the system will not invoke the
ACS routines to determine the target data set class names. One can specify the DFDSS
RESTORE keywords STORCLAS and MGMTCLAS to assign the class names. Note the
SC MC SG combination of BYPASSACS and NULLSTORCLAS forces the selected data set to non-SMS.
Type of processing DC ACS
ACS ACS ACS
DFDSS RESTORE N Y C C DFDSS CONVERTV
The DFDSS CONVERTV command will not invoke the storage ACS routine. It is important to
DFDSS RESTORE insure the volume being converted is defined to a storage group that can satisfy the storage and
N N N C
BYPASSACS management class requirements. For example, do not assign data sets a management class that
requires incremental backup when the data set is allocated on a volume in a storage group with
DFDSS CONVERTV N Y C N the attribute AUTO BACKUP=NO.
DFHSM
N Y C C
RECOVER/RECALL DFHSM RECALL/RECOVER
DFHSM The original class names (storage and management) are passed to the ACS routines as they
N N N N were when the data set was migrated or backed up. These classes can be accepted "as is" by the
FORCENONSMS
ACS routines, or new ones can be assigned, depending on the ACS logic.

DFHSM FORCENONSMS
Using the DFHSM parameter FORCENONSMS on the RECALL or RECOVER command forces
• DC ACS routine not invoked when &ACSENVIR is the system to bypass the ACS routines and put the data set on a non-SMS volume. Of course, a
non-SMS volume must be known to DFHSM to complete the request.
RECALL/RECOVER/CONVERT In addition, the following points are worth noting:
• SG ACS routine is not invoked for DFDSS
CONVERTV - DFHSM RECALL/RECOVER are DFHSM-authorized commands (not to be confused with
HRECALL/HRECOVER). The FORCENONSMS option in RECALL/RECOVER should be used
• ACS is bypassed when DFHSM keyword only as a fallback process to direct recalls or recovers to non-managed volumes.
FORCENONSMS is used
- You can assign (through ISMF or IDCAMS ALTER command) a different storage class and
management class to an existing data set. The ACS routines are not invoked in this case. This
function should be RACF-protected.

Smsacs.prs 8
 ACS Routine
Invocation Examples

All ACS routines are bypassed for ...

• DFSMShsm RECOVER with REPLACE

• DFSMShsm RECALL/RECOVER with

FORCENONSMS

• IDCAMS IMPORT INTOEMPTY

• ISMF/IDCAMS ALTER for SC and MC

• Data sets not supported by DFSMS

i.e. ISAM and unmovable

Smsacs.prs 9
 Constraints on Read-only variables

Constraints On ACS routines receive input variables coming from different sources such as JCL,
RACF, or the preceding routines. These variables are not always available for

Read-Only Variables each of the ACS routines. Their content depends on:

- The information specified externally

- The calling environment (ALLOC, RECALL, etc.)
- The usage of RACF
Not allowed in
Only available Not all read-only variables are allowed in every environment or in every routine.
storage group
in initial
ACS routine
allocation Only available at initial allocation
AND
Not allowed in storage group ACS routine

The following read-only variables are not passed to any ACS routine except for
• &ACCT_JOB • &ACCT_JOB initial allocation (&ACSENVIR=ALLOC). This is very logical because the following
information is not saved anywhere for future reference. For example, when
• &ACCT_STEP • &ACCT_STEP recalling a data set from DFHSM , the job name that initially allocated the data set
• &DD • &DD is not available.
- &ACCT_JOB the accounting information from the JOB card
• &GROUP
- &ACCT_STEP the accounting information from the EXEC card
• &JOB • &JOB - &DD DD (data definition) statement describing the data set
• &MVSGP - MSS only • &MVSGP - MSS only - &GROUP the name specified on the GROUP= JCL keyword

• &PGM • &PGM - &JOB the job name, the started task name, or the TSO/E userid from the JOB
card, depending on your execution mode (&XMODE)
• &USER • &USER - &MVSGP MSS only - the group name for mass storage (MSS) volumes
• &XMODE • &XMODE - &PGMthe name of the program the system is running
- &USER the userid of the person creating the data set
- &XMODE the execution mode in which the data set is being created, one of:
BATCH, TSO, or TASK.

Smsacs.prs 10
 Objectives

ACS routines should be designed to be:

Designing ACS Routines - simple and straightforward

- Easy to understand and maintain

Objectives - Durable

The next few foils explain how to achieve these objectives by observing certain
• Simple and straightforward design criteria and considerations, a recommended structure for ACS routines, as
well as documentation and standards.

Requirements
• Easy to understand and maintain
The ACS routines reflect and implement the installation storage management
policy. The first part of the design phase is to identify the data requirements in an
• Durable installation. This work can be split into two tasks:

- Understand the requirements of the DFSMS Implementation Plan

Requirements
- Classify the data

• Understand requirements of DFSMS These tasks will now be discussed in more detail.

Implementation Plan

• Classify the data

Smsacs.prs 11
 In order to design the ACS routines, it is first necessary to develop an
implementation plan that covers the implementation of DFSMS, moving from the
current environment by staged implementation to the final target environment. The
The DFSMS developer of the ACS routines should be cognizant of the:

Implementation Plan - User requirements

- Established service level agreements
- Target environment
Target Installation - Major objectives of the installation.
ISMF
Pool
However, this planning activity should not be taken to extremes. A realistic time
SG frame for the planning phase is an elapsed 2- 6 weeks. The exact time frame will
SG depend on the complexity of the installation.
Esoteric Pools
Evaluate Pool
Environment Several publications cover the implementation planning phase in great detail,
SG including MVS/DFP SML: Migration Planning Guide, DFSMS Implementation
Classes
SG Primer Series, DFSMS Quick Start, and Converting to DFSMS.
& Grps

Current Environment System-Managed

Be cognizant of:

User requirements
Established service level agreements
Target environment
Major objectives of the installation

Smsacs.prs 12
 A major task of the planning phase will be to identify the following requirements
which will form the basis of the policies used to drive DFSMS.

Data Classification - Data requirements

SLAs for Data Under DFSMS -

-
User requirements
Formal and informal service levels.

Once these high-level requirements have been identified, the data classification
Application/Business System methodology suggested in the following foils can be applied to:
Requirements Capabilities
- Translate the requirements into data classes, storage classes, and
management classes.
SLAs - Identify the decision points needed in the ACS routines.
Application
Standards

System Policies with DFSMS

ACS
DC SC MC SG
Routines

• Identify requirements (data/user)

• Use requirements to design classes
• Identify decision points needed in the
ACS routines

Smsacs.prs 13
 Data Classification Methodology

Data Classification The suggested technique is to build a tree diagram where the root is managed
data, and each major branch (pool) is a collection of data that will be migrated to

Methodology DFSMS management in each separate phase of the master implementation plan.

Next, each pool is split by different data types into further branches until there are
no more downward splits to be made. These are the leaves of the tree, and each
leaf is a distinct type of data that may require a discrete set of assigned classes.
R
Managed O
Data O
T The decision needs to be made as to whether a leaf requires discrete classes
B assigned on the basis of user requirements, service level agreements, and any
R technical requirements.
A
System Devl. Prod. TSO Batch Temp N
C
H When the requirements for each leaf have been identified, all cases that require
E more than the standard classes will be decision points (WHEN ... or IF ...) in the
B S
R ACS routines. The criteria for the decision points need to be determined by
A
N
identifying the unique characteristic(s) of each exception case.
System Shared User C
H
E This foil shows six pools of data that are to be migrated to DFSMS management
S
separately in staged implementation.
L Note: This picture is only an example and may not reflect all the pools in your
E
Profiles JCL Source Data A installation. This sample can be used as a starting point to build the data
V classification tree for a specific installation.
E
S

• Root - DFSMS Managed Data

• Branches - collection of data (a pool) to be migrated
to DFSMS
• Leaves - distinct type of data that requires discrete
services

Smsacs.prs 14
 This example shows how the TSO POOL may be split into different data types until
there are no more splits to be made, thus identifying the leaves of the tree.
Profiles, JCL, programs and data are the USER data sets identified as leaves.
Data Classification
Methodology The TSO System and Shared data may each be considered leaves if further splits
do not show any exceptions in terms of class assignment.

User requirements, service level agreements, and technical requirements are

identified for each leaf, and classes are assigned on the basis of those
requirements.
TSO BRANCH

B Although both JCL and Source have been identified as having the same
requirements, this need not necessarily have been the case. For example, Source
R
could have been split further if different users had different requirements.
A
System Shared N
User C
H
DC=null DC=null
SC=FAST SC=FAST E
MC=NOMIG MC=STANDARD S

L
E
Profiles JCL Source Data A
V
DC=null FIXED80 FIXED80 null E
SC=STANDARD STANDARD STANDARD STANDARD S
MC=NOMIG EXTRABAK EXTRABAK STANDARD

Assign classes to each leaf

Smsacs.prs 15
 This foil shows how a segment of a management class ACS routine may be coded
for this environment using each branch to identify different data types and, where
necessary, decision criteria for the exception cases.
Data Classification
Methodology The decision criteria used in these cases have been either &HLQ or &DSN. More
than 30 read- only variables can be tested for decisions.

TSO BRANCH

SELECT

&HLQ=ISR &HLQ=SERVICE OTHERWISE B

&HLQ=ISP R
A
N
System Shared User C
DC=null DC=null H
SC=FAST SC=FAST E
MC=NOMIG MC=STANDARD S

SELECT
FILTLIST
*.LOG.MISC **.CNTL **.COBOL
OTHERWISE
*.PDF.PROFILE **.JCL **.ASM
L
E
Profiles JCL Source Data A
V
DC=null FIXED80 FIXED80 null
E
SC=STANDARD STANDARD STANDARD STANDARD
S
MC=NOMIG EXTRABAK EXTRABAK STANDARD

Decide decision criteria for class assignment

Smsacs.prs 16
 Each ACS routine consists of a main line SELECT, which branches to the relevant
subroutines that contain (optionally) installation standards enforcement and logic
that executes each class assignment method. The subroutines invoked vary for
Structure for ACS each ACS routine.

Routines Data Class Routine

There are only three possible conditions to branch to in the main line SELECT of
the data class routine. Note the allocation of objects will not invoke this routine.
START The three conditions are:
1. non- DASD or non- tape allocation (i.e. VTAM)
Main Line SELECT
2. DASD data set allocation
WHEN not data allocation
SET class EXIT 3. Tape data set allocation

WHEN DASD data set Storage Class Routine

SET class EXIT
The storage class routine has four possible conditions in the main line SELECT.
WHEN tape data set 1. non- DASD or non- tape allocation (i.e. VTAM)
SET class EXIT 2. DASD data set allocation
WHEN object 3. Tape data set allocation
SET class EXIT 4. Object allocation

End Main Line SELECT

Management Class Routine
END If the data set has been assigned a storage class then the management class
routine is invoked. There are three possible conditions in the main line SELECT.
Tape is considered a separate condition at this point because the tape data set
• Each ACS routine consists of a Main Line SELECT may need a special management class to manage the redirected tape data set on
DASD.
• Each branch goes to a subroutine 1. DASD data set allocation
2. Tape data set allocation
Installation standards enforcements (optional) 3. Object allocation
and/or
Class assignment Storage Group Routine
At this point, there are only two conditions possible. The allocation is a data set
directed to DASD (or VIO) or an object allocation. :ol compact
Smsacs.prs 17
1. DASD data set allocation
2. Object allocation
 This is the subroutine logic for class assignments that can be used for the tape,
data, or object conditions (branches) in the main line SELECT. The pyramid shows
how many data sets are affected by each method of class assignment.
Structure for ACS
Routines Shown here are four methods of class assignments.

1. External specification

This is where a user would request a specific class (i.e. management class) on
External there data set allocation statement.
Specification
Few
2. ACS routine logic

ACS routine M
Sets E Code would be written to identify groups of data sets that required specific classes.
logic
with same criteria T
H 3. RACF defaults
RACF All O
defaults associated with an D
You have the option to use RACF defaults. The ACS routine can assign RACF
HLQ, USER, or Group defaults to a data set if the data set has a default.

Otherwise 4. The data that did not fall in the previous three categories.
All other Data Sets
This would be considered the masses, the data sets that don't have any special
requirements. These data sets would be assigned standard classes.

Amount of Data Sets

Note that the entire pyramid need not be used by an installation or within an
individual type of ACS routine. The ACS routines should only use the layers of
pyramid that are necessary to associate data set exceptions to their classes.

Structure for class assignment

Smsacs.prs 18
 This is an example of a DASD data set subroutine for the storage class ACS
routine. This is how the logic in the pyramid would be translated to ACS routine
logic. Each level of the pyramid would be represented in ACS code by a SELECT
Structure for ACS case statement. The OTHERWISE of the case statement would determine the
class for the bottom layer of the pyramid, or the "masses".
Routines
WHEN DASD data set
DO
Installation Standards
SELECT
WHEN condition
code ....
?
END
External specification S
SELECT E
WHEN &STORCLAS not NULL T
code .... E
?
C X
END
ACS Code Logic L I
SELECT A T
WHEN multivolume
WHEN temporary S
WHEN critical S
WHEN ...
RACF Defaults
WHEN RACF default class
OTHERWISE
END
END

• Sample structure for storage class subroutine

• Assign a SC to DASD data set

Smsacs.prs 19
 Comments set apart from the executable code

Documenting ACS Routines ACS routines should be well documented. This will make it easier for future
modifications. Also, if the modifications are performed by someone other than the
author, documentation contributes to the ease of understanding and maintenance
Comments set apart from executable code of the ACS routines.

PROC 0 STORCLAS
For ACS routines, the best place for documentation is within the routines
/*===============================================================*/
/* C H A N G E H I S T O R Y */ themselves. Comments set apart from the executable code should begin by
/* ============================ */ stating the nature and purpose of the routine.
/* DATE RESP DESCRIPTION OF CHANGE */
/* ------ ------ ----------------------- */
/* 98/05/04 LTN CLEAN UP DEAD CODE */ Following that should be a log of all changes to the routine. This log of changes
/* 96/09/23 DMR ALLOW SYSTEM PROGRAMMERS TOTAL FREEDOM */ should identify the date of the change, initials of persons responsible, and the
/* 96/09/16 DMR DELETED PRF FROM EXCLUDE LIST */ nature of the changes. The log entries should be made in descending date order
/*===============================================================*/
/* FILTLIST SPECIFICATIONS FOLLOW */
(latest change is at the start of the log), so that it is immediately evident who made
/*---------------------------------------------------------------*/ the last change and why. Usually, the latest change is responsible for the most
FILTLIST &DASD INCLUDE('3390', /* Valid DASD devices for SMS */ recent problem!
'3380', /* allocation. */
SYS*,
'')
/*---------------------------------------------------------------*/
/* IGNORE ALLOCATIONS FOR NON-DASD DEVICES */
/*---------------------------------------------------------------*/
IF &UNIT NE &DASD
THEN DO
SET &STORCLAS EQ ''
EXIT
END
/*---------------------------------------------------------------*/

• State the nature and purpose of the routine

• Log the changes to the routine
– Names of persons altering the routine
– Nature of the changes
– Descending date order - the latest change is probably
responsible for the most recent problem!

Smsacs.prs 20
 Comments within the code - two types

Documenting ACS Routines There should be two types of comments in the code of the ACS routines.

Comments within the code - two types 1. Describe the purpose of a section of code

These comments are set off from the code, as separate complete comment lines.
/*--------------------------------------------------------------------*/
/* CHECK AND AUTHORIZE EXTERNAL SPECIFICATION OF STORCLAS. */ They refer to the overall function of the block of code that follows.
/* IF AUTHORIZED, ALLOW SPECIFICATION TO REMAIN AND EXIT. */
/*--------------------------------------------------------------------*/
IF &STORCLAS NE '' THEN 2. Describe the specific purpose of the programming statements
DO /* Start main DO-group 1. */
SELECT /* Start SELECT-group 1. */
These comments form part of the detail of the code, and as such, are tied to it. If a
WHEN ( &JOB EQ &SYSPROG ) /* Permit system programmers */ statement is altered in any way, any comment related to it will likely be changed.
EXIT /* to bypass the system. */ These comments may either be:
WHEN ( &DSN EQ &DB2TEST ) /* DB2 test uses specific SC */ - Set apart from the code and distinguished from the general comments by
SET &STORCLAS EQ 'SCODB2D' /* */ entering them in lower cases.
WHEN ( &ACSENVIR EQ 'RECOVER' OR /* If recall/recover, then set */
&ACSENVIR EQ 'RECALL' ) /* &STORCLAS to the current */ - or alternatively,
SET &STORCLAS EQ &STORCLAS /* value. */

OTHERWISE /* In all other cases, routine */ - Entered to the right of the relevant statements in the code. In this case,
SET &STORCLAS EQ 'NORMAL' /* will continue and assign */
vertical alignment of the start and end columns of the comments provides a
END /* End SELECT-group 1. */ neat layout, which adds clarity to the routine.
END /* End main DO-group 1. */
END /* End of STORCLAS ACS Routine.*/
- As a rough guideline, there should be about the same number of comment
statements as program statements.

• Describe the purpose of a section of code

• Describe the specific purpose of the programming
statements

Smsacs.prs 21
 Changes to ACS routines can affect an entire installation and therefore cannot be taken lightly.
Designing durable routines should be a primary objective for the storage administrator. Some
considerations having to do with code durability are included below.

Use durable variables

Design Considerations Some ACS variables are transitional. Therefore, the values of these variables will change from
one environment or operation to another. Examples of such variables are:
&ACCT_JOB &ACCT_STEP &DD &DSORG
&GROUP &JOB &PGM &USER

Strive for Code Durability Furthermore, some of these variables can contain null values, or values that are not associated
with the data set that is currently being processed. For example, the &PGM variable is null in a
RECALL or RECOVER environment, and the &USER variable is set to the userid that is causing
the RECALL or RECOVER, not to the userid associated with the original allocation of the data set.
• Use durable variables
The durability of the ACS routine code will be greatly enhanced by using these variables rather
– The ACS environment than transitional variables wherever possible. Variables in this category are:
- The ACS environment variable (&ACSENVIR)
– Data set name related variables - Data set name related variables (&DSN, &HLQ, &LLQ, &NQUAL ....)
- The RACF default variables.
– RACF default variables
Minimize maintenance

• Minimize maintenance It is possible that the same FILTLIST may need to be coded for more than one ACS routine.
(Typically this may occur during the migration phase when FILTLISTs are built to include or
exclude data sets from DFSMS management.) This requirement can multiply the maintenance
– FILTLISTs common to more than effort by up to four times each time a change is made to the FILTLISTs. It also adds to the
volatility of the ACS routines. One technique for avoiding this duplicated effort is to code a
one ACS routine separate member (FILTLIST) in the ACS source library of duplicated FILTLISTs. This member
can be updated and then imbedded into each ACS routine as required.

Design Flexible ACS routines

• Design flexible ACS routines
As the stages of the master implementation plan are executed, the ACS routines will change.
– DFSMS implementation Future exploitation of DFSMS may also need the ACS routines to change. For example, the
installation may wish to add new device types, new applications, OAM support and so forth. The
– ACS routine evolution structure for ACS routines described in the design section builds ACS code that should be flexible
enough to allow the addition of new decision points without redesigning the logic for the entire
routine. This can be achieved by adding or deleting:
- Subroutines specified within WHEN...DO...END statements to or from the main line
SELECT
- WHEN decision points from within the subroutines.
Smsacs.prs 22
 The SMS Starter Set

A starter set for the DFSMS constructs and ACS routines is supplied in
SYS1.SAMPLIB.
Design Considerations Enforcing Installation Standards

It is possible within the ACS routines to enforce installation data set standards that
might previously have been controlled by user exits in the operating system.

In General Either the data class or the storage class ACS routine can be used for enforcing
installation standards.

In general, the storage class ACS routine can be used to enforce standards when:
• SMS starter set
- The data class ACS routine is not executed, such as during in- place volume
• Enforcing installation standards conversion and for data set recall or recovery.

• RACF - The standard to be enforced is influenced by DATACLAS selection.

– Resource class facilities - The standard to be enforced relies on allocation values that are not set until the
data class ACS routine has been exited.
STORCLAS/MGMTCLAS ACS
defaults The data class ACS routine can be used for all other installation standards
enforcement to encompass the following:
• DFSMShsm RECALL/RECOVER
- VOL=REF backward DD references that bypass the storage class ACS routine.
• PDSE
- Fail an allocation as early as possible, thus avoiding the execution of the storage
• Artificial classes class ACS routine.

- Installation standards for tape allocations may involve assigning a DATACLAS to

categorize data as active, backup, large, or portable.

- Data sets that are redirected from DASD to tape may need a DATACLAS assigned
to provide SPACE allocation.

- Typically the storage class ACS routine is the most complex ACS routine. It can be
simplified if installation standards are enforced by the data class ACS routine.
Smsacs.prs 23
 The value of each ACS default is found in the data set owner profile (either USER or
RACF Considerations GROUP). If the data set has a USER profile and an ACS default is blank, then the
USER's default GROUP profile is used for that ACS default. If no value is found through
RACF Resource Class Facilities STORCLAS and MGMTCLAS this process or ACSDEFAULTS=NO, then all the variables are set to null.

The STORCLAS and MGMTCLAS RACF general resource class facilities can be The use of RACF ACS defaults can reduce the complexity of the ACS routines because
used to prevent unauthorized use of privileged storage and management classes. they can address:
This removes the need to do complicated authorization checking in the ACS
routines. The use of the RACF resource class facilities has the following - All data sets for specific HLQs
advantages:
- All data sets for any number of USERs
- All data sets for any number of GROUPs
- Addition and removal of storage classes and management classes should not
affect the logic of the ACS routines.
Considerations for DFSMShsm RECALL and RECOVER
- Changes to the resource access list (adding and deleting users authorized to use DFSMShsm keeps track of the original storage and management class when migrating
specific storage and management classes) will not require extra coding within the or backing up a data set. During the recall or recover, these values are passed to the
ACS routines. ACS routines. There are several ways to handle DFSMShsm recall and recover.

RACF ACS Defaults - Always redrive to get a new class

- Redrive only if the class is null
There are four RACF ACS defaults: - Redrive only if the class is null or class is invalid
- Redrive to reflect changes in service level
- DATAAPPL - Always redrive if &ACSENVIR is RECOVER
- DATACLAS
- STORCLAS PDSE Considerations
- MGMTCLAS. The ACS routines can be used to ensure that a storage class is always assigned to a
PDSE data set.

These ACS defaults are specified through RACF on the DATAAPPL, DATACLAS,
STORCLAS, and MGMTCLAS portions of the DFP segment associated with the Artificial Classes
owner of the data set if defined in RACF. The data set owner is either specified in An artificial class is a class that has no attributes coded and is used purely as a switch
the data set profile in the RESOWNER field or the HLQ of the data set if no for ACS logic. These classes will never be assigned to any managed data sets. An
RESOWNER is specified. When the ACS routines are entered, the following example is shown in the next section of foils.
variables are set to the associated RACF ACS default if specified:
Bypassing the normal ACS routine process may be necessary in emergency situations.
- APPLIC Therefore, the ACS routines must allow specific users to assign any class or select any
storage group for the data sets. Sufficient RACF authority to both data set and SMS
- DEF_DATACLAS class profiles must be provided for these users. Consideration needs to be given to the
- DEF_STORCLAS need for emergency bypass when there is a disaster recovery situation.
- DEF_MGMTCLAS.
 USE FILTLIST TO SIMPLIFY CODING

Use FILTLIST FILTLISTs are a practical, easy- to- update way to simplify code for the testing of
multiple OR conditions, using INCLUDE lists. Their power lies in their ability to

To Simplify Coding combine literals and data set masks in its INCLUDE and EXCLUDE lists. By
grouping FILTLISTs at the beginning of ACS routines, the number of executable
code can be reduced, and its readability enhanced.

Instead of complex AND and OR testing FILTLISTs can also be used to build NOT conditions, through the use of
EXCLUDE lists.
SELECT
WHEN ((&LLQ EQ 'CNTL')
Instead of complex AND and OR testing
OR (&LLQ EQ LINK* AND &LLQ NE 'LINKLST")
OR (&LLQ EQ SRC*)) In this example the low level qualifier of a data set is being tested. The technique is
DO a complex series of AND/OR testing in a case statement. The code is not straight
forward, and the results of the test are not obvious. This type of coding is not
. recommended. Instead, use FILTLIST to simplify coding.
.
Use FILTLIST INCLUDE and EXCLUDE Use FILTLIST INCLUDE and EXCLUDE

By using the INCLUDE and EXCLUDE parameters of the FILTLIST statement ACS
FILTLIST &PDSF routine logic can be greatly simplified. One can see the code is simple and easy to
INCLUDE ('CNTL',LINK*,SRC*) understand.

EXCLUDE ('LINKLST')
.
.
SELECT
WHEN (&LLQ EQ &PDSF)
DO
.
.
Smsacs.prs 25
 USE FILTLIST TO MINIMIZE CHANGES

Use FILTLIST To add new application

To Minimize Changes FILTLIST statements can be used to minimize changes. For example, set up a
FILTLIST to identify applications under SMS control. The FILTLIST can be used in
subsequent code of the ACS routine. When a new application is converted to
SMS, one can simply update the FILTLIST statement thus leaving the code
To add new application untouched.

Alter FILTLIST to include SALES

FILTLIST &SMS_APPLIC INCLUDE(ACCOUNT.**,TEST.**,...)
.
Let's assume all the data sets of the application "SALES" use "SALES" as the first
. level qualifier. If you want to manage all the new data sets of this application, you
SELECT can accomplish this by changing the filter without altering the rest of the ACS
routine.
WHEN (&DSN EQ &SMS_APPLIC)
DO
.
.
Alter FILTLIST to include SALES

FILTLIST &SMS_APPLIC
INCLUDE(ACCOUNT.**,TEST.**,SALES.**,...)
.
.
SELECT
WHEN (&DSN EQ &SMS_APPLIC)
DO
.
. Smsacs.prs 26
 USE PARENTHESES TO GROUP OR CONDITIONS

Use Parentheses to AND conditions tested before OR

Group OR Conditions Without parentheses, the AND conditions will be tested first, and results may differ
from what is expected.

Is equivalent to
AND conditions tested before OR
By using parentheses, it is obvious which condition will be tested first - the
condition in parentheses. Use parentheses to clarify the logic in your ACS
routines.
WHEN &LLQ=&PDSF OR &DSORG='PO' AND &USER='MYONE'
And different from

By just one change in the parentheses, the entire logic will change.
Is equivalent to

WHEN &LLQ=&PDSF OR
(&DSORG='PO' AND &USER='MYONE')

And different from

SELECT
WHEN (&LLQ=&PDSF OR &DSORG='PO') AND
&USER='MYONE'

Smsacs.prs 27
 PLACE TESTS IN THE PROPER SEQUENCE

Place Tests in the Proper In general, there should be no overlapping between the character strings and
masks used in tests. If it should be necessary, test for the specific cases before

Sequence testing for the general ones. Remember, once a true WHEN has been
encountered, the rest of the SELECT is not processed.

Don’t test the more general condition first!

Don’t test the more general condition first

When setting up multiple tests, it is important to test the more general condition
first. In this example the data set name is being compared to a mask. The first
SELECT compare will catch all the data sets having the low level qualifier beginning with
WHEN (&DSN EQ P*.*.CN*) DO ... EXIT END CN*. Consequently the second test will never be met because the first test will
capture all 'CNTL' data sets.
WHEN (&DSN EQ P*.*.CNTL) DO ... EXIT END
. Instead test the most explicit conditions first
.
END /*SELECT*/ Test the most explicit conditions first. When comparing using masks, test the most
qualified names first. In this example, a data set name is being compared to a
mask. However, in this case the first test compares the data set name against
First test will capture all ‘CNTL’ P*.*.CNTL which will catch data set names ending in CNTL. The second test will
Second test will never be met catch data sets that end in CN* but not CNTL.

Instead test the most explicit conditions first

SELECT
WHEN (&DSN EQ P*.*.CNTL) DO ... EXIT END
WHEN (&DSN EQ P*.*.CN*) DO ... EXIT END
.
.
END /*SELECT*/
Smsacs.prs 28
 CHECK VALID CLASSES

Check Valid Classes During During DFSMShsm Recall/recover

DFSMShsm Recall/Recover DFSMShsm keeps track of the original storage and management class when
migrating or backing up a data set. During the recall or recover, these values are
passed to the ACS routines.

PROC &MGMTCLAS
Our recommendation is that, where practical, do not accept the storage class and
management class presented to ACS. Rather, re- drive the allocation through the
FILTLIST &VALID_MGMTCLAS INCLUDE ACS routine and redetermine the class. However, depending on how ACS routines
are written and the variables used to assign classes, this may not always be
('STANDARD','EXTRABAK',..) possible. For example, if you are use RACF group or userid to assign classes in
FILTLIST &DF_ENVIR INCLUDE ('RECALL','RECOVER') the first place, then you will almost certainly want the original class assigned during
DFSMShsm recall/recover. (The ACS variables &GROUP and &USER are not
. available during DFSMShsm recall/recover.) However, if you are restoring data
. sets from another site, you should always redetermine the classes.
.
If you decide to accept the class presented to the ACS routine, then you should
SELECT check the names to see if they are still valid. Here are two situations that could
WHEN (&ACSENVIR EQ &DF_ENVIR) cause problems:
SELECT
WHEN (&MGMTCLAS EQ &VALID_MGMTCLAS) - The class has been removed from the SMS configuration. Any attempt to use
an undefined class will cause allocation failure.
DO - The attributes for the class have been altered since the creation of the data
SET &MGMTCLAS EQ &MGMTCLAS set but the class name remains the same. The data set will be given a wrong
service level.
/*Accept as is*/
END /*when*/ If you decide to check classes, then the list of valid classes must be maintained in
OTHERWISE your ACS routines. The addition and removal of classes should occur infrequently
for an SMS installation that is in production.
SET &MGMTCLAS EQ '' /*redrive through*/
END /*select*/
.
.
Smsacs.prs 29
 DATA THAT MUST BE SYSTEM- MANAGED

Data That Must Be PDSE

System-Managed The ACS routines can be used to ensure that a storage class is always assigned to
the PDSE data sets.

PDSE

PROC &DATACLAS
.
.
SELECT
.
WHEN &DSNTYPE EQ 'LIBRARY'
DO
SET &STORCLAS='BASE'
/*ENSURE SYSTEM MANAGED*/
EXIT
END
.
.

Smsacs.prs 30
 USING ARTIFICIAL CLASSES

Programming technique to use class names as switches

Using Artificial Classes Switches can be defined in the SMS configuration to be used in the ACS routines.
To implement this technique, define a class that will be used as switch. This class
is in essence an artificial class. The definition is a dummy definition and will have
no practical use in the management of the data set being allocated.
• Programming technique to use class
names as "switches" These classes will not be assigned to any data sets

These classes will not be assigned to any data sets. They will be used as
indicators to the ACS routines.
• These classes will not be assigned to
any data sets Example - SMS Starter Set

The SMS Starter Set uses the "artificial" storage class "NONSMS" to enable
• Example - in SMS Starter Set authorized users to allocate a non- SMS data set. Another example is to define a
data class with the name "YES". This data class will be tested in the data class
– "NONSMS" storage class ACS routine A data class will be determined by the routine only when
DATACLAS=YES is specified externally.
– Allow authorized users to allocate
non-SMS data sets
– Specified externally -
//DDX DD DSN=SYSPGM.MUST.BE.NONSMS,STORCLAS=NONSMS, ...

– STORCLAS ACS routine

WHEN (&STORCLAS = 'NONSMS') SET &STORCLAS=' '

Smsacs.prs 31
 The first stage is to test the new SCDS prior to activation:

- Define test cases for each decision point by using the ISMF test facility. These
Testing ACS Routines test cases should be based on the data classification exercise detailed in previous
foils. A test case must be defined for each leaf that has been identified as requiring
special class assignment. Test cases must also be defined for all further decision
points in the code logic. These decision points are WHEN or IF conditional
statements and will be identified when designing the structure of the ACS routines.

Stage 1
It is possible to define a set of test cases by using ISMF to save specific data set
Execute test cases for each leaf lists that contain the criteria necessary for a specific test. Then the saved lists can
be processed by REXX or CLIST to create the test cases.

- Execute the test cases by using the ISMF test facility.

Stage 2 - Save the results for regression testing in the next implementation phase.
Execute bulk test cases for real
data sets The second stage is to generate bulk testing for real data sets:

- Generate bulk test cases to use for regression testing in the initial
implementation phase by using ISMF to save data set lists or the storage class
Stage 3 ACS exit if SMS is active. Then process the saved lists or SMF data to create test
libraries for the ISMF test facility. (REXX or CLIST can be used to create the code
Execute tests against an active to process the saved lists into test case libraries.)
configuration
- Execute the test cases by using the ISMF test facility to process each test
library.

The third stage is to activate the new configuration and test using the
preproduction methods described in the next section.

Smsacs.prs 32
 Testing with the ISMF Test Facility

The following should be taken into consideration when using the ISMF test facility:

Testing Methods - Successful test results produced by the ISMF test facility should not be relied
upon as a complete and representative test of the ACS routines. Coding ISMF test
cases is a manual task (unless created by CLISTs or REXX) and therefore error
prone.

• ISMF test facility - Using the data classification output and a diagram of the structure of the ACS
routines, a person other than the ACS routine code developer should be able to
code test cases that may exercise the code logic more thoroughly.

• DFSMSdss CONVERTV - Code descriptions should be provided for each test case to identify the nature
of the test for future tests and regression testing.
– TEST keyword
– REDETERMINE Testing with DFSMSdss CONVERTV TEST

Consider the following when using DFSMSdss CONVERTV TEST to test the ACS
routine:
• ACS Write statement
- The output generated from a CONVERTV TEST is in a format that is
complicated to read. It is possible to postprocess the output using REXX or CLIST
to present the results in a simplified manner.
• SC ACS Exit
- The TEST keyword does not test all aspects of an actual CONVERTV
conversion. It is possible to achieve a zero return code with the TEST keyword and
then fail the actual conversion when the TEST keyword is removed. One example
is when a data set is allocated. CONVERTV with TEST will complete with a zero
return code. When TEST is removed, the data set that is allocated will cause an
error. Another example is RACF checking. No checking is carried out with
CONVERTV and TEST. When the TEST keyword is removed, any unauthorized
use of a class will fail the CONVERTV.

- Multivolume data sets must be converted simultaneously. Each volume that

contains part of a multivolume data set must be included in a single CONVERTV
step with the keyword ALLMULTI used. This includes VSAM clusters that are split
across volumes.
Smsacs.prs 33
TEST Keyword

When the TEST keyword is specified with DFSMSdss CONVERTV, the conversion is
simulated for storage class and management class ACS routines; no actual physical
conversion takes place. The data class and storage group ACS routines will not be
entered. If the data that is to be migrated to DFSMS management is contained on one
or more volumes, the TEST keyword can be a valuable tool to produce bulk test output
and for regression testing.

REDETERMINE Keyword

This keyword can be added to a DFSMSdss CONVERT with TEST to redetermine the
classes for all existing managed data on one or more volumes. The output from this
operation can be compared to existing class assignments, and exception, can be
noted. This method also adds to regression testing.

The WRITE Statement

The WRITE statement can be used to provide "trace" facilities from within the ACS
routines to aid preproduction testing.

The Storage Class ACS Exit

The storage class ACS exit (IGDACSSC) can be used to enhance the testing of ACS
routines. This exit captures the ACS variables used in allocation and writes them to
SMF. The SMF records can be processed to:

- Produce test cases from the actual allocations, or

- Be used as a debugging aid for unexpected allocation results.

A sample exit and postprocessor are currently available in SYS1.SAMPLIB.

This sample exit allows the variables to be recorded to SMF or the JOBLOG. This can
be triggered by adding the field DEBUG to the step accounting information of the job.
The account field is not available in some ACS environments, such as RECALL.
Therefore, no ACS variables will be written in these circumstances.
 You must allocate either a sequential data set, a member of a partitioned data set
(PDS), or a member of a partitioned data set extended (PDSE) for each of the
ACS routines that you intend to write. As a general guideline, use an LRECL of
Maintaining ACS 80. After allocating the data sets you can EDIT them from ISPF or alternatively,
select option 7, Automatic Class Selection Application, from the ISMF Primary
Routines Option Menu.

After creating an ACS routine, you must translate it into executable form. The
translation process checks your source code for syntactic and semantic errors,
Source code: generates an object form if no errors exist, and places the object form into the
PS SCDS you specified on the translate panel. If the ACS routine that you are
translating already exists in the SCDS, the new object form replaces the existing
or PDS object form. To translate an ACS routine, select option 2, TRANSLATE, from the
ISMG Automatic Class Selection Application Selection panel.
or PDSE
with LRECL=80 SMS validates the entire SCDS when it is saved. You can validate the individual
ACS routines of an SMS configuration after successfully translating them. You
should also validate the entire configuration yourself so that you can see any error
Translate to Object code: messages that result. To validate an ACS routine, select option 3, VALIDATE on
the Automatic Class Selection Application Selection panel.
SCDS
It is necessary to ACTIVATE the configuration for any changes made to the SCDS
to take effect. Select option 8, Control Data Set, from the ISMF Primary Option
Validate Menu.

To display information about the currently active configuration, issue the following
Activate ACDS command:
D SMS,ACTIVE or D SMS
where D is an abbreviation for DISPLAY. (The default for the DISPLAY command
is to display the active configuration when no options are specified.). The display
D SMS on console to display shows the names of the current control data sets.

Smsacs.prs 35
 A rigorous approach to change management is imperative in maintaining ACS routines.
Consider the following:

Maintaining ACS - A change control and problem management system should be set up for the
constructs and ACS routines during the initial implementation phase.
Routines
- Use RACF to restrict the use of SMS- related ISMF applications to authorized
personnel.

• Set up a change control and problem - Include detail and meaningful comments in the ACS routines
management system
- Keep a minimum of four different SCDS data sets:

- The production SCDS

• Use RACF to restrict DFSMS-related - The minus- 1 version of the production SCDS
ISMF applications - The SCDS under development
- The minimum SMS configuration.
This may prove invaluable if it is necessary to fall back.
• Include detail and meaningful
- Keep a minimum of three different ACS source code data sets:
comments in the ACS routines
- The production ACS source code
- The minus- 1 version of the production ACS source code
• Keep several generations of - The ACS source code under development.

– SCDSs Each source code data set should only contain source for one
– ACS routines - data class routine
- storage class routine
– Test cases and results - management class routine
- storage group routine.

• Keep at least one backup copy of the - Keep results of the translation and validation of all configurations

latest ACDS - There must be at least one ACDS data set in case of corruption of the ACTIVE
Smsacs.prs 36 ACDS.
 Use the SMF Type 42 subtype 3 records "New Configuration Change Audit" to log
all changes made to the active configuration. This record is written when issuing:

Maintaining ACS - The 'VARY SMS' storage group or volume command

Routines - The ACTIVATE command

- The VARY command for a managed volume.

• Use the SMF Type 42 subtype 3 record
This record contains, among other information, the SCDS and ACDS name.

– Log changes made to the active When the SMS subsystem is active, any change to the active configuration can
configuration affect all users who create data sets. Therefore, the timing and nature of changes
must be considered.

– Record written when issuing:

• The VARY SMS storage group or
volume command
• The ACTIVATE command
• The VARY command for a
system-managed volume

– Record contains the SCDS and

ACDS name

Smsacs.prs 37
 More Documentation

• MVS/ESA Storage Management Library:

– Storage Management Subsystem Migration Planning
Guide SC26-4659
– Implementing SMS SC26-3213
• DFSMS/MVS DFSMSdfp Storage Administration Reference
SC26-4920
• DFSMS/MVS OAM PISA for Object Support SC26-4918
• DFSMS/MVS DFSMSdss Storage Administration Guide
SC26-4930

Old Redbooks, Still Very Useful:

• DFSMS Implementation Primer Series: Writing ACS
Routines GG24-3403
• DFSMS Implementation Primer Series: Designing Classes
and Storage Groups GG24-3301
• DFSMS Implementation Primer Series: DFSMS Quick Start
GG24-3302
• DFSMS Implementation Primer Series: DFSMS and RACF
Usage Considerations GG24-3378
• Converting to DFSMS GG24-3357

Sample code:
• http://www.interlog.com/~hal/mvss

Smsacs.prs 38
 Summary

• Design ACS routines with a master plan

• Design with future changes in mind

• Keep design simple

• Use change control

• Document procedures

Smsacs.prs 39