Publish Directory Object (QgldPubDirObj) API
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(*) |
Default Public Authority: *USE
Library Name/Service Program: QSYS/QGLDPAPI
Threadsafe: No
The Publish Directory Object (QgldPubDirObj) API publishes objects to the directory server. It can be used to perform the following publishing requests:
- Add a new object to the directory.
- Delete an object from the directory.
- Change an object in the directory.
- Change the relative distinguished name of an object in the directory server.
Before this API can be called, the Directory Services property page for the system must be configured. This can be done from System i™ Navigator or by using the Change Directory Server Attributes (QgldChgDirSrvA) API. The directory server indicates the server to which objects will be published. The parent distinguished name indicates the suffix in the directory to which objects will be published. This parent distinguished name is referred to as a publish point.
Authorities and Locks
*ALLOBJ 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. The maximum value for this parameter is 16 776 704.
- Format name
- INPUT; CHAR(8)
The format name identifying the type of publishing request. The possible format names follow:
POBJ0100 Add a new object to the directory server. POBJ0200 Delete an object from the directory server. POBJ0300 Change an object in the directory server. POBJ0400 Change the relative distinguished name of an object in the directory server. 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.
POBJ0100 Format
This format is used to add a new object to the directory server.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Offset to publishing agent name |
| 4 | 4 | BINARY(4) | Length of publishing agent name |
| 8 | 8 | BINARY(4) | Offset to object RDN |
| 12 | C | BINARY(4) | Length of object RDN |
| 16 | 10 | BINARY(4) | Offset to attribute entries |
| 20 | 14 | BINARY(4) | Number of attribute entries |
| 24 | 18 | CHAR(40) | Reserved |
| CHAR(*) | Publishing agent name | ||
| CHAR(*) | Object RDN | ||
| Attribute entries: | |||
| 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) | Displacement to attribute values |
| 16 | 10 | BINARY(4) | Number of attribute values |
| 20 | 14 | BINARY(4) | Attribute value data type |
| 24 | 18 | CHAR(8) | Reserved |
| CHAR(*) | Attribute name | ||
| Attribute values: | |||
| 0 | 0 | BINARY(4) | Displacement to next value |
| 4 | 4 | BINARY(4) | Displacement to attribute value |
| 8 | 8 | BINARY(4) | Length of attribute value |
| 12 | C | CHAR(4) | Reserved |
| CHAR(*) | Attribute value | ||
POBJ0200 Format
This format is used to delete an object from the directory server.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Offset to publishing agent name |
| 4 | 4 | BINARY(4) | Length of publishing agent name |
| 8 | 8 | BINARY(4) | Offset to object RDN |
| 12 | C | BINARY(4) | Length of object RDN |
| 16 | 10 | BINARY(4) | Delete directory subtree |
| 20 | 14 | CHAR(44) | Reserved |
| CHAR(*) | Publishing agent name | ||
| CHAR(*) | Object RDN | ||
POBJ0300 Format
This format is used to change an object in the directory server.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Offset to publishing agent name |
| 4 | 4 | BINARY(4) | Length of publishing agent name |
| 8 | 8 | BINARY(4) | Offset to object RDN |
| 12 | C | BINARY(4) | Length of object RDN |
| 16 | 10 | BINARY(4) | Offset to modification entries |
| 20 | 14 | BINARY(4) | Number of modification entries |
| 24 | 18 | BINARY(4) | Add object if it does not exist |
| 28 | 1C | CHAR(36) | Reserved |
| CHAR(*) | Publishing agent name | ||
| CHAR(*) | Object RDN | ||
| Modification entries: | |||
| 0 | 0 | BINARY(4) | Displacement to next entry |
| 4 | 4 | BINARY(4) | Change type |
| 8 | 8 | BINARY(4) | Displacement to attribute entries |
| 12 | C | BINARY(4) | Number of attribute entries |
| Attribute entries: | |||
| 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) | Displacement to attribute values |
| 16 | 10 | BINARY(4) | Number of attribute values |
| 20 | 14 | BINARY(4) | Attribute value data type |
| 24 | 18 | CHAR(8) | Reserved |
| CHAR(*) | Attribute name | ||
| Attribute values: | |||
| 0 | 0 | BINARY(4) | Displacement to next value |
| 4 | 4 | BINARY(4) | Displacement to attribute value |
| 8 | 8 | BINARY(4) | Length of attribute value |
| 12 | C | CHAR(4) | Reserved |
| CHAR(*) | Attribute value | ||
POBJ0400 Format
This format is used to change the relative distinguished name (RDN) of an object in the directory server.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Offset to publishing agent name |
| 4 | 4 | BINARY(4) | Length of publishing agent name |
| 8 | 8 | BINARY(4) | Offset to object RDN |
| 12 | C | BINARY(4) | Length of object RDN |
| 16 | 10 | BINARY(4) | Offset to new object RDN |
| 20 | 14 | BINARY(4) | Length of new object RDN |
| 24 | 18 | BINARY(4) | Delete old RDN |
| 28 | 1C | CHAR(36) | Reserved |
| CHAR(*) | Publishing agent name | ||
| CHAR(*) | Object RDN | ||
| CHAR(*) | New object RDN | ||
Field Descriptions
Add object if it does not exist. Create the object if a request is made to modify an object that does not exist. The following values may be specified:
| 0 | Do not create the object if it does not exist. |
| 1 | Create the object if it does not exist. All required attributes for the object must be specified on the API in order for the object to be successfully created. |
Attribute name. The name of a directory object attribute. This field is specified in UTF-16 (CCSID 13488).
Attribute value. The value of a directory object attribute.
Attribute value data type. The type of data for the attribute values. The following values may be specified.
| 1 | The attribute values are specified in UTF-16 (CCSID 13488). |
| 2 | The attribute values contain binary data. |
| 3 | The attribute values contain integer data. |
| 4 | The attribute values contain boolean data. |
Change type. The type of change being made to a directory object. The following values may be specified:
| 1 | Add a new attribute |
| 2 | Delete an attribute |
| 3 | Replace an attribute |
| 4 | Add an attribute if it does not exist |
| 5 | Add an attribute value if it does not exist |
| 6 | Delete an attribute if it exists |
| 7 | Delete an attribute value if it exists |
Delete directory subtree. The directory object and any child directory objects should be deleted. The following values may be specified:
| 0 | Do not delete the directory subtree. Only the directory object itself will be deleted. |
| 1 | Delete the directory subtree. |
| 2 | Delete the directory subtree. The root of the subtree will not be deleted. |
Delete old RDN. The old relative distinguished name (RDN) of a directory object should be deleted. The following values may be specified:
| 0 | Do not delete the old RDN. The old RDN attribute value will be retained as an attribute of the object. |
| 1 | Delete the old RDN. |
Displacement to attribute entries. The displacement, in bytes, from the start of the current entry to the attribute entries.
Displacement to attribute name. The displacement, in bytes, from the start of the current entry to the attribute name field.
Displacement to attribute value. The displacement, in bytes, from the start of the current entry to the attribute value field.
Displacement to attribute values. The displacement, in bytes, from the start of the current entry to the attribute values.
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 next value. The displacement, in bytes, from the start of the current value to the next value in the input data.
Length of attribute name. The length, in Unicode characters, of the attribute name field.
Length of attribute value. The length of the attribute value field. If the attribute value is specified in UTF-16 (CCSID 13488), this is the length in Unicode characters. If the attribute value contains binary data, this is the length in bytes. If the attribute value contains integer or boolean data, this field must contain the value 4.
Length of new object RDN. The length, in Unicode characters, of the new object RDN field.
Length of object RDN. The length, in Unicode characters, of the object RDN field.
Length of publishing agent name. The length, in Unicode characters, of the publishing agent name field.
New object RDN. The new relative distinguished name (RDN) of the directory object. This field is specified in UTF-16 (CCSID 13488).
Number of attribute entries. The number of attribute entries.
Number of attribute values. The number of attribute values.
Number of modification entries. The number of modification entries.
Object RDN. The relative distinguished name (RDN) of the directory object being published. This name, combined with the publishing point specified during configuration, form a distinguished name (DN). This field is specified in UTF-16 (CCSID 13488). For example, if the publishing point is 'O=ACME Corp., C=US' and the object RDN is 'CN=Bart', the object DN to be published is 'CN=Bart, O=ACME Corp., C=US'.
Offset to attribute entries. The offset, in bytes, from the start of the input data area to the attribute entries.
Offset to modification entries. The offset, in bytes, from the start of the input data area to the modification entries.
Offset to new object RDN. The offset, in bytes, from the start of the input data area to the new object RDN field.
Offset to object RDN. The offset, in bytes, from the start of the input data area to the object RDN field.
Offset to publishing agent name. The offset, in bytes, from the start of the input data area to the publishing agent name field.
Publishing agent name. The agent making the publishing request. This determines where in the directory the object will be published. The publishing agent information must be configured using the QgldChgDirSvrA API before calling this API. 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. |
Reserved. A reserved field. This field must be set to binary zero.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPFA314 E | Memory allocation error. |
| CPFB802 E | The caller of the API must have *ALLOBJ special authority. |
| CPFB803 E | Publishing agent &1 is not configured or has been disabled. |
| CPFB805 E | Value specified in input data is not valid. |
API introduced: V4R4