ICHUT200 is a RACF utility program that identifies inconsistencies in the internal organization of a RACF data set. It performs the following functions:
• Scans the index blocks and prints information about problems with the index block chains <P
• Compares the segments of the data set that are actually in use to the segments allocated according to the BAM blocks, and prints information about
inconsistencies
• Creates a backup copy of a RACF data set, if requested
If you specify a work data set in your JCL, ICHUT200 copies the RACF data set into this work data set. ICHUT200 reserves the RACF data set during the copying by using a RESERVE macro instruction with a request for shared control. After the copying is complete, the RACF data set is released.
If you do not specify a work data set, the RACF data set is not released after the copying is complete. It remains reserved for the duration of the processing.
If a DD statement for the RACF data set is not included in your JCL, the utility assumes that a copy already exists in the work data set.
If a RACF data set is RACF-protected, you must have at least READ authority to access the data set. ICHUT200 runs as an APF-authorized program.
When running the ICHUT200 utility under a TMP (terminal monitor program) that allows multitasking, you cannot have any other active task in your session.
Allow ICHUT200 to complete before executing any other TSO command.
Scanning the Index Blocks
Unformatted Printout
When an index block scan is requested, ICHUT200 performs the following verifications:
• The pointer to every index block must be a multiple of 1024.
• Every index block must begin with the value X'8A'.
• Every index entry name must have a valid length.
• Every pointer entry in the index block must be preceded by the value X'6x' (x may be any value).
• Only level one blocks can appear in the sequence set.
• Offsets to the last index entry in each block must be correct.
• Offsets to free space in each index block must be correct.
If an index block does not meet all the requirements during the verification process, ICHUT200 prints a dump of the block in hex. An error message precedes the dump.
Some of these messages are also printed in a message data set. For an
explanation of these messages, see "RACF Data Set Verification Utility Program (ICHUT200) Messages" later in this chapter.
ICHUT200 provides the following information for each block that is not dumped:
• Title lines identifying the level and relative byte address (RBA) of the index block
• Validity check messages pertaining to the block
• The total number of entry names in the block
• The number of unused bytes in the block
• The average name length in the block
• The level of the block as defined in the header
• The offset to the last entry name in the block
• The offset to free space as defined in the header of the block
Chapter 6. RACF Utilities 6-9
Formatted Printout
Following this information are summary statistics about the index. These statistics might not be representative of the entire data set because they represent only the processed blocks that were not dumped due to errors. The following summary statistics are:
• The total number of index entry names in a RACF data set. A name is counted each time it appears in the index.
• The average number of names per index block.
• The average name length in the entire index.
• The average number of unused bytes per index block.
• The total number of index blocks.
• The total number of level one index blocks.
If a formatted index scan is requested, ICHUT200 also provides, in addition to the output previously described, a formatted printout of each index block that is not dumped because of an error. The formatted block immediately follows any validity check messages for that block. The following information is provided for each index entry within the block:
• The offset of the entry within the block
• The front-end compression count
• The entry name (generic entry names are followed by a G in parentheses)
• The last qualifier encode byte
• The RBA of the next-level index block or, for level one blocks, the RBA of the profile
• The block, byte, and bit of the BAM that describes the storage of the segment pointed to by the RBA
Notes:
1. For connect entries (such as IBMUSERjSYS1), the slash (f) represents X'OO'.
2. See Figure 6-2 Jor sample output that ICHUT200 produces when you request Jormattedindex blocks.
~
Q
01A 06 AWB632/M01632 000000073500
02B 02 AWM095 0000002A0600
039 02 AWM095/M01PGM 00000OOEC400
04E 02 AWM095/M01095 000000101000
063 00 A05 000000324700
070 00 A05.CMDLIB 00000000C500
084 00 A05.PGMLIB 000OOO325EOO
098 00 A05.PROCLIB 000000006400
OAD 00 A05C 0OOOO020F500
OBB 01 AOS801 00OOOOO1EFOO
OCA 01 A05952 OOOOOOlFB900
009 01 A05980 OOOOOOOlF100
OEB 00 BACKER 0OOOOOO3ACOO
OF8 00 BACKER/M0153K 000OOOO32FOO
10F 00 BAC1R2 00000033FIOO
l1F 00 BAC1R2/RACFTEMP 000000344000
138 00 BALlAS 000000440000
148 00 BAL1AS/RACFTEMP 000000440100
161 00 BAl83K 000000016800
171 00 BAL83K/RACFTEMP OOOOOOOOBFOO
18A 00 BARNWEl 000000317300
19B 00 BARNWEl/RACFTEST 000000029400
IB5 00 BASE2 0OOOOO059AOO
lC4 00 BASE2/SYS1 00000OO5ABOO
108 00 BASE2.* (G) 00000026E500
lEA 00 BCBB86 0000002F8EOO
1FA 00 BCBB86/B86IAR OOOOOOODCBOO
211 00 BCBB86/M02B86JM 0000001E3200
22A 00 BCBB86/PARM OOOOOOlOBEOO
23F 00 BCBB86/PL 0000002F8500
252 00 BCBB86/RELEASE 0000001A6900
26A 00 BCBBS6/R510 000000108700
27F SEQUENCE SET POINTER 000000130400
TOTAL NAMES IN THIS BLOCK-033. UNUSED BYTES-0376. AVERAGE NAME lENGTH-09.
LEVEL NUMBER-01. DISPLACEMENT TO LAST KEY-027F. DISPLACEMENT TO FREE SPACE-0288.
(G) - ENTITY NAME IS GENERIC
RBA 000000004400 RBA 000000167COO RBA 0000002A8800 RBA OOOOOOlE5COO RBA 00000036AOOO RBA 000000101000 RBA 00000034BOOO RBA 0000003BOOOO RBA 000000341400 RBA 000000306400 RBA 00000036EOOO RBA 000000309000 RBA 00000007A400 RBA 000000197000 RBA '000000130400 RBA 000000446800 RBA OO~000046000
RBA 00000038DOOO RBA 000000372000 RBA 000000340800 RBA 000000387000 RBA 000000342800 RBA 0000003A6400 RBA 0000003A5000 RBA 0000003A3COO RBA 000000166COO RBA 000000346COO RBA 000000337000
****
SEQUENCE SET RBAS****
****
INDEX FUNCTION STATISTICS****
TOTAL NUMBER OF NAMES IN RACF DATA SET 00020431
TOTAL NUMBER OF INDEX BLOCKS IN RACF DATA SET 00000797 AVERAGE NUMBER OF NAMES PER INDEX BLOCK 025
AVERAGE NAME LENGTH 09
AVERAGE NUMBER OF UNUSED BYTES PER INDEX BLOCK 0497
TOTAL NUMBER OF LEVEL 01 BLOCKS IN RACF DATA SET 000~0773
Figure 6-2 (Part 2 of 2). Sample Output of Formatted Index Produced by ICHUT200
BAM I
Allocation ComparisonWhen a BAM/allocation comparison is requested, rCHUT200 performs the following verifications:
• Every index entry name must have a valid length.
• The logical length of profiles must be a multiple of 256 and must be less than or equal to the allocated length as defined in the header of the profile.
• The actual number of templates must be less than or equal to the space allocated for templates in the index control block (rCB).
• The RBA of each template defined in the rCB must have these characteristics:
It is a mUltiple of 1024.
The first two bytes are zero.
The last four bytes are nonzero.
• The RBA of each BAM block must be a multiple of 1024 and its first two bytes must be zero.
• The count of BAM blocks in the rCB must be greater than zero.
• The number of blocks defined by a BAM block must be from 1 to 2008.
When a block does not meet all of these requirements, rCHUT200 prints a dump of the block in hex. An error message precedes the dump.
Some of these messages are also printed in a message data set. For an
explanation of these messages, see "RACF Data Set Verification Utility Program (rCHUT200) Messages" later in this chapter.
rCHUT200 produces an encoded map of each BAM block. Each map is identified by a block number and its relative byte address (RBA), and contains byte offsets to the coded masks within the block. The codes indicate the type of block and the types of consistencies or inconsistencies that exist between the actual allocation of data set segments and the status of the segments as defined by the masks in the BAM blocks. The codes and their meanings are as follows:
Symbol Meaning
* The segment is defined as allocated by the BAM and is actually allocated.
o The segment is defined as unallocated by the BAM and is actually unallocated.
The segment is defined as allocated by the BAM but is actually unallocated.
+ The segment is defined as unallocated by the BAM but is actually allocated.
Refers to an index block with the level in the next positions. This symbol implies *.
B Refers to a BAM block. This symbol implies *.
T Refers to a template block. This symbol implies *.
F Refers to the first block (Iell). This symbol implies *.
Chapter 6. RACF Utilities 6-13
$
?
%
@
#
Refers to an index, BAM, or first block that is defined as unallocated but is actually allocated.
Refers to a template or other special block that is defined as unallocated but is actually allocated.
Refers to block that is defined as allocated and is actually allocated. The block is invalid so its type is unknown.
Refers to block that is defined as unallocated but is actually allocated. The block is invalid so its type is unknown.
The segment is defined as allocated but is pointed to by more than one entry in the index block.
The segment is defined as unallocated but is pointed to by more than one entry in the index block.
Undefined space.
Following the encoded blocks, ICHUT200 prints a table of conflict messages that lists the first 200 locations of possible conflicts in the BAM blocks. These messages locate the inconsistencies by referencing the corresponding block, byte, and bit of the encoded mappings. Each word of the encoded map represents one byte of the BAM block. The relative byte address (RBA) of the storage
represented by the bit is also included.
ICHUT200 also provides the following summary statistics concerning the RACF data set:
• The number of BAM blocks defined in the ICB
• The RBA of the last BAM block that defines used space
• The total number of index blocks in the data set
• The total number of level one index blocks
• The number of profiles of each type in the data set
• The percentage of space used on a RACF data set
ICHUT200 produces an encoded map for every BAM block, whether
inconsistencies are found or not. As an option, you can request that the encoded maps for an entire RACF data set be printed. If inconsistencies are found, a table of conflict messages follows.
See Figure 6-3 for a sample printout of the encoded map that ICHUT200 produces.
* o BAM=UNALLOC , ACTUAL=ALLOC SPECIAL BLK BAM=ALLOC , ACTUAL=ALLOC UNKNOWN BLK BAM=UNALLOC ACTUAL=ALLOC UNKNOWN BLK BAM=ALLOC , DUPLICATE ALLOCATION BAM=UNALLOC , DUPLICATE ALLOCATION UNDEFINED STORAGE
Chapter 6. RACF Utilities 6-15
Input and Output
Control
Job Control Statements
ICHUT200 uses the following input:
• A control data set, which contains the utility control statements that indicate the functions to be performed.
• A RACF data set. (This data set is not required if the work data set already contains a copy.)
• A work data set into which a RACF data set is copied. (This data set is not required if a RACF data set is to be used throughout processing.) Note that this work copy can be used as a backup RACF data set.
ICHUT200 produces the following output:
• A message data set - containing diagnostic error messages.
• An output data set - for printing statistical data and the results of the ICHUT200 operations.
ICHUT200 is .controlled by job control statements and utility control statements.
The job control statements are necessary to execute or invoke the program and define the data sets used and produced by the program. The utility control statements control the functions of the program.
The following job control statements are necessary for using ICHUT200:
Statement JOB EXEC
SYSRACFDD
SYSUTl DD
SYSINDD
SYSUT2 DD SYSPRINT DD
Use
Initiates the job.
Specifies the program name (PGM = ICHUT200) or, if the job control statements reside in a procedure library, the procedure name.
Defines a RACF data set on a direct access device. ICHUT200 requires this data set unless the work data set already contains a copy of the RACF data set.
Defines a work data set on a direct access device. ICHUT200 requires this data set unless a RACF data set is used throughout processing.
Defines the control data set. The control data set is normally found in the input stream; however, it can be a member of a procedure library or a sequential data set existing elsewhere.
Defines a sequential message data set.
Defines a sequential data set for printed output. The data set can be written to an output device, a tape volume, or a direct access device.
Note: If the utility is run under TSO, you can allocate both the SYSIN and SYSUT2 data sets to the terminal. Although you can allocate SYSPRINT to the
Utility Control Statements
terminal, it should be allocated to SYSOUT because ICHUT200 may produce a large volume of output.
ICHUT200 is controlled by utility control statements that have the following format:
INDEX [FORMAT]
I
where:
INDEX specifies you want the index scan function performed.
FORMAT specifies a formatted listing of all the index blocks.
Only one blank can separate INDEX and FORMAT.
You can use only columns 1 through 72.
MAP [ALL]
M
where:
MAP specifies you want the BAM/allocation verification performed.
ALL specifies that you want the encoded map for each BAM block in the RACF data set printed.
Only one blank can separate MAP and ALL.
You can use only columns 1 through 72.
END
where:
END terminates the utility program. An end-of-file on SYSIN also terminates the program.
You can use only columns 1 through 72.
Chapter 6. RACF Utilities 6-17
ICHUT200 Example
In the following ex~mple, ICHUT200 copies a RACF data set to the SYSUTI data set. A summary listing of all the index blocks is printed. Any BAM that contains conflicts is also printed with a table of the locations of the conflicts.
//VERIFY
Following are the unnumbered ICHUT200 messages that might be printed out to a message data set. Because these messages are unnumbered, they are arranged in this section in alphabetical order by message text.
Note: See RACF Messages and Codes for the ICHUT200 numbered messages.
BAM BLOCK CHAIN FIELD IS BROKEN - MAP FUNCTION TERMINATED.
Explanation: ICHUT200 was processing the BAM when the count of the number of BAMs in the ICB was exceeded. The fields might be in a loop.
~
COUNT OF BAM BLOCKS IN ICB IS ZERO - MAP FUNCTION TERMINATED.
Explanation: The ICB contains a count of zero for the number of BAM blocks in the RACF data set.
COUNT OF NUMBER OF BLOCKS DEFINED BY A BAM IS INVALID - MAP FUNCTION TERMINATED.
Explanation: The count of the number of blocks defined by the BAM contained in the header is either zero or greater than 2008.
DATA BLOCK FAILED VALIDITY CHECK.
Explanation: The segment pointed to by a level one index block does not begin with the value X'82'.
DATA BLOCK KEY LENGTH INVALID.
Explanation: The record name in the profile is not from 1 to 44 bytes in length.
DISPLACEMENT TO FREE SPACE IS INCORRECT.
Explanation: The offset (in the header of the index block) to the free space in the block is incorrect, or the end-of-block delimiter (X'OC') is not present.
DISPLACEMENT TO LAST KEY IS INCORRECT.
Explanation: The offset (in the header of the index block) to the last entry is incorrect, or the entry identifier (X'21' or X'20') is not present.
E(P) BYTE/RBA OF NEXT BLOCK IN SEQUENCE SET IS INVALID.
Explanation: The sequence set pointer entry in the level one index block is not preceded by the value X'6x', or the next level one block is invalid for one of the following reasons:
• The first two bytes are not zero.
• The last four bytes are zero and this is not the last block in the chain.
• The RBA is not a multiple of 1024.
Chapter 6. RACF Utilities 6-19
E(P) BYTE/RBA xxxxxxxxxxxx FAILED VALIDITY CHECK.
Explanation: The pointer entry of an index entry in the block is not preceded by the value X'6x', or the RBA xxxxxxxxxxxx of the next level index block or profile is invalid for one of the following reasons:
• The first two bytes are not zero.
• The last four bytes are zero.
• The RBA is not a multiple of 1024.
• For level one blocks, the RBA is not a multiple of 256.
ICHUT200 does not dump the index block if only the RBA is invalid.
END OF DATA FLAG BYTE POSSIBLY MISSING.
Explanation: The end-of-block delimiter at the end of the index block is not X'OC' or the displacement to this byte is incorrect. The displacement is calculated by adding the sum of the length of the last entry name in the block and the length of the pointer entry to the offset of the last entry name in the block. If the length of the entry name is incorrect, the displacement to this byte is incorrect.
FOLLOWING LEVEL 01 BLOCK IS NOT POINTED TO BY A LEVEL 02 BLOCK.
Explanation: An index block with a level greater then X'02' points to an index block with a level of X'OI' in the header. ICHUT200 processes the level one index block normally.
I/O ERROR REREADING BAM BLOCK - MAP FUNCTION TERMINATED.
Explanation: ICHUT200 encountered an unrecoverable I/O error while attempting to reread a BAM block. The block is not dumped.
INDEX BLOCK FAILED VALIDITY CHECK.
Explanation: The block does not begin with the value X'SA'.
INVALID E(K) BYTE IN KEY ENTRY AT OFFSET aa
Explanation: An index entry name might not be preceded by a valid key byte. All entries in index blocks that are not level one must begin with the value X'21'. In
level one index blocks, either X'22' or X'21' must precede each entry except for the last entry, which must be preceded by X'20'.
KEY ENTRY LENGTH Th.TVALID AT OFFSET aa
Explanation: An index entry name does not have a valid length. An entry, other then the first entry in a block that is not level one, might have a zero length. If it does, it must also have a compression count other than zero. The compression count must not be greater then the length of the first entry in the block. The field 'aa' is the offset of the beginning of the invalid entry in the index block.
LOGICAL LENGTH OF DATA BLOCK IS INVALID.
Explanation: The logical length of the profile is not a multiple of 256, or is greater then the allocated length as defined in the header.
MORE THAN 200 BAM ALLOCATION ERRORS FOUND.
Explanation: In verifying the BAM blocks with the actual allocation of segments in the RACF data set, ICHUT200 found more then 200 locations with possible conflicts.
NON LEVEL 01 INDEX BLOCK IS IN SEQUENCE SET.
Explanation: The index block is in the sequence set, but the level in the header is not one.
PossmLE COMPRESSION COUNT ERROR IN KEY ENTRY AT OFFSET aa
Explanation: An index entry name might not have a valid compression count.
The first entry must have a zero compression count. An entry, other then the first entry, must have a compression count which is less than or equal to the length of the first entry name. The field 'aa' is the offset of the beginning of the invalid entry in the index block.
PossmLE LOOP IN SEQUENCE SET.
Explanation: The first entry name of the level one index block is not
alphabetically greater then the first entry name of the previous level one index block.
Chapter 6. RACF Utilities 6-21
PROGRAM LIMIT EXCEEDED - PROCESSING OF INDEX
PROGRAM LIMIT EXCEEDED - PROCESSING OF INDEX