The arm_getid subroutine is used to register a transaction as belonging to an application and assign a unique identifier to the application/transaction pair. In the PTX implementation of ARM, multiple instances of a transaction within one application can't be defined. The lower library implementation of this subroutine may provide support for instances of transactions. A transaction must be registered before any ARM measurements can begin.
ARM Library (libarm.a).
#include arm.h
arm_tran_id_t arm_getid( arm_appl_id_t appl_id, /* application handle
*/
arm_ptr_t *tran_name, /* transaction name */
arm_ptr_t *tran_detail, /* transaction additional info */
arm_flag_t flags, /* Reserved = 0 */
arm_data_t *data, /* Reserved = NULL */
arm_data_sz_t data_size); /* Reserved = 0 */
Each transaction needs to be defined by a unique name within an application. Transactions can be defined so they best fit the application environment. For example, if a given environment has thousands of unique transactions, it may be feasible to define groups of similar transactions to prevent data overload. In other situations, you may want to use generated transaction names that reflect what data a transaction carries along with the transaction type. For example, the type of SQL query could be analyzed to group customer query transactions according to complexity, such as customer_simple, customer, customer_complex. Whichever method is used to name transactions, in the PTX implementation of the ARM API, measurements are always collected for each unique combination of:
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 transaction ID. If the returned value from the lower library is zero or negative, the return value is the one generated by the PTX library code.
The identifier returned by an earlier call to arm_init (arm_init Dual Call Subroutine). The identifier is passed to the arm_getid 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 appl_id argument to its own identifier by consulting the cross-reference table created by arm_init. If one can be found, it is used for the PTX implementation; if no cross reference is found, the appl_id is used as passed in. The PTX implementation does not require that the arm_init subroutine call was issued by the same program or process now issuing the arm_getid subroutine call. However, the number of issued arm_init subroutine calls for the application name must exceed the number of issued arm_end subroutine calls for this appl_id.
In the PTX implementation, the appl_id (as retrieved from the cross-reference table) is used to look for an application 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.
A unique transaction name. The name only needs to be unique within the appl_id. The maximum length is 128 characters including the terminating zero. In the PTX implementation, the argument is converted to a key by removing all blanks and truncating the string to 32 characters, including a terminating zero. This key is used to look for a transaction structure (that belongs to the application identified in the first argument) in the library's private shared memory area. If a transaction structure is found, its use-count is set to one and the transaction ID stored in the structure is saved. If the structure is not found, one is created and assigned the next free transaction ID, given a use-count of one and added to the application's linked list of transactions. The new assigned transaction ID is saved. If the call to the lower library was successful, a cross-reference is created from the lower library's transaction ID to the PTX library's transaction ID for use by arm_start (arm_start Dual Call Subroutine).
Up-to 64 bytes, including the terminating zero, of the tran_name parameter is saved as the description of the SpmiCx context that represents the transaction in the Spmi hierarchy. The key is used as the short name of the context.
Can be passed in as NULL or some means of specifying a unique instance of the transaction. In the PTX implementation of the ARM API, this parameter is ignored. Consequently, it is not possible to define unique instances of a transaction. If specified as non-NULL, this parameter must be a string not exceeding 128 bytes in length, including the terminating zero.
For the implementation to take this argument in use, another context level would have to be defined between the application context and the transaction context. This was deemed excessive.
For the lower library implementation of this subroutine call, the tran_detail argument may have significance. If so, it's transparent to the PTX implementation.
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 an tran_id application identifier. 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_start (arm_start Dual Call Subroutine) subroutine, which will cause arm_start to function as a no-operation.
If the call to the lower library was successful, the tran_id transaction identifier 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 tran_id returned is the one assigned by the PTX library. If both implementations fail, a value less than zero is returned. In compliance with the ARM API specification, an error return value can be passed to the arm_start (arm_start Dual Call Subroutine) subroutine, which will cause arm_start to function as a no-operation.
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.
Note that the use-count for a transaction structure is either one or zero. This ensures that as long as the application structure is active, so are all transactions for which an arm_getid call was issued after the application was activated by an arm_init (arm_init Dual Call Subroutine) call. The transaction use-count is reset to zero by the arm_end (arm_end Dual Call Subroutine) call if this call causes the application use-count to go to zero.
Note that the implementation of arm_getid doesn't allow unique instances of a transaction to be defined. The tran_id associated with a transaction is stored in the ARM shared memory area and will remain constant throughout the life of the shared memory area. Consequently, subsequent executions of a program that defines one or more transactions under a given application will usually have the same ID returned for the transactions each time. The same is true when different programs define the same transaction within an application: As long as the shared memory area exists, they will all have the same ID returned. This is done to minimize the use of memory for transaction definitions and because it makes no difference from a PTX point of view.
If this is not acceptable from an application point of view, programs can dynamically generate transaction names to pass on the arm_getid subroutine call.
Regardless of the implementation restrictions of the PTX library, the lower library may or may not have its own implementation restrictions.
| /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_end (arm_end Dual Call Subroutine) subroutine.