The arm_end subroutine is used to mark the end of an application. This subroutine call must always be called when a program that issued an arm_init (arm_init Dual Call Subroutine) subroutine call terminates. In the PTX implementation of ARM, application data structures may persist after arm_end is issued. This may not be the case for the lower library implementation.
ARM Library (libarm.a).
#include arm.h
arm_ret_stat_t ARM_API arm_end( arm_appl_id_t appl_id, /* application id
*/
arm_flag_t flags, /* Reserved = 0 */
arm_data_t *data, /* Reserved = NULL */
arm_data_sz_t data_size); /* Reserved = 0 */By calling the arm_end subroutine, an application program signals to the ARM library that it has ceased issuing ARM subroutine calls for the application specified and that the library code can remove references to the application. As far as the calling program is concerned, all references to transactions defined for the named application can be removed as well.
Before the PTX implementation code is executed, the lower library is called. If this call returns a value of zero, that return value is passed to the caller. If the value returned by the lower library is non-zero, 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, in the PTX implementation of ARM, multiple processes can issue arm_init (arm_init Dual Call Subroutine) subroutine calls for a given application with the effect that multiple simultaneous definitions of the application are effective. The ARM library code points all these definitions to a single application structure in the ARM private shared memory area. A use-count keeps track of the number of simultaneous definitions. Each time arm_init is issued for the application name, the counter is incremented and each time the arm_end subroutine call is issued for the associated appl_id, the counter is decremented. No call to arm_end is permitted to decrement the counter less than zero.
Only when the counter reaches zero is the application structure inactivated. As long as the counter is non-zero, transactions defined for the application remain active and new transactions can be defined for the application. It does not matter which process created the definition of the application.
This implementation was chosen because it makes perfect sense in a PTX environment. Any more restrictive implementation would have increased memory use significantly and would be useless for PTX monitoring purposes.
For the implementation of arm_end in the lower library, other restrictions may exist.
The identifier returned by an earlier call to arm_init (arm_init Dual Call Subroutine). The identifier is passed to the arm_end function of the lower library. If the lower library returns a zero, a zero is 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 from the cross-reference table created by arm_init (arm_init Dual Call Subroutine). 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_end subroutine call. However, each time the arm_end subroutine call is issued against an appl_id, the use-count of the transaction structure is decremented. When the count reaches zero, the application structure and all associated transaction structures are marked as inactive. Subsequent arm_init calls can reactivate the application structure but transaction structures formerly associated with the application are not automatically activated. Each transaction must be reactivated through the arm_getid (arm_getid Dual Call Subroutine) subroutine call.
In the PTX implementation, the appl_id (as retrieved from the cross-reference table) is used to look for an application structure. If none is found, no action is taken and the PTX function is considered to have failed. If one is found, the use-count of the application structure is decremented. If that makes the counter zero, the use-counts of all associated transaction structures are set to zero. The total number of application structures that have been initialized for the calling process but not ended is decremented. If this count reaches zero, access to the shared memory from the process is released and the count of users of the shared memory area is decremented. If the count of users of the shared memory segment reaches zero, the shared memory segment is deleted.
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 zero. If the subroutine fails, a value less than zero is returned. If the call to the lower library was successful, a zero is returned. If the subroutine call to the lower library failed but the PTX implementation didn't fail, a zero is returned. If both implementations failed, 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. |