List Directory Server Attributes (QgldLstDirSvrA) API
Required Parameter Group:
| 1 | Qualified user space name | Input | Char(20) |
| 2 | Format name | Input | Char(8) |
| 3 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Library Name/Service Program: QSYS/QGLDUAPI
Threadsafe: No
The List Directory Server Attributes (QgldLstDirSvrA) API retrieves a list of directory server attributes including the following:
- Suffixes present on the server
- Attribute indexes maintained by the underlying database
- Network server publishing attributes associated with the LDAP server.
- IP address information
Authorities and Locks
- User Space Library Authority
- *EXECUTE
- User Space Authority
- *CHANGE
- User Space Lock
- An exclusive, no-read lock is obtained on the list space.
Required Parameter Group
- Qualified user space name
- INPUT; CHAR(20)
The user space that is to receive the created list. The first 10 characters contain the user space name, and the second 10 characters contain the name of the library where the user space is located. The content and format of this space is determined by the format name. See Format of Output Data for a description of these formats.
- Format name
- INPUT; CHAR(8)
The content and format of the data to be retrieved. The possible format names follow:
LSVR0200 Retrieve a list of suffixes on the server. LSVR0300 Retrieve a list of database indexes maintained by the server. LSVR0500 Retrieve a list of network server publishing attributes associated with the LDAP server. LSVR0600 Retrieve a list of referral servers. LSVR0800 Retrieve a list of IP addresses See Format of Output Data for a description of these formats.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Format of Output Data
The user space contains:
- A user area
- A generic area
- An input parameter section
- A header section
- A list data section:
- LSVR0200
- LSVR0300
- LSVR0500
- LSVR0600
- LSVR0800
For details about the user area and generic header, see User spaces. For details about the remaining items, see the following sections. For detailed descriptions of the fields in the list that is returned, see Field Descriptions.
When you retrieve list entry information from the list space, do not use the entry size that is returned in the generic header. Instead, use the displacement to next entry field that is returned in each list entry. If you do not use the displacement to next entry field, the results may not be valid.
LSVR0200 Format
The LSVR0200 format is used to retrieve a list of the directory suffixes present on this server.
Starting with V6R1M0, this format is being deprecated. It is still supported with the V5R4M0 level of function but will no longer be enhanced. You should now use the LSVR0200 format of the QgldLstDirSvrInstA API.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Displacement to next entry |
| 4 | 4 | BINARY(4) | Displacement to suffix |
| 8 | 8 | BINARY(4) | Length of suffix |
| 12 | C | BINARY(4) | Reserved |
| CHAR(*) | Suffix | ||
LSVR0300 Format
The LSVR0300 format is used to retrieve information about database indexes maintained by the server. The indexes are used to speed up retrieval of objects when a directory server client searches for specified object attributes.
Starting with V4R5M0, this format is not supported. Database index information is to be retrieved using an LDAP client or the Directory Management Tool (DMT) starting with V4R5M0.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Displacement to next entry |
| 4 | 4 | BINARY(4) | Displacement to attribute name |
| 8 | 8 | BINARY(4) | Length of attribute name |
| 12 | C | BINARY(4) | Index type |
| 16 | 10 | BINARY(4) | Reserved |
| CHAR(*) | Attribute name | ||
LSVR0500 Format
The LSVR0500 format is used to retrieve the network server publishing attributes associated with the server.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Displacement to next entry |
| 16 | 10 | BINARY(4) | Displacement to publishing agent name |
| 12 | C | BINARY(4) | Length of publishing agent name |
| 16 | 10 | BINARY(4) | Displacement to server name |
| 20 | 14 | BINARY(4) | Length of server name |
| 24 | 18 | BINARY(4) | Displacement to bind DN |
| 28 | 1C | BINARY(4) | Length of bind DN |
| 32 | 20 | BINARY(4) | LDAP port number |
| 36 | 24 | BINARY(4) | Connection type |
| 40 | 28 | BINARY(4) | Displacement to parent distinguished name |
| 44 | 2C | BINARY(4) | Length of parent distinguished name |
| 48 | 30 | BINARY(4) | Publishing agent disabled |
| 52 | 34 | BINARY(4) | Reserved |
| 56 | 38 | BINARY(4) | Kerberos authentication indicator |
| 60 | 3C | BINARY(4) | Displacement to Kerberos key tab file |
| 64 | 40 | BINARY(4) | Length of Kerberos key tab file |
| 68 | 44 | BINARY(4) | Displacement to Kerberos principal |
| 72 | 48 | BINARY(4) | Length of Kerberos principal |
| 76 | 4C | BINARY(4) | Displacement to Kerberos realm |
| 80 | 50 | BINARY(4) | Length of Kerberos realm |
| CHAR(*) | Publishing agent name | ||
| CHAR(*) | Server name | ||
| CHAR(*) | Bind DN | ||
| CHAR(*) | Parent distinguished name | ||
| CHAR(*) | Kerberos key tab file | ||
| CHAR(*) | Kerberos principal | ||
| CHAR(*) | Kerberos realm | ||
LSVR0600 Format
The LSVR0600 format is used to retrieve a list of referral servers.
Starting with V6R1M0, this format is being deprecated. It is still supported with the V5R4M0 level of function but will no longer be enhanced. You should now use the LSVR0600 format of the QgldLstDirSvrInstA API.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Displacement to next entry |
| 4 | 4 | BINARY(4) | Displacement to referral server URL |
| 8 | 8 | BINARY(4) | Length of referral server URL. |
| 12 | C | BINARY(4) | Reserved |
| CHAR(*) | Referral server URL. | ||
LSVR0800 Format
The LSVR0800 format is used to retrieve a list of the IP addresses to which the directory server connects.
Starting with V6R1M0, this format is being deprecated. It is still supported with the V5R4M0 level of function but will no longer be enhanced. You should now use the LSVR0800 format of the QgldLstDirSvrInstA API.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Displacement to next entry |
| 4 | 4 | BINARY(4) | Displacement to IP address |
| 8 | 8 | BINARY(4) | Length of IP address |
| CHAR(*) | IP address | ||
Field Descriptions
Attribute name. The name of a directory object attribute for which database indexes will be maintained. This field is specified in UTF-16 (CCSID 13488). The following special value may also be returned:
| *DEFAULT | The rules for this attribute apply to all attributes for which no explicit rules have been defined. |
Bind DN. A distinguished name to use when publishing objects to the directory.This field is specified in UTF-16 (CCSID 13488). The following special value may be specified:
| *NONE | No value is specified. |
Connection type. The type of connection to use to the LDAP server. The following values may be returned:
| 1 | Nonsecure |
| 2 | Secured, using SSL |
Displacement to attribute name. The displacement, in bytes, from the start of the current entry to the attribute name field.
Displacement to bind DN. The displacement, in bytes, from the start of the current entry to the bind DN field.
Displacement to IP address. The displacement, in bytes, from the start of the current entry to the IP address field.
Displacement to Kerberos key tab file. The displacement, in bytes, from the start of the current entry to the Kerberos key tab file field.
Displacement to Kerberos principal. The displacement, in bytes, from the start of the current entry to the Kerberos principal field.
Displacement to Kerberos realm. The displacement, in bytes, from the start of the current entry to the Kerberos realm field.
Displacement to next entry. The displacement, in bytes, from the start of the current entry to the next entry.
Displacement to parent distinguished name. The displacement, in bytes, from the start of the current entry to the parent distinguished name field.
Displacement to publishing agent name. The displacement, in bytes, from the start of the current entry to the publishing agent name field.
Displacement to referral server URL. The displacement, in bytes, from the start of the current entry to the referral server URL field.
Displacement to server name. The displacement, in bytes, from the start of the current entry to the server name field.
Displacement to suffix. The displacement, in bytes, from the start of the current entry to the suffix.
Format name specified. The format name specified on the call to this API.
Index type. The kind of database indexes that will be created for an attribute. Creating database indexes improved the performance of directory searches on those attributes. The following values may be returned:
| 0 | No indexes will be created for the attribute. |
| 1 | Equal |
IP address. The IPv4 or IPv6 address of the client for which the directory server will accept connections. The IP address must already exist to be specified. A value of hexadecimal zeroes and leading zeroes is not allowed. An IPv4 address is expressed in standard dotted-decimal form www.xxx.yyy.zzz; for example, 130.99.128.1. An IPv6 address always has at least one occurrence of a colon (':') in the format. Some possible IPv6 address formats would be: ::x (for example, ::1) or ::w.xxx.y.zzz (for example, ::9.130.4.169). For further IPv6 examples and explanation, refer to the Usage Notes section in the Convert IPv4 and IPv6 Addresses Between Text and Binary Form (inet_pton) API. This field is specified in UTF-16 (CCSID 13488).
The following special value may be returned:
| *ALL | All IP addresses defined on the local system will be bound to the server. |
Kerberos authentication indicator. The following special values may be specified:
| 0 | Do not support Kerberos authentications. |
| 1 | Support Kerberos authentications. |
Kerberos key tab file. The integrated file system path name for the key tab file that contains the server's secret key used for authentication. The QDIRSRV user profile is given authorization to read this file. This field is specified in UTF-16 (CCSID 13488). The following special value may be specified:
| *NONE | No value is specified. |
Kerberos principal. The principal in the key tab file to use for authentication. This field is specified in UTF-16 (CCSID 13488). The following special value may be specified:
| *NONE | No value is specified. |
Kerberos realm. The realm where the principal is registered to use for authentication. This field is specified in UTF-16 (CCSID 13488). The following special value may be specified:
| *NONE | No value is specified. |
LDAP port number. The LDAP server's TCP/IP port.
Length of attribute name. The length, in UTF-16 (CCSID 13488) characters, of the attribute name field.
Length of bind DN. The length, in UTF-16 (CCSID 13488) characters, of the bind DN field.
Length of IP address. The length, in UTF-16 (CCSID 13488) characters, of the IP address field.
Length of Kerberos key tab file. The length, in UTF-16 (CCSID 13488) characters, of the Kerberos key tab file field.
Length of Kerberos principal. The length, in UTF-16 (CCSID 13488) characters, of the Kerberos principal field.
Length of Kerberos realm. The length, in UTF-16 (CCSID 13488) characters, of the Kerberos realm field.
Length of parent distinguished name. The length, in UTF-16 (CCSID 13488) characters, of the parent distinguished name field.
Length of publishing agent name. The length, in UTF-16 (CCSID 13488) characters, of the publishing agent name field.
Length of referral server URL. The length, in UTF-16 (CCSID 13488) characters, of the referral server URL field.
Length of server name. The length, in UTF-16 (CCSID 13488) characters, of the server name field.
Length of suffix. The length, in UTF-16 (CCSID 13488) characters, of the suffix field.
Length of update DN. The length, in UTF-16 (CCSID 13488) characters, of the update DN field.
Parent distinguished name. The parent distinguished name to be used. This field is specified in UTF-16 (CCSID 13488).
Publishing agent name. The agent which will publish information to a directory server and parent distinguished name. This field is specified in UTF-16 (CCSID 13488).
The following publishing agent names are predefined by the operating system:
| *AS400_COMPUTERS | This agent name is used for publishing system information such as the system and printers. |
| *AS400_PRINTSHARES | This agent name is used for publishing print shares to an Active Directory server. |
| *AS400_USERS | This agent name is used for publishing System Distribution Directory users. |
| *OS400_TC1_QOS | This agent name is used for publishing TCP/IP Quality of Service policy information. |
Publishing agent disabled. Indicates whether or not the publishing agent is disabled. The configuration data still exists, but publishing has been disabled for the publishing agent. The following values may be returned:
| 0 | The publishing agent is enabled. |
| 1 | The publishing agent is disabled. |
Referral server URL. The uniform resource locator (URL) of the referral server. This field is specified in UTF-16 (CCSID 13488).
Reserved. A reserved field. This field must be set to zero.
Server name. The name of the server. This field is specified in UTF-16 (CCSID 13488).
Suffix. The directory name for the starting point of a directory information tree.This field is specified in UTF-16 (CCSID 13488).
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| GLD0215 E | Server has not been configured. |
| GLD022F E | Format not supported. |
API introduced: V4R3