Search System Directory (QOKSCHD) API


  Required Parameter Group:

1 Receiver variable Output Char(*)
2 Length of receiver variable Input Binary(4)
3 Format name of receiver variable Input Char(8)
4 Function Input Char(10)
5 Keep temporary resource indicator Input Char(1)
6 Request variable Input Char(*)
7 Length of request variable Input Binary(4)
8 Format name of request variable Input Char(8)
9 Error code I/O Char(*)

  Default Public Authority: *USE

  Threadsafe: No

The Search System Directory (QOKSCHD) API searches the system distribution directory and returns user information that matches the criteria input. It also is used to query fields in the directory. It is most useful when the system distribution directory is used as a repository for information about users, and can be used in a program to query this information.


Authorities and Locks

To search the system directory, *USE authority is required to the QOKSCHD API.


Required Parameter Group

Receiver variable
OUTPUT; CHAR(*)

The receiver variable that is to receive the information requested. You can specify the size of the area smaller than the format requested as long as you specify the length of the receiver variable correctly. As a result, the API returns only the data the area can hold.

Length of receiver variable
INPUT; BINARY(4)

The length of the receiver variable.

Format name of the receiver variable
INPUT; CHAR(8)

The format of the information returned. The possible format names are:

SRCV0100 System directory user information. See SRCV0100 Format for more information on the SRCV0100 format.
SRCV0200 System directory field names. See SRCV0200 Format for more information on the SRCV0200 format.

Function
INPUT; CHAR(10)

The function name of this request. The functions supported are:

*SEARCH Search the system directory
*CLEANUP Clean up resources (if temporary resources were kept on previous search requests). Note that for cleanup, the keep temporary resource indicator parameter has to be 0.

Keep temporary resource indicator
INPUT; CHAR(1)

An indicator of whether to keep or delete the temporary resource that the search uses for search requests. This temporary resource keeps files open and other relevant information between calls. Performance will be better if this is done and you do multiple searches. If this API is called and this indicator is set to keep temporary resources, the last call should have the Function parameter set to *CLEANUP to close files and delete the resources.

0 Do not keep the temporary resource (and close the files).
1 Keep the temporary resource (and the files open).

The resource handle stores the information about the open files. When the search API is called again and the files have been left open, the resource handle needs to be passed. The resource handle differs from the continuation handle in that the resource handle saves information about open files. The same resource handle can be used to request different kinds of searches. If you are doing multiple types of searches, you do not want to do Function of *CLEANUP between the calls to the QOKSCHD API. Pass the same resource handle for these calls and it will make the searches perform faster. The continuation handle is used to continue the search with the same criteria because there are more users that match the search criteria. The continuation handle is documented in Field Descriptions.

Request variable
INPUT; CHAR(*)

The request variable that is the input buffer that requests the type of search to do.

Length of request variable
INPUT; BINARY(4)

The length of the request variable.

Format name of request variable
INPUT; CHAR(8)

The information requested. The possible format names are:

SREQ0100 System directory user information. See SREQ0100 Format for more information on the SREQ0100 format.
SREQ0200 System directory field names. See SREQ0200 Format for more information on the SREQ0200 format.

Error code
I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.


SREQ0100 Format

The following table is the layout of the request variable, format SREQ0100, for requesting searches on the system directory user information.

Offset Type Field
Dec Hex
0 0 BINARY(4) CCSID of data input
4 4 BINARY(4) Character set of data input
8 8 BINARY(4) Code page of data input
12 C CHAR(4) Wildcard character
16 10 CHAR(1) Convert receiver data indicator
17 11 CHAR(1) Data to search
18 12 CHAR(1) Run verify indicator
19 13 CHAR(1) Continuation handle (input)
20 14 CHAR(16) Resource handle
36 24 CHAR(8) Format name of the search request array
44 2C BINARY(4) Offset to the search request array
48 30 BINARY(4) Number of elements in the search request array
52 34 CHAR(8) Format name of array of fields to return
60 3C BINARY(4) Offset to array of fields to return
64 40 BINARY(4) Number of elements in the fields to return array.
68 44 CHAR(8) Format name of array of users to return in the receiver variable
76 4C BINARY(4) Number of elements to return in the array of users to return
80 50 CHAR(8) Format name of array of fields for each user returned
88 58 CHAR(8) Format name of the order of field names to return
96 60 CHAR(1) Return fields in order specified option
97 61 CHAR(3) Reserved
    CHAR(*) Array of fields to return
    CHAR(*) Search request array


