The following commands control the functions of ICHUT300 after it is invoked by the BLKUPD command:
• READ command - reads a RACF data set block into storage. Subcommands of the READ command update the block.
• LOCATE command -- locates an index entry in the RACF sequence set.
• END command (required) - terminates the processing of ICHUT300.
Considerations When Using ICHUT300
The following considerations apply to the use of the block update utility:
• ICHUT300 does not support attention handling. If an attention interruption occurs, and the user enters any data other than a null line or TIME
command, the BLKUPD command and its subcommands terminate.
• Wl1en executing ICHUT300 under control of command procedures, you must add the DATA and END DATA command procedure statements around each ICHUT300 command and subcommand that is also a command procedure statement. See the TSO Command Language Reference for a description of command procedures.
• When executing ICHUT300 under a TMP (terminal monitor program) that 'allows multitasking, you cannot have any other active task in your session.
Allow ICHUT300 to complete before executing any other TSO command.
• You can use ICHUT300 on any active RACF data set or a coPY of the RACF data set.
• The subcommands of BLKUPD follow the TSO syntax rules. See the TSO Command Language Reference for a description of TSO command syntax rules.
• . If a RACF data set is RACF-protected, you must have at least UPDATE
authority to the data set. .
Invoking ICHUT300
• ICHUT300 runs as an APF-authorized program. Because any changes made to the data set are not made to the in-storage blocks, do not use ICHUT300 to make changes against an active RACF -protected data set if you are using the in-storage data or index block options.
The BLKUPD command invokes ICHUT300. Optionally, this command can allocate a RACF data set.
The format of the BLKUPD command is as follows:
BLKUPD [racfdsname]
where:
racfdsname specifies the name of a cataloged RACF data set. The name can be from 1 to 44 characters. If a name is not specified, you must have allocated the RACF data set on a SYSRACF DD statement before invoking ICHUT300.
Updating a RACF Block
You can use the READ function to update a RACF data set block. The READ command causes a block to be read into storage and copied into a work area.
The subcommands of the READ command update the block in the work area or print portions of the original block or the updated block. The updated block is called the new block; the original block is called the old block.
The format of the READ command is as follows:
READ rba UPDATE NOUPDATE
where:
rba specifies the relative byte address of the block to be read. If rba does not represent an address on a lK boundary, the block on the IK boundary that contains rba is read. You can enter the value rba as a hexadecimal (X'nn') or decimal (nnn) number. Hexadecimal numbers can be from 1 to 8 characters;
decimal numbers can be from 1 to 10 characters.
UPDATE specifies that this RACF data set is to be under exclusive control until the READ function terminates. You should use UPDATE only during slack time in system operations ..
NOUPDATE specifies that this RACF data set is for shared use only.
Commands that update the block are rejected. NOUPDATE is the default.
Chapter 6. RACF Utilities
6-25
LIST Subcommand
The following subcommands control the READ function:
• LIST subcommand - prints portions of the block in hexadecimal
• FORMAT subcommand - produces a formatted listing of the contents of an index block
• FIND subcommand - locates the offset of data in the block
• REP subcommand - replaces data in the block
• DISPLAY subcommand - displays the entries of a new index block.
Subcommands of DISPLA Y update the entries.
• REREAD subcommand - overlays the new block in the work area with the old block
• END subcommand - terminates the READ function
The LIST subcommand prints a hexadecimal dump of all or part of the RACF block.
The format of the LIST subcommand is as follows:
LIST OLD RANGE(xxx,yyy) NEW ALL
where:
OLD specifies the original block obtained by the READ command. OLD is the default.
NEW specifies the block that was updated.
RANGE defines the parts of the block to be listed.
xxx specifies the offset into the block where the listing is to start. The default is O.
yyy specifies the number of bytes to be listed. The default is 16.
The values for xxx and yyy can be hexadecimal or decimal numbers. If the sum of xxx and yyy exceeds 1024, the dump ends at the end of the block.
ALL specifies a hexadecimal listing of the entire RACF block.
FORMAT Subcommand
The FORMAT subcommand prints a formatted list of the contents of an index block. The list contains the following information:
• The RBA of the block
• The level of the block
• The offset to the last entry
• The offset to free space
• The offset of each entry within the block
• The front-end compression count of each entry
• The name of each entry (generic names are identified by a G in parentheses after the name)
• The last qualifier encode byte of each entry
• The RBA of the next-level index block for each entry or, for level one blocks, the RBA of the profile
If the block obtained by the READ command is not a valid index block, the request is rejected.
The format of the FORMAT subcommand is as follows:
FORMAT OLD
FMT NEW
where:
OLD specifies the original index block obtained by READ. OLD is the default.
NEW specifies the index block that was updated.
Chapter 6. RACF Utilities 6-27
FIND Subcommand
REP Subcommand
The FIND subcommand finds and prints the hexadecimal offset of a string in the block.
The format of the FIND subcommand is as follows:
FIND string OLD NEW
where:
string specifies the string to be located. The string can be hexadecimal (which is specified as X'string') or characters (which can be quoted or unquoted).
Hexadecimal strings are right-justified and padded with zeroes to a byte boundary.
OLD specifies the original block obtained by READ. OLD is the default.
NEW specifies the block that was updated.
The REP subcommand replaces a string in the new block with another string.
Optionally, this subcommand verifies the original string before making the replacement.
The format of the REP subcommand is as follows:
REP string OFFSET(xxx) [VER(string)]
where:
string specifies the new string of data. String can be hexadecimal (which is specified as X'string') or characters (which can be quoted or unquoted).
Hexadecimal strings are right-justified and padded with zeroes to a byte boundary.
OFFSET(xxx) specifies the offset into the block where the string is to be replaced.
VER(string) specifies the original string that is to be verified. If the string is not found at offset xxx into the new block, the replacement is not made.
DISPLAY Subcommand
The DISPLAY subcommand displays each entry of a new index block. The subcommands of DISPLAY are used to modify the displayed entries. If the block obtained by the READ command is not a valid index block, the request is
rejected.
Note: Entry names for general resources must begin with the first 4 characters of the c1assname followed by a dash (for example, DASD-). Unless spac~ in the index blocks is a problem, enter the entry name as is. RACF performs compression when the index block becomes full.
The format of the DISPLAY subcommand is as follows:
DISPLAY [ENTRY(name)] [GENERIC]
where:
ENTRY(name) specifies the index entry where the display begins. If you do not specify a name, the display begins at the first entry in the index block;
name can be from I to 44 alphanumeric characters.
GENERIC: indicates that the index specified in ENTITY(name) is a generic name.
The subcommands of DISPLAY are as follows:
NEXT
N
which displays the next entry. The displayed entry is not changed. A null line also displays the next entry.
DELETE
D
which deletes the index entry. The next entry is displayed.
Chapter 6. RACF Utilities 6-29
CHANGE [ENTRY(name)] [GENERIC] [RBA(rba)] [COMP(xx)] DUPLICATE
C NODUPLICATE
which changes the name, the RBA of the index entry displayed, the compression count, and/or the entry identifier byte. ICHUT300 displays the changed entry;
you must enter the NEXT subcommand or a null line to display the next entry.
Some definitions and considerations are:
• The values xx and rba can be from 1 to 8 hexadecimal characters or from 1 to 10 decimal characters.
• The length of name plus the compression count cannot exceed 44. To create a fully compressed name, specify ENTRY (' ') with a nonzero compression count. (If the first entry in the index block is encoded, do not specify full compression; compress only up to the last period (.) in the entry name or ignore compression.)
• DUPLICATE changes the entry identifier byte to X'22'; NODUPLICATE changes the byte to X'21'. If you omit both DUPLICATE and
NO DUPLICATE, the entry identifier byte is not changed.
• GENERIC identifies the entry name as a generic name.
INSERT ENTRY(name) [GENERIC] RBA(rba) [COMP(xx)] DUPLICATE
I NODUPLICATE
which inserts a new index entry immediately preceding the entry that is displayed.
ICHUT300 displays the new entry; entering the NEXT subcommand displays the original entry again.
Some definitions and considerations are:
• GENERIC indicates that the index entry specified in ENTRY(name) is a generic name.
• The values xx and rba can be from 1 to 8 hexadecimal characters or from 1 to 10 decimal characters.
• The length of name plus the compression count cannot exceed 44. To create a fully compressed name, specify ENTRY (' ') with a nonzero compression count. (If the first entry in the index block is encoded, do not specify full compression; compress only up to the last period (.) in the entry name or ignore compression.)
• DUPLICATE sets the entry identifier byte toX'22'; NODUPLICATE sets the byte to X'21'. NODUPLICATE is the default.
REREAD Subcommand
END Subcommand
END SAVE
NOSAVE
which ends the DISPLAY function. You can continue to update the block under the READ function.
SAVE updates the new index block to reflect the changes made under the DISPLAY subcommand. NOSA VE ignores all changes made under the DISPLAY subcommand. If UPDATE was not specified on the READ command, NOSA VE is forced.
The REREAD subcommand overlays the new RACF block in the work area with the old block (in case mistakes were made in updating the new block).
The format of the REREAD subcommand is as follows:
REREAD
The END subcommand ends processing on the RACF data set block obtained by the READ command.
The format of the END subcommand is as follows:
END SAVE
NOSAVE
where:
SAVE specifies that the new block is written back to the RACF data set in place of the one that was read.
NOSA VE specifies that the RACF data set is not updated with the new block. NOSA VE is forced if UPDATE was not specified on the READ command or if no changes were made in the block.
Chapter 6. RACF Utilities 6-31
Locating an Index Entry
The LOCATE command locates an index entry in the sequence set and prints a formatted list of the contents of the level one index block containing the entry name. Optionally, LOCATE prints a listing of all the index blocks in the chain from the highest-level index block to the appropriate level one block. The formatted list contains the same information as that produced by the FORMAT subcommand of the READ command.
If an index block in the chain contains an error, ICHUT300 produces a hexadecimal dump of the block. If the name is not found in a level one block, ICHUT300 prints the block that should contain it. If the block containing the name is not found by a hierarchy index search because of errors in the chain, ICHUT300 searches the sequence set.
The format of the LOCATE command is as follows:
LOCATE entryname [GENERIC] [LISTALL]
where:
Terminating ICHUT300
entryname specifies the index entry to be located; entryname can be from 1 to 44 characters. Entry names for general resources must begin with the first 4 characters of the class name followed by a dash (for example, DASD-).
GENERIC specifies that entryname is generic.
LIST ALL specifies that all the index blocks in the hierarchy chain are to be printed.
The END command terminates ICHUT300.
The format of the END command is:
END