DFSMS, z/OS System Managed Storage - ACS Routines

ACS routines

ACS routines are used to assign the 4 SMS classes to datasets, tapes or objects. These routines can interrogate a number of read-only variables such as &DSN (datasetname) and &JOB (job name) then use that info to decide what values to assign to the 4 read-write variables &DATACLAS &MGMTCLAS &STORCLAS &STORGRP.

The four ACS routines are processed in the order DATACLAS - STORCLAS - MGMTCLAS - STORGRP. If a data allocation is redriven from DFHSM or DFDSS then it can go straight to the STORCLAS routine. If an allocation is not to be SMS managed then it will exit at the STORCLAS routine with the &STORCLAS variable set to NULL. Once the STORGRP is assigned, SMS goes on to select the allocation volume.


Accelerate DB2 Write with zHyperWrite and "EADM™ by Improving DB2 Logs Volumes Response Time:

You will store your base ACS routines in a PDS, and its name will be unique to your site. The ACS routines are split into two sections, the first section combines lists of files and objects together, the second section contains the code which processes those lists. The ACS routines are processed every time a dataset is allocated, so SMS can be a big CPU user. However, SMS uses cross-memory services, so the CPU is not allocated to the SMS address space, but is passed over to the address space of the requesting user. This means that its difficult to determine just how much CPU SMS is using. CPU is expensive, so

  • If possible, keep the ACS routines simple
  • Put popular hits at the front of the code
  • If you have SMS compatible dataset names, you can keep your filtlists simple by using dataset name patterns. If you are replacing an older system, or introducing a new one, use the opportunity to influence the naming standards to make them SMS friendly. It is not a good idea to go to the expense of renaming all your files just to fix SMS.
  • Select ... When ... Otherwise statements are easier to write and understand, than nested If .. then .. else .. statements. Remember to code EXIT statements at the end of every WHEN clause, or everything will default to the otherwise clause.



To make changes to your ACS routines follow the process below.

  1. Take ISMF option 7 - UPDATE then option 1. EDIT to edit your routines. You will need to supply the name of your ACS library here. Strictly speaking, you do not need to use ISMF for this option, you could edit the library directly from TSO. You site will almost certainly have a process for this that involves taking a backup of the routines first.
  2. Once you have edited your routine, take option 2, TRANSLATE. This will produce a dataset that lists out what happened during the translation and hopefully tells you that it was successful. If not, go back to EDIT, fix the errors then try another translation. When you come out of the TRANSLATE panel ISMF will ask you what you want to do with the listing file. Unless your site process requires that you keep the listing for audit purposes, I'd suggest that you always delete the listing file. The reason why is that it could be some weeks before you make another change, your file will probably get migrated to tape, then you have to wait for the recall next time you want to make a change.
  3. Take option 3 VALIDATE. This checks that the ACS routines are consistent with the whole SMS Setup. Again, I'd suggest you delete the listing file when you are finished
  4. Test your routines. Many sites have a pre-defined set of test scripts that you can run through to make sure that your change will not affect existing rules and allocations. IBM has also introduced a NaviQuest tool for testing. This builds test cases based on real data extracted from ISMF, DCOLLECT and SMF. It can be run in batch and can do before and after compares so you can see exactly what will changed. It even produces reports.
  5. When you are happy with your testing, go back to the main ISMF menu and take option 8. Control Data Set, then option 5, ACTIVATE. This promotes your new ACS routine from the SCDS to the ACDS and refreshes anything in storage on every LPAR.

As DFSMS is now old and well established software, the biggest challenge is probably that ACS routines have mutated over the years and have become difficult to understand and change. This is especially true if your company has gone through a few mergers and several different SMS systems have been welded together. Two fundamental issue are, how do you debug SMS routines when something has gone wrong, and how can you safely change them when necessary.
One suggestion from IBM is to analyse each routine and produce a spreadsheet 'map' which shows ACS class names going down the sheet, and ACS variable names across the sheet, so you can see at a glance which variable values cause a given class name to be used. If you go to the trouble of setting up such a map, the issue then is that everyone who makes changes to the routines must update the map, or it becomes invalid.

A simple tip for debugging issues is to work backwards from the problem. If your dataset is getting the wrong management class, scan the mgmtclas routine and find the SET statements which allocate that class, there may be more than one. Once you find the SET statement, work out which variables and filtlists trigger that SET statement, then check exactly what parameters are used when allocating the file. Hopefully you will then understand why you are getting that management class. Now you need to work out what combinations of ACS variables and filtlists would be required to pick up the correct management class. You can probably see now how that spreadsheet map would make your life easier.

If you need to update an existing complex routine, always work from a copy. Try to understand how the original author's logic style worked and if possible use the same logic style yourself. Different styles within the same routine can be very confusing. A logic map can be very useful. Use comments to explain what you have done, you won't remember yourself in 3 months time. Once you have made the change, test, and test again before making the change live.
DO NOT put a simple catch all statement at the start of the routine that guarantees that your new allocation will work, not even just to test something. I once saw an experienced person do this and then direct all new allocations to tape. All tape drives were in use within seconds and the master console was flooded with 'no drives available' messages. All new dataset allocations hung and the systems ground to a halt. It took 2 minutes to backout the change, but freeing up the console took a lot longer.