SREQ0101 Format

The following table is the search request array, format SREQ0101. This format name is used as input in the request variable, SREQ0100, in the field, format name of the search request array.

This is an array of search fields. There is a maximum of 100 entries.

The first element that is entered in the search request array is considered to be the key for the search. This is important for performance because the more distinct the key, the faster the search. Records will be returned in the order of the field specified as the key.

A performance consideration that should be made when choosing the key value for the value to match field is whether the field will contain a wildcard character. The search key should contain fields that occur a minimum number of times on the system. For this reason, it is more efficient to specify a key search value that does not contain wildcard characters. A wildcard character at the end of a search key value does not affect performance.

The search is an AND of all of the input fields. It will be a complete match or a generic match if a wildcard character is used as the last character of the field value.

Offset Type Field
Dec Hex
0 0 BINARY(4) Length of entry (including this field)
4 4 CHAR(1) Compare value
5 5 CHAR(10) Field name
15 F CHAR(7) Product ID
22 16 CHAR(1) Case of data input
23 17 CHAR(1) Reserved
24 18 BINARY(4) Length of value
28 1C CHAR(*) Value to match


SREQ0102 Format

The following table is the array of fields to return, format SREQ102. This format name is used as input in the request variable, SREQ0100, in the field, format name of array of fields to return.

The SREQ0102 format provides for selecting a user controlled set of system distribution directory fields.

Offset Type Field
Dec Hex
0 0 CHAR(10) Field name
10 A CHAR(7) Product ID


SREQ0103 Format

The following table is the array of special values representing the fields to be returned, format SREQ0103. This format name is used in the request variable, SREQ0100, in the field, format name of the array of fields to return.

The SREQ0103 format provides for selecting a predefined set of system distribution directory fields. The allowed special values are *SYSDIR, *ORNAME, and *SMTP. See Field Descriptions for a definition of the special value of fields to be returned field.

Offset Type Field
Dec Hex
0 0 CHAR(10) Special value of fields to be returned


SREQ0200 Format

The following table is the layout of the request variable, format SREQ0200. This request returns the fields defined in the system distribution directory.

Offset Type Field
Dec Hex
0 0 CHAR(1) Type of system distribution directory fields to return
1 1 CHAR(17) Continuation handle for directory fields (input)


SRCV0100 Format

The following table is the layout of the receiver variable, format SRCV0100. The receiver variable is the output buffer for the search results. This format defines the structure of the receiver variable.

Fields returned in the receiver variable will be in the order as documented in System directory field names. All of the fields with a product ID of *IBM will precede any fields with a product ID other than *IBM. Also, fields with a product ID of *IBM that appear in the array of fields to return more than once will be returned one time.

Offset Type Field
Dec Hex
0 0 BINARY(4) Number of bytes returned
4 4 BINARY(4) Offset to order of fields returned array
8 8 BINARY(4) Offset to the first array of users entry
12 C BINARY(4) Number of directory entries returned
16 10 CHAR(1) Continuation handle (output)
17 11 CHAR(16) Resource handle
    CHAR(*) Array of users that match the search criteria
    CHAR(*) Order of fields returned array


SRCV0101 Format

The following table is the structure of the array of users returned, format SRCV0101. This format name is specified in the request variable structure, SREQ0100, in the field, format name of array of users to return.

Offset Type Field
Dec Hex
0 0 BINARY(4) Length of data for this user
4 4 BINARY(4) Number of fields returned
8 8 CHAR(*) Array of fields for each user that was requested in the search request variable


SRCV0111 Format

The following table is the structure of the array of fields for each user returned, format SRCV0111. The format name is specified in the request variable structure, SREQ0100, in the field, format name of array of fields for each user returned. All fields requested are returned even if the fields are blank. The fields are returned in the order documented in System directory field names.

Offset Type Field
Dec Hex
0 0 CHAR(10) Field name
10 A CHAR(7) Product ID
17 11 CHAR(3) Reserved
20 14 BINARY(4) Character set or CCSID of the value
24 18 BINARY(4) Code page of the value
28 1C BINARY(4) Length of field value returned
32 20 CHAR(*) Field value


SRCV0112 Format

The following table is the structure of the array of fields for each user returned, format SRCV0112. The format name is specified in the request variable structure, SREQ0100, in the field, format name of array of fields for each user returned.

