Initialize

The initialize request must precede all processing requests. Among other things, the initialize control block contains the information required by the API to enable it to connect to the Transaction Server. The API requires the following information to achieve this connection:
  • A host name or IP address
  • A port number
The API attempts to resolve this information by using the following data, in the specified order:
  1. The data fields in the request parameter passed by the client application
  2. The data fields in the configuration file (see API configuration file)
  3. The default values

Preparing the call

Prior to calling the initialization request, the client application must build the required control blocks. The initialize request requires the following parameters:
  • An initialize request control block (TSAPI_INIT_REQUEST)
  • A client API handle (TSAPI_HANDLE)
Table 1 shows the input fields in the initialization request control block for this request. The fields are either required or optional. Refer to Table 1 for a description of all of the fields in this control block.
Table 1. TSAPI_INIT_REQUEST Control Block Input Fields
Field Name Required
Identifier Yes
pApplicationId Yes
pAdjustmentRef1 No
freePrevRetrievedData2 No
pTransactionServerName No
transactionServerPort No
connectTimer No
responseTimer No
closeTimer No
itsAppRequestTimer No
pTimingsFileInfo No
Note:
  1. The adjustment reference is only required when the client is issuing adjustment requests; these include insert, delete, recover, update, and undo requests.
  2. This field is being deprecated and should not be used. It will be moved to the API retrieve requests in a future release.

Calling the API

The format of the call is shown below. 
short returnCode = TsApi_Init(TSAPI_INIT_REQUEST     *pInitRequest,
                              TSAPI_HANDLE           *pTsApiHandle);
The client application must not alter the API handle either before or after the request.

Checking the Results

Following the completion of the request, the client application should check the return code. If there is a nonzero return code, the client application should check the values of the return code, reason code, and error message fields located in the request control block. If the return code is zero, the client application can check the contents of any fields in the passed control blocks that may have been updated as a result of the request.