Brief: Although it is advantageous to have specific directory entries for each remote user, synchronizing directories among machines is difficult if done manually. You can use *ANY entries in the directory to represent remote users, but this approach has disadvantages. This article describes the system- provided, directory shadowing capability. Shadowing lets you automatically synchronize directories and maintain remote-user entries on your machine with data from each home machine.

The system directory on each AS/400 contains entries for users local to that machine and for selected users on other AS/400s. In addition to being used for SNADS distributions, the directory is used with OfficeVision. The directory includes data about users, departments, and locations.

Directory entries can be either specific or generic. A specific entry contains a user ID, address, and system name. SNADS can immediately verify the user ID and address of a specific entry in your system directory before sending the distribution.

A generic entry contains *ANY in the user ID, or user ID and address parts. Generic entries are useful when you need to be able to send distributions to remote users, but you don't want to add specific remote users to your directory. If SNADS does not find the specific directory entry and cannot use a generic entry, the distribution is not sent. You are notified of the faulty user ID and address with out incurring any communications overhead. With a generic entry, SNADS sends the distribution to the remote system, which then checks for the user ID and address. You are still notified if you use an incorrect user ID and address but only after incurring the greater communications overhead.

Ideally, all remote users to whom you send distributions or mail have specific directory entries on your system. That way, the send programs can validate the intended recipient locally. The problem is that it can be extremely difficult to manually maintain directory entries for remote users on your system. To do that, you need a procedure to monitor any changes in the remote directory, so that users who are remote to you are added as local users. You have to replicate the changes in the remote directory in your local directory. This procedure has to be followed for each system to which you send distributions. You need to perform the directory maintenance at each of the remote systems.

Rather than face the horrible job of manually synchronizing directories, many administrators simply choose to use the generic *ANY entries. After all, one *ANY entry can represent a number of remote users. This approach is workable but not optimal because of possible communications overhead due to errors.

Alternatively, you can use the system-provided, directory shadowing function. With directory shadowing, you can collect directory entries from other systems and add them to your system directory. You can then supply your directory entries to other systems. Shadowing is designed to be run periodically, so any changes to directory entries on remote systems will be applied to your directory soon after they are made.

Shadowing Concepts

Although shadowing is concerned with the system directory, which is used by SNADS and OfficeVision, it operates independently of those products. All that is needed is an APPC connection between machines that will shadow their directories (the machines can be in an APPN network).

Shadowing uses the terms supplier and collector to describe the relationship of machines to each other. At your local system, you indicate those machines that supply their directory information using their machine names. Those remote systems are supplier systems. Your machine, in turn, is regarded by each of the suppliers as a collector system-i.e., your machine collects directory information from them. A machine can be both a supplier and a collector. For example, you may want two AS/400s to shadow each other's directory. Each machine is a supplier because it supplies its directory entries to the other machine. Each machine is also a collector because it collects directory entries from the other machine.

You can designate any number of other machines as suppliers to your machine. A remote machine cannot send directory entries to your machine through directory shadowing until you identify it as a supplier. At a remote site, no command can be used to force its directory entries onto your machine. Similarly, any number of other machines can have a collector relationship to your machine. You can either accept collectors by default or create a list of authorized collector machines.

In addition to defining the supplier and collector relationships; you set options to control when shadowing occurs; the number of retries in the event of errors during shadowing; which directory entries are modified in your directory from remote systems; which directory entries are shadowed from your directory to a remote system; and whether or not remote entries within your directory are supplied to remote machines.

Shadowing supplies all directory information with the exception of the mail indicator field, print cover page field, indirect user field, user profile, nickname, and distribution lists. After the initial load, shadowing only sends directory changes to the collector system. Directory changes include additions, deletions, and modifications to directory, department and location information. Changes to the IBM-supplied directory entries QSECOFR, QSYS, QDFTOWN, QLPAUTO, QLPINSTL, and QUSER are never shadowed from one system to another.

Get Set to Shadow

The actual shadowing process is trivial; in fact, after setting it up correctly, shadowing is automatic and runs as a background task. There are two difficult parts of shadowing: setting up your system and its suppliers so you get the directory entries you want, and completing and understanding the first shadow event. 1 lists the steps you take use to start shadowing another system's directory.

