Directory Maintenance Exit Program

 QSYSINC Member Name:  EOKDRVF

 Exit Point Name:  QIBM_QOK_VERIFY
                   QIBM_QOK_NOTIFY

 Exit Point Format Name:  VRFY0100

The Directory Maintenance exit program allows the administrator to make decisions based on directory entry additions, changes, or deletions. Two exit points are available.

The maintenance program registered at exit point QIBM_QOK_VERIFY is called before any directory entry, department, or location is added, changed, or removed from the system. This exit program is more specifically known as the verification maintenance exit program. The verification maintenance exit program allows the administrator to define additional security or syntax checking on the data.

The maintenance program registered at exit point QIBM_QOK_NOTIFY is called after any directory entry, department, or location is added, changed, or removed from the system. This exit program is more specifically known as the notification maintenance exit program.

The verification maintenance exit program is specified on the VRFPGM parameter of the Change System Directory Attribute (CHGSYSDIRA) command. The verification maintenance exit program can also be specified using the Work with Registration Information (WRKREGINF) command. The notification maintenance exit program can only be specified using the Work with Registration Information (WRKREGINF) command.

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

The maintenance programs are given all updated information known about the directory entry, department, or location. The verification maintenance exit program returns to the directory service an indication as to whether the add, change, or delete operation is to be applied to the Enterprise Address Book (EAB). On the iSeries server, this is called the system distribution directory. The EAB is a collection of data, such as information about people, departments, and locations in a network. An example of an enterprise is a company.

Whether or not update requests that are rejected by the verification maintenance exit program are supplied to other systems depends on the origin of the update.

• When a local update request is rejected by the verification maintenance exit program, the update does not affect the local system. If the iSeries server is participating in directory shadowing, the update is not supplied to other systems in the directory shadowing network.
  
  
• If the iSeries server is participating in directory shadowing and a shadowed update request is received and is rejected by the verification maintenance exit program, then the update does not affect the local system.

  Other systems in the directory shadowing network may be affected. The results depend on the nature of the shadowed update request:

  • When an add request is rejected, it is filtered out of (does not appear on) the local system, but remains on the network. Information about the add request is stored separately in a change log and will subsequently be supplied to other systems in the directory shadowing network.
    
    
  • When a change or delete request is rejected, the local system keeps its original information. In addition, the original information will be supplied again to other systems, including the system the information originated from, to keep directory information consistent throughout the network.

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

The system can get back the data which was filtered, but it is not a simple task. In order to retrieve the data which has been filtered out, the data can be shadowed again from the system where the data resides.

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:

CHKP0100	Directory entry (See CHKP0100 Format.)
CHKP0200	Department entry (See CHKP0200 Format.)
CHKP0300	Location entry (See CHKP0300 Format.)

These formats have the same layout as the SUPP0100, SUPP0200, and SUPP0300 formats used for the Directory Supplier exit program. This allows a single program to be used as both a verification maintenance program and a supplier 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 modification.

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 modification.

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 (CHKP0100 Format , CHKP0200 Format , or CHKP0300 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 Maintenance exit program. This parameter is provided so that a single program can be used as both a maintenance program and a supplier program. This parameter is set to *VRFPGM if calling the verification maintenance exit program or *NFYPGM if calling the notification maintenance exit program.

Field name and product ID in error

OUTPUT; CHAR(17)

The field name and product ID that caused the CPF89A4 error. The first 10 characters are the field name; the second 7 characters contain the product name. The product ID can have the following special values:

*NONE	A field name that does not have a product ID.
*IBM	A field defined by the i5/OS system distribution directory.

This parameter is used only by the verification maintenance exit program. The notification maintenance exit program does not use any output parameter. This is because the information has already been added to the directory and the notification maintenance exit program cannot reject it.

This field will be recognized only for an add or a change of a directory entry where the Work with Directory Entries (WRKDIRE) panel support is being used. The field will be highlighted and the cursor will be positioned on the field. The field will be ignored under any other conditions.

The field name can be a user-defined name or a name supplied by the i5/OS system distribution directory. To display the user-defined names, either type CHGSYSDIRA and press F4, or use the SREQ0200 format of the QOKSCHD API. For more information on the SREQ0200 format of the QOKSCHD API, see SREQ0200 Format.

The following names are defined by the i5/OS system distribution directory. The product ID of these names is *IBM.

LSTNAM	Last name
FSTNAM	First name
MIDNAM	Middle name
PREFNAM	Preferred name
FULNAM	Full name
DEPT	Department
USRID	User ID (DEN)
USRADDR	User address (DGN)
USRD	User description
SYSNAME	System name (REN)
SYSGRP	System group (RGN)
USER	User profile
NETUSRID	Network user ID
TELNBR1	Telephone number 1
TELNBR2	Telephone number 1
FAXTELNBR	Fax telephone number
LOC	Location
BLDG	Building
CMPNY	Company
OFC	Office
TITLE	Job title
ADDR1	Mailing address line 1
ADDR2	Mailing address line 2
ADDR3	Mailing address line 3
ADDR4	Mailing address line 4
INDUSR	Indirect user
LCLDTA	Local data indicator
TEXT	Text
COUNTRY	Country or region
ADMD	Administration domain
PRMD	Private management domain
ORG	Organization
SURNAM	Surname
GIVENNAM	Given name
INITIALS	Initials
GENQUAL	Generation qualifier
ORGUNIT1	Organization unit 1
ORGUNIT2	Organization unit 2
ORGUNIT3	Organization unit 3
ORGUNIT4	Organization unit 4
DMNDFNAT1	Domain-defined attribute type 1
DMNDFNAV1	Domain-defined attribute value 1
DMNDFNAT2	Domain-defined attribute type 2
DMNDFNAV2	Domain-defined attribute value 2
DMNDFNAT3	Domain-defined attribute type 3
DMNDFNAV3	Domain-defined attribute value 3
DMNDFNAT4	Domain-defined attribute type 4
DMNDFNAV4	Domain-defined attribute value 4
CCMAILADR	cc:Mail address
CCMAILCMT	cc:Mail comment
MSFSRVLVL	Mail server framework service level
PREFADR	Preferred address
ALWSYNC	Allow synchronization
DLOOWN	DLO owner

Rejecting an Update Operation

The user-written verification maintenance exit program may reject update requests. To do so, the verification maintenance exit program must signal a specific program message to the directory services module that called it, and then return. An update is rejected based on the restrictions that have been identified. For example, if three people have authority to make updates but the program allows only one user to do updates, then update requests by all other users are rejected.

To allow a directory update request, the verification maintenance exit program only returns to the program that called it. Two program messages have been defined for the purpose of rejecting directory updates. 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:

CHKP0100 Format

Array for User-Defined Fields

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

CHKP0200 Format

CHKP0300 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. 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.

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

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. This field is used only if the user is an indirect user. The value specifies 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 personal. The values are 0 for no and 1 for yes.

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 field value are passed in the user-defined fields 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