[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions, Volume 1


arm_getid Subroutine

Purpose

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. See Implementation Specifics. A transaction must be registered before any ARM measurements can begin.

Library

ARM Library (libarm.a).

Syntax

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

Description

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:

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

Parameters

appl_id

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.

tran_name

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.

tran_detail

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.

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

Error Codes

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

Implementation Specifics

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.

Files


/usr/include/arm.h Declares the subroutines, data structures, handles, and macros that an application program can use to access the ARM library.

Related Information

arm_init (arm_init Subroutine) subroutine, arm_end (arm_end Subroutine) subroutine.


[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]