arm_stop Dual Call Subroutine

Purpose

The arm_stop subroutine is used to mark the end of the execution of a transaction. Measurement of the transaction response time completes at the execution of this subroutine.

Library

ARM Library (libarm.a).

Syntax

#include arm.h

arm_ret_stat_t arm_stop(  arm_start_handle_t arm_handle,  /* unique transaction handle
*/
       const arm_status_t comp_status, /* Good=0, Abort=1, Failed=2  */
       arm_flag_t         flags,       /* Reserved = 0               */
       arm_data_t         *data,       /* Reserved = NULL            */
       arm_data_sz_t      data_size);  /* Reserved = 0               */

Description

Each arm_stop subroutine call marks the end of an instance of a transaction within an application. Multiple instances (simultaneous executions of the transaction) may exist. Control information for the transaction instance is held from the execution of the arm_start (arm_start Dual Call Subroutine) subroutine call and until the execution of a matching arm_stop subroutine call, at which time the elapsed time is calculated and used to update transaction measurement metrics for the transaction. Metrics are accumulated for each unique combination of the following three components:

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

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.

Parameters

arm_handle

The identifier is returned by an earlier call to arm_start, arm_start Dual Call Subroutine. The identifier is passed to the arm_stop function of the lower library. If the lower library returns a zero return code, that return code is returned to the caller. After the invocation of the lower library, the PTX implementation attempts to translate the arm_handleargument to its own identifier from the cross-reference table created by arm_start. If one can be found, it is used for the PTX implementation; if no cross reference is found, the arm_handle is used as passed in. The PTX implementation uses the start_handle argument to look for the slot structure created by the arm_start subroutine call. If one is found, a post structure is allocated and added to the linked list of post structures used to pass data to the SpmiArmd daemon. The post structure is updated with the start time from the slot structure, the path to the transaction context, and the stop time of the transaction instance. If no slot structure was found, the PTX implementation is considered to have failed.

In compliance with the ARM API specifications, if the start_handle passed is one returned from a previous arm_start subroutine call that failed, or from an arm_start subroutine operating as a no-operation function, the arm_stop subroutine call executes as a no-operation function. It will return a zero to indicate successful completion.

comp_status

User supplied transaction completion code. The following codes are defined:

• ARM_GOOD - successful completion. Response time is calculated. The response time is calculated as a fixed point value in milliseconds and saved in the metric resptime. In addition, the weighted average response time (in respavg) is calculated as a floating point value using a variable weight, that defaults to 75%. The average response time is calculated as weight percent of the previous value of the average plus (100 - weight) percent of the latest response time observation. The value of weight can be changed from the SpmiArmd daemon's configuration file /etc/perf/SpmiArmd.cf. In addition, the maximum and minimum response time for this transaction is updated, if required. Finally the count of successful transaction executions is incremented.
• ARM_ABORT - transaction aborted. The aborted counter is incremented. No other updates occur.
• ARM_FAILED - transaction failed. The failed counter is incremented. No other updates occur.

flags, data, data_size

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.

Return Values

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.

Error Codes

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

Files