The arm_init subroutine is used to define an application or a unique instance of an application to the ARM library. While, in the PTX implementation of ARM, instances of applications can't be defined, the ARM implementation in the lower library may permit this. An application must be defined before any other ARM subroutine is issued.
ARM Library (libarm.a).
#include arm.h
arm_appl_id_t arm_init( arm_ptr_t *appname, /* application name
*/
arm_ptr_t *appl_user_id, /* Name of the application user */
arm_flag_t flags, /* Reserved = 0 */
arm_data_t *data, /* Reserved = NULL */
arm_data_sz_t data_size); /* Reserved = 0 */Each application needs to be defined by a unique name. An application can be defined as loosely or as rigidly as required. It may be defined as a single execution of one program, multiple (possibly simultaneous) executions of one program, or multiple executions of multiple programs that together constitute an application. Any one user of ARM may define the application so it best fits the measurement granularity desired. For the PTX implementation, 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 application 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.
This subroutine is part of the implementation of the ARM API in the Performance Toolbox for AIX® licensed product.
Note that the implementation of arm_init doesn't allow unique instances of an application to be defined. The appl_id associated with an application 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 applications will usually have the same ID returned for the application each time. The same is true when different programs define the same 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 application 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 application names to pass on the arm_init subroutine call.
Regardless of the implementation restrictions of the PTX library, the lower library may or may not have its own implementation restrictions.
A unique application name. The maximum length is 128 characters including the terminating zero. The PTX library code converts this value 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 an application structure in the library's private shared memory area. If a structure is found, its use-count is incremented and the application ID stored in the structure is saved. If the structure is not found, one is created, assigned the next free application ID and given a use-count of one. The new assigned application ID is saved. If the call to the lower library was successful, a cross-reference is created from the lower library's application ID to the PTX library's application ID for use by arm_getid (arm_getid Dual Call Subroutine) and arm_end (arm_end Dual Call Subroutine).
Up-to 64 bytes, including the terminating zero, of the appname parameter is saved as the description of the SpmiCx context that represents the application 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 user ID for the application. This allows the calling program to define unique instances of an application. In the PTX implementation of the ARM API, this parameter is ignored. Consequently, it is not possible to define unique instances of an application. If specified as non-NULL, this parameter must be a string not exceeding 128 bytes in length, including the terminating zero.
For the PTX 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 appl_user_id 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.
If the call to the lower library was successful, the subroutine returns an appl_id application identifier as returned from the lower library. If the subroutine call to the lower library fails but the PTX implementation doesn't fail, the appl_id 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.
| 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. |