| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | List information | Output | Char(80) |
| 4 | Number of records to return | Input | Binary(4) |
| 5 | Format name | Input | Char(8) |
| 6 | Profile type | Input | Char(10) |
| 7 | Profile name | Input | Char(10) |
| 8 | Windows® domain name qualifier | Input | Char(*) |
| 9 | Length of Windows domain name qualifier | Input | Binary(4) |
| 10 | Windows server name qualifier | Input | Char(*) |
| 11 | Length of Windows server name qualifier | Input | Binary(4) |
| 12 | Error code | I/O | Char(*) |
The Open List Network Server Users (QFPADOLU) API generates a list of Windows domains and servers, and the associated profiles enrolled to them in the network. The list will be returned grouped by domain or server name, and within the domain or server, by profile name.
The receiver variable that receives the information requested. You can specify the size of the area to be smaller than the format requested as long as you specify the length parameter correctly. As a result, the API returns only the data the area can hold.
The length of the receiver variable provided. The length of the receiver variable parameter may be specified up to the size of the receiver variable specified in the user program. If the length of the receiver variable parameter specified is larger than the allocated size of the receiver variable specified in the user program, the results are not predictable. The minimum length is 0 bytes.
Information about the list created by this program. For a description of the layout of this parameter, see Format of List Information.
The number of records in the list to put into the receiver variable. The value must be 0 or greater.
The format of the information returned. You must use the following format name:
| DOLU0100 | Returns records for user and associated group records, or records for group and associated user records. |
| DOLU0150 | Returns records for user and associated group
records, or records for group and associated user records.
The difference between this format and format
DOLU0100 is that this format includes the Windows user name in user records.
Note: The Windows user name could be different than the enrolled IBM® i user name if Enterprise Identity Mapping (EIM) is being used for the enrolled user. |
| DOLU0200 | Returns a short version of
records for user and associated group records,
or records for group and associated user records.
Note: This format is faster than formats DOLU0100 and DOLU0150. |
Whether profile information returned is on a user profile or group profile basis. Values can be:
| *USER | Retrieve information about profiles defined as users on the selected domains or servers. The group information for each group of which the user is a member is also returned. |
| *GROUP | Retrieve information about profiles defined as groups on the selected domains or servers. The users belonging to each group are also returned. |
| *USERBASIC | Retrieve information about profiles defined as
users on the selected domains or servers. All user records are returned, without the
associated group records.
Note: This option is faster than the *USER option. |
| *GRPBASIC | Retrieve information about profiles defined as groups
on the selected domains or servers. All group records are returned, without the
associated user records.
Note: This option is faster than the *GROUP option. |
| *ALL | Retrieve both group and user information for a single domain or server. All group records are returned first, without the associated user records. Then all user records are returned, without the associated group records. The records will be returned in the *USER format if a specific user profile is requested. |
| *NONE | Retrieve information for domains and servers, but not for users or groups. Records for domains are returned first, followed by records for servers. No user or group records are returned. |
The names of the profiles to be included in the list. A specific profile can be specified, or the profile name can be specified with a generic name (such as 'USER*') to retrieve a list of all profiles starting with the specified letters. Allowable values are:
| *ALL | Information about all profiles |
| Profile name | Information about the specified profile name record only. |
| Generic profile name* | Information about profiles matching the generic profile name string. |
Usage note: Avoid the use of characters '5B'X, '7B'X, and '7C'X (CCSID 37 characters '$', '#', and '@', respectively) in profile names.
The names of the Windows domains to be included in the list. A specific domain can be specified, or the domain name can be specified with a generic name (such as 'DMN*') to retrieve a list of all domains starting with the specified letters. Allowable values are:
| *ALL | All domains with which users are enrolled are to be included in the list. |
| *NONE | No domains are to be included in the list. |
| *NWSA | Only the system default domains shown on the Display Network Server Attributes (DSPNWSA) command are to be included in the list. |
| Domain name | Information about the specified domain only. |
| Generic domain name* | Information about domains matching the generic domain name string. |
The length of the Windows domain name qualifier.
The names of the Windows servers to be included in the list. A specific server can be specified, or the server name can be specified with a generic name (such as 'SRV*') to retrieve a list of all servers starting with the specified letters. Allowable values are:
| *ALL | All servers with which users are enrolled are to be included in the list. |
| *NONE | No servers are to be included in the list. |
| *NWSA | Only the system default servers shown on the Display Network Server Attributes (DSPNWSA) command are to be included in the list. |
| Server name | Information about the specified server only. |
| Generic server name* | Information about servers matching the generic server name string. |
The length of the Windows server name qualifier.
The structure in which to return error information. For the format of the structure, see Error code parameter. If this parameter is omitted, diagnostic and escape messages are issued to the application.
The list data returned for the DOLU0100, DOLU0150 and DOLU0200 formats contain three types of records:
| Server records | Contain information about a domain or server. |
| User records | Contain information about a user profile. |
| Group records | Contain information about a group profile. |
If the profile type requested is *USER, then records are returned as follows:
If the profile type requested is *GROUP, then records are returned as follows:
If the profile type requested is *USERBASIC, then records are returned as follows:
If the profile type requested is *GRPBASIC, then records are returned as follows:
If the profile type requested is *ALL, then records are returned as follows:
If the profile type requested is *NONE, then records are returned as follows:
The following tables describe the order and format of the data for each record format in the list. For detailed descriptions of the fields in the tables, see Field Descriptions.
The following table defines the structure of each record returned for format DOLU0100.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Displacement to next record |
| 4 | 4 | BINARY(4) | Length of record |
| 8 | 8 | BINARY(4) | Record type |
| 12 | C | BINARY(4) | Number records to next record same level |
| 16 | 10 | BINARY(4) | Number records next lower level |
| 20 | 14 | BINARY(4) | Displacement to name |
| 24 | 18 | BINARY(4) | Length of name |
| 28 | 1C | BINARY(4) | Server type |
| 32 | 20 | BINARY(4) | Enrollment reason |
| 36 | 24 | BINARY(4) | Member enrollment |
| 40 | 28 | BINARY(4) | Profile status |
| 44 | 2C | CHAR(50) | Profile description |
| 94 | 5E | CHAR(6) | Enrollment error code |
| 100 | 64 | CHAR(10) | Message file |
| 110 | 6E | CHAR(10) | Primary message file library |
| 120 | 78 | CHAR(7) | Message ID |
| See note | See note | CHAR(*) | Name |
| Note: The displacement and length for the name are specified in the corresponding displacement and length variables. | |||
The following table defines the structure of each record returned for format DOLU0150.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Displacement to next record |
| 4 | 4 | BINARY(4) | Length of record |
| 8 | 8 | BINARY(4) | Record type |
| 12 | C | BINARY(4) | Number records to next record same level |
| 16 | 10 | BINARY(4) | Number records next lower level |
| 20 | 14 | BINARY(4) | Displacement to name |
| 24 | 18 | BINARY(4) | Length of name |
| 28 | 1C | BINARY(4) | Server type |
| 32 | 20 | BINARY(4) | Enrollment reason |
| 36 | 24 | BINARY(4) | Member enrollment |
| 40 | 28 | BINARY(4) | Profile status |
| 44 | 2C | CHAR(50) | Profile description |
| 94 | 5E | CHAR(6) | Enrollment error code |
| 100 | 64 | CHAR(10) | Message file |
| 110 | 6E | CHAR(10) | Primary message file library |
| 120 | 78 | CHAR(7) | Message ID |
| 127 | 7F | CHAR(1) | Reserved |
| 128 | 80 | BINARY(4) | Displacement to Windows name |
| 132 | 84 | BINARY(4) | Length of Windows name |
| See note | See note | CHAR(*) | Name |
| See note | See note | CHAR(*) | Windows name |
| Note: The displacement and length for the name and Windows name are specified in the corresponding displacement and length variables. | |||
The following table defines the structure of each record returned for format DOLU0200.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Displacement to next record |
| 4 | 4 | BINARY(4) | Length of record |
| 8 | 8 | BINARY(4) | Record type |
| 12 | C | BINARY(4) | Number records to next record same level |
| 16 | 10 | BINARY(4) | Number records next lower level |
| 20 | 14 | BINARY(4) | Displacement to name |
| 24 | 18 | BINARY(4) | Length of name |
| 28 | 1C | BINARY(4) | Server type |
| 32 | 20 | BINARY(4) | Enrollment reason |
| 36 | 24 | BINARY(4) | Member enrollment |
| 40 | 28 | BINARY(4) | Profile status |
| See note | See note | CHAR(*) | Name |
| Note: The displacement and length for the name are specified in the corresponding displacement and length variables. | |||
Displacement to name. The displacement in bytes from the beginning of the record to the name.
Displacement to next record. The displacement in bytes from the beginning of the record to the next record. If this is the last record, this value will be zero.
Displacement to Windows name. The displacement in bytes from the beginning of the record to the Windows name. This field is set to zero if the enrolled IBM i user name and the Windows user name are the same.
Enrollment error code. This value is only specified if the record is a user or group type record. Normally it is blank, but it will be set to the last enrollment error code that was received while attempting to create, delete, or update a user on a server. This should only be non-blank if the profile is in one of the recovery or delete statuses.
The enrollment error codes are:
| 239 | User enrollment failed because the password can not be retrieved. |
| 240 | Password not available for user enrollment create. |
| 241 | Invalid Windows profile name. |
| 245 | User enrollment failed because the password can not be retrieved. |
| 247 | Update of group failed because domain group type cannot be changed. |
| 248 | Unable to delete user from Windows domain or server. |
| 249 | Unable to delete group from Windows domain or server. |
| 260 | User not created because specified name is a reserved name in Windows. |
| 261 | Group not created because specified name is a reserved name in Windows. |
| 262 | User not deleted because specified name is a reserved name in Windows. |
| 263 | Group not deleted because specified name is a reserved name in Windows. |
| 264 | Enrollment request cannot complete because domain controller not found. |
| 265 | User not created because user template not found. |
| 266 | User not created because user name already exists. |
| 267 | Create or update of user failed for an unknown reason. |
| 268 | Create or update of group failed for an unknown reason. |
| 269 | User was created or updated successfully on Windows. The user, however, was not added to the AS400_Users group on Windows. |
| 270 | A request to delete the user from Windows failed because the user is a member of the AS400_Permanent_Users group on Windows. |
| 271 | A request to delete the group from Windows failed because the group is not empty on Windows. |
| 272 | Add user to an enrolled group failed on Windows. |
| 273 | Create failed because user or group already exists on Windows. |
| 274 | Add user to a group listed in the user template failed on Windows. |
| 275 | User successfully enrolled, but not marked as enrolled on Windows. |
| 276 | Group successfully enrolled, but not marked as enrolled on Windows. |
| 277 | User unenrolled, but still marked as an enrolled user on Windows. |
| 278 | Group unenrolled, but still marked as an enrolled group on Windows. |
| 279 | Create or update of user failed on Windows; password not valid. |
| 280 | Create or update user failed. A network server description (NWSD) associated with the Windows domain or server must be varied on. |
| 281 | Enrollment request to local server not valid on domain controller. |
| 282 | Service not authorized to manage domain groups and users on the domain. |
| 296 | Unable to create home directory for user. |
| 452 | More than one EIM identifier defined for IBM i user. |
| 454 | More than one EIM Windows user profile source association defined. |
| 459 | EIM processing error for user. |
Enrollment reason. This value is specified only if the record is a user type record. It indicates why a profile has been selected for enrollment:
| 1 | The user is a member of a group that has enrolled members. |
| 2 | The user is specifically enrolled to a domain or server. |
Length of name. The length of the name.
Length of record. The length of the data for the current record.
Length of Windows name. The length of the Windows name. This field is set to zero if the enrolled IBM i user name and the Windows user name are the same.
Member enrollment. This value is specified only if the record is a group type record. It indicates whether group members are enrolled.
| 0 | Group members are not enrolled. |
| 1 | Group members are enrolled. |
Message file. This value is specified only if the record is a user or group type record. The message file that contains the message ID for a message that describes the enrollment error code for a failed enrollment operation.
Message ID. This value is specified only if the record is a user or group type record. The message that describes the enrollment error code for a failed enrollment operation.
Name. The name of a Windows domain or server, or an enrolled IBM i user or group, depending on the record type.
Usage note: Avoid the use of characters '5B'X, '7B'X, and '7C'X (CCSID 37 characters '$', '#', and '@', respectively) in user and group profile names.
Number records next lower level. The number of sub-records that exist for a record. For example, if the current record is a group record, followed by three user records for that group, then the number of records next lower level would be three.
Number records to next record same level. The number of records to traverse to locate the next record of the same type (server, user, or group). If there are no more records of the same type, this value is zero.
For example, if the current record is a group record, followed by three user records for the group, followed by another group record, then the number of records to next record same level would be four.
Primary message file library. The library that contains the message file. This value is specified only if the record is a user or group type record.
Note: If the message text is retrieved, use *LIBL (library list) as the message file library so that the correct national language version of the message text is retrieved. If the message file returned by this API is not in any of libraries in the library list, then message retrieval operation will fail with message CPF2407 "Message file x in *LIBL not found." If this occurs, then attempt the retrieval operation again, using the primary message file library that is returned by this API.
Profile description. The description for this profile. This value is specified only if the record is a user or group type record.
Profile status. The current status of a user or group on a server. This value is specified only if the record is a user or group type record. The following values represent the various status values:
| 1 | Profile is enrolled on the server (up-to-date). |
| 2 | Enrollment pending on the server. |
| 3 | Enrollment retry pending on the server. |
| 4 | Enrollment failed. |
| 5 | Unenrollment pending on the server. |
| 6 | Unenrollment retry pending on the server. |
| 7 | Unenrollment failed. |
| 8 | Only group members enrolled. The users in the group are enrolled to the servers, but the group itself is not enrolled to the servers. This status is valid only for a group. |
| 9 | Profile is enrolled on the server using the IBM i profile name. An error occured when looking up the Windows user name using Enterprise Identity Mapping (EIM). |
Record type. The record type for a record. The values that represent the various types follow:
| 1 | A server type record. |
| 2 | A user type record. |
| 3 | A group type record. |
Note: The first record in the list is always a server type record.
Reserved. Reserved area for 4-byte boundary alignment.
Server type. The type of server represented by the record. This value is specified only if the record is a server type record.
| 1 | A Windows domain. |
| 2 | A Windows server. |
Windows name. The name of the user on Windows. This field is not returned if the enrolled IBM i user name and the Windows user name are the same.
Note: The Windows user name could be different than the enrolled IBM i user name if Enterprise Identity Mapping (EIM) is used for the enrolled user.
The following table shows the format of the list information parameter. For detailed descriptions of the field in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Total records |
| 4 | 4 | BINARY(4) | Records returned |
| 8 | 8 | CHAR(4) | Request handle |
| 12 | C | BINARY(4) | Record length |
| 16 | 10 | CHAR(1) | Information complete indicator |
| 17 | 11 | CHAR(13) | Date and time created |
| 30 | 1E | CHAR(1) | List status indicator |
| 31 | 1F | CHAR(1) | Reserved |
| 32 | 20 | BINARY(4) | Length of information returned |
| 36 | 24 | BINARY(4) | First record in buffer |
| 40 | 28 | CHAR(40) | Reserved |
Date and time created. The date and time the list was created. The 13 characters are:
| 11 | Century, where 0 indicates years 19xx and 1 indicates years 20xx. |
| 2-7 | The date, in YYMMDD (year, month, day) format. |
| 8-13 | The time of day, in HHMMSS (hours, minutes, seconds) format. |
First record in buffer. The number of the first record in the receiver variable.
Information complete indicator. Whether all information requested has been supplied.
| I | Incomplete information. An interruption caused the list to contain incomplete information about a buffer or buffers. |
| P | Partial and accurate information. Partial information is returned when the maximum space was used and not all of the buffers requested were read. |
| C | Complete and accurate information. All the buffers requested were read and returned. |
Length of information returned. The size, in bytes, of the information returned in the receiver variable.
List status indicator. The status of the list building. The indicators are:
| 0 | The list building is pending. |
| 1 | The list is in the process of being built. |
| 2 | The list has been built completely. |
| 3 | An error occurred while building the list. The next call to QGYGTLE will cause the error to be signalled to the caller of QGYGTLE. |
Record length. The length of each record of information returned. For variable length records, this value is set to 0. For variable length records, you can obtain the length of individual records from the records themselves.
Records returned. The number of records returned in the receiver variable. This is the smallest of the following values:
Request handle. The handle of the request that can be used for subsequent requests of information from the list. The handle is valid until the Close List (QGYCLST) API is called to close the list or until the job ends.
Note: This field should be treated as a hexadecimal field. It should not be converted from one CCSID to another (for example, EBCDIC to ASCII) because doing so could result in an unusable value.
Reserved. Reserved field. Must be set to hexadecimal or binary zero.
Total records. The total number of records available in the list.
| Message ID | Error Message Text |
|---|---|
| CPFA314 E | Memory allocation error. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF2634 E | Not authorized to object &1. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C1D E | Length specified in parameter &1 not valid. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3C3C E | Value for parameter &1 not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| CPF9999 E | Function check. &1 unmonitored by &2 at statement &5, instruction &3. |