If you do not need user-defined fields or the field name and product ID, then request this format in SREQ0100 instead of SRCV0111, as it will save some overhead space. All fields requested are returned even if the fields are blank.

Format SRCV0120 tells the order in which the fields are returned. The order of the fields are always returned in the order as documented in System directory field names, but you may have a coding reason for needing to order the fields returned array.

Offset Type Field
Dec Hex
0 0 BINARY(4) Character set or CCSID of the value
4 4 BINARY(4) Code page of the value
8 8 BINARY(4) Length of field value returned
12 C CHAR(*) Field value


SRCV0120 Format

The following table is the structure of the order of fields returned array, format SRCV0120. The format name is specified in the request structure, SREQ0100, in the field, format name of order of field names array returned.

Offset Type Field
Dec Hex
0 0 CHAR(10) Field name
10 A CHAR(7) Product ID


SRCV0200 Format

The following table is the layout of the receiver variable, format SRCV0200. The receiver variable is the output buffer for the results from the system directory field name search request. The format name defines the structure of the receiver variable.

Offset Type Field
Dec Hex
0 0 BINARY(4) Number of directory field names returned
4 4 BINARY(4) Number of directory fields
8 8 BINARY(4) Offset to the array of directory field names
12 C CHAR(17) Continuation handle for directory fields (output)
    CHAR(*) Array of directory field names in the system distribution directory


Array of Directory Field Names

The following table is the structure of the field name array. This format contains the field names of the type that was requested in SREQ0200.

Offset Type Field
Dec Hex
0 0 CHAR(10) Directory field name
10 A CHAR(7) Product ID
17 11 CHAR(10) Directory field type
27 1B CHAR(1) Reserved
28 1C BINARY(4) Maximum field length


Field Descriptions

Array of directory field names in the system distribution directory. The array of fields that are returned as a result of the search request array. This array contains the directory field name, product ID, directory field type, and the maximum field length.

Array of fields for each user that was requested. The actual data for each field for the user returned as a result of the match. See either SRCV0111 Format, or SRCV0112 Format for the structure of this array.

Array of fields to return. The field names that the user wants returned in the receiver variable for each user found that matches the search criteria. See either SREQ0102 Format, or SREQ0103 Format for the structure of this array. There is no maximum number of elements.

Array of users that match the search criteria. The array of users that matches the search criteria on the request. See SRCV0101 Format for the structure of this array.

Case of data input. The case of the data input. The valid values are:

blank The data of all fields except two is searched without regard to the case of the data (case-insensitive search). The exceptions are the IBM fields SMTPUSRID and SMTPRTE, which are searched with regard to the case of the data (case-sensitive search).
0 The same as blank, the preceding value description.
1 The data of all fields is searched without regard to the case of the data (case-insensitive search).
Note: When you use the case of data input field for the SMTPUSRID or SMTPRTE field names, always qualify these field names with the product ID *IBM.

CCSID of data input. The CCSID of the data input or a special value. The special values are:

0 The default job CCSID will be used.
-1 The character set and code page will be used.
65535 The default job CCSID will be used.

Character set of data input. The character set of the data input. This field is used if the CCSID of data input is -1.

Character set or CCSID of the value. If the conversion of the data (convert receiver data indicator) was set to 0, this is the character set of the field value as it exists on the system. If the convert receiver indicator was set to 1, this is either a character set or CCSID depending on what was specified in the request variable for CCSID of data input. If the convert receiver data indicator was set to 2, this is the CCSID of the field value.

Code page of data input. The code page of the data input. This field is used if the CCSID of data input is -1.

Code page of the value. If the conversion of the data (convert receiver data indicator) was set to 0, this is the code page of the field value as it exists on the system. If the convert receiver indicator was set to 1, this is either a code page or CCSID depending on what was specified in the request variable for CCSID of data input. Otherwise, the code page is set to 0.

Compare value. The way to compare the value given with the field value in the system distribution directory entry. Only the value, 1 (equal), is currently supported.

Continuation handle (input). This allows you to continue to return data on a search if there was not enough space available to return all the entries that matched the search criteria on a previous search.

This value is 0 on the first search request. If you are continuing a search, this value needs to be set from the continuation handle (output) field.

The resource handle must be set if you are going to continue a search.

To use the continuation handle, you must keep the temporary resource space by setting the keep temporary resource indicator field to 1.

Continuation handle (output). An indicator for more directory entries available. The valid values are:

0 No
1 Yes

