IRRIRA00 stage conversion

To convert a database to use an alias index, you must run the IRRIRA00 utility to advance the database through a series of stages. You can perform a single transition for each IRRIRA00 invocation, moving from stage 0 to 1, 1 to 2, or 2 to 3. You cannot skip a stage or retreat to a previous stage. This multi-step approach is intended to give you manageable, uninterrupted use of your database through the conversion. You need to understand the stages and how they affect RACF®.

Table 1. IRRIRA00 stage summary
Stage	Manager	Commands	Callable Services
0	Does not maintain alias index Purges VLF Does not allow alias index entry locates	Maintains VLF and mapping profiles	Identity search order: VLF Mapping profile or database search
1	Maintains alias index Purges VLF Does not allow alias index entry locates	Maintains VLF and mapping profiles	Identity search order: VLF Mapping profile or database search
2	Maintains alias index Purges VLF Allows alias index entry locates	Maintains VLF and mapping profiles	Identity search order: Alias index entry locate VLF Mapping profile or database search
3	Maintains alias index Purges VLF Allows alias index entry locates	Maintains VLF	Identity search order: VLF Alias index entry locate
Note: Mapping profiles are used if the appropriate class is active (for example, UNIXMAP, NOTELINK, NDSLINK). If UNIXMAP is not active, RACF searches through all the user and group profiles in the database with an OMVS segment until a match is found for the GID or UID. VLF is applicable only for an OMVS UID or GID. The IRRUMAP or IRRGMAP class must be active.

Important:

Before advancing the stage of your database, make a copy of the database for recovery purposes. If the utility fails, you might need to restore the database from a valid backup. Then resolve any conditions that caused the utility to fail and rerun the utility.
This utility fails if more than 129 8-byte user IDs are assigned to the same UID, or more than 129 8-byte group names are assigned to the same GID. (The limit is higher for user IDs or group names that are less than 8 bytes.) You can run the ICETOOL utility to verify that no UIDs or GIDs are approaching this limit. For information on the ICETOOL utility, see z/OS Security Server RACF Security Administrator's Guide.

Stage 0

The database does not have an alias index and the RACF database manager does not attempt to use or maintain the alias index. It continues to use the mapping profiles. Any database created earlier than OS/390® Release 10 exists in stage 0 automatically until you convert it with IRRIRA00.

Stage 1

Important: Before advancing to stage 1, run IRRMIN00 PARM=UPDATE and IPL the system if it was not done during previous migration steps.

To enter stage 1, IRRIRA00 sets the stage indicator in the ICBs and the RCVT to 1 and builds the alias index based on the information in the RACF database.

In stage 1, the database contains the existing mapping profiles and the new alias index. RACF uses VLF and the mapping profiles to locate a base USER or GROUP profile name that has been given another product's identity information. The RACF database manager maintains an alias index but does not use it to locate user or group names. RACF user and group commands such as ADDUSER maintain both the mapping profiles and the alias index entries during addition, modification, or deletion of USER and GROUP profiles.

Stage 2

To enter stage 2, IRRIRA00 sets the stage indicator in the ICBs and RCVT to 2.

In stage 2, RACF maintains both alias index entries and mapping profiles. The RACF database manager can use the alias index to locate user and group names.

At this stage, the identity mapping callable services look up application IDs in an alias index to retrieve corresponding RACF user or group names. If the entry is not found in the index, RACF searches through VLF, mapping profiles, or base profiles, depending on the alias type and active classes. If the secondary search locates the alias index entry successfully, the callable services:

Return the associated user or group name
Write a LOGREC entry indicating that the alias index does not match other mapping information

The callable services also generate a LOGREC entry if the search fails for any reason other than not found, regardless of the success of a secondary search.

To identify the error types, look for LOGREC entries that include the string IRRRUM01, IRRRGM01, or IRRRIM00 in the "FREE FORMAT COMPONENT INFORMATION" section. See z/OS Security Server RACF Callable Services to help you interpret return codes and determine how to correct any errors. You must resolve the problems before moving to stage 3.

Stage 3

Important:

You can advance to stage 3 after successfully operating in stage 2. Before entering stage 3, check the LOGREC entries and correct any errors that might have occurred when the callable services searched for alias index entries during stage 2.
You should enter stage 3 only when all sharing systems have the OS/390 Release 10 Security Server or later installed. If you are sharing a RACF database with a system that is at a lower level, you might receive unpredictable results.

To enter stage 3, IRRIRA00 sets the stage indicators to 3 in the ICBs and the RCVT and deletes the mapping profiles from the database.

In stage 3, RACF does not use mapping profiles for UID, GID, SNAME, and UNAME associations. Commands such as ADDUSER no longer maintain the old mapping profiles. You can deactivate the RACF UNIXMAP, NOTELINK, and NDSLINK classes.

A database created in OS/390 Release 10 or later is automatically set to stage 3.