IAM/RLS Automatic Data Set Eligibility

IAM/RLS Data Set Selection

IAM can automatically decide during OPEN processing which IAM data sets are to be handled by IAM/RLS. Automatic selection is based on the share options that a data set was defined with, if an RLSID was specified when a data set is defined or loaded, and/or by the data set name table. An installation specifies the criteria IAM is to use through the IAM Global Options Table, via the RLS option. Using the RLS option, users can specify the minimum share option required for eligibility for IAM/RLS processing, and whether or not a data set name table has been provided to IAM/RLS. If a combination of share option and data set name eligibility is requested, the user can specify via the RLS option whether a data set must meet both the share option criteria and be in the data set name table, or if a match on either one sets the data set as eligible for IAM/RLS.

RLS Global Option

Multiple values can be specified for the RLS Global Option Parameter. This parameter indicates how IAM/RLS and IAM/PLEX will be selecting the IAM data sets to place under their control.

RLS Option Value	Description
AND	Indicate that to be automatically eligible for IAM/RLS, a data set must have the specified share option AND must be selected in the data set name table.
NONE	Indicates that no data sets are to be considered for automatic eligibility for IAM/RLS. Set this option if you are not going to be activating the IAM/RLS address space, or if you want to manually direct activity to IAM/RLS through the IAM Overrides. This is the default option as shipped.
OPTIONAL	Allows data sets to be opened without IAM/RLS when the IAM/RLS address space is not active. This is useful for when the TABLE option has been specified and IAM/RLS may not be active on all LPAR’s because IAM/RLS has to at least have been active at some point in time for the data set include and exclude tables to be loaded. If specified, this value will also be applied to data sets defined with an RLSID, in that if IAM/RLS is not active, the data set will be opened locally.
OR	Indicates that to be automatically eligible for IAM/RLS, a data set must have either the specified share option OR be in the data set name select list. If a data set meets the share option eligibility, then the data set name table will not be examined. If a data set does not meet the share option eligibility criteria, then it must selected in the data set name table to be selected for IAM/RLS processing. OR is the default if both TABLE and a SHAREx value are specified.
REQUIRED	Indicates that IAM/RLS must be active if a data set is eligible for IAM/RLS processing, or when the TABLE Global Option is specified. IF IAM/RLS is not active, then any attempt to open a potentially IAM/RLS eligible data set will be failed. REQUIRED is the default. For data sets defined with an RLSID, IAM/RLS must be active even if RLS=NONE is set, unless RLS=(NONE,OPTIONAL) is specified.
SHARE1	Indicates that data sets with any cross-region share option value (1, 2, 3, or 4) will be eligible for IAM/RLS processing. Use of this value is not recommended.
SHARE2	Indicates that data sets with cross-region share options of 2, 3, or 4 will be eligible for IAM/RLS processing. Use of this value is not recommended.
SHARE3	Indicates that data sets with cross-region share options of 3 or 4 will be eligible for IAM/RLS processing.
SHARE4	Indicates that only data sets with a cross-region share option of 4 will be eligible for IAM/RLS processing.
TABLE	Indicates that IAM is to search the data set name table to determine eligibility for IAM/RLS processing, subject to other criteria. Be careful of using the options TABLE with REQUIRED. With both of those options, no IAM data sets can be opened until an table has been loaded into virtual storage. If IAM/RLS is not started up immediately during the IPL process, consider starting the IAM/RLS with PARM=DSNTLOAD which will start VIF and load the DSN TABLE then exit. The default is that the data set name tables will not take part in eligibility selection for IAM/RLS.

Using the RLS Global Option

The following discussion applies to the use of the RLS Global Option. Full use of the IAM Global Option Change Facility is described in IAM-Global-Option-Change-Facility of the IAMUsers space. Multiple values can be specified for the RLS option, by enclosing them within parenthesis. When the RLS option is specified on the ZAP control statement, the values specified will act as a complete replacement for the existing RLS option. As shipped, the default value is RLS=NONE, meaning that no IAM files are automatically eligible for IAM/RLS processing.

To use only the data set name table for automatic data set selection specify the RLS Global Option of either RLS=(TABLE,OPTIONAL) or RLS=(TABLE,REQUIRED). Use of the REQUIRED option will make sure that files selected for RLS will not open if RLS is not available. Also note with REQUIRED, that no IAM files can be opened unless an IAM/RLS address space has been started since the last IPL and initialized the data set selection table in ECSA. Once the table is initialized, the IAM/RLS and IAM/PLEX address spaces can be started and shutdown as desired, the table will still remain in storage.