If this continuation handle is 0, either all the records that matched the search criteria were returned to this structure, or there were more records but the search files were not requested to be left open.

If the continuation handle is 1, there are more records available in the directory that match the search criteria, but there was no room available in the return structure. You may request more data by using this value in the request variable along with the resource handle.

Continuation handle for directory fields (input). Allows you to continue to return data on a search of directory fields if there was not enough space available to return all of the directory fields that matched the request.

This value is blank on the first request. If you are continuing a search, this value needs to be set from the continuation handle for directory fields (output) field.

Continuation handle for directory fields (output). Contains a value if there are more directory fields available for the search criteria requested. You may request more directory fields by using this value in the request variable field, continuation handle for directory fields (input).

Convert receiver data indicator. The option to convert the field values in the array of users returned for each user in the receiver variable.

The valid values are:

0 Do not convert receiver data. All data returned will be returned in the character set and code page as the data exists on the system. The character set and code page of the receiver data is in the array of fields for each user. See either SRCV0111 Format, or SRCV0112 Format for more information on the array of fields for each user.
1 Convert the receiver data. All data will be returned in the CCSID or character set and code page specified in the request variable.
2 Do not convert receiver data. All data will be returned as the data exists on the system, but the character set and code page will be converted to a CCSID tag. The CCSID of the receiver data is in the array of fields for each user. See either SRCV0111 Format, or SRCV0112 Format for more information on the array of fields for each user.

Data to search. The type of data to search on this system.

The valid values are:

0 Local data
1 All data on the system including shadowed data

Directory field name. Depending on the request in the SREQ0200 format, either an IBM-defined or a user-defined field. IBM® i system distribution directory field names have a product ID of *IBM. All other field names are for user-defined fields.

Directory field type. The following values can be returned for the field type and is meaningful only for user-defined fields:

*DATA User-defined field is for data.
*MSFSRVLVL User-defined field is for a mail service level.
*ADDRESS User-defined field is for an address.

See SRCV0200 Format for the field types for user-defined.

Field name. The field name can be an IBM-defined field name, or a user-defined field name. To determine the user-defined field names defined on the system, either use the Change System Directory Attributes (CHGSYSDIRA) command with F4, or retrieve the fields using the SREQ0200 format.

The following is a list of predefined field names that can be specified in the field name field of the array of search fields and the array of fields to return.

Notes:

  1. There is a maximum of 512 bytes for user-defined fields.

  2. There is a performance impact when a mixture of system directory field names, SMTP field names, and user-defined fields are specified in the search request array.

System directory field names

Note: This is the order in which the field names are returned when the return fields in order specified option is not 1 (0 is the default). The field is truncated so that ending blanks are not returned. This group of field names is the *SYSDIR group when the SREQ0103 format is used. See SREQ0103 Format for more information on the SREQ0103 format.

USER User profile. The maximum length is 10.
INDUSR

Indirect user. The maximum length is 1. This only applies for local directory entries. The valid values are:

1 Yes
0 No
PRTCOVER

Print cover page. The maximum length is 1. This only applies for local directory entries. The valid values are:

1 Yes
0 No
Note: The PRTCOVER field can only be returned. It cannot be searched on.
NFYMAIL Mail notification. The maximum length is 3. The first byte value represents:
1 Specific types of mail
2 All mail
3 No mail

For specific types of mail:

  • The second byte represents priority, private, and important mail. The valid values are:

    1 Yes
    0 No

  • The third byte represents messages. The valid values are:

    1 Yes
    0 No

Note: The NFYMAIL field can only be returned. It cannot be searched on.

USRID User ID (DEN). The maximum length is 8.
LCLDTA Local data indicator. The maximum length is 1. The valid values are:

0 Local
1 Shadowed
This indicates where this user was created (origination). If the user was created on this system, this indicator is 0. If the user was shadowed from another system, this indicator is 1. If a remote user was created on this system, this indicator is 0.
USRADDR User address (DGN). The maximum length is 8.
SYSNAME System name (REN). The maximum length is 8.
SYSGRP System group (RGN). The maximum length is 8.
USRD User description.
Each description field has a maximum length of 50. If a user has only one description, it will be returned trimmed. If a user has more than one description, all of the descriptions will be returned in this field, with each description using a maximum of 50 characters. The length of the value will tell how long the field is and, in effect, how many descriptions exist. For example, if a user has 3 descriptions, the length of value field will be 150 (50 characters for each description).
Note: When there is more than one description, blank truncation is not performed.
FSTNAM First name. The maximum length is 20.
PREFNAM Preferred name. The maximum length is 20.
MIDNAM Middle name. The maximum length is 20.
LSTNAM Last name. The maximum length is 40.
FSTPREFNAM First or preferred name. The maximum length is 20.
Note: This is an input-only field. It is not output.
FULNAM Full name. The maximum length is 50.
TITLE Job title. The maximum length is 40.
CMPNY Company. The maximum length of is 50.
DEPT Department. The maximum length is 10.
NETUSRID Network user ID. The maximum length is 47.
TELNBR1 Telephone number 1. The maximum length is 26.
TELNBR2 Telephone number 2. The maximum length is 26.
FAXTELNBR Fax telephone number. The maximum length is 26.
LOC Location. The maximum length is 40.
BLDG Building. The maximum length is 20.
OFC Office. The maximum length is 16.
ADDR1 Mailing address line 1. The maximum length is 40.
ADDR2 Mailing address line 2. The maximum length is 40.
ADDR3 Mailing address line 3. The maximum length is 40.
ADDR4 Mailing address line 4. The maximum length is 40.
CCMAILADR cc:Mail** address. The maximum length is 255.
CCMAILCMT cc:Mail comment. The maximum length is 126.
TEXT Text. The maximum length is 50.
MSFSRVLVL Mail server framework service level.

The field for the mail service level. When requesting this field to be searched on, supply only the field name and product ID with the field name in the first 10 bytes and the product ID in the last 7 bytes. When this field is returned in SRCV0111 or SRCV0112, the mail service level value contains the following structure:

  • CHAR(10)-Field name

    The field name can be a special value or a user-defined field name. The special values are:

    *USRIDX User index
    *SYSMS System message store
    *DOMINO Lotus® Domino® mail database

  • CHAR(7)-Product ID

    The product ID of a user-defined field. *NONE indicates that there is no product ID for the user-defined field.

  • BINARY(4)-Length of mail service level

    If the value is 0, then the field did not exist in the directory, the field was blank, or the field name is a special value of *USRIDX, *SYSMS, or *DOMINO.

  • CHAR(*)-The value of the mail service level field and product ID. This value will be blank for *USRIDX, *SYSMS, and *DOMINO. For user-defined fields, it is the value of that field in the system distribution directory.

    The maximum size is 512.
See either SRCV0111 Format or SRCV0112 Format for more information on either the SRCV0111 format or the SRCV0112 format.
PREFADR Preferred address.
The field for the preferred address. When requesting this field to be searched on, supply only the field name and product ID, with the field name in the first 10 bytes and the product ID in the last 7 bytes. When this field is returned in SRCV0111 or SRCV0112, the preferred address value contains the following structure:
  • CHAR(10)-Field name

    The field name can be a special value, a user-defined field name, or an IBM-defined field name. The special values are:

    *USRID User ID/address
    *ORNAME X.400 O/R name
    *SMTP SMTP name

  • CHAR(7)-Product ID

    The product ID of the field. *IBM i ndicates an IBM-defined field name. *NONE indicates that there is no product ID for the user-defined field.

  • CHAR(4)-Address type value

  • CHAR(8)-Address type name

  • BINARY(4)-Length of preferred address value

    If the value is 0, either the field did not exist in the directory or the field was blank.

  • CHAR(*)-The value of the preferred address field and the product ID.

    The following is the structure of this field based on the field name value:

    *USRID User ID (DEN) in the first 8 bytes, user address (DGN) in the second 8 bytes, system name (REN) in the third 8 bytes, and system group (RGN) in the last 8 bytes.
    *ORNAME X.400 O/R name is formatted from the X.400 O/R name fields that exist for this user. See the IBM-defined field ORNAME for the structure of this field. The maximum size for this field is 909 bytes.
    *SMTP The maximum size of the SMTP user ID is 24 bytes. The maximum size changes to 64 bytes if SMTP names are converted using the Convert Name SMTP (CVTNAMSMTP) command. You can check if the CVTNAMSMTP command has been run with the WRKNAMSMTP command. You get error TCP9610 if CVTNAMSTMP has been run. The first part of the *SMTP structure does not change. The SMTP user ID is the first 24 bytes followed by either the SMTP domain or route for 256 bytes. To support the new SMTP user ID length, 64 bytes follow the SMTP domain or route portion. Both the old SMTP user ID and the new SMTP user ID contain the SMTP user ID except when the SMTP user ID has more than 24 bytes. In this case the old SMTP user ID is blank.
    IBM-defined or user-defined field The contents of the field will be the value of the field in the system distribution directory. The maximum size is 512 bytes.

    See either SRCV0111 Format or SRCV0112 Format for more information on either the SRCV0111 format or the SRCV0112 format.
