Admin Alert: How to Recreate/Restore a System Distribution Directory

May 7, 2008 Joe Hertvik

In recent articles, I detailed how to change the communications identity of one i5/OS box so that it can impersonate another system and take its place on the network. However, I glossed over one important step: how to restore the i5/OS System Distribution Directory (SDD) from one machine to another. This week, I correct that error by showing you how to transfer an SDD from one machine to another.

What Is the SDD?

Although an SDD sounds like something you might catch when you’re not being too careful about the company you choose, the System Distribution Directory has been a key player in i5/OS and OS/400 shops for a very long time. The SDD plays an important role in distributing output for several major IBM licensed programs, including the iSeries Access product line and the AnyMail Server Framework (MSF). It is also used in many third-party i5/OS applications, including fax server and email server applications. For many products, a user must have an entry in the SDD in order to use the product.

The SDD is seeded by using the Work with Directory Entries (WRKDIRE) command, and directory entry information is distributed and kept in the following files in the QUSRSYS library.

The QAOKL* files
The QAOKP* files
The QAOZL03A file

The good news is that the SDD, its associated commands, and its files have been around for a long time. According to IBM, the SDD and the commands that populate the SDD (ADDDIRE, CHGDIRE, WRKDIRE, and CHGSYSDIRA) have not undergone major changes since the OS/400 V3R1M0 timeframe. So we’re dealing with a fairly stable system feature and these instructions should apply to most recent versions of i5/OS and OS/400, and they may even apply to i 6.1. The techniques shown here were demonstrated by using two i5/OS V5R3 machines.

Why Restore an SDD?

There are three good reasons why you may need to restore and replace an SDD on a target machine.

When a System i box fails over to a Capacity BackUp (CBU) system for testing or in an emergency. As mentioned above, if users are going to sign on and use an impersonating system as if it were their production system, you will also need to duplicate the SDD from the production system to make sure your applications work for your guest users.
When failing back to your production system after running production on a CBU system. In order to make the CBU function correctly again in its backup role, you may need to restore the SDD that was replaced.
When objects in your System Distribution Directory are damaged or deleted, and you need to restore the directory in order to make your applications work together. If you’re having trouble with an SDD, the underlying files may be corrupted and need to be replaced.

Transferring an SDD Between Two Consenting Hosts

Going through old IBM documentation, I created and tested the following procedure for restoring an SDD from one system to another. This scenario will also work when restoring an SDD from backup media. I tested this scenario by restoring a SDD from one i5/OS V5R3 machine to another. Since IBM has not made any major changes to the SDD in a long time, this scenario should also work for other versions of the i5/OS and OS/400 operating system, but note again that it has only been tested on a V5R3 machine. To protect yourself from accidental mistakes, however, make sure to take a copy of the QUSRSYS library on your target machine before beginning this procedure.

First Step To Take On the Source Machine

This procedure should be followed on the source machine that you are copying the SDD from.

Save the following QUSRSYS library objects to media or to a save file by using a variation of the following Save Object (SAVOBJ) command.

SAVOBJ     OBJ(QAOKL* QAOKP* QAOZL03A) LIB(QUSRSYS)
             DEV(*SAVF) SAVF(save_file_lib/save_file_name)
             SAVACT(*SYNCLIB) SAVACTMSGQ(QSYS/QSYSOPR)

After saving these objects, you should have 15 physical files and 33 logical files in your save file, for a total of 48 objects. If you have more than 48 objects and there are files on your source system with names fitting either the QAOKxxxxxx or QAOKLxxxxxx format (where xxxxxx is a number between ‘000000’ and ‘999999’), consult IBM Software Technical Document 14995701, QMSF Jobs Fail with a CP9A9C Errors with QAOK* Files. Follow the instructions in the section titled Fixing up QAOKL* and QAOKP* System Distribution Directory Files in QUSRSYS before running the SAVOBJ command again, and that should help you save only the 48 files that an SDD transfer needs.

The SAVOBJ command shown here demonstrates how to save the data to a save file. Make the appropriate changes in this command if you want to save the information to media. This step saves all the objects that contain SDD information from the machine where the information is stored.

Notice how I used a save-while-active (SWA) version of the SAVOBJ command to save this information. This is because some of these objects are locked to different system and program functions, and the only way to save them is by performing a SWA. If you don’t perform an SWA save, you won’t be able to save all the necessary objects for your SDD restore unless you put your machine in restricted state first.

Steps To Take on the Target Machine

On the target machine where you want to restore the saved source SDD to, perform the following steps:

1. Back up the target system’s current QUSRSYS library to media in case you make a mistake and need to restore some QUSRSYS objects back to the system. This can easily be done by using the following Save Library (SAVLIB) command.

SAVLIB LIB(QUSRSYS) DEV(*SAVF) 
SAVF(save_file_library/save_file_name) SAVACT(*SYNCLIB) 
SAVACTMSGQ(QSYSOPR)

Notice again that I used a SWA version of the command to ensure that I save all the objects.

2. Put the machine in restricted mode. This is necessary in order to delete the objects in your current SDD files. You can find instructions for putting your Power i, System i, iSeries, or AS/400 box into restricted mode by reading this article

3. Use the following Delete Files (DLTF) command to remove the following files from the QUSRSYS library. (Again I caution you to save these objects before deleting them in case they need to be replaced later.)

DLTF       FILE(QUSRSYS/QAOZL03A)
DLTF       FILE(QUSRSYS/QAOKL*)
DLTF       FILE(QUSRSYS/QAOKP*)

You must run these DLTF commands in this order because the QAOZL03A file is a logical file that is built over eight different QAOKP* physical files. If you don’t remove the logical file first, you won’t be able to remove the QAOKP* files that it is built over.

4. Restore the new SDD files from your source system by using the following Restore Object (RSTOBJ) command. Use the source media that you saved in the section “First Step To Take On the Source Machine” to perform this step.

RSTOBJ     OBJ(QAOKL* QAOKP*) SAVLIB(QUSRSYS) +
             DEV(*SAVF) SAVF(save_file_library/save_file_name)

RSTOBJ     OBJ(QAOZL03A) SAVLIB(QUSRSYS) DEV(*SAVF) +
             SAVF(save_file_library/save_file_name)

Note that because the QAOZL03A file is dependent on several QAOKP* files being restored, you should restore that file last after all the QAOKP* files have been processed.

5. Run the Initialize System (INZSYS) command, which helps to initialize the restored information in the QUSRSYS library.

INZSYS

It’s important to avoid performing the next step until this INZSYS command has finished. If you run the next step before INZSYS completes, you could damage your system. For information on how to tell when INZSYS completes, see my article on how to use INZSYS.

6. After INZSYS completes, run the following two Change System Directory Attributes (CHGSYSDIRA) commands to update your directory search information from the new SDD files. These commands first delete the old search information associated with the System Distribution Directory, before rebuilding it with the new SDD information.

CHGSYSDIRA ALWSCH(*NO) 

CHGSYSDIRA ALWSCH(*YES)

The first command deletes the old information, while the second rebuilds the search information.

7. At this point, your new SDD should be ready to use on your target machine. You can verify that all the entries have been transferred by running the Work with Directory Entry (WRKDIRE) command and checking to see that all the entries have been properly restored to your system.

Steps To Restore the Original SDD

If you’re ready to restore the original SDD on your target system, it’s fairly easy to do. All you have to do is perform steps 1 through 7 on your target system by using the save file or media that contains the original QAOKL*, QAOKP*, and QAOZL03A files from before you overrode the old SDD with the new SDD. The process will work exactly the same as it did for overriding the SDD, and you’ll have your original SDD back on the system in no time.