arm_update Dual Call Subroutine

Purpose

The arm_update subroutine is used to collect information about a transaction's progress. It is a no-operation subroutine in the PTX implementation but may be fully implemented by the lower library.

Library

ARM Library (libarm.a).

Syntax

#include arm.h

arm_ret_stat_t arm_update(  arm_start_handle_t arm_handle, /* unique transaction handle
*/
       arm_flag_t         flags,      /* Reserved = 0                */
       arm_data_t         *data,      /* Reserved = NULL             */
       arm_data_sz_t      data_size); /* Reserved = 0                */

Description

The arm_update subroutine is implemented as a no-operation in the PTX version of the ARM API. It is intended to be used for providing status information for a long-running transaction. Because there's no feasible way to display such information in current PTX monitors, the subroutine is a NULL function.

The lower library implementation of the arm_update subroutine is always invoked.

This subroutine is part of the implementation of the ARM API in the Performance Toolbox for AIX® licensed product. It is implemented as a NULL subroutine call.

Parameters

start_handle

The identifier is returned by an earlier call to arm_start, arm_start Dual Call Subroutine. The identifier is passed to the arm_update 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 the PTX implementation is considered to have succeeded, otherwise it 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_update subroutine call executes as a no-operation function. It will return a zero to indicate successful completion.

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