ALWSYNC Allow synchronization. The maximum length is 1.
This field indicates whether the user's entry should be synchronized with directories other than the System Distribution Directory. The valid values are:
1 Yes
0 No
DLOOWN DLO owner. The maximum length is 10.
This field indicates if the user profile or the group profile will be assigned the ownership of the document library objects (DLOs) for this directory entry. The valid values are:
*USRPRF User profile
*GRPPRF Group profile
MGRCODE Manager code. The maximum length is 1.
This field indicates whether the user is a manager. The valid values are:
1 Yes
0 No
ORNAME X.400 O/R field names: These fields are the group of fields for the *ORNAME special value in the SREQ0103 format.
The paper representation of the X.400 O/R name. This field cannot be searched on, but it can be returned in the receiver variable.
The string starts with X.400 and is followed by the following formats:
  • Non-DDA (domain-defined attributes) are represented as: 
    <attribute type>=<attribute value>
  • DDA (domain-defined attributes) are represented as: 
    DDA.<DDA type>=<DDA value>
Abbreviations for the attributes in an X.400 O/R name are:
C Country or region name
A Administration Domain (ADMD) name
P Private Management Domain (PRMD) name
O Organization name
OU Organizational unit name
OU1 Organizational unit 1 name
OU2 Organizational unit 2 name
OU3 Organizational unit 3 name
OU4 Organizational unit 4 name
S Surname
G Given name
I Initials
GQ Generation qualifier
DDA Domain-defined attribute
When an O/R name contains only one organization unit attribute, the type OU is used. When an address contains more than one organization unit attribute, the types OU1, OU2, OU3, and OU4 are used. OU1 is the most significant designator in the organization's hierarchy.
Every attribute, except the last one is followed by a semicolon.
An example paper representation of an X.400 O/R name is:
X.400 C=US;A=ANYMAIL;P=XYZ;O=CLEANING COMPANY;
OU=SALES DEPT;S=DOE;G=John;I=JA;DDA.ID=123999

If each X.400 field is returned separately, then:

  • COUNTRY would be US
  • ADMD would be ANYMAIL
  • PRMD would be XYZ
  • ORG would be CLEANING COMPANY
  • One of the organizational units would be SALES DEPT
  • SURNAM would be DOE
  • GIVENNAM would be JOHN
  • INITIALS would be JA
  • One of the domain-defined attribute types fields would be ID, and the value of that field would be 123999.
COUNTRY Country or region. The maximum length is 3.
ADMD Administration domain. The maximum length is 16.
PRMD Private management domain. The maximum length is 16.
ORG Organization. The maximum length is 64.
SURNAM Surname. The maximum length is 40.
GIVENNAM Given name. The maximum length is 16.
INITIALS Initials. The maximum length is 5.
GENQUAL Generation qualifier. The maximum length is 3.
ORGUNIT1 Organization unit 1. The maximum length is 32.
ORGUNIT2 Organization unit 2. The maximum length is 32.
ORGUNIT3 Organization unit 3. The maximum length is 32.
ORGUNIT4 Organization unit 4. The maximum length is 32.
DMNDFNAT1 Domain-defined attribute type 1. The maximum length is 8.
DMNDFNAV1 Domain-defined attribute value 1. The maximum length is 128.
DMNDFNAT2 Domain-defined attribute type 2. The maximum length is 8
DMNDFNAV2 Domain-defined attribute value 2. The maximum length is 128.
DMNDFNAT3 Domain-defined attribute type 3. The maximum length is 8.
DMNDFNAV3 Domain-defined attribute value 3. The maximum length is 128.
DMNDFNAT4 Domain-defined attribute type 4. The maximum length is 8.
DMNDFNAV4 Domain-defined attribute value 4. The maximum length is 128.

See SREQ0103 Format for more information on the SREQ0103 format.

Simple Mail Transfer Protocol (SMTP) field names:

These fields are the group of fields for the *SMTP special value in the SREQ0103 format.

SMTPUSRID SMTP user ID. The maximum length is 24.

However, the maximum length changes to 64 if the SMTP names are converted using the CVTNAMSMTP command.

