arm_start Subroutine

Purpose

The arm_start subroutine is used to mark the beginning of the execution of a transaction. Measurement of the transaction response time starts at the execution of this subroutine.

Library

ARM Library (libarm.a).

Syntax

#include arm.h

arm_start_handle_t arm_start( arm_tran_id_t tran_id,   /* transaction name identifier
*/
       arm_flag_t    flags,         /* Reserved = 0                  */
       arm_data_t    *data,         /* Reserved = NULL               */
       arm_data_sz_t data_size);    /* Reserved = 0                  */

Description

Each arm_start subroutine call marks the beginning of another instance of a transaction within an application. Multiple instances (simultaneous executions of the transaction) may exist. Control information for the transaction instance is held until the execution of a matching arm_stop (arm_stop Subroutine) subroutine call, at which time the elapsed time is calculated and used to update transaction measurement metrics for the transaction. Metrics are accumulated for each unique combination of the following three components:

1. Hostname of the machine where the instrumented application executes.
2. Unique application name.
3. Unique transaction name.

This subroutine is part of the implementation of the ARM API in the Performance Toolbox for AIX® licensed product.

Parameters

tran_id

The identifier is returned by an earlier call to arm_getid, arm_getid Subroutine. The PTX implementation does not require that the arm_getid subroutine call was issued by the same program or process now issuing the arm_start subroutine call. However, the transaction's application structure must be active, which means that the number of issued arm_init subroutine calls for the application name must exceed the number of issued arm_end subroutine calls for the application's appl_id. If an application was inactivated by issuing a sufficient number of arm_end calls, all transactions defined for that application will have their use_count set to zero. The count remains zero (and the transaction inactive) until a new arm_getid subroutine is issued for the transaction.

The tran_id argument is used to look for a transaction structure. If one is not found or if the use-count of the one found is zero, no action is taken and the function returns -1. If one is found, a transaction instance structure (called a slot structure) is allocated, assigned the next free instance ID, and updated with the start time of the transaction instance. The assigned instance ID is returned to the caller.

In compliance with the ARM API specifications, if the tran_id passed is one returned from a previous arm_getid subroutine call that failed, the arm_start subroutine call functions as a no-operation function. It will return a NULL start_handle, which can be passed to subsequent arm_update (arm_update Subroutine) and arm_stop (arm_stop Subroutine) subroutine calls with the effect that those calls are no-operation functions.

flags, data, data_size

In the current API definition, the last three arguments are for future use and they are ignored in the implementation.

Return Values

If successful, the subroutine returns a start_handle, which uniquely defines this transaction execution instance. If the subroutine fails, a value less than zero is returned. In compliance with the ARM API specifications, the error return value can be passed to the arm_update (arm_update Subroutine) and arm_stop (arm_stop Subroutine) subroutines, which will cause those subroutines to operate as no-operation functions.

Error Codes

No error codes are defined by the PTX implementation of the ARM API.

Files