NAME

arm_update - show the progress of a long transaction, or provide extra information about a transaction, or provide a larger opaque application private buffer.

SYNOPSIS

error_status=arm_update(start_handle,flags,data,data_size)

DESCRIPTION

Function arm_update() is an optional call, used for the following purposes:

• To show the progress of a long transaction. Each insertion of arm_update() call into an application program after arm_start() and before arm_stop() generates a heartbeat indicating that the transaction instance is still running. This would typically be done after a fixed interval of time (such as every minute) or after a fixed amount of work is completed (such as 1000 records processed). There can be any number of arm_update() calls between an arm_start/arm_stop pair. This call is most useful for long-running transactions that take minutes or hours to complete. Another way to capture data about the steps within a long transaction is to use component transactions (see Three Ways to Instrument within a Transaction Instance , which describes three ways to instrument within a transaction instance).

  Function arm_update() is also useful for updating any of the metric or string variables passed in the buffer pointed to by the data parameter (as defined in arm_getid()). This could be used to show not only that the transaction is progressing, but also how far it has progressed. For example, every time another 1000 records are processed, an arm_update() call could be made with an updated count in the buffer.

• To provide extra information about a transaction. Each time you want to provide special information about a transaction instance, insert an arm_update() call into an application program after arm_start() and before arm_stop(). If there is no additional information to be provided, pass a NULL pointer. There are several types of additional information that may be useful, including about the size of the transaction (such as the number of bytes in a print job), about the state of the application (such as the number of threads that are running), and diagnostic information. This type of information can be provided via application-defined metrics on any or all of the arm_start(), arm_update(), and arm_stop() calls. See Format of Data Buffer in arm_start/arm_update/arm_stop for description of the detailed buffer format.

• To provide a larger opaque application private buffer. Information that does not conform well to application-defined metrics (for example long diagnostic messages) may be provided via an opaque buffer containing up to 1020 bytes of data (Format 2). Except for the 4-byte Format field, the content of the buffer is entirely defined by the application developer. Because the contents of the buffer containing the information is known only to the application developer, measurement agents cannot do much with the data in this field. A typical measurement agent might provide an option to write the buffer with the information to a log file, but this is the most that can be expected.

  Measurement agents are not required to do anything with the information in this call.

PARAMETERS

start_handle (int32)

The unique handle from the arm_start() call that marked the start of this transaction instance. The start_handle must be passed in each arm_update() call. Many transaction instances may be executing at the same time from this and other applications, so this handle is essential to identify which transaction instance is being updated. If start_handle is less than zero, this arm_update() call will be treated as a NULL operation, and a negative ERROR_STATUS returned.

flags (int32)=0

Reserved for future use. It must be set to zero.

data (char*)

A pointer to a buffer with additional data that can optionally be passed. If no additional data is passed, this parameter should be set to zero (0).

There are two possible buffer formats:

1

If the Format field contains the value 1, then application-defined metrics as defined in arm_getid() can be passed. The correlator field is not used in the arm_update() call.

2

If the Format field contains the value 2, then a status message up to 1020 bytes in length may be passed in.

See Format of Data Buffer in arm_start/arm_update/arm_stop for description of the format of the data buffer in arm_start(), arm_update(), and arm_stop().

data_size (int32)

The length in bytes of the buffer pointed to by data. If data is set to zero (0), data_size should also be set to zero.

RETURN CODE

ERROR_STATUS (int32)

Contains a zero if successful and a negative value if an error occurred.

ERRORS

If the value returned in ERROR_STATUS is less than zero, an error occurred in communicating with the measurement agent. The most likely cause is passing an invalid value for start_handle. The error should be logged so corrective action can be taken.

EXAMPLE

status = arm_update (my_handle,         /* transaction handle         */
                     0,                 /* reserved for future use    */
                     my_buffer_ptr,     /* data description           */
                     my_buffer_length); /* length of data description */