Note: This field is a case-sensitive field.
SMTPDMN SMTP domain.

Either the SMTP domain or the SMTP route can exist, not both. The maximum length is 256.
SMTPRTE SMTP route.

Either the SMTP domain or the SMTP route can exist, not both. The maximum length is 256.

See SREQ0103 Format for more information on the SREQ0103 format.

Field value. The value of the field.

Format name of array of fields for each user returned. The format name of the array of fields for each user returned. This is the specific structure for each user in either the SRCV0111 format or the SRCV0112 format. See either SRCV0111 Format, or SRCV0112 Format for more information on the array of fields for each user.

Format name of array of fields to return. The format name of the array of fields to return so that the fields of each user found matching the search criteria that is needed is known. The possible values are SREQ0102 and SREQ0103. See SREQ0102 Format, or SREQ0103 Format for more information on the array of fields to return for each user.

Format name of array of users to return in the receiver variable. The format name of the array of users to return after the search is complete. This is so the format to return the search results is known. The possible value is SRCV0101. See SRCV0101 Format for more information on the array of users returned.

Format name of order of field names array returned. The format name of the order of field names to be returned. Possible values are blank and SRCV0120. If the value is blank, the order of the field names array is not returned. The order of field names array is not returned if user-defined fields are requested as only the user-defined fields that exist for each user is returned and are not in any specified order.

Format name of the search request array. The format name of the search request array so that the format of the search request is known. The possible value is SREQ0101. See SREQ0101 Format for more information on the array of search fields.

Length of data for this user. The length of both the header information and the fields that are returned for the user.

Length of entry (including this field). The length of the entry in the array of all of the fields including this field.

Length of field value returned. The length, in bytes, of the field value. If this value is 0, there is no data in the field.

Length of value. If the length of the value is 0, this field is ignored on the search request. There must be at least one field in the search request array with a length of value greater than 0 and the value is not blank spaces.

The maximum length is 512.

Maximum field length. The maximum length of this directory field.

Number of bytes returned. The length of the data returned. If the receiver variable is not large enough to hold all of the data available, only the data that will fit in the space available is returned and this value will be less than the bytes available.

Number of directory entries returned. This is the number of directory entries that are returned in SRCV0101. It is the number of directory entries found as a result of the search request. If more directory entries are available but there was not enough space available in the SRCV0101 structure, the continuation handle will be 1. If all of the entries are returned, the continuation handle will be 0.

Number of directory field names returned. The number of elements in the field name array.

Number of directory fields. The total number of directory fields for the type of fields requested. If the continuation handler for directory fields is not blank, then there are more fields available.

Number of elements in the fields to return array. The number of fields to be returned for each user. These fields are returned in the receiver variable.

Number of elements in the search request array. The number of fields and values to match for the search request. The maximum number of elements allowed is 100.

Number of elements to return in the array of users to return. The number that should be used to return a fixed number of elements on a call to the API. The number of elements returned will be less than or equal to the number specified here. If the number returned is less than the number specified, then either all of the elements that met the criteria were returned or the size of the receiver variable could not hold the number specified.

The continuation handle will be set if more data exists after returning the number of elements specified for this parameter.

If this number is 0, the maximum number of elements possible is returned.

This field could be used to limit the run time of the API. For instance, it could be used to retrieve only the number of users needed to file a subfile page.

Number of fields returned. The number of fields returned for the user. Fields are returned even if blank.

Offset to array of fields to return. The offset, in bytes, to the array of fields to return.

Offset to order of fields returned array. The offset, in bytes, to the order of fields returned array. The value can be 0 if either the order of the fields is not needed or the user-defined fields are returned. This is requested in the SREQ0100 format. See SREQ0100 Format for more information on the offset to order of fields returned array.

Offset to the array of directory field names. The offset, in bytes, to the array of directory field names at the bottom of the SRCV0200 structure.

Offset to the first array of users entry. The offset, in bytes, to the array of users in the SRCV0100 structure. This is the offset to the first entry in the array of users that are returned that match the search criteria.

Offset to the search request array. The offset, in bytes, to the search request array in the SREQ0100 format. See SREQ0100 Format for more information on the offset to the search request array.

Order of fields returned array. The array of fields names of the order of the fields in the array of fields for each user (in either the SRCV0111 format or the SRCV0112 format) that is returned. For more information see SRCV0120 Format.

Product ID. A special value of *IBM i ndicates that the field is an IBM i system distribution directory field. A value of blank spaces indicates that there is no product ID associated with the field name.

