NAME

arm_getid - assign a unique identifier to a transaction class.

SYNOPSIS

tran_id=arm_getid(appl_id,tran_name,tran_detail,flags,data,data_size)

DESCRIPTION

The arm_getid() function call is used to assign a unique identifier to a transaction class, and optionally to describe the format of additional data passed on arm_start(), arm_update(), and arm_stop() calls. This is often done during the initialization of your application. The identifier returned by arm_init() is passed as a parameter in arm_start() calls to identify which class of transaction is starting.

A transaction class is a description of a unit of work, such as Check Account Balance. Any number of transaction classes can be defined within each application. The transaction class name should help a person understand what function the transaction performs. The call to arm_getid() need be made only once for each transaction class each time the application is started. A call to arm_getid() can be made with the same information as a previous call, in which case the transaction identifier (tran_id) that is returned will be the same as the previous calls. Four types of information are tested to see if the information is the same. If any of these are different, a different tran_id will be returned:

• The application identifier (appl_id).

• The transaction name (tran_name).

• The data pointer (data) was NULL on previous calls and is not NULL, or it was not NULL on previous calls and now it is NULL.

• If the data pointer (data) is not NULL on previous calls and this call, and the contents and size (data_size) of the buffer pointed to by the data parameter differ.

Any number of transaction classes can be defined within each application. In each application, each transaction class may be executed any number of times. Each time a transaction class is executed - via arm_start()- it is called a transaction instance. There can be any number of instances of each transaction class executing simultaneously.

PARAMETERS

appl_id (int32)

The unique reference to an application/user identifier returned from the arm_init() call. If the appl_id is less than zero, this arm_getid() call will be treated as a NULL operation, and a negative tran_id returned.

tran_name (char*)

The unique name of the transaction class. It is defined for each transaction class by the application developer. It must be unique within the application (for each arm_init() call). The maximum length is 128 bytes, including the NULL string terminator.

tran_detail (char*)

Transaction detail allows a developer to provide additional information about a transaction class. It is a free-form text area that is set once for each appl_id/tran_name pair. If the contents of the field change on later calls using the same appl_id/tran_name pair, the new contents are ignored. The maximum length is 128 bytes including the NULL string terminator. If no tran_detail is associated with this transaction, the NULL value (0) must be specified.

flags (int32)=0

Reserved for future use. It must be set to zero.

data (char*)

A pointer to a buffer that describes the format of additional data that can be passed on arm_start(), arm_update(), and arm_stop() calls. If no additional data is passed on these calls, this parameter must be set to zero (0). See Format of Data Buffer in arm_getid for the format of the data buffer in arm_getid.()

data_size (int32)

The length in bytes of the buffer pointed to by data. If data is set to zero (0), data_size must also be set to zero.

RETURN CODES

tran_id (int32)

The unique identifier assigned for this transaction class. This id needs to be passed on arm_start() calls.

ERRORS

If the value returned in tran_id is less than zero, an error occurred in communicating with the measurement agent. The most likely cause is passing an invalid value for appl_id. The value returned on an error can be passed to arm_start(), which will cause arm_start() to function as a NULL operation. The error should be logged so corrective action can be taken.

EXAMPLE

my_tran_id = arm_getid (my_appl_id, /* application name */
             "Part Number Query",   /* transaction name */
             "Call to Server XYZ",  /* transaction details */
             0,                     /* reserved for future use */
             my_buffer_ptr,         /* metrics data/metrics meta-data */
             my_buffer_length);     /* length of data buffer */