Change Directory Server Attributes (QgldChgDirSvrA)

Required Parameter Group: 1 Input data Input Char(*) 2 Length of input data Input Binary(4) 3 Format name Input Char(8) 4 Error code I/O Char(*) Threadsafe: No

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

*ALLOBJ and *IOSYSCFG special authority is required to use this API.

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

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.

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Read only
4	4	BINARY(4)	Server is replica
8	8	BINARY(4)	Security
12	C	BINARY(4)	Nonencrypted port number
16	10	BINARY(4)	Encrypted port number
20	14	BINARY(4)	Current cipher protocols
24	18	BINARY(4)	Search time limit
28	1C	BINARY(4)	Search size limit
32	20	BINARY(4)	Maximum connections
36	24	BINARY(4)	Reserved
40	28	BINARY(4)	Referral port
44	2C	BINARY(4)	Password format
48	30	BINARY(4)	Offset to referral server
52	34	BINARY(4)	Length of referral server
56	38	BINARY(4)	Offset to administrator DN
60	3C	BINARY(4)	Length of administrator DN
64	40	BINARY(4)	Offset to administrator password
68	48	BINARY(4)	Length of administrator password
72	48	BINARY(4)	Offset to update DN
76	4C	BINARY(4)	Length of update DN
80	50	BINARY(4)	Offset to update password
84	54	BINARY(4)	Length of update password
92	5C	BINARY(4)	Offset to key ring file
96	60	BINARY(4)	Length of key ring file
100	64	BINARY(4)	Offset to database path
104	64	BINARY(4)	Length of database path
108	68	BINARY(4)	Level indicator
Additional fields if level indicator is equal to 1:
112	70	BINARY(4)	SSL authentication method
116	74	BINARY(4)	Number of database connections
120	78	BINARY(4)	Schema checking level
124	7C	BINARY(4)	Offset to master server URL
128	80	BINARY(4)	Length of master server URL
132	84	BINARY(4)	Change log indicator
136	88	BINARY(4)	Maximum number of change log entries
140	8C	BINARY(4)	Terminate idle connections
144	94	BINARY(4)	Reserved
Variable length string fields:
		CHAR(*)	Referral server
		CHAR(*)	Administrator DN
		CHAR(*)	Administrator password
		CHAR(*)	Update DN
		CHAR(*)	Update password
		CHAR(*)	Key ring file
		CHAR(*)	Database path
		CHAR(*)	Master server URL

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.

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Offset to change entry
4	4	BINARY(4)	Number of change entries
			Change entry
Suffix change entries:
0	0	BINARY(4)	Displacement to next entry
4	4	BINARY(4)	Action
8	8	BINARY(4)	Displacement to suffix
12	C	BINARY(4)	Length of suffix
		CHAR(*)	Suffix

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.

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Offset to change entry
4	4	BINARY(4)	Number of change entries
			Change entries
Add or change attribute index entries:
0	0	BINARY(4)	Displacement to next entry
4	4	BINARY(4)	Action
8	8	BINARY(4)	Displacement to attribute name
12	C	BINARY(4)	Length of attribute name
16	10	BINARY(4)	Index type
20	14	BINARY(4)	Reserved
		CHAR(*)	Attribute name
Delete attribute index entries:
0	0	BINARY(4)	Displacement to next entry
4	4	BINARY(4)	Action
8	8	BINARY(4)	Displacement to attribute name
12	C	BINARY(4)	Length of attribute name
16	10	BINARY(4)	Reserved
		CHAR(*)	Attribute name

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 AS/400 Operations Navigator. The publishing attributes define how to publish user information.

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Offset to the server name
4	4	BINARY(4)	Length of server name
8	8	BINARY(4)	LDAP port number
12	C	BINARY(4)	Connection type
16	10	BINARY(4)	Offset to parent distinguished name
20	14	BINARY(4)	Length of parent distinguished name
24	18	BINARY(4)	Reserved
		CHAR(*)	Server name
		CHAR(*)	Parent distinguished name

CSVR0500 Format

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

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Offset to change entries
4	4	BINARY(4)	Number of change entries
			Change entries
Add or change publishing agent change entries:
0	0	BINARY(4)	Displacement to next entry
4	4	BINARY(4)	Action
8	8	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)	Displacement to bind credentials
36	24	BINARY(4)	Length of bind credentials
40	28	BINARY(4)	LDAP port number
44	2C	BINARY(4)	Connection type
48	30	BINARY(4)	Displacement to parent distinguished name
52	34	BINARY(4)	Length of parent distinguished name
56	38	BINARY(4)	Disable publishing agent
60	3C	BINARY(4)	Reserved
		CHAR(*)	Publishing agent name
		CHAR(*)	Server name
		CHAR(*)	Bind DN
		CHAR(*)	Bind credentials
		CHAR(*)	Parent distinguished name
Delete publishing agent change entries:
0	0	BINARY(4)	Displacement to next entry
4	4	BINARY(4)	Action
8	8	BINARY(4)	Displacement to publishing agent name
12	C	BINARY(4)	Length of publishing agent name
16	10	BINARY(4)	Reserved
		CHAR(*)	Publishing agent name

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.

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Offset to change entries
4	4	BINARY(4)	Number of change entries
			Change entries
Referral server change entries:
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
		CHAR(*)	Referral server URL

Field Descriptions

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

1

Add suffix, index rule, or publishing agent

2

Change index rule or publishing agent

3

Remove suffix, index rule, or publishing agent

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 UCS-2 (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 UCS-2 (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 UCS-2 (CCSID 13488). The following special value may be specified:

*DEFAULT

Specifies the index types to be created for those attributes that have no explicit rules defined.

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 UCS-2 (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 UCS-2 (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:

0

No, do not have a change log

1

Yes, have a change log

-1

The value remains the same

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

1

Nonsecure

2

Secured, using SSL

-1

The value remains the same

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

-1

The value remains the same

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

0x0100

Triple Data Encryption Standard (DES) Secure Hash Algorithm (SHA) (U.S.)

0x0200

DES SHA (U.S.)

0x0400

Rivest Cipher 4 (RC4) SHA (U.S.)

0x0800

RC4 Message Digest 5 (MD5) (U.S.)

0x1000

RC2 MD5 (export)

0x2000

RC4 MD5 (export)

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. This field is specified in UCS-2 (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:

0

The publishing agent is enabled.

1

The publishing agent is disabled.

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

-1

The value of this field does not change.

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:

0

No indexes will be maintained for the specified attribute

1

Equal

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

Key ring file. The path name of the SSL key ring file. A key ring file must be configured when using SSL.

Starting with V4R4M0, this field is ignored for format CSVR0100. This field is specified in UCS-2 (CCSID 13488). The following special value may be specified:

*NONE

No value is specified.

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

-1

The value remains the same

Length of administrator DN. The length, in Unicode characters, of the administrator DN field.

Length of administrator password. The length, in Unicode characters, of the administrator password field.

Length of attribute name. The length, in Unicode characters, of the the attribute name field.

Length of bind credentials. The length, in Unicode characters, of the bind credentials field.

Length of bind DN. The length, in Unicode characters, of the bind DN field.

Length of database path. The length, in Unicode characters, of the database path field.

Length of key ring file. The length, in Unicode characters, of the key ring file field.

Length of master server URL. The length, in Unicode characters, of the master server URL field.

Length of parent distinguished name. The length, in Unicode characters, of the parent distinguished name field.

Length of publishing agent name. The length, in Unicode characters, of the publishing agent name. The length can be at most 50 Unicode characters.

Length of referral server. The length, in Unicode characters, of the referral server name.

Length of referral server URL. The length, in Unicode characters, of the referral server URL field.

Length of server name. The length, in Unicode characters, of the server name field.

Length of suffix. The length, in Unicode characters, of the the suffix field.

Length of update DN. The length, in Unicode characters, of the update DN field.

Length of update password. The length, in Unicode characters, of the update password field.

Level indicator. The level indicator of the data supplied for a format.

0

No additional fields fields supplied.

1

Additional fields are supplied. See format CSVR0100 format for a list of these fields.

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

-1

The value of this field does not change.

0

Do not limit the number of connections.

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:

-1

The value of this field does not change.

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:

-1

The value of this field does not change.

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 entry. 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 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 referral server. The offset, in bytes, from the start of the input data area to the referral server 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 UCS-2 (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:

-1

The value of this field does not change.

1

Unencrypted.

2

SHA. (Default)

3

MD5.

4

Crypt (The password is one-way hashed using a modified DES algorithm. The "crypt" algorithm originally was used by many Unix operating systems for password protection.)

Publishing agent name. The agent which will publish information to a directory server and parent distinguished name. This field is specified in UCS-2 (CCSID 13488).

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

-1

The value of this field does not change.

0

Places the directory server into update mode to allow directory updates. This is the normal mode of operation.

1

Places the directory server into read-only mode.

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 value may be specified:

0

No port number is returned as part of the referral.

-1

The value of this field does not change.

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.

Starting with V4R5M0, this field is ignored for format CSVR0100. This field is specified in UCS-2 (CCSID 13488). To leave the value unchanged, specify a length and offset to this field of zero. The following special value may be specified:

*NONE

No value is specified.

Referral server URL. The uniform resource locator (URL) of the referral server. This field is specified in UCS-2 (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:

-1

The value does not change.

0

None.

1

LDAP version 2.

2

LDAP version 3 strict.

3

LDAP version 3 lenient.

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:

-1

The value of this field does not change.

0

Do not limit the number of entries returned.

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:

-1

The value of this field does not change.

0

Do not limit the search time.

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

-1

The value does not change

1

Allow nonencrypted connections only

2

Allow encrypted connections only

3

Allow both encrypted and nonencrypted connections

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:

-1

The value of this field does not change.

0

The server is a master for the directory suffixes present on the server.

1

The server is a replica server for the directory suffixes present on the server.

Server name. The name of the server. This field is specified in UCS-2 (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:

-1

The value does not change.

1

Server authentication.

3

Server and client authentication.

Suffix. The name of the directory suffix to be added or removed from the server. This field is specified in UCS-2 (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. The following values may be specified:

0

Do not terminate idle connections.

1

Terminate idle connections.

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 UCS-2 (CCSID 13488). The following special value may be specified:

*NONE

No value is specified.

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 UCS-2 (CCSID 13488). To leave the value unchanged, specify a length and offset to this field of zero. The following special value may be specified:

*NONE

No value is specified.

Error Messages

CPF2209 E

Library &1 not found.

CPFA0A9 E

Object not found.

CPFA0DB E

Object name not a QSYS object.

CPFA314 E

Memory allocation error.

GLD0204 E

Attribute name not valid.

GLD0205 E

Administrator DN not valid.

GLD0208 E

Key ring file name not valid.

GLD0209 E

Update DN not valid.

GLD020A E

Suffix not valid.

GLD020B E

Referral server name not valid.

GLD020D E

Index rule already defined for attribute.

GLD020E E

Index rule not found for attribute.

GLD0211 E

Value &1 specified at offset &2 in input format &3 is not valid.

GLD0212 E

Field &1 required when server is using SSL.

GLD0215 E

Directory Services server has not been configured.

GLD0217 E

A value was specified in list entry &1 that is not valid. Reason code &2.

GLD0219 E

Administrator DN and password both required.

GLD021A E

Field not allowed when server is not a replica.

GLD021B E

Field is required when server is a replica.

GLD021C E

The caller of the API must have *ALLOBJ and *IOSYSCFG special authority to configure the server.

GLD021D E

Error occurred when processing the input list of entries.

GLD021E E

&1 password is not valid.

GLD0221 E

Offset &1 specified in input data is not valid.

GLD0222 E

Length &1 specified in input data is not valid.

GLD0223 E

Database path not valid.

GLD0224 E

&1 is not a valid key ring file.

GLD0227 E

Distinguished names cannot be modified while the server is active.

GLD0229 E

Validation list not found.

GLD022F E

Format not supported.