The actual shadowing process is trivial; in fact, after setting it up correctly, shadowing is automatic and runs as a background task. There are two difficult parts of shadowing: setting up your system and its suppliers so you get the directory entries you want, and completing and understanding the first shadow event. Figure 1 lists the steps you take use to start shadowing another system's directory.

Shadowing maintains your directory by applying changes that occurred in other directories based on the date and time of those changes. Coordinating system timestamping of changes to directory entries is important, particularly when shadowing from several systems. Shadowing uses the timestamp value to determine which directory change to use. If the entry was changed on more than one system, the most recent change is applied. To coordinate system timestamping, you set the Universal Time Coordinated Offset system value (QUTCOFFSET). This value is used to timestamp changes to directory entries so that the system can determine which changes are the most recent, even across time zones. (For more information, see the article, "Automate Daylight Saving Time Changes," MC, March 1994.)

Next, you use the Change Directory Attributes (CHGDIRA) command to set the values used in shadowing. (Although it's called "change," this command functions like an edit command, in that you are shown the current values, and you can work with them.) You need to consider several parameters: the verification and supplier programs, the retry interval and limit, the message queue, and shadow remote users. The CHGDIRA command display is shown in 2.

Next, you use the Change Directory Attributes (CHGDIRA) command to set the values used in shadowing. (Although it's called "change," this command functions like an edit command, in that you are shown the current values, and you can work with them.) You need to consider several parameters: the verification and supplier programs, the retry interval and limit, the message queue, and shadow remote users. The CHGDIRA command display is shown in Figure 2.

You can use the verification program (VRFPGM) and supplier program (SUPPGM) parameters to identify programs you write to control directory shadowing. The parameter lists and the return codes used with these programs are documented in the System Programmer's Interface Reference. These programs are optional; if supplied, they are called when changes are made to your directory. You can include any required logic in the programs to accept or reject a proposed change to your directory.

The verification program is called before any changes are made to a directory entry, department, or location information. You can use the verification program to reject a proposed change from another system's directory. An important use of the verification program is to verify and reject the remote directory entries supplied to your system. On the supplier system, a remote directory entry may be an entry that is local to your system-the remote entry system's directory describes one of your users. Rather than accept its version of your user, you might choose to reject the remote entry. You use this defense mechanism in conjunction with the shadow remote users (RMTSHD) parameter of the CHGDIRA command, described later. If you rely solely on the RMTSHD setting, you may not be able to control the directory entries supplied.

The opposite of the verification program is the supplier program. You may want to use this program to filter out directory entries that are intended strictly for local use on your system; entries for temporary employees, for example. This program monitors your directory when it is called upon to be a supplier to a remote system. Whenever a directory entry is modified, it becomes a conadidate for shadowing. The supplier program can reject an entry before it is supplied to the remote system.

Although the frequency of shadowing is set in other commands, you control shadowing retries with the retry interval (RTYITV) and retry limit (RTYLMT) parameters of the CHGDIRA command. These parameters are used to indicate what to do if there is an error during the shadowing process. Examples of errors include inactive communications (the line not being varied on), disconnects during the shadowing process, or a power failure on either system.

You should change the message queue (MSGQ) parameter from the default value of QSYSOPR before starting shadowing. That way, you can easily review the messages after the shadowing process is complete. The messages indicate the date and time shadowing started and ended, the number of directory entries that were shadowed, and any errors encountered with shadowed data.

The last parameter on CHGDIRA, shadow remote users (RMTSHD), is one of the most important parameters in the entire shadowing process. The RMTSHD parameter asks whether or not remote user directory entries should be shadowed to other systems. (A directory contains entries for users who are local and remote to your system. The remote entries in your system are local entries on the other system.) The default is to not shadow remote user data from one system to another. You may not want to rely entirely on the RMTSHD parameter setting because the value could be inadvertently changed by an unknowing system administrator at the remote site. You may need the protection of a verification program to keep your local user entries safe from updates sent from other systems.

The Initial Load

To start shadowing, identify the systems that will be suppliers to your system and perform an initial load from the suppliers' directories. You identify the systems and specify how to perform the initial load with the Add Directory Shadow System (ADDDIRSHD) command. You can also use the Work with Directory Shadow Systems (WRKDIRSHD) command, which includes options to add, change, remove, and display shadowed systems, in addition to options to suspend and resume shadowing.

The ADDDIRSHD command, shown in 3, includes four main groups of parameters. These parameter groups are used to identify the remote system that is to be a supplier, the schedule of shadowing, the initialization option, and miscellaneous parameters.

The ADDDIRSHD command, shown in Figure 3, includes four main groups of parameters. These parameter groups are used to identify the remote system that is to be a supplier, the schedule of shadowing, the initialization option, and miscellaneous parameters.

The first group of parameters includes the system name (SYSNAME) parameter, which specifies the remote system. This parameter should name another AS/400 to which you already have an APPC connection. You can further identify the system using the remote location name (RMTLOCNAME) and remote network ID (RMTNETID). Unless you have made changes to the network attributes on the remote machine (using the CHGNETA command), you will probably be able to use the default values for RMTLOCNAME and RMTNETID.

Parameters in the second group describe the shadowing schedule. You can request shadowing on an hourly, daily, weekly, biweekly, or monthly basis. You should select a schedule based upon the volatility of your directories and the importance of keeping your directories synchronized. The default value is *WEEKLY. Because shadowing runs as a communications job it creates overhead on your lines. You want to select a frequency that does not create undue drag on your system or the remote system.

You use the initial shadow (INZ) parameter to describe how you intend to load directory entries from the shadowed system the first time. During the initial shadow, all of the directory information from the shadowed system is used. Subsequent shadowing only sends changes. You can load the directory manually or with the APPC communication link.

If the directory you want to shadow is huge (several thousand entries), and you don't want to incur the overhead of a potentially long communications session, or if you do not yet have the APPC link, you may want to load the directory manually. The Copy From Directory (CPYFRM-DIR) command creates a tape or diskette file of directory entries on the supplier system. On the collector system, you use the Copy To Directory (CPYTODIR) command to load the directory from the tape or diskette.

If you manually shadow the directory, you specify either *NONAPPC or *COMPLETED for the INZ parameter. *NONAPPC means that you intend to manually shadow the directory, but have not yet done so. If you use *NONAPPC, be sure that you use the CPYTODIR command to load the diskette or tape before the next scheduled shadow event. You need the directory entries on your machine so that any changes that occurred on the supplier system after the CPYFRMDIR command can be applied. *COMPLETED means that you have completed the CPYFRMDIR and CPYTODIR process prior to using the ADDDIRSHD command and you are ready to start shadowing.

The alternative method to load your directory is to use *APPC as the parameter value. This value means you want the initial shadow event to run as a communications job. You indicate when the initial shadow event is to occur using the scheduled date and time parameter (SCD). The default value for this parameter is *CURRENT, which indicates your system will attempt to start the initial shadow event immediately. You can set a specific date and time for the initial shadow event if you prefer.

The INZ parameter also contains a replace data option with values of *YES or *NO. The default value, *NO, means a duplicate directory entry from another system will not replace the entry on your system. *YES means the entry from the other system replaces your entry.

The miscellaneous parameters include the communications mode (MODE), the local location name (LCLLOCNAME), and text describing the shadowed system. You should be able to use the default values for MODE and LCLLOCNAME. You should supply text; it is available for review on the WRKDIRSHD display.

At this point, you've added a supplier to your system. Shadowing that supplier system will happen at the specified date and time (immediately if you used *CURRENT for the scheduled date and time). Shadowing runs as a job in the QSYSWRK subsystem, which I'll describe next.

The Shadowing Process

After the initial load, shadowing runs automatically based on the frequency value that you set for the system to be shadowed. You can shadow any number of other systems, each of which has its own frequency.

Shadowing runs in the QSYSWRK subsystem. When QSYSWRK starts, an autostart job entry starts job QDIRSHDCTL if any systems are identified as suppliers to your system. The QDIRSHDCTL job then submits additional jobs to QSYSWRK to shadow the suppliers when the scheduled shadow date and time arrives. If subsystem QSYSWRK is active before you define any system to be shadowed, you can start the QDIRSHDCTL job with the Start Directory Shadowing (STRDIRSHD) command.

When the date and time for shadowing a system arrives, QDIRSHDCTL starts another job in QSYSWRK. The job name is the name of the system being shadowed. That job assumes an APPC connection is active, and a session is available to the remote system. The shadowing job will not activate the communications link between the two systems.

During shadowing, if any errors occur with a directory entry, messages are sent to the message queue identified in the CHGDIRA command. If the shadowing job ends abnormally, a job log is written. You should make it a habit to review the message queue and check for a job log after each shadowing event.

Controlling and Monitoring Shadowing

Once you define your supplier systems and do the initial load from each system, shadowing runs as a background job. Your primary control point is the WRKDIRSHD command. You have the option to select whether to work with supplier systems or collector systems.

The supplier option lists all of the systems you identified as supplying directory entries. In addition to the name, the current status, number of attempts, and date and time of the next shadow event are shown. For successful shadow events, the status is COMPLETED. If you review the display when shadowing is being done, the status is IN PROCESS. If any errors occurred during the shadowing, the status is ERROR. An error status applies to the job itself, not to any errors with directory entries.

You can select options for each shadowed system on the display. You can force shadowing to occur before the next scheduled date and time by selecting the change option and resetting the next scheduled shadow.

Shadowed systems can also be suspended and resumed on the WRKDIRSHD display. For example, if you know that a communications line will not be available during a scheduled shadow session, you can suspend shadowing and resume it later.

The second option of WRKDIRSHD lets you work with collector systems or systems that shadow your directory. This is a simpler display than the display for supplier systems. The only options you have for systems are to add additional collectors or to remove a collector. You normally do not have to add collectors; a collector is automatically added to this list the first time it shadows your system. However, a setting on the collector display lets you control collectors. The "check authority when shadowing" option defaults to 'N', meaning that any other system that contacts your system through APPC is allowed to shadow your directory. If you set the check authority option to 'Y', then another system can only shadow your system if it is in the list of collectors shown on the display. If you set the option to 'Y', you need to manually add new collector systems; the collector systems won't be able to add themselves to your system as collectors.

The Shadow Knows

Directory shadowing is the simplest way to maintain directories among systems. You don't need to do much addtional work to start shadowing, since the process uses the same communications link that other processes between systems use.

You should review the documentation in the Distribution Services Network Guide to understand your options when you are shadowing among many systems. You do not necessarily want every system to have supplier and collector relationships with every other system. That situation can lead to unnecessary shadowing and the possibility of losing synchronization.

If your directories are small or if you are satisfied using *ANY directory entries, then you may decide not to use directory shadowing. But if you are maintaining large directories and need them available across an enterprise network, you should investigate shadowing, starting with a few systems and extending it as far as required.

Craig Pelkie can be reached through Midrange Computing.

References Communications: Distribution Services Network Guide (SC41-9588, CD-ROM QBKA1B02). Programming: Work Management Guide (SC41-8078, CD-ROM QBKA9J02). System Programmer's Interface Reference (SC41-8223, CD-ROM QBKA8402).

Shadowing the SNADS Directory

Figure 1 Steps to Shadow Another System's Directory

 1. Verify that you have an APPC connection to the other system, and that the connection is active. 2. Consider setting system value QUTCOFFSET if the systems are in different time zones. 3. Use the Change Directory Attributes (CHGDIRA) command on your machine to set values for the verification program, the retry interval and limits, and the message queue. 4. Use the CHGDIRA command on the other machine to set values for the supplier program and to shadow remote users. 5. Use the Add Directory Shadow System (ADDDIRSHD) command on your machine to add the remote system as a system to be shadowed. 6. Initialize the directory shadow, either with the APPC connection or with the Copy from Directory (CPYFRMDIR) and Copy to Directory (CPYTODIR) commands. 7. Use the Start Directory Shadowing (STRDIRSHD) command on your machine to start the directory shadowing job QDIRSHDCTL in subsystem QSYSWRK, if necessary. Once shadowing is set up, the Work with Directory Shadow Systems (WRKDIRSHD) command can be used to control shadowing activities. 
 
 Shadowing the SNADS Directory
 
 Figure 2 The CHGDIRA Command
 
 UNABLE TO REPRODUCE GRAPHICS 
 
 Shadowing the SNADS Directory
 
 Figure 3 The ADDDIRSHD Command
 
 UNABLE TO REPRODUCE GRAPHICS