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.
ARM Library (libarm.a).
#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 */
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 Dual Call 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:
Before the PTX implementation code is executed, the lower library is called. If this call returns a value greater than zero, that return value is passed to the caller as the start handle. If the value returned by the lower library is zero or negative, the return value is the one generated by the PTX library code.
The identifier is returned by an earlier call to arm_getid, arm_getid Dual Call Subroutine. The identifier is passed to the arm_start function of the lower library. If the lower library returns an identifier greater than zero, that identifier is the one that'll eventually be returned to the caller. After the invocation of the lower library, the PTX implementation attempts to translate the tran_id argument to its own identifier from the cross-reference table created by arm_getid. If one can be found, it is used for the PTX implementation; if no cross reference is found, the tran_idis used as passed in.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.
In the PTX implementation, the tran_id (as retrieved from the cross-reference table) is used to look for a transaction structure. If one is not found or if the use-count of the one found is zero, the PTX implementation is considered to have failed and no action is taken by the PTX library. 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 saved as the start_handle. If the call to the lower library was successful, a cross-reference is created from the lower library's start_handle to the PTX library's start_handle for use by arm_update (arm_update Dual Call Subroutine) and arm_stop (arm_stop Dual Call Subroutine).
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 Dual Call Subroutine) and arm_stop (arm_stop Dual Call Subroutine) subroutine calls with the effect that those calls are no-operation functions.
In the current API definition, the last three arguments are for future use and they are ignored in the implementation.In the current API definition, the last three arguments are for future use and they are ignored in the implementation.
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 Dual Call Subroutine) and arm_stop (arm_stop Dual Call Subroutine) subroutines, which will cause those subroutines to operate as no-operation functions.
If the call to the lower library was successful, the start_handle instance ID returned is the one assigned by the lower library. If the subroutine call to the lower library failed but the PTX implementation didn't fail, the start_handle returned is the one assigned by the PTX library. If both implementations fail, a value less than zero is returned.
No error codes are defined by the PTX implementation of the ARM API.
This subroutine is part of the implementation of the ARM API in the Performance Toolbox for AIX licensed product.
| /usr/include/arm.h | Declares the subroutines, data structures, handles, and macros that an application program can use to access the ARM library. |
arm_init (arm_init Dual Call Subroutine) subroutine, arm_getid (arm_getid Dual Call Subroutine) subroutine, arm_end (arm_end Dual Call Subroutine) subroutine.