You might desire some combination of selection criteria; for example, you want all share option 3 or 4 files to be eligible, and some selected share option 2 files. For this, you would specify RLS=(SHARE3,OR,TABLE). You would then specify the names of the other files to be included or excluded in the data set name tables. The reason for both an include and an exclude list is so that you could select all data sets beginning with PROD.SHARE for IAM/RLS processing. You would specify in the data set name table SELECT DSN=PROD.SHARE** (ending with a double *). However, perhaps there is a file with that name prefix that you want excluded from IAM/RLS, so you could specify EXCLUDE DSN=PROD.SHARE.FILE1.

Another possibility is that you might want only share option 3 or 4 files to be eligible for IAM/RLS, however, you might want to exclude some selected files. In this situation, you would specify RLS=(SHARE3,AND,TABLE). Then in the data set name table, you would specify SELECT DSN=* which will include all data sets, and then exclude specific data sets, such as EXCLUDE DSN=PROD.DONOT.SHARE.FILE1.

Please remember to refresh LLA after any changes to the IAM Global Options, which is necessary if IAM is in the link list for the changes to take effect.

RLS DSN Table

The data set name table is provided to the IAM/RLS address space through the IAMDSNTB DD statement. This DD must specify a card image data set, either sequential or a PDS member. The table is read during initialization of the first IAM/RLS or IAM/PLEX address space started on an LPAR, and stored in ECSA. The table is kept in common to minimize the overhead of searching the table during IAM OPEN processing. Customers can update the data set name tables within the IAMDSNTB data set, and activate the updated tables by using the CHANGEDSNT command of the IAM/RLS address space. If you have IAM/RLS running on multiple LPARs, you will have to issue the command on one IAM/RLS address space on each LPAR.

Within the IAMDSNTB data set, two lists of data set names can be provided. Each data set name entry is considered a full data set name unless it contains 1 or more of the special masking characters. The masking characters allow a single entry in the table to represent multiple data set names, resulting in a smaller table. Refer to the topic below on data set name masking for complete information. The old use of a trailing single asterisk (*) will still work the same as it did previously.

The first list is the data set name selection list. It is specified by “SELECT RLISD=rlsx,DSN=(” followed by a list of data set names, separated by commas. All of the data sets included on that select statement are assigned to the specified RLSID. Multiple cards can be used, however, each data set name or mask must be fully contained within a single card image. A closing parenthesis is used at the end of the last data set name. If there is just one data set name, or only the * (single asterisk) then no parenthesis is needed.

The exclude list is specified by the “EXCLUDE DSN=(” followed by a list of data set names, separated by commas. Multiple cards can be used, however, each data set name or mask must be fully contained within a single card image. A closing parenthesis is used at the end of the last data set name. If there is just one data set name, or only an **, then no parenthesis is needed. The EXCLUDE statement must start on a new card.

The EXCLUDE list is always searched first, so if the data set name matches any mask in the exclude list, it is automatically not eligible for IAM/RLS processing even if it is in the INCLUDE list. As much as possible, it is recommended that the EXCLUDE list be kept short but very broad so that as many data sets as possible will be recognized as not requiring IAM/RLS or IAM/PLEX processing.

For Alternate Indexes, the PATH data set name should be used in the DSN table. It is not necessary to include AIX data set names. If the PATH data set name is covered by a mask (see below), then you do not need to include the PATH DSN.

You can group data set names by RLSID. If no RLSID is specified on the SELECT statement then it will be blank in the table and during open processing the RLSID provided by the CREATE or ACCESS overrides or the default in the Global Options Table will be used. There can be multiple SELECT DSN= and EXCLUDE DSN= statements in the IAMDSNTB DD input file. Each statement will be processed with the data set names added to the corresponding Select or Exclude table in storage. If an error is encountered on the first SELECT or EXCLUDE statement, and there was already a Select or Exclude table in storage, then the old table will still be in effect. If an error is encountered on a subsequent SELECT or EXCLUDE statement in the processing of the IAMDSNTB DD input file, then the storage Select and Exclude table will contain only those data set names that were successfully processed on the previous input cards before the error was encountered. A maximum of 399 input cards can be specified for each SELECT or EXCLUDE statement with multiple data set names on each card. A total maximum of 32,767 names can be specified for each list. However, it is highly recommended that you keep the lists as short as possible, to keep the ECSA storage requirement low, and to minimize the searching CPU time.

Data Set Name Masking

To provide more flexibility and help reduce the size of the table, IAM provides a masking facility that can be used when specifying data set names on the SELECT and EXCLUDE statements. The mask may contain:

Any valid alpha-numeric or national character representing itself
/ (slash) symbol represents a single valid character
| (vertical bar) represents a single alphabetic character
+ (plus) represents a single valid numeric character
? (question mark) represents a single valid national character (that is, #, $, or @ in the US)
* (single asterisk) represents zero or more valid characters within one index level except when it is the last character in the mask, in which case, it is treated as a meaning any subsequent characters.
** (double asterisk) represents zero or more valid characters contained in one or more index levels (including their periods)
. (period) represents a period (index level) in the data set name except as noted in special cases below. A period at the beginning of the mask, or immediately following another period is interpreted as an *. (single asterisk, period).
**. (double asterisk, period) at the beginning of a string represents one or more index levels at the beginning of the data set name
.* (period, single asterisk) at the end of the string represents one or more index levels at the end of the data set name
.**. (period, double asterisk, period) in the middle of the string represents either a SINGLE period or one or more index levels at that point in the data set name
The last character specified cannot be a period.
*** (triple asterisks) are invalid.
An **.** is invalid, If you want to represent at least a specific number of index levels use *.*.

Masking Examples

Below is a sampling of some of the data set name variations that can be built with the masking capability.

ABC.GLEDGER.MASTER This example is for a complete data set name
XYZ.PROD.GROUP*.MSTR.MUPD This example allows multiple for data sets with additional characters as part of the GROUP index level. For example, this would pick up GROUP0, GROUP1A, GROUP001, GROUPABC, and so on.
XYZ.PROD.GROUP++.MSTR.MUPD In this variation the GROUP must be followed by 2 numeric digits, such as GROUP25, or GROUP99, and so on.
PROD.IAM.PAYROLL.* Includes all data sets that begin with
PROD.IAM.PAYROLL.* Includes all data sets that begin with PROD.IAM.PAYROLL.
XYZ.*.SHARED Allows data sets that start with XYZ, have any second level index, and ending with ‘.SHARED,’ for example: XYZ.F1.SHARED or XYZ.ABC12345.SHARED
PROD//.ARMASTER.* Includes data sets that begin with PROD followed by any two valid characters such as PRODNY.ARMASTER.abc and followed by any characters at the end. Other possible matches include: PRODNJ.ARMASTER.d060510.master, or PROD99.ARMASTER.xyz
TEST* Any data sets that begin with the characters TEST

RLS DSN Table Example

Shown below is an example of an RLS Data Set Name table:

Example of IAM/RLS Data Set Name Table (EX2020A)

SELECT RLSID=RLS1,DSN=(PROD.PAYROLL.IAM.*,
                    PROD.AR///.IAM.*,
                    IAMV.**.RLS,
                    PROD.APAY.*.SHARED)
SELECT RLSID=RLS2,DSN=(PROD2.PAYROLL.IAM.*,
                    PROD2.AR*.IAM.*,
                    IAMV2.*.RLS)
EXCLUDE DSN=(PROD.PAYROLL.IAM.TESTFILE,
               PROD.AR.IAM.HISTORY,
               TEST.*,
               IAMV.RLS999.DONOT.SHARE.*)

Automatic RLS Data Set Selection

During OPEN processing of any loaded enhanced format IAM data set, first the data set is checked to see if the RLSIDIAM CREATE Override was specified when the data set was defined or loaded, and if so then IAM will look for the specified IAM/RLS address space. If the data set was not defined with an RLSID, next check is, if an ACCESS override with RLSID= and which RLS was specified. If both are true, then the specified RLSID will be used for the data set. Next, the RLS Global Option is checked. If RLS=NONE is in effect, then normal open processing continues. If the RLS Global Option so indicates, the share options are checked. Then based on the RLS Global Options, if the criteria include the data set name tables, the data set name tables are searched for a match. When IAM refers to the data set name tables during open processing, first the exclude list is searched. If a matching name or mask is found in the exclude table, the IAM data set is treated as being ineligible for IAM/RLS processing. If no match was found in the exclude table, then the selection table is searched. If the data set name or prefix is found in the select table, then the data set is eligible for IAM/RLS processing.

For the preliminary testing phase of IAM/RLS, the installation will most likely set a very limited scope. It may be useful to set the RLS option to a value of NONE, and use the IAM/RLS override or the IAM CREATE RLSID override to initiate processing or provide a very limited set of eligible data sets.

Subsequent to testing, a wider scope is recommended. Data sets that have shared update access by multiple jobs should be handled by the IAM/RLS address space. Such data sets will normally be defined with share options of (3,3), (3,4), (4,3) or (4,4). These data sets will be automatically routed to the IAM/RLS address space when RLS=SHARE3, if it is active.

In some cases, it may also be beneficial for Share Option 2 data sets to be processed by IAM/RLS. This would be particularly true if an application requires full read integrity, while other jobs or CICS regions are updating the data set. If there are only a few share option 2 data sets meeting those criteria, then using the data set name tables would be recommended. However, if almost all of the share option 2 data sets need full read integrity, then it would most likely be better to set the RLS global option to SHARE2.

IAM/RLS does incur additional resources, primarily CPU time, to process an I/O request than without IAM/RLS. It takes additional resources to ship an I/O request over to another address space for processing, and then return data and status back to the originating address space. For this reason, it is recommended that you only put the IAM files that really need sharing support under IAM/RLS, and let standard IAM process the data sets that do not have update sharing active.