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. 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:
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 Subroutine) call. The transaction use-count is reset to zero by the arm_end (arm_end 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.
The identifier returned by an earlier call to arm_init (arm_init Subroutine). 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.
The appl_id is used to look for an application 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.
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. 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 returned to the caller. 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 returned to the caller.
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.
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 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.
| Item | Description |
|---|---|
| /usr/include/arm.h | Declares the subroutines, data structures, handles, and macros that an application program can use to access the ARM library. |