Prerequisites and method of functioning

The LDAP client marks a request for the HCD LDAP backend as being part of a transaction by specifying an LDAP V3 control for the request. For this reason, transactions in the HCD LDAP backend can only be used with LDAP clients supporting LDAP V3 controls.

LDAP V3 controls represent additional information which can be included with a request to, or to a response from the IBM Tivoli Directory Server for z/OS.

In order to use transactions offered by the HCD LDAP backend, the following two LDAP V3 controls, both of which are supported by the HCD LDAP backend, are required. Both controls must always be used with a valid value which determines how the HCD LDAP backend will react to the control.

Examples of how to use these controls are shown on page ***

1. hcdTransactionControl:
   • Name: hcdTransactionControl
   • Description: This control is used on the first and last request of a transaction, to indicate either the start (via value NEW) and finish (via value COMMIT or ROLLBACK) of a transaction request sequence.
   • Assigned Object Identifier: 1.3.18.0.2.10.3
   • Target of Control: Server
   • Control Criticality: Critical
   • Values: Value is exactly one char 0 terminated string in UTF-8 encoding representing exactly one of the strings (words):
     • NEW
     • COMMIT
     • ROLLBACK
     These strings are not case sensitive. The following byte values (shown as two digit hexadecimal numbers) represent these strings:

     Value      Byte sequence
     
     NEW      = 4E 45 57 00
     COMMIT   = 43 4F 4D 4D 49 54 00
     ROLLBACK = 52 4F 4C 4C 42 41 43 4B 00

2. hcdTransactionId:
   • Name: hcdTransactionId
   • Description: This control is used on all requests of a transaction except the first request. The value of this control indicates which particular transaction a request belongs to.

     If an LDAP client initiates a new transaction with an appropriate request, the HCD LDAP backend answers the request with an LDAP response containing control hcdTransactionId. The LDAP client has to extract this control's value from the response and must specify the value for hcdTransactionId on all following requests belonging to the transaction.

   • Assigned Object Identifier: 1.3.18.0.2.10.4
   • Target of Control: Server
   • Control Criticality: Critical
   • Values: Value is exactly one char 0 terminated string in UTF-8 encoding representing a non-negative, non-zero long int value in decimal format which is the transaction ID. Only values previously received from the HCD LDAP backend are allowed - all others are rejected.
     Example: Assuming a transaction has an ID of 238. Then, the following byte values (shown as two digit hexadecimal numbers) represent the appropriate hcdTransactionId control value:

     32 33 38 00.

     The 10 decimal digits have the following character representation in UTF-8 (shown as two digit hexadecimal numbers):

     0 = 30, 1 = 31, 2 = 32, 3 = 33, ..., 9 = 39.

In order to perform a transaction containing a sequence of LDAP requests R₁, R₂, ..., R_n, the LDAP client has to do the following:

1. Send the LDAP requests R₁, R₂, ..., R_n of the transaction one after another to the IBM Tivoli Directory Server for z/OS and wait for a response to each request before sending the next.
2. To initiate a new transaction (containing the requests R₁, R₂, ..., R_n) extend the first request R₁ with control hcdTransactionControl and specify NEW as value for this control. Control hcdTransactionId must not be used on the first request R₁. If the HCD LDAP backend is able to open the new transaction, it will respond by returning the control hcdTransactionControl and the control hcdTransactionId with a transaction ID as value. In the case of failure neither controls will be returned.
3. Send all subsequent requests R₂, ..., R_n of the current transaction, with the control hcdTransactionId containing the valid transaction ID issued by the HCD LDAP backend as a response to the first request R₁.
4. Commit (or if necessary rollback) the whole transaction using the control hcdTransactionControl and the value COMMIT (or ROLLBACK). This must be added to the last request (R_n) of the transaction. If, however, any request in between fails, you can use the hcdTransactionControl to initiate an immediate ROLLBACK. The control hcdTransactionId with the appropriate value must, of course, also be specified.