Retrieve Directory Server Attributes (QgldRtvDirSvrA) API

The Retrieve Directory Server Attributes (QgldRtvDirSvrA) API retrieves information about the directory server configuration. It can be used to retrieve information about:

• General server properties
• Encrypted communications configuration. The Secure Sockets Layer (SSL) is used for encrypted communications.
• Performance settings
• Auditing settings

Authorities and Locks

To retrieve format RSVR0700, Server auditing information, the caller of this API must have either *ALLOBJ or *AUDIT special authorities.

For all other formats, no IBM^® i special authority is required.

Required Parameter Group

Receiver variable

OUTPUT; CHAR(*)

The variable to receive output data. See Format of Output Data for a description of the format of the output data associated with a specific format name.

Length of receiver variable

INPUT; BINARY(4)

The length of the receiver variable area.

Format name

INPUT; CHAR(8)

The format name identifying the type of information to be retrieved. The possible format names follow:

RSVR0100	Basic server configuration
RSVR0400	Attributes for publishing users in an LDAP directory
RSVR0700	Server auditing information
RSVR0900	Server administration information

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

For details about the format of the output data, see the following sections. For details about the fields in each format, see Field Descriptions.

RSVR0100 Format

This format is used to retrieve basic server configuration information.

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 RSVR0100 format of the QgldRtvDirSvrInstA API.

RSVR0400 Format

This format is used to retrieve the attributes for publishing users in an LDAP directory. User information from the system distribution directory can be published to an LDAP server by the Synchronize System Distribution Directory to LDAP (QGLDSSDD) API and from System i™ Navigator. The publishing attributes define how to publish user information.

RSVR0700 Format

This format is used to retrieve server auditing configuration information.

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 RSVR0700 format of the QgldRtvDirSvrInstA API.

RSVR0900 Format

This format is used to retrieve server administration information.

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 RSVR0900 format of the QgldRtvDirSvrInstA API.

Field Descriptions

ACL model. The ACL model that is being used. The following special values may be returned:

Administrator DN. A distinguished name (DN) that has access to all objects in the directory. This field is specified in UTF-16 (CCSID 13488).

Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.

Bytes returned. The number of bytes of data returned.

Change log indicator. The indicator of whether a change log exists for entries that have been added, changed and deleted. The following values may be returned:

Connection type. The type of connection to use to the LDAP server. The following values may be returned:

Current cipher protocols. The cipher protocols that the server allows when using encrypted connections. The value is the sum of zero or more of the following values:

Database path. The integrated file system path name of the library containing the directory database. This field is specified in UTF-16 (CCSID 13488).

Encrypted port number. The port number to use for encrypted connections. The standard port number for encrypted connections is 636.

Event notification registration indicator. Indicator of whether to allow client to register for event notification. The following special values may be returned:

Installed cipher protocols. The cipher protocols installed on the system. Refer to the current cipher protocols field for a description of the values.

Kerberos administrator ID. The name of the Kerberos administrator. This field is specified in UTF-16 (CCSID 13488). The following special value may be returned:

Kerberos administrator realm. The realm in which the kerberos administrator is registered. This field is specified in UTF-16 (CCSID 13488). The following special value may be returned:

Kerberos authentication indicator. The following special values may be returned:

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. This field is specified in UTF-16 (CCSID 13488). The following special value may be returned:

Kerberos to DN mapping indicator.

LDAP port number. The LDAP server's TCP/IP port.

Length of administrator DN. The length, in UTF-16 (CCSID 13488) characters, of the administrator DN field.

Length of database path. The length, in UTF-16 (CCSID 13488) characters, of the database path field.

Length of Kerberos administrator ID. The length, in UTF-16 (CCSID 13488) characters, of the Kerberos Administrator ID field.

Length of Kerberos administrator realm. The length, in UTF-16 (CCSID 13488) characters, of the Kerberos administrator realm field.

Length of Kerberos key tab file. The length, in UTF-16 (CCSID 13488) characters, of the Kerberos key tab file field.

Length of master server URL. The length, in UTF-16 (CCSID 13488) characters, of the master server URL field.

Length of parent distinguished name. The length, in UTF-16 (CCSID 13488) characters, of the parent distinguished name field.

Length of projected suffix. The length, in UTF-16 (CCSID 13488) characters, of the projected suffix field

Length of server administration URL. The length, in UTF-16 (CCSID 13488) characters, of the server administration URL field.

Length of server name. The length, in UTF-16 (CCSID 13488) characters, of the server name field.

Length of referral server. The length, in UTF-16 (CCSID 13488) characters, of the referral server field.

Length of update DN. The length, in UTF-16 (CCSID 13488) characters, of the update DN field.

Level of authority integration. The level of IBM i authority integration to use to determine if a distinguished name (DN) can become an LDAP administrator. The following special values may be specified:

Log client messages. Whether the directory server will log client messages in the server joblog. The following values may be returned:

Master server URL. The uniform resource locator (URL) of the master server. This field is specified in UTF-16 (CCSID 13488). The following special value may be returned:

Maximum connections. Returns the maximum number of simultaneous connections that can be established with the server.

Starting with V5R1M0, this field is no longer supported and the value returned is 0. The following special value may be returned:

Maximum event registrations for connection. The following special values may be returned:

Maximum event registrations for server. The following special values may be returned:

Maximum age of change log entries. The age, in seconds, of change log entries that can be stored. If the maximum is reached, the change log entries will be deleted starting with the oldest entry. This value only valid if 'Change log indicator' is set to 1. The following special values may be returned:

Maximum number of change log entries. The maximum number of change log entries that can be stored. If the maximum is reached, the change log entries will be deleted starting with the oldest entry. This value only valid if 'Change log indicator' is set to 1. The following special values may be returned:

Maximum operations per transaction. The maximum number of operations that are allowed for each transaction. Transaction support allows a group of directory changes to be handled as a single transaction.

Maximum pending transactions. The maximum number of pending transactions allowed. Transaction support allows a group of directory changes to be handled as a single transaction.

Number of database connections. The number of database connections used by the server.

Offset to administrator DN. The offset, in bytes, from the start of the receiver variable to the administrator DN field.

Offset to database path. The offset, in bytes, from the start of the receiver variable to the database path field.

Offset to Kerberos administrator ID. The offset, in bytes, from the start of the input data area to the Kerberos administrator ID field.

Offset to Kerberos administrator realm. The offset, in bytes, from the start of the input data area to the Kerberos administrator realm field.

Offset to Kerberos key tab file. The offset, in bytes, from the start of the input data area to the Kerberos key tab file field.

Offset to master server URL. The offset, in bytes, from the start of the receiver variable to the master server URL field.

Offset to parent distinguished name. The offset, in bytes, from the start of the receiver variable to the parent distinguished name field.

Offset to projected suffix. The offset, in bytes, from the start of the input data area to the projected suffix field.

Offset to referral server. The offset, in bytes, from the start of the receiver variable to the referral server field.

Offset to server administration URL. The offset, in bytes, from the start of the receiver variable to the server administration URL field.

Offset to server name. The offset, in bytes, from the start of the receiver variable to the server name field.

Offset to update DN. The offset, in bytes, from the start of the receiver variable to the update DN field.

Parent distinguished name. The parent distinguished name for published objects. For example, if the parent distinguished name is 'ou=rochester, o=ibm, c=us', a published directory object for user John Smith might be 'cn=john smith, ou=rochester, o=ibm, c=us'. This field is specified in UTF-16 (CCSID 13488).

Password format. The format of the encrypted password. The following values may be returned:

Projected suffix. The suffix under which all projected objects for this server reside including user and group profiles. This field is specified in UTF-16 (CCSID 13488).

Read only. Whether the directory server allows changes to be made to the directory contents. The following values may be returned:

Read only projected suffix. Whether the directory server will allow updates to be made to the projected suffix. The following values may be returned:

Read only schema. Whether the directory server will allow updates to be made to the directory schema. The following values may be returned:

Referral port. An optional port number to be returned to a client when a request is made for a directory object that does not reside on this server. The referral port and referral server together are used to form a referral URL. The following special value may be returned:

Referral server. The IP name of a server to return to a client when a request is made for a directory object that does not reside on this server. This field is specified in UTF-16 (CCSID 13488). The referral port and referral server are used together to form a referral URL. The following special value may be returned:

Reserved. A reserved field. This field must be set to zero.

Schema checking level. The level of schema checking performed by the server. The following values may be returned:

Search size limit. The maximum number of entries that the server will return for a given search request. The following special value may be returned:

Search time limit. The maximum time, in seconds, that the server will spend performing a given search request. The following special value may be returned:

Security. Whether the server is to use encrypted connections. The following values may be returned:

Note: SSL is used for encrypted connections to the server.

Security audit option for objects. When the QAUDCTL system value is set to *OBJAUD, then object auditing can be done in the directory. See the Security reference topic collection for information about Directory Server auditing. The following special values may be returned:

Server is replica. Whether the server is a master server or a replica server. The following values may be returned:

Server administration URL. The server administration URL. This field is specified in UTF-16 (CCSID 13488).

Server name. The name of the server. This field is specified in UTF-16 (CCSID 13488).

SSL authentication method. The method used during SSL authentication. The following values may be returned:

Terminate idle connections. The server will terminate idle connections when necessary. The following values may be returned:

Note: Starting with V5R1M0, this field is no longer supported and the value returned is 0.

Transaction time limit. The maximum time, in seconds, that the server will spend performing a transaction request. Transaction support allows a group of directory changes to be handled as a single transaction.

Unencrypted port number. The port number to be used for unencrypted connections. The standard port number is 389.

Update DN. The distinguished name that the master server must use when propagating directory updates to this replica server. This field is specified in UTF-16 (CCSID 13488). The following value may be returned:

Use encrypted connections. Whether this server should use encrypted connections when making updates to the replica server. The following values may be returned:

Version. Returns the version of the LDAP server.

Error Messages

[ Back to top | UNIX-Type APIs | APIs by category ]