Some the ACS tips

When you are comparing sizes, you can use KB and MB suffixes, for example 500 MB, but note that in the ACS language one KB = 1,024 bytes and one MB = 1,048,576 bytes. This conflicts with the way these suffixes are used for DASD storage, where K and M normally mean 1000 and 1000000. If you are comparing sizes against the &SIZE and &MAXSIZE read-only variables, then you have to use KB or MB.

If you are using literal constants like 'SYS1.PARMLIB' then you need to enclose them in single quotation marks. If your literal includes a single quotation mark, then double it up, of example 'O'HARA' would be specified as 'O''HARA'.

You can use pattern masks in character strings to identify groups of objects by using the special characters '*' and '%', where an asterisk '*' represents zero or more characters and a percent '%' represents a single character. Masks are not enclosed in single quotation marks.

You would usually compare the requested allocation against read-only variables which contain data set and system information as they exist at the time of the allocation request. Some of the read-only variables you can use are:

  • &ACSENVIR is the allocation environment. Options are:
    • ALLOC
    • RENAME
    • RECALL

  • &DSN is the name of the data set being allocated. For VSAM data sets this would be the cluster name, not the component names. If the dataset is a GDG, then the absolute or relative generation number is stripped from &DSN and the generation number is the low-level qualifier of the data set name.

    Masks are used extensively when comparing dataset names, and data set masks are a bit more complicated as up to 5 qualifiers can be specified, separated by periods. Each qualifier has a maximum length of eight characters, so the maximum length for the entire data set mask is 44 characters. 'dsn.*' means that at least one qualifier follows the dsn high level qualifier. 'dsn.a*z' means that in the second qualifier, zero or more characters can be present between the 'a' and the 'z'. 'dsn.*.outfile' means there is one extra qualifier between 'dsn' and 'outfile'. 'dsn.**.outfile' means that zero or more qualifiers can be present between 'dsn' and 'outfile'.

  • Three other useful dataset related variables are:

  • &HLQ - The high-level (first) qualifier of the data set.
  • &LLQ - The low-level (last) qualifier of the data set.
  • &NQUAL - The number of qualifiers in the data set.

Some parameters that describe the dataset are:

  • &DSNTYPE - The data set name type, which can be one of:
    • BASIC - A normal data set
    • EXC - Extended format data set is preferred, but the data set can be allocated in nonextended format if necessary
    • EXR - Extended format data set is required and the data set allocation will fail if this is not possible
    • HFS - Hierarchical file system data set
    • LARGE - A Large format data set is a sequential file that can have more than 65535 tracks of data per volume
    • LIBRARY - PDSE, partitioned data set extended
    • PDS - Partitioned data set
    • null - No value specified

  • &DSORG - The data set organization, which can be one of:
    • PS - Physical sequential
    • PO - Partitioned. If DIRECTORY blocks are specified on the SPACE parameter in the JCL then the &DSORG is set to PO.
    • VS - VSAM organization
    • DA - BDAM organization
    • null - No value specified

  • &DSTYPE - The data set type, which can be one of:
    • GDS - A GDG dataset member of a generation data group
    • PERM - Standard permanent data sets
    • TEMP - Temporary data sets
    • null - None of the above.

  • &BLKSIZE - is the value for the block size specified on the DD statement, dynamic allocation, or TSO ALLOCATE.

  • &EATTR - The Extended Attribute value, which can be:
    • OPT - Extended attributes are optional
    • NO - The data set cannot have extended attributes
    • blank - Not specified. This is the default.

  • &RECORG - The VSAM data set record organization, one of:
    • KS - KSDS
    • ES - ESDS
    • RR - RRDS
    • LS - Linear
    • null - No value specified

Some volume and space allocation parameters are:

  • &NVOL - The biggest one of the volume count, the UNIT count, or explicit VOL=SER statements.
  • &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
  • &MAXSIZE - The maximum size (in KB or MB) of a new data set.
  • &SPACE_TYPE and &SECOND_QTY are used together to determine the the secondary space allocation amount. &SPACE_TYPE can be one of TRK, CYL, K, M, U, BLK, and blank
  • &ALLVOL and &ANYVOL both refer to the list of volumes specified when a dataset is allocated. &ANYVOL is true if any volume in the list matches, &ALLVOL is only true if all the volumes on the list matches. If the environment is recall or recover, then these parameters are 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. Neither if these parameters are available to the storage group ACS routine when the environment is recall or recover and when VOLCOUNT(ANY) is specified.

Some general allocation parameters are

  • &JOB - Could be the job name, or maybe the started task name or the TSO/E userid, depending on how the file is being allocated.
  • &UNIT - A generic name for a device type like 3390 or SYSDA, or a specific unit like /324A. Note that a preceding slash to show this is a unit address.
  • &SYSPLEX - Specifies the Parallel Sysplex name of the system on which the ACS routine is executing.
  • &USER - The user ID of the person allocating the data set.

back to top