An error will be signaled if:

Reserved. This is used to align the character set of the value field.

Resource handle. This value needs to be set from the output resource handle variable that was used as output in the receiver buffer from a previous search.

On the first call, this value needs to be blank.

To use the resource handle, you must specify to keep the temporary resources option on the previous search.

If you are continuing a search, the resource handle must be set from the output resource handle variable from a previous search of the same criteria.

If you are not continuing a search, the resource handle can be reused and the continuation handle will be set to 0. This will reuse the open files and temporary work areas.

If a resource handle is reused on another search, a continuation of a previous search is attempted using the same resource handle and the continuation is no longer valid for the previous search.

Return fields in order specified option. The option to return the fields in the order specified in the array of fields to return format. See SREQ0102 Format for the structure of this array. The valid values are:

0 Return fields in the predefined order as specified in the Field name field description in Field name. This is the default.
1 Return the fields as specified in SREQ0102 Format. This option may give slower response on the search request. SRCV0120 Format and SREQ0103 Format cannot be used with this option.

Run verify indicator. The option to verify the input parameters. Running the verification process has the potential to increase the time it takes to run a search. If the verification flag is set off and no valid data is passed as input, unpredictable results may occur.

The purpose of this indicator is so verification does not have to be run when continuing the return of data, or when a search request is repeated.

The valid values are:

0 Do not run the verification process.
1 Run the verification process.

For the first search request, it is recommended that this value be 1.

Search request array. An array of search fields. There is a maximum of 100 entries. See SREQ0101 Format for the structure of this array.

The first element that is entered in the search request array is considered to be the key for the search. This is important for performance because the more distinct the key, the faster the search. Records will be returned in the order of the field specified as the key.

A performance consideration that should be made when choosing the key value is a value to match that contains wildcard characters. The search key should contain fields that occur a minimum number of times on the system. For this reason, it is more efficient to specify a key search value that does not contain wildcards.

The search is an AND of all the input fields. It will be a full match or a generic match if a wildcard character is used as the last character of the field value.

Special value of fields to be returned. This field selects a group of fields depending on the special value. The order of the field names returned in the SRCV0101 format is returned in the format, SRCV0120. The SRCV0120 format is optional. It is optional because the order of the field names is always the same, but it is given so you can programmatically find the order of fields returned.

The special values are:

*SYSDIR Returns all of the system distribution directory fields except the X.400 O/R name fields, the SMTP name fields, and the user-defined fields.
*ORNAME Returns the X.400 O/R name fields.
*SMTP Returns the SMTP name fields.

Type of system distribution directory fields to return. The indicator for the type of system distribution directory fields that are defined on the system to be returned.

The possible values are:

0 All system distribution directory fields, including both IBM-defined fields and user-defined fields.
1 IBM-defined system distribution directory fields.
2 User-defined system distribution directory fields.

Value to match. If a blank value is encountered, the API will ignore the field.

All values entered are monocased and converted to a common character set and code page before the search takes place. Therefore, the uppercase and lowercase characters are not distinguished, except for the SMTP user ID where it is distinguished. However, if the SMTP names are converted (CVTNAMSMTP command), the SMTP user ID is not distinguished because the SMTP fields are converted into user-defined fields.

A maximum of one wildcard character is allowed in the value to match field.

Wildcard character. The wildcard character indicates the wildcard character used for wildcard searches. An example of a wildcard character is an asterisk (*); however, the wildcard character can be anything you specify. If the character is encountered in the values to search on, that value indicates a wildcard search. This wildcard character will be in the CCSID or character set and code page (CHRID) that is used as input.

The wildcard character represents any number of characters (not just one character) in the search value to match. If a blank is used for a wildcard value, the API will not check for wildcards and the value will be checked specifically as input.

Note: The wildcard character field is a CHAR(4) because of DBCS and SBCS. In addition, for SBCS the wildcard character field is left-adjusted.


Error Messages

Message ID Error Message Text
CPF3C90 E Literal value cannot be changed.
CPF3CF1 E Error code parameter not valid.
CPF9A8C E Error occurred with QOKSCHD API. Reason code &1.
CPF9845 E Error occurred while opening file &1.
CPF9846 E Error while processing file &1 in library &2.
CPF9847 E Error occurred while closing file &1 in library &2.
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3.
CPI9A9C I Search data does not exist.

API introduced: V3R1

[ Back to top | Office APIs | APIs by category ]