NAME

arm_stop - mark the end of a transaction instance that was started with arm_start().

SYNOPSIS

error_status=arm_stop(start_handle,tran_status,flags,data,data_size)

DESCRIPTION

Function 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.

PARAMETERS

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.

0

Transaction successful (defined as ARM_GOOD in <arm.h>). Use this value when the operation completed normally and as expected.

1

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.

2

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_stop for 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.

RETURN CODE

ERROR_STATUS (int32)

Contains a zero if successful, and a negative value if an error occurred.

ERRORS

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.

EXAMPLE

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 */