NAME

arm_start - mark the beginning of execution of a transaction.

SYNOPSIS

start_handle=arm_start(tran_id,flags,data,data_size)

DESCRIPTION

Function arm_start() is used to mark the beginning of execution of a transaction. Each time a transaction executes, it is called a transaction instance. Function arm_start() must be called in an application at the beginning of each transaction instance required to be monitored.

Additional information about the transaction can be provided in the optional data buffer. If no additional information is provided, a NULL pointer must be passed. This information can be provided on any or all of the arm_start(), arm_update(), and arm_stop() calls, except for correlation information, which is passed only on arm_start(). See Advanced Topics for details on how to pass this information.

PARAMETERS

tran_id (int32)

The unique identifier assigned to the transaction class. This is the id generated by arm_getid(). If the tran_id is less than zero, this arm_start() call will be treated as a NULL operation, and a negative start_handle returned.

flags (int32)=0

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

data (char*)

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

data_size (int32)

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

RETURN CODES

start_handle (int32)

The unique transaction handle assigned to this instance of a transaction. This handle must be passed on arm_stop and any arm_update calls.

ERRORS

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

EXAMPLE

my_handle = arm_start (my_tran_id,  /* transaction handle      */
              0,                    /* reserved for future use */
              my_buffer_ptr,        /* metrics data/correlator */
              my_buffer_length);    /*length of data buffer    */