Change Directory Server Attributes (QgldChgDirSvrA) API

The Change Directory Server Attributes (QgldChgDirSvrA) API changes the directory server configuration. It can be used to change the following server properties:

• General server properties
• Suffixes served by this server
• Encrypted connection configuration. The Secure Sockets Layer (SSL) is used for encrypted communication.
• Performance settings

Authorities and Locks

*ALLOBJ and *IOSYSCFG special authority is required to use this API with formats CSVR0100, CSVR0200, CSVR0300, CSVR0400, CSVR0500, CSVR0600, CSVR0800, or CSVR0900. *AUDIT special authority is required to use this API with format CSVR0700.

Required Parameter Group

Input data

INPUT; CHAR(*)

A variable that contains the input data. See Format of Input Data for a description of the data associated with a specific format name.

Length of input data

INPUT; BINARY(4)

The length of the input data area.

Format name

INPUT; CHAR(8)

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

CSVR0100	Basic server configuration
CSVR0200	Add or remove suffixes from this server
CSVR0300	Add, change, or remove directory indexing rules
CSVR0400	Add or change the attributes for publishing users in an LDAP directory.
CSVR0500	Add or change the network server publishing attributes associated with the LDAP server.
CSVR0600	Add or change referral server information
CSVR0700	Server auditing information
CSVR0800	IP address information
CSVR0900	Server administration information

See Format of Input 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 Input Data

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

CSVR0100 Format

This format is used to change 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 CSVR0100 format of the QgldChgDirSvrInstA API.

CSVR0200 Format

This format is used to add or remove suffixes from the server. The input data consists of a header and a series of change entries. The header identifies the number of suffixes to be added or removed. Each change entry identifies a suffix and the action to be performed (add or remove the suffix).

Note: Removing a suffix from a server will result in the loss of all directory entries with that suffix.

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 CSVR0200 format of the QgldChgDirSvrInstA API.

CSVR0300 Format

This format is used to add, change, or remove directory indexes. Creating indexes for one or more attributes allows for faster retrieval of directory entries based on those attributes. The input data consists of a header and a series of change entries. The header identifies the number of indexes to be added, changed, or removed. Each change entry identifies an attribute and the action to be performed (add, change, or remove the indexes).

Starting with V4R5M0, this format is not supported. Database index information is to be changed using an LDAP client or the Directory Management Tool (DMT) starting with V4R5M0.

CSVR0400 Format

This format is used to set the attributes for publishing users in an LDAP directory. User information from the system distribution directory (SDD) 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.

CSVR0500 Format

This format is used to set the network server publishing attributes associated with the server.

CSVR0600 Format

This format is used to change referral server configuration information. The input data consists of a header and a series of change entries. The header identifies the master server information and the number of referral servers. This replaces the referral server information, if any, that is currently configured.

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 CSVR0600 format of the QgldChgDirSvrInstA API.

CSVR0700 Format

This format is used to change the 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 CSVR0700 format of the QgldChgDirSvrInstA API.

CSVR0800 Format

This format is used to change the IP address configuration information. The input data consists of a header and a series of change entries. The header identifies the number of IP addresses in the list. This replaces the IP address information that is currently configured. At least one IP address value must be specified for the 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 CSVR0800 format of the QgldChgDirSvrInstA API.

CSVR0900 Format

This format is used to change the 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 CSVR0900 format of the QgldChgDirSvrInstA API.

Field Descriptions

ACL model. Indicator of the ACL model to use. The following special values may be specified:

Action. The action to be performed for a given entry. The following values may be specified:

Note: Change is valid only for the CSVR0300 and CSVR0500 formats.

Administrator DN. A distinguished name that has access to all objects in the directory. When either the administrator DN or the administrator password field is changed, both must be specified. This field is specified in UTF-16 (CCSID 13488). To leave the value unchanged, specify a length and offset to this field of zero.

Administrator password. The password used when connecting to the directory server using the administrator DN. When either the administrator DN or the administrator password field is changed, both must be specified. This field is specified in UTF-16 (CCSID 13488). To leave the value unchanged, specify a length and offset to this field of zero.

