arm_stop - mark the end of a transaction instance that was started with
arm_stop()is used to mark the end of a transaction instance that was started with arm_start(). It should be called from your application program just after each transaction instance ends.
In addition to signaling the end of the transaction instance, which allows a measurement agent to calculate the elapsed time since the
arm_start(), additional information about the transaction can be provided in the optional data buffer. This information can be provided on any or all of the arm_start(), arm_update(), and arm_stop()calls.
- start_handle (int32)
The unique handle from the
arm_start()call that marked the start of this transaction instance. start_handle must be passed in each arm_stop()call. Many transaction instances may be executing at the same time from this and other applications, so this handle is essential for the measurement agent to use to identify which transaction instance is stopping. If start_handle is less than zero, this arm_stop()call will be treated as a NULL operation, and a negative ERROR_STATUS returned.
- tran_status (int32)
The completion code of the transaction, as determined by the application.
- Transaction successful (defined as ARM_GOOD in
<arm.h>). Use this value when the operation completed normally and as expected.
- Transaction aborted (defined as ARM_ABORT in
<arm.h>). Use this value when there was a fundamental failure in the system. For example, a timeout from a communications protocol stack, or an error when doing a database operation.
- Transaction failed (defined as ARM_FAILED in
<arm.h>). Use this value in applications where the transaction worked properly, but no result was generated. For example, when making an airline reservation, a server indicates no seats are available on the requested flight. Since no reservation was made, the transaction was not successful; however, since the reservation system is operating correctly, it is not an aborted transaction either. In this case, it might be desirable to record the transaction as a failed transaction.
- 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 should be set to zero (0). The format is identical to the
arm_start()call, except the Correlator field is not used in the arm_stop()call. See Format of Data Buffer in arm_start/arm_update/arm_stopfor a description of the format of the data buffer in arm_start(), arm_update(), and arm_stop().
- 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 should also be set to zero.
- ERROR_STATUS (int32)
Contains a zero if successful, and a negative value if an error occurred.
If the value returned in ERROR_STATUS is less than zero, an error occurred in communicating with the measurement agent. The most likely cause is passing an invalid value for start_handle. The error should be logged so corrective action can be taken.
status = arm_stop (my_handle, /* transaction handle */ ARM_GOOD, /* transaction status */ 0, /* reserved for future use */ buffer_ptr, /* data description */ buffer_length); /* length of data description */