Directory Supplier Exit Program

The supplier program allows the administrator to decide whether operations (add, change, or delete) for directory entries, departments, and locations should be shadowed to collector systems. The advantages this provides is additional security to allow other systems on the network to see only the data you want them to see. It also gives you a way to provide partial replication through shadowing. If a user exit program is defined, it is called before any changes are shadowed to a collector system. The supplier program is specified on the SUPPGM parameter of the Change System Directory Attributes (CHGSYSDIRA) command, or through the registration facility for common exit programs.

Exit programs that have been registered through the registration facility can be viewed using the Work with Registration Information (WRKREGINF) command.

During directory shadowing, the supplier program is given all information known about the changes to the directory entries, departments, and locations. The exit program returns to the directory service an indication as to whether the add, change, or delete operation should be supplied to the collecting system.

The supplier program can reduce the amount of processing on the network, as opposed to the verification maintenance program. The supplier program can decide not to supply changes to the collecting system. However, the verification maintenance program can only decide not to apply changes that have already been supplied to the collecting system.

The supplier criteria should be consistent on all your systems to help reduce the amount of processing on the network.

Authorities and Locks

None.

Required Parameter Group

Function being requested

INPUT; CHAR(10)

The type of operation that the user is requesting to do to the directory information that is described by the other parameters.

*ADD	Information is being added.
*ADDDSC	User description is being added.
*CHG	Information is being changed. All fields in the directory information that are not changed will be X'00' except for the first field of every table. That field indicates what directory entry, department, or location is being changed.
*DLT	Information is being deleted.
*DLTDSC	User description is being deleted.

Directory information format

INPUT; CHAR(10)

The format of the directory information that is being worked with. The information is provided in the directory information parameter. The valid formats are:

SUPP0100	Directory entry (See SUPP0100 Format.)
SUPP0200	Department entry (See SUPP0200 Format.)
SUPP0300	Location entry (See SUPP0300 Format.)

These formats have the same layout as the CHKP0100, CHKP0200, and CHKP0300 formats used for the Directory Maintenance exit program. This allows a single program to be used as both a supplier program and a verification maintenance program.

Owning system name

INPUT; CHAR(8)

The name of the system that "owns" the directory entry, department, or location that is being worked with. The owning system is the system that originally added the data to the network.

*LOCAL

The entry is owned by the local system.

User making request

INPUT; CHAR(10)

The user profile name of the user that is doing the request. When using the shadowing function, this is the user that originated the change.

System making request

INPUT; CHAR(8)

The system from which the request is coming. When using the shadowing function, this is the system that originated the change.

Length of directory information

INPUT; BINARY(4)

The length of the directory information in the directory information parameter. The length depends on the directory information format. Each format has a different (but fixed) length as shown in specific format tables.

Directory information

INPUT; CHAR(*)

The directory information that is associated with the directory entry, department, or location that the request is made against. For the format of this character parameter, refer to the specific format table (SUPP0100 Format, SUPP0200 Format , or SUPP0300 Format) and to the Field Descriptions.

User exit program type

INPUT; CHAR(10)

The user exit program type that is associated with the call of the Directory Supplier exit program. This parameter is provided so that a single program can be used as both a supplier program and a verification program. This parameter is always set to *SUPPGM.

The Directory Supplier exit program will support a required parameter of 8 or 9 parameters. This is so the same exit program can be used for the Directory Supplier exit program or the verification maintenance exit program. To use a Directory Supplier exit program with 9 parameters, the first 8 parameters should be defined as documented for this exit program. The ninth parameter should be defined as documented for the ninth parameter for the verification maintenance exit program. When the Directory Supplier exit program is called with 9 parameters, the ninth parameter is ignored.

See Directory Maintenance Exit Program for more information on the verification maintenance exit program.

Rejecting a Directory Shadowing Record

The user-written exit program may reject requests to supply changes to a collector system. To do so, the exit program must signal a specific program message to the directory services module that called it, and then return. A directory shadowing operation is rejected based on the restrictions that have been identified. For example, if the exit program allows only five of ten systems in an advanced program-to-program communications (APPC) network to collect directory information, then directory shadowing requests by all other systems are rejected.

To allow a directory shadowing record to be supplied, the exit program only returns to the program that called it. Two program messages have been defined for the purpose of rejecting directory shadowing records. The messages are:

Note: The message must be signalled as an escape message. A diagnostic or informational message can be signalled before the escape message to give additional information about the error.

You may provide an optional data structure with message variable substitution text. This will help clarify the reasons for the rejection to the users. The optional data structure is:

SUPP0100 Format

Array for User-Defined Fields

The following table is the array for the user-defined fields, format SUPP0100.

SUPP0200 Format

SUPP0300 Format

Field Descriptions

Allow synchronization. Whether the directory entries should be synchronized with directories other than the system distribution directory. The values are 0 for no and 1 for yes.

Building. The name or number that identifies the user's building.

cc:Mail address. The cc:Mail address for a user. This field has a maximum of 126 characters, or 255 if the cc:Mail address contains both a remote post office name and an alias name.

cc:Mail comment. The cc:Mail comment for this user.

Character set. The character identifier (graphic character set) that was used by the work station to enter the data for the field.

Code page. The value specified on this parameter is used to instruct the printer device to interpret the hexadecimal byte string to print the same characters that were intended when the text was created.

Company. The name of the company for whom the user works.

Department. The name or number that identifies the user's department.

Description. The description associated with the user ID. One entry in the directory can have several different descriptions.

Displacement to next user-defined field element in this array. The displacement, in bytes, to the next user-defined field. Use this value to increment the pointer to get to the next user-defined field.

DLO owner. A special value indicating whether the user profile or the group profile will be assigned ownership of newly created document library objects (DLOs) associated with this directory entry.

Fax telephone number. The facsimile telephone number.

Field name. The user-defined field name.

Field value. The value of the user-defined field. The maximum is 512 bytes.

First name. The user's first name or given name.

Full name. The user's full name as it appears when a directory is viewed or searched.

Indirect user. A user enrolled in the system distribution directory who receives mail but never signs on to view it. An indirect user receives printed mail only. The values are 0 for no and 1 for yes.

Job title. The title of the user's occupation.

Last name. The user's last name.

Length of field value returned. The length of the user-defined field value. If the value is 0, there is no data in that field for this user.

Location. The location of the business or system. Some examples of location are city, state, or street address.

Location changed to. The new location value after combining locations.

Location lines 1 through 6. The location of the business or system. These fields further describe a location name. For example, the field may contain the general mailing address for the location.

Mail notification. Whether or not the user wants to be notified when mail arrives.

The user can specify these values:

Mail service level. A 17-byte field where the first 10 bytes are the field name and the last 7 bytes are the product ID. The values for the mail service level can be:

Mailing address lines 1 through 4. The address of the user.

Manager user ID/address. The department manager's user ID and address.

Middle name. The user's middle name.

Network user ID. A unique value associated with each user in the Enterprise Address Book. For example, the value could be the user ID/address, the social security number, or the employee number.

New user ID/address. The new user ID and address used during the rename operation.

Office. The name or number that identifies the user's office.

Old department. The previous department value before being changed.

Old location. The previous location value before being changed.

Old user to forward from user ID/address. This field shows the previous user ID and address from which the user forwards mail.

Preferred address. A 29-byte field where the first 10 bytes are the field name, the second 7 bytes are the product ID, the third 4 bytes are reserved, and the last 8 bytes are the address type name.

The special values of the field name in preferred address can be:

Preferred name. The name by which the user prefers to be known.

Print cover page. Whether a cover page is printed when the user's mail is printed. The values are 0 for no and 1 for yes.

Print personal mail. Whether to print the mail that can be accessed only by the receiver, but not by someone working on behalf of the receiver. When mail is sent, it can be assigned the classification of personal. This field is used only if the user is an indirect user. The values are 0 for No and 1 for Yes.

Product ID. The product ID of the user-defined field. If the value is *NONE, there is no product ID associated with the field.

Reports to department. The department to which this department reports.

Reserved. An ignored field.

System name/group. An IBM-supplied name that uniquely identifies the system. It is used as a network value for certain communications applications such as APPC.

Telephone number 1. The telephone number of the user's office or business, or telephone numbers that are significant to the user. The most important number should be listed on the first line because only the first line is displayed when you use the search directory function.

Telephone number 2. The second line for telephone numbers.

Text. Any additional information that describes the entry.

Title. A department title that further describes the department name.

User-defined fields. Fields that are defined on the system by the Change System Directory Attributes (CHGSYSDIRA) command. The value of these user-defined fields can then be filled in on the directory entry for each user. The field name, product ID, and the value is passed in the user-defined field array. The product ID will be blank if the product ID does not exist.

User ID/address. A two-part network name used in the system distribution directory and in the office applications to uniquely identify a user and to send electronic mail.

User profile. The user profile name, if any, associated with a user ID and address.

X.400 administration domain. The administration management domain part of the X.400 originator/recipient (O/R) name. An administration management domain is a management domain that is administered by a public organization, such as a national Post Telephone and Telegraph Administration (PTT). A management domain is a set of message transfer agents (MTAs) and user agents (UAs) that comprise a message handling system.

X.400 country or region. The country or region part of the X.400 originator/recipient (O/R) name.

X.400 domain attribute types 1 through 4. The type of a domain-defined attribute for this object. The domain-defined attribute is not defined by X.400 standards but is allowed in the X.400 originator/recipient (O/R) name to accommodate values of existing systems sending messages.

X.400 domain attribute values 1 through 4. The code immediately following the attribute type that specifies a particular property from the set defined by the attribute type.

X.400 generation qualifier. The generation qualifier part of the X.400 originator/recipient (O/R) name. For example, the generation qualifier in the name John R. Smith, III, is III. If you specify a generation qualifier, you must specify an X.400 surname.

X.400 given name. The user first name, or given name, part of the X.400 originator/recipient (O/R) name. The default for the given name is the equivalent of the first name. If you specify a given name, you must specify an X.400 surname.

X.400 initials. The first and middle initials of the X.400 originator/recipient (O/R) name. For example, the initials for John Henry Smith are JH. If you specify initials, you must specify a surname.

X.400 organization. The organization name part of the X.400 originator/recipient (O/R) name.

X.400 organization units 1 through 4. The organization-defined unit part of the X.400 originator/recipient (O/R) name.

X.400 private domain. The private management domain part of the X.400 originator/recipient (O/R) name. A private management domain is a management domain that is administered by a private company or a noncommercial organization.

X.400 surname. The user last name, or surname, part of the X.400 originator/recipient (O/R) name.

Error Messages