Attribute index entries. The list of changes to be made to the attribute indexes.

Attribute name. The name of a directory object attribute for which database indexes will be created. This field is specified in UTF-16 (CCSID 13488). The following special value may be specified:

Note: The *DEFAULT attribute entry may be removed or added. Adding or removing *DEFAULT attribute is equivalent to not creating any indexes, or creating indexes for all attributes, depending on the index types specified.

Bind credentials. The password used when connecting to the directory server using the bind DN. When either the bind DN or the bind credentials field is changed, both must be specified. This field is specified in UTF-16 (CCSID 13488). To leave the value unchanged, specify a length and displacement to this field of zero.

Bind DN. A distinguished name to use when publishing objects to the directory. When either the bind DN or the bind credentials field is changed, both must be specified. This field is specified in UTF-16 (CCSID 13488). To leave the value unchanged, specify a length and displacement to this field of zero.

Change entry. A structure identifying a change to be made. The structure identifies the suffix, attribute, or publishing agent and the operation to be performed (add, change, or delete).

Change log indicator. The indicator of whether to have a change log for entries that are added, changed or deleted. The following values may be specified:

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

Current cipher protocols. The cipher protocols that the server will allow when using encrypted connections. The following values may be specified:

Or the sum of one or more of the following values:

Database path. The path to an existing library containing the directory database objects. This is an integrated file system path name, for example, /QSYS.LIB/DIRSRV.LIB. By changing this field, you make the current directory contents inaccessible. By changing the field back to its original value, you restore the original directory contents. The library can exist in a system ASP or a basic user ASP (ASP value of 1 to 32). Also, the library can exist in an independent ASP (ASP value greater than 32). This field is specified in UTF-16 (CCSID 13488). To leave the value unchanged, specify a length and offset to this field of zero.

Disable publishing agent. Indicates whether or not the publishing agent is disabled. The following values may be specified:

Displacement to attribute name. The displacement, in bytes, from the start of the current entry to the attribute name field.

Displacement to bind credentials. The displacement, in bytes, from the start of the current entry to the bind credentials 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 in the input data.

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

Encrypted port number. The port number to use for encrypted connections. The standard port number for encrypted connections (SSL) is 636. Valid port numbers are in the range 1 to 65535. The following special value may be specified:

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

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 specified:

Note: For a delete request, 0 must be specified for this field.

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 specified:

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

To leave the value unchanged, specify a length and offset to this field of zero.

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

To leave the value unchanged, specify a length and offset to this field of zero.

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

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:

To leave the value unchanged, specify a length and offset or displacement to this field of zero.

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:

To leave the value unchanged, specify a length and offset or displacement to this field of zero.

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:

To leave the value unchanged, specify a length and offset or displacement to this field of zero.

Kerberos to DN mapping indicator. The following values may be specified:

Key ring file. The path name of the SSL key ring file. A key ring file must be configured when using SSL. The following special value may be specified:

Note: Starting with V4R4M0, this field is ignored for format CSVR0100. This field is specified in UTF-16 (CCSID 13488).

To leave the value unchanged, specify a length and offset to this field of zero.

LDAP port number. The LDAP server's TCP/IP port. The following values may be specified:

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

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

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

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

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

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

Length of IP address. The length, in UTF-16 (CCSID 13488) characters, of the IP address 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 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 key ring file. The length, in UTF-16 (CCSID 13488) characters, of the key ring 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 publishing agent name. The length, in UTF-16 (CCSID 13488) characters, of the publishing agent name. The length can be at most 50 characters.

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

Length of referral server URL. The length, in UTF-16 (CCSID 13488) characters, of the referral server URL 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 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.

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

Level indicator. The level indicator of the data supplied for a format. See the format descriptions for possible uses and values of this 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. Allowing a user profile to become an LDAP administrator can be done by setting the value of the Level of authority integration field to 1 and then authorizing specific user profiles to the Directory Server Administrator function of the operating system through System i Navigator's Application Administration support. The Change Function Usage Information (QSYCHFUI) API, with a function ID of QIBM_DIRSRV_ADMIN, can also be used to change the list of users that are allowed to be an LDAP administator. The user profile can be mapped to a DN as a projected user (for example, for user profile 'FRED', and the projected suffix of 'systemA', the projected user's DN would be os400-profile=FRED,cn=accounts,os400-sys=systemA ).

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 specified:

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 specified:

To leave the value unchanged, specify a length and offset to this field of zero.

Maximum connections. The maximum number of simultaneous connections that can be established with the server. The following special values may be specified:

Note: Starting with V5R1M0, this field is no longer supported and is ignored if a value is passed.

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

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

Maximum age of change log entries. The maximum 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 used if 'Change log indicator' is set to 1. The following special values may be specified:

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 used if 'Change log indicator' is set to 1. The following special values may be specified:

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. The following special values may be specified:

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. The following special value may be specified:

Nonencrypted port number. The port number to be used for nonencrypted connections. The standard port number is 389. Valid port numbers are in the range 1 to 65535. The following special value may be specified:

Number of change entries. The number of change entries present in the input data.

Number of database connections. The number of database connections used by the server. Valid numbers are in the range 4 to 32. The following special value may be specified:

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

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

Offset to change entries. The offset, in bytes, from the start of the input data area to the the first change entry.

Offset to database path. The offset, in bytes, from the start of the input data area 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 key ring file. The offset, in bytes, from the start of the input data area to the key ring file field.

Offset to master server URL. The offset, in bytes, from the start of the input data area to the master server URL field.

Offset to parent distinguished name. The offset, in bytes, from the start of the input data area 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 input data area to the referral server field.

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

Offset to server name. The offset, in bytes, from the start of the input data to the server name field.

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

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

Offset to update password. The offset, in bytes, from the start of the input data area to the update password 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). To leave the value unchanged, specify a length and offset to this field of zero.

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

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

Publishing agent name. The agent that 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:

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

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

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

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 referral server and port fields must be configured when changing the Server is replica field to make this server a replica. Valid port numbers are in the range 1 to 65535.

Starting with V4R5M0, this field is ignored for format CSVR0100. Referral server information can be changed using the CSVR0600 format of the QgldChgDirSvrA API. The following special values may be specified:

Referral server. The IP name or address of a server to return 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 are used together to form a referral URL. The referral server and port fields must be configured when changing the Server is a replica field to make this server a replica. In this case, the referral is typically to the master server. The following special value may be specified:

Note: Starting with V4R5M0, this field is ignored for format CSVR0100. This field is specified in UTF-16 (CCSID 13488). To leave the value unchanged, specify a length and offset to this field of zero.

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.

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

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

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

Security. Whether the server should use encrypted connections. The following values may be specified:

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 specified:

Server is replica. Whether the server is a master server or a replica server. When this field is changed to make the server a replica, the update DN, update password, and referral fields must be specified. The following values may be specified:

Server administration URL. The server administration URL. This field is specified in UTF-16 (CCSID 13488). To leave the value unchanged, specify a length and offset to this field of zero.

Server name. The name of the server. This field is specified in UTF-16 (CCSID 13488). To leave the value unchanged, specify a length and offset to this field of zero.

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

Suffix. The name of the directory suffix to be added or removed from the server. This field is specified in UTF-16 (CCSID 13488).

Suffix change entries. The list of suffixes to be added or deleted.

Terminate idle connections. The server will terminate idle connections when necessary.

Starting with V5R1M0, this field is no longer supported and is ignored if a value is passed. The following values may be specified:

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. The following special values may be specified:

Update DN. The distinguished name that the master server must use when propagating directory updates to this replica server. This field may be specified only when the server is a replica. When either the update DN or the update password field is changed, both must be specified. This field is specified in UTF-16 (CCSID 13488). The following special value may be specified:

To leave the value unchanged, specify a length and offset to this field of zero.

Update password. The password used when connecting to this server using the update DN. This field may be specified only when the server is a replica. When either the update DN or the update password field is changed, both must be specified. This field is specified in UTF-16 (CCSID 13488). To leave the value unchanged, specify a length and offset to this field of zero. The following special value may be specified:

Error Messages

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