Login and session information
Almost every BMC Remedy AR System C API function has a
control parameter as its first input argument. This parameter contains the login and session information required to connect to an BMC Remedy AR System server and, thus, required for almost every operation.
The control parameter was optional in BMC Remedy AR System version 3.x and earlier. Therefore, you must add the control parameter to recompiled pre-4.x API programs if you use these programs with later versions of the BMC Remedy AR System API.
The control parameter is a pointer to an
ARControlStruct structure (see the following figure).
Structure used to provide required login information
This structure has the following elements:
Identifier of the cache area allocated by the server to store user information. Before the first API call, initialize it to zero. The server assigns this value; do not change it. It enables the server to use the cache instead of reloading user information for each API call.
Timestamp specifying the date and time the operation occurred on the server. The server assigns this value for each API call.
(Required) Login name to connect to the server. The privileges associated with the user determine whether the API function call can be performed.
(Required) Password for the specified user name, in clear text. The API encrypts this parameter before sending it to the server.
(Required) String that specifies the language for returning error messages (if a message catalog exists), formatting date and time information, sorting or comparing values, and locale information. The locale information is in the following form:
Identifier for the session control block, a structure containing all data needed to maintain the state of API operations. Each API session has a unique session control block, created when you initialize the session by calling
(Required) String specifying the name of the server to connect to.
Client-provided authentication string, such as the domain.
Nearly all function calls require the login and session information that
ARControlStruct contains (stored in both single- and multiple-server environments) because the API does not always maintain a server connection between calls.
When a program calls
ARInitialization at the beginning of its execution, the BMC Remedy AR System C API returns the data in a
ARControlStruct. This is the structure that the program passes as an input parameter in subsequent API calls.