Use the split/merge/extend utility to copy an existing RACF data set to a larger data set, even if you are not splitting or merging the data set(s).
By using the split/merge/extend utility for an extend operation, you can:
• Compress the index to reduce the number of index blocks
• Place profile records in collating sequence near the appropriate index blocks
Chapter 6. RACF Utilities
6-35
Executing the Split/Merge/Extend Utility
The following job control statements are necessary for executing ICHUT400:
Statement JOB EXEC
SYSPRINTDD
INDDnDD OUTDDnDD
Use
Initiates the job.
Specifies the program name (PGM = ICHUT400) or, if the job control statements are in a procedure library, the procedure name. You can also request ICHUT400 processing options by specifying parameters in the PARM field. See "Parameter Specification."
Defines a sequential message data set. The data set can be written to an output device, a tape volume, or a direct access volume.
Defines the RACF input data set(s). See "Input Data Set Specification."
Defines the RACF output data set(s). This statement is not required if you are executing the utility only to identify inconsistencies in a RACF data set(s). See "Output Data Set Specification."
If you are redistributing the profiles across more than one RACF data set, you must also provide a range table. The range table indicates which profiles are placed in each output data set. See "Range Table" in Chapter 5 and "Output Data Set Selection" later in this chapter. If any of the input data sets are RACF-protected, you must have at least UPDATE authority for those data sets.
Input Data Set Specification
Allowable ddnames for input data sets are INDDI through INDD255. The input data sets must be numbered consecutively. For example, if 25 input data sets are provided, they must be assigned ddnames INDDI through INDD25. The utility processes the input data sets until a number is omitted. You must provide at least one input data set (INDDl).
The only considerations in ordering the input data sets (that is, which data set you assign to INDDl, which to INDD2, and so on) are the following:
• The utility copies the ICB and templates from the input data set defined by INDDI to all output data sets.
• If you do not allow duplicate names in the DATASET class or if duplicate entries exist within any other class, the utility copies the entry from the input data set identified by the lowest-numbered ddname.
You can specify active RACF data sets as input data sets. However, to prevent updates to the data sets during the processing of the utility, you should specify the LOCKINPUT option. (See "Parameter Specifications"). Each input data set must be a correctly formatted RACF data set.
Note: The ICHUT400 utility does not copy empty RACF data sets; the index must contain valid profile data set entries for the utility to copy the data set.
Output Data Set Specification
Output Data Set Selection
Output Data Set Processing
When redistributing or copying a RACF data set, you must code an OUTDDn statement for every RACF data set that the utility will create. The ddnames of the statements defining the output data sets have a relationship to the range table.
If a range table is provided, ICHUT400 uses the greatest data set number in the table as an upper boundary for processing. If no range table is provided, the upper boundary is one. ICHUT400 does not process any output data set
identified by a ddname with a number greater than the upper boundary. You can specify as many as 255 output data sets on statements named OUTDDl through OUTDD255.
Output data sets can be new or old direct access data sets. As with all RACF data sets, RACF uses only the first extent. Therefore, do not create any data sets with a secondary space allocation.
If you are executing ICHUT400 only to identify inconsistencies in the RACF data set(s), do not code an OUTDDn statement. See "Processing of Conflicts and Inconsistencies" for a description of inconsistencies found in the data set(s).
If multiple output data sets are created, the utility uses the range table to
determine which profiles to copy to which output data sets. Therefore, you must supply a range table that indicates the range of profiles to be placed on each data set. You specify the name of the module that contains the range table in the TABLE parameter of the P ARM field in the EXEC statement. (See "Parameter Specification.") Chapter 5 describes the format of the range table. If you are using a new range table, you should check that the data set name table is consistent with the new range table. See Chapter 5 for a description of the data set name table.
ICHUT400 initializes each provided output data set as a completely independent RACF data set, with an ICB, templates, BAM blocks to describe free space, and an index structure to describe the data set's contents.
ICHUT400 processing is similar to the processing of the ICHMINOO utility. As does ICHMINOO, ICHUT400 uses only the first extent of the data set. For old data sets, the user must ensure that only one extent is currently allocated because the utility cannot detect multiple extents for existing data sets.
The two utilities are different, however, because ICHMINOO builds the templates using control records read from the SYSTEMP file; ICHUT400 merely copies templates read from INDDi. Also, ICHMINOO builds an ICB with default option settings; ICHUT400 copies the option settings from the ICB of INDDi.
ICHUT400 builds the index of each output data set sequentially from the bottom up. You can request that free space be left in each index block by specifying the FREESPACE parameter. (See "Parameter Specification" later in this chapter).
Specifying FREESP ACE allows new entries to be added to a data set while RACF is active, without causing an index block split.
Chapter 6. RACF Utilities 6-37
Parameter Specification
Aside from the free space requested, the utility compresses the index. ICHUT400 also writes profiles to the output data sets in collating sequence. You can request, with the ALIGN parameter, that no profile span physical blocks if it can fit into a single physical block (1024 bytes). This decreases the amount of I/O required to access profiles that occupy two, three, or four 256-byte segments. The option has no effect on profiles that occupy only one segment.
You can specify a number of parameters in the P ARM field of the EXEC statement of the step executing ICHUT400. The syntax for the parameters is similar to that of the TSO command language. They can be separated by one or
~ore blanks. Embedded blanks are not allowed. Any keyword can be abbreviated to the number of initial characters that uniquely identify that
keyword. The specification of redundant or contradictory keywords is considered an error. The allowable keywords are:
LOCKINPUT /NOLOCKINPUT
Provides a means of ensuring that, with the exception of updating statistics, any RACF data sets used as input are not updated. Specifying
LOCKINPUT means updates are no longer allowed to an input data set for which LOCKINPUT is specified, even after the utility terminates. To indicate that updates are no longer allowed, the utility sets the extend bit (at offset 26 in the ICB) on. NOLOCKINPU,T is the default.
T ABLE(table-name )/NOT ABLE
Permits the specification of a user-written range table to be used to select an output data set for each profile. Specifying TABLE(table-name) indicates that the named load module is to be used. NOTABLE is the default; either specifying or defaulting to it forces the selection of OUTDD 1 for all
profiles.
FREESPACE(percent)/NOFREESPACE
Allows you to control the amount of free space left in index blocks created for the output data sets. You can specify that from 0 to 50 percent of the space within the index block is to be left free. The sequence set (level one) will contain the specified percentage of free space; level two will contain one seventh of the specified percentage. Index levels higher than two will contain no free space. NOFREESPACE (which is equivalent to
FREESPACE(O)) is the default.
ALIGN/NOALIGN
Allows you to control profile space allocation. Specifying ALIGN forces profiles that occupy two, three, or four 256-byte segments to be placed so that they do not span 1024-byte physical blocks. Having a single physical block can decrease the I/O needed to process these profiles. Specifying NOALIGN (the default) causes no special alignment.
DUPDATASETS/NODUPDATASETS
Allows you to control the processing of DATASET entries with identical names from different input data sets. Specifying DUPDAT ASETS indicates that duplicates are allowed and that all DATASET entries are to be
processed. If you specify NODUPDATASETS and the utility encounters duplicate entries on different data sets, the utility copies the DATASET entry from the input data set identified by the lowest-numbered ddname.
When NODUPDAT ASETS is in effect, duplicates occurring on a single input data set are all accepted, assuming that they do not conflict with an entry from another data set earlier in the selection sequence.
NODUPDATASETS is the default.
Processing of Conflicts and Inconsistencies
If more than one input data set is being processed, you ~an encounter entries with duplicate names. The way in which entries with duplicate names are processed depends on which classes they belong to. If the utility encounters duplicate names across classes or within classes other than DATASET, it copies the entry from the input data set identified by the lowest-numbered ddname and issues a message indicating the entry that was not copied. See the description of the
DUPDATASETSjNODUPDATASETS parameter for information on how duplicate DATASET entries are handled.
If there is a logical error in an input RACF data set, it is possible that an index entry does not point to the profile for the correct entity. In this case, ICHUT400 issues an error message because it is impossible to copy the entity to an output data set.
The possibility of conflicts between tape volume sets exists even when only one input data set is specified. The utility detects:
• If more than one output data set is specified, a tape volume set might contain members that are assigned to different output data sets by the range table.
Because of the way that tape volume sets are implemented, it is impossible to reconstruct such a tape volume set on the output data sets. Therefore, ICHUT400 does not copy the entire tape volume set, including all its members, and issues a message to that effect.
• It is possible for two tape volume sets to contain one or more members with the same names. Usually, this happens only when more than one input data set is specified. (Because of an internal inconsistency however, it is possible for it to happen even with only one input data set.) It is impossible for ICHUT400 to copy both of these tape volume sets to the output data set. A message is issued to indicate which data set is not copied.
Chapter 6. RACF Utilities 6-39
Utility Return Codes
ICHUT400 Examples
The codes returned to the caller by the split/merge/extend utility are:
Hex (Decimal)
Duplicate IBM-defined names caused one or more warning conditions One or more error conditions occurred because of one of the following reasons:
• Duplicate non-IBM-defined names
• A defective tape volume set
One or more severe error conditions resulted from an error on an output data set
A terminating error condition occurred because of one of the following reasons:
• A recovery environment could not be established
• The SYSPRINT file could not be opened
• An error was found in a parameter specification
• A range table was requested but could not be loaded
• An error was detected in the specified range table.
• An error occurred on an input data set
These examples show how to code the split/merge/extend utility (lCHUT400) to perform different functions.
Example 1
In this example, ICHUT400 copies the profiles from a single input data set to a single output data set. This one-to-one copy does not require a range table because all profiles are directed to OUTnn 1. ICHUT400 compresses the output data set, which might be larger or smaller than the input data set, and might even reside on a different type of device. The index blocks of the output data sets will contain free space to allow for expansion.