Functions

ARM 4.0 Functions
[ARM 4.0]

Functions

 arm_register_application (const arm_char_t *app_name, const arm_id_t *input_app_id, const arm_int32_t flags, const arm_buffer4_t *buffer4, arm_id_t *output_app_id)
 describes and registers the application with ARM
 arm_destroy_application (const arm_id_t *app_id, const arm_int32_t flags, const arm_buffer4_t *buffer4)
 destroy any registered ARM application data
 arm_register_transaction (const arm_id_t *app_id, const arm_char_t *tran_name, const arm_id_t *input_tran_id, const arm_int32_t flags, const arm_buffer4_t *buffer4, arm_id_t *output_tran_id)
 describes and register a transaction with ARM
 arm_register_metric (const arm_id_t *app_id, const arm_char_t *metric_name, const arm_metric_format_t metric_format, const arm_metric_usage_t metric_usage, const arm_char_t *metric_unit, const arm_id_t *input_metric_id, const arm_int32_t flags, const arm_buffer4_t *buffer4, arm_id_t *output_metric_id)
 describes and register metrics with ARM
 arm_start_application (const arm_id_t *app_id, const arm_char_t *app_group, const arm_char_t *app_instance, const arm_int32_t flags, const arm_buffer4_t *buffer4, arm_app_start_handle_t *app_handle)
 indicates that an instance of an application has started running
 arm_stop_application (const arm_app_start_handle_t app_handle, const arm_int32_t flags, const arm_buffer4_t *buffer4)
 stop application
 arm_start_transaction (const arm_app_start_handle_t app_handle, const arm_id_t *tran_id, const arm_correlator_t *parent_correlator, const arm_int32_t flags, const arm_buffer4_t *buffer4, arm_tran_start_handle_t *tran_handle, arm_correlator_t *current_correlator)
 start transaction
 arm_stop_transaction (const arm_tran_start_handle_t tran_handle, const arm_tran_status_t tran_status, const arm_int32_t flags, const arm_buffer4_t *buffer4)
 stop transaction
 arm_update_transaction (const arm_tran_start_handle_t tran_handle, const arm_int32_t flags, const arm_buffer4_t *buffer4)
 update transaction status
 arm_discard_transaction (const arm_tran_start_handle_t tran_handle, const arm_int32_t flags, const arm_buffer4_t *buffer4)
 discard a started transaction.
 arm_block_transaction (const arm_tran_start_handle_t tran_handle, const arm_int32_t flags, const arm_buffer4_t *buffer4, arm_tran_block_handle_t *block_handle)
 indicates that a transaction is blocked.
 arm_unblock_transaction (const arm_tran_start_handle_t tran_handle, const arm_tran_block_handle_t block_handle, const arm_int32_t flags, const arm_buffer4_t *buffer4)
 unblock transaction
 arm_bind_thread (const arm_tran_start_handle_t tran_handle, const arm_int32_t flags, const arm_buffer4_t *buffer4)
 bind a transaction to the excuting thread
 arm_unbind_thread (const arm_tran_start_handle_t tran_handle, const arm_int32_t flags, const arm_buffer4_t *buffer4)
 unbind a transaction from the excuting thread
 arm_report_transaction (const arm_app_start_handle_t app_handle, const arm_id_t *tran_id, const arm_tran_status_t tran_status, const arm_response_time_t response_time, const arm_stop_time_t stop_time, const arm_correlator_t *parent_correlator, const arm_correlator_t *current_correlator, const arm_int32_t flags, const arm_buffer4_t *buffer4)
 report transaction statistics
 arm_generate_correlator (const arm_app_start_handle_t app_handle, const arm_id_t *tran_id, const arm_correlator_t *parent_correlator, const arm_int32_t flags, const arm_buffer4_t *buffer4, arm_correlator_t *current_correlator)
 generate a correlator or pass instrumentation control information.
 arm_get_correlator_length (const arm_correlator_t *correlator, arm_correlator_length_t *length)
 get length of correlator
 arm_get_correlator_flags (const arm_correlator_t *correlator, const arm_int32_t corr_flag_num, arm_boolean_t *flag)
 get value of correlator flag
 arm_get_arrival_time (arm_arrival_time_t *opaque_time)
 gets current time in opaque format.
 arm_get_error_message (const arm_charset_t charset, const arm_error_t code, arm_message_buffer_t msg)
 get an error message
 arm_is_charset_supported (const arm_charset_t charset, arm_boolean_t *supported)
 check supported character encoding

Function Documentation

arm_bind_thread ( const arm_tran_start_handle_t  tran_handle,
const arm_int32_t  flags,
const arm_buffer4_t *  buffer4 
)

bind a transaction to the excuting thread

arm_bind_thread() indicates that the thread from which it is called is performing on behalf of the transaction identified by the start handle.

The thread binding could be useful for managing computing resources at a finer level of granularity than a process. There can be any number of threads simultaneously bound to the same transaction.

A transaction remains bound to a thread until either an arm_discard_transaction(), arm_stop_transaction(), or arm_unbind_thread() is executed passing the same start handle.

arm_bind_thread() and arm_block_transaction() are used independently of each other.

Parameters:
[in] tran_handle A handle returned in an out parameter from an arm_start_transaction() call in the same process.
[in] flags Contains 32-bit flags. No values are currently defined. The field should be zero (ARM_FLAG_NONE).
[in] buffer4 Pointer to the optional buffer, if any. If the pointer is null, there is no buffer. No sub-buffer types are currently valid with this function call, so the pointer should be null (ARM_BUF4_NONE).
Returns:
The returned code is a status that may indicate whether an error was detected. If the return code is negative, an error occurred. If the return code is not negative, an error may or may not have occurred - the determination of what is an error and whether an error code is returned is at the discretion of the ARM implementation. The application can test the return code if it wants to provide its own error logging. See ARM error handling and error codes for further information about error handling.
See also:
arm_block_transaction(), arm_discard_transaction(), arm_start_transaction(), arm_stop_transaction(), arm_unbind_thread()
arm_block_transaction ( const arm_tran_start_handle_t  tran_handle,
const arm_int32_t  flags,
const arm_buffer4_t *  buffer4,
arm_tran_block_handle_t *  block_handle 
)

indicates that a transaction is blocked.

arm_block_transaction() is used to indicate that the transaction instance is blocked waiting on an external transaction (which may or may not be instrumented with ARM) or some other event to complete. It has been found useful to separate out this "blocked" time from the elapsed time between the arm_start_transaction() and arm_stop_transaction().

A transaction remains blocked until arm_unblock_transaction() is executed passing the same tran_block_handle, or either an arm_discard_transaction() or arm_stop_transaction() is executed passing the same tran_handle.

The blocking conditions of most interest are those that could result in a significant and/or variable length delay relative to the response time of the transaction. For example, a remote procedure call would be a good situation to indicate with arm_block_transaction() or arm_unblock_transaction(), whereas a disk I/O would not.

A transaction may be blocked by multiple conditions simultaneously. In many application architectures arm_block_transaction() would be called just prior to a thread suspending, because the thread is waiting to be signaled that an event has occurred. In other application architectures there would not be a tight relationship between the thread behavior and the blocking conditions. arm_bind_thread() and arm_block_transaction() are used independently of each other.

A description of the blocking cause can be provided in the optional Block Cause sub-buffer.

Parameters:
[in] tran_handle A handle returned in an out parameter from an arm_start_transaction() call in the same process.
[in] flags Contains 32-bit flags. No values are currently defined. The field should be zero (ARM_FLAG_NONE).
[in] buffer4 Pointer to the optional buffer, if any. If the pointer is null, there is no buffer. The sub-buffers that may be used are:

  • arm_subbuffer_block_cause_t
  • arm_subbuffer_message_rcvd_event_t
  • arm_subbuffer_message_sent_event_t
[out] block_handle Pointer to a handle that is passed on arm_unblock_transaction() calls in the same process. There are no requirements on what value it is set to, except that it must be possible to pass it on arm_unblock_transaction() without the application needing to do any error checking.
Returns:
The returned code is a status that may indicate whether an error was detected. If the return code is negative, an error occurred. If the return code is not negative, an error may or may not have occurred - the determination of what is an error and whether an error code is returned is at the discretion of the ARM implementation. The application can test the return code if it wants to provide its own error logging. See ARM error handling and error codes for further information about error handling.
See also:
arm_bind_thread(), arm_discard_transaction(), arm_start_transaction(), arm_stop_transaction(), arm_unblock_transaction()
arm_destroy_application ( const arm_id_t *  app_id,
const arm_int32_t  flags,
const arm_buffer4_t *  buffer4 
)

destroy any registered ARM application data

arm_destroy_application() indicates that the registration data about an application previously registered with arm_register_application() is no longer needed.

The purpose of this call is to signal the ARM implementation so that it can release any storage it is holding. Ending a process or unloading the ARM library results in an implicit arm_destroy_application() for any previously registered applications.

It is possible for multiple arm_register_application() calls to be made in the same process with identical identity data. When this is done, arm_destroy_application() is assumed to be paired with one arm_register_application(). For example, if arm_register_application() is executed twice with the same output ID, and arm_destroy_application() is executed once using this ID, it is assumed that an instance of the application is still active and it is not safe to discard the application registration data associated with the ID.

Parameters:
[in] app_id Application ID returned from an arm_register_application() call in the same process.
[in] flags Contains 32-bit flags. No values are currently defined. The field should be zero (ARM_FLAG_NONE).
[in] buffer4 Pointer to the optional buffer, if any. If the pointer is null, there is no buffer. No sub-buffer types are currently valid with this function call, so the pointer should be null (ARM_BUF4_NONE).
Returns:
The returned code is a status that may indicate whether an error was detected. If the return code is negative, an error occurred. If the return code is not negative, an error may or may not have occurred - the determination of what is an error and whether an error code is returned is at the discretion of the ARM implementation. The application can test the return code if it wants to provide its own error logging. See ARM error handling and error codes for further information about error handling.
See also:
arm_register_application()
arm_discard_transaction ( const arm_tran_start_handle_t  tran_handle,
const arm_int32_t  flags,
const arm_buffer4_t *  buffer4 
)

discard a started transaction.

arm_discard_transaction() signals that the referenced arm_start_transaction() should be ignored and treated as if it never happened. Measurements associated with a transaction that is processing should be discarded. Either arm_discard_transaction() or arm_stop_transaction() is used - never both.

An example of when a transaction would be discarded could happen is if proxy instrumentation believes a transaction is starting, but then learns that it did not. It can be called from any thread in the process that executed the arm_start_transaction(). In general, the use of arm_discard_transaction() is discouraged, but experience has shown a few use cases that require the functionality.

arm_discard_transaction() clears any thread bindings [arm_bind_thread()] and blocking conditions [arm_block_transaction()].

Parameters:
[in] tran_handle A handle returned in an out parameter from an arm_start_transaction() call in the same process.
[in] flags Contains 32-bit flags. No values are currently defined. The field should be zero (ARM_FLAG_NONE).
[in] buffer4 Pointer to the optional buffer, if any. If the pointer is null, there is no buffer. No sub-buffer types are currently valid with this function call, so the pointer should be null (ARM_BUF4_NONE).
Returns:
The returned code is a status that may indicate whether an error was detected. If the return code is negative, an error occurred. If the return code is not negative, an error may or may not have occurred - the determination of what is an error and whether an error code is returned is at the discretion of the ARM implementation. The application can test the return code if it wants to provide its own error logging. See ARM error handling and error codes for further information about error handling.
See also:
arm_bind_thread(), arm_block_transaction(), arm_start_transaction(), arm_stop_transaction()
arm_generate_correlator ( const arm_app_start_handle_t  app_handle,
const arm_id_t *  tran_id,
const arm_correlator_t *  parent_correlator,
const arm_int32_t  flags,
const arm_buffer4_t *  buffer4,
arm_correlator_t *  current_correlator 
)

generate a correlator or pass instrumentation control information.

arm_generate_correlator() is used for two very different purposes:

  1. It is used to generate a correlator for use with arm_report_transaction().
  2. It is used (beginning with ARM 4.1) to exchange control information that indicates the level of instrumentation for this transaction that is desired by the ARM implementation.

Generating a Correlator

A correlator is a correlation token passed from a calling transaction to a called transaction. The correlation token may be used to establish a calling hierarchy across processes and systems. A correlator contains a two-byte length field, a one-byte format ID, a one-byte flag field, plus it may contain other data that is used to uniquely identify an instance of a transaction. Applications do not need to understand correlator internals. The maximum length is 512 (ARM_CORR_MAX_LENGTH) bytes.

It is useful to think about its use in the context of what arm_start_transaction() and arm_stop_transaction() do:

Based on this positioning, it should be clear that arm_generate_correlator() can be used whenever an arm_start_transaction() can be used. More specifically, the following calls must have been executed first: arm_register_application(), arm_register_transaction(), and arm_start_application(). The same parameters are also used, except there is no need for a start handle, and there is no need for the Arrival Time or Metric Values sub-buffers. The other sub-buffers may be used. The correlator that is output can be used in the same way that a correlator output from arm_start_transaction() is used.

Controlling the Level of Instrumentation for a Transaction

There is a special use of arm_generate_correlator() that is not intuitive because it is unrelated to generating a correlator. It is used because this allowed a new capability to be added without adding any new function calls, which would have impacted backwards-compatibility with ARM libraries that support ARM 4.0 but not ARM 4.1 or later ARM 4.x versions. Further details are available in the descriptions of the Application Control sub-buffer (see arm_subbuffer_app_control_t) and Transaction Instance Control sub-buffer (see arm_subbuffer_tran_instance_control_t).

When used for this special purpose, the meaningful parameters are:

  • app_handle
  • buffer4
    • arm_subbuffer_app_control_t
    • arm_subbuffer_tran_id_control_t
    • arm_subbuffer_tran_instance_control_t
  • current_correlator = NULL

This special form is recognized by setting the current_correlator pointer to null, which renders the call meaningless for the purpose of generating a correlator.

Parameters:
[in] app_handle Value returned from an arm_start_application() call in the same process. The ARM implementation may use this handle to access application instance data that may become part of the correlator; e.g., the arm_subbuffer_system_address_t.
[in] tran_id A transaction ID returned in an out parameter from an arm_register_transaction() call in the same process. If arm_generate_correlator() is being used for purposes of instrumentation control, tran_id is ignored.
[in] parent_correlator A pointer to the parent correlator, if any. The pointer may be null (ARM_CORR_NONE). If arm_generate_correlator() is being used for purposes of instrumentation control, parent_correlator is ignored.
[in] flags Contains 32-bit flags.

[in] buffer4 Pointer to the optional buffer, if any. If the pointer is null (ARM_BUF4_NONE), buffer4 there is no buffer. The sub-buffers that may be used are:

  • arm_subbuffer_app_control_t
  • arm_subbuffer_tran_context_t
  • arm_subbuffer_tran_id_control_t
  • arm_subbuffer_tran_instance_control_t
  • arm_subbuffer_user_t
[out] current_correlator A pointer to a buffer into which the ARM implementation will store a correlator for the transaction instance, if any. The length of the buffer should be (at least) ARM_CORR_MAX_LENGTH. The value must be non-null if arm_generate_correlator() is being used to generate a correlator. If arm_generate_correlator() is being used to pass the Application Control, Transaction ID Control, or Transaction Instance Control sub-buffer, then current_correlator must be set to null.
Returns:
The returned code is a status that may indicate whether an error was detected. If the return code is negative, an error occurred. If the return code is not negative, an error may or may not have occurred - the determination of what is an error and whether an error code is returned is at the discretion of the ARM implementation. The application can test the return code if it wants to provide its own error logging. See ARM error handling and error codes for further information about error handling.
See also:
arm_register_application(), arm_register_transaction(), arm_report_transaction(), arm_start_application(), arm_start_transaction(), arm_stop_transaction()
arm_get_arrival_time ( arm_arrival_time_t *  opaque_time  ) 

gets current time in opaque format.

arm_get_arrival_time() stores a 64-bit integer representing the current time.

There are situations in which there is a significant delay between the time when processing of a transaction begins and when all the context property values that are needed before arm_start_transaction() can be executed are known. In order to get a more accurate response time, arm_get_arrival_time() can be used to capture an implementation-defined representation of the current time. This integer value is later stored in the Arrival Time sub-buffer (arm_subbuffer_arrival_time_t) when arm_start_transaction() executes. The ARM library will use the "arrival time" as the start time rather than the moment when the arm_start_transaction() executes.

Parameters:
[out] opaque_time Pointer to an arm_int64_t that will contain the arrival time value. Note that the value is implementation-defined so the application should not make any conclusions based on its contents.
Returns:
The returned code is a status that may indicate whether an error was detected. If the return code is negative, an error occurred. If the return code is not negative, an error may or may not have occurred - the determination of what is an error and whether an error code is returned is at the discretion of the ARM implementation. The application can test the return code if it wants to provide its own error logging. See ARM error handling and error codes for further information about error handling.
See also:
arm_start_transaction()
arm_get_correlator_flags ( const arm_correlator_t *  correlator,
const arm_int32_t  corr_flag_num,
arm_boolean_t *  flag 
)

get value of correlator flag

arm_get_correlator_flags() returns the value of a specified flag in the correlator header.

A correlator header contains bit flags. arm_get_correlator_flags() is used to test the value of those flags. See arm_generate_correlator() for a description of a correlator.

Parameters:
[in] correlator Pointer to a buffer containing a correlator. It serves no purpose to make the call if the pointer is null.
[in] corr_flag_num An enumerated value that indicates which flag's value is requested. The enumerated values are:

[out] flag Pointer to a boolean that is output indicating whether the flag is set.
Returns:
The returned code is a status that may indicate whether an error was detected. If the return code is negative, an error occurred. If the return code is not negative, an error may or may not have occurred - the determination of what is an error and whether an error code is returned is at the discretion of the ARM implementation. The application can test the return code if it wants to provide its own error logging. See ARM error handling and error codes for further information about error handling.
See also:
arm_generate_correlator(), arm_start_transaction()
arm_get_correlator_length ( const arm_correlator_t *  correlator,
arm_correlator_length_t *  length 
)

get length of correlator

arm_get_correlator_length() returns the length of a correlator, based on the length field within the correlator header. Note that this length is not necessarily the length of the buffer containing the correlator.

A correlator header contains a length field. arm_get_correlator_length() is used to return the length. The function handles any required conversion from the network byte order used in the header and the endian (big versus little) of the platform. See arm_generate_correlator() for a description of a correlator.

Parameters:
[in] correlator Pointer to a buffer containing a correlator. It serves no purpose to make the call if the pointer is null.
[out] length Pointer to an arm_correlator_length_t (a 16-bit integer) into which the ARM implementation will store the length. It serves no purpose to make the call if the pointer is null. If the pointer is not null, some value will be stored. The stored value will be the actual value if the value is apparently correct; otherwise, it will be zero. Examples of when zero would be stored are when the input correlator pointer is null or the length field is invalid, such as being greater than ARM_CORR_MAX_LENGTH bytes.
Returns:
The returned code is a status that may indicate whether an error was detected. If the return code is negative, an error occurred. If the return code is not negative, an error may or may not have occurred - the determination of what is an error and whether an error code is returned is at the discretion of the ARM implementation. The application can test the return code if it wants to provide its own error logging. See ARM error handling and error codes for further information about error handling.
See also:
arm_generate_correlator(), arm_start_transaction()
arm_get_error_message ( const arm_charset_t  charset,
const arm_error_t  code,
arm_message_buffer_t  msg 
)

get an error message

arm_get_error_message() stores a string containing an error message for the specified error code.

ARM implementations return values that are specific to the implementation. The only enforced convention is that a return code of zero indicates that no errors are reported (though an error could have occurred), and a negative return code indicates that some error occurred. Some implementations may report an error at times when another implementation would not.

To help an application developer or administrator understand what a negative error code means, arm_get_error_message() can be used to store a string containing an error message for the specified error code. The ARM library is not obliged to return a message, even if it returned a non-zero return code.

Parameters:
[in] charset An IANA (Internet Assigned Numbers Authority - see http://www.iana.org) MIBenum charset value [see arm_is_charset_supported()]. If a non-null message is returned, it will be in this encoding. It is strongly recommended that no value be used for charset that has not been tested for support by the library using arm_is_charset_supported().
[in] code An error code returned as arm_error_t from an API call.
[out] msg Pointer to a buffer that can contains 256 characters (including the termination character) into which the null-terminated error message will be copied. The message will be in the encoding specified by the charset parameter. If the implementation cannot honor the request, the implementation must store at least the null termination character (i.e., which it would do if it does not return a message or does not recognize the error code or cannot return the message in the application's encoding). The function is ignored if the pointer is null and an error status may be returned.
Returns:
The returned code is a status that may indicate whether an error was detected. If the return code is negative, an error occurred. If the return code is not negative, an error may or may not have occurred - the determination of what is an error and whether an error code is returned is at the discretion of the ARM implementation. The application can test the return code if it wants to provide its own error logging. See ARM error handling and error codes for further information about error handling.
See also:
arm_is_charset_supported()
arm_is_charset_supported ( const arm_charset_t  charset,
arm_boolean_t *  supported 
)

check supported character encoding

arm_is_charset_supported() indicates whether an ARM library supports a specified character encoding.

The default encoding for all strings provided by the application on all operating systems is UTF-8. An application may specify an alternate encoding when executing arm_register_application(), and then use it for all strings it provides on all calls including but should never do so without first issuing arm_register_application(), arm_is_charset_supported() to test whether the value is supported.

An ARM library on the operating systems listed in the following table must support the specified encodings. Applications are encouraged to use one of these encodings to ensure that any ARM implementation will support the application's ARM instrumentation. Another alternative is to use one of these encodings along with a preferred encoding. If the ARM library supports the preferred encoding, it is used; otherwise, one of the mandatory encodings is used.

IANA MIBenumCharacter Set Common Name UNIX & LinuxMicrosoft Windows IBM I5/OSIBM zOS
ARM_CHARSET_ASCII ASCII-7 (US-ASCII) YesYesYesYes
ARM_CHARSET_UTF8 UTF-8 (UCS-2 characters only) YesYesYesYes
ARM_CHARSET_UTF16LEUTF-16 Little Endian (UCS-2 characters only)  Yes  
ARM_CHARSET_IBM037 IBM037   Yes 
ARM_CHARSET_IBM1047IBM1047    Yes
Parameters:
[in] charset An IANA (Internet Assigned Numbers Authority - see www.iana.org) MIBenum charset value. Support for some values is mandatory by any ARM implementation on a specified platform, as shown in the table.
[out] supported Pointer to a boolean value that is set to ARM_TRUE or ARM_FALSE to indicate whether charset is a supported encoding.
Returns:
The returned code is a status that may indicate whether an error was detected. If the return code is negative, an error occurred. If the return code is not negative, an error may or may not have occurred - the determination of what is an error and whether an error code is returned is at the discretion of the ARM implementation. The application can test the return code if it wants to provide its own error logging. See ARM error handling and error codes for further information about error handling.
See also:
arm_get_error_message(), arm_register_application()
arm_register_application ( const arm_char_t *  app_name,
const arm_id_t *  input_app_id,
const arm_int32_t  flags,
const arm_buffer4_t *  buffer4,
arm_id_t *  output_app_id 
)

describes and registers the application with ARM

arm_register_application() describes metadata about an application.

The application uses arm_register_application() to inform the ARM library of metadata about the application. This metadata does not change from one application instance to another. It contains part of the function of the ARM 2.0 call arm_init(); arm_start_application() contains the other part.

ARM generates an ID that is passed in arm_register_transaction() and arm_start_application().

Returns:
The returned code is a status that may indicate whether an error was detected. If the return code is negative, an error occurred. If the return code is not negative, an error may or may not have occurred - the determination of what is an error and whether an error code is returned is at the discretion of the ARM implementation. The application can test the return code if it wants to provide its own error logging.
Parameters:
[in] app_name Pointer to a null-terminated string containing the name of the application. The maximum length of the name is 128 characters, including the termination character. It serves no purpose and is illegal to make this call if the pointer is null. A name should be chosen that is unique, so generic names that might be used by a different development team, such as "Payroll Application", should not be used. The name should not contain trailing blank characters or consist of only blank characters. If the application has a copyrighted product name, the copyrighted name would be a good choice.
[in] input_app_id Pointer to an optional 128-bit ID (16 bytes) that is unique and that can be treated as an alias for the other metadata. It can be any value except all zeros or all ones. If the pointer is null (ARM_ID_NONE), no ID is provided. See Unique ARM ID for further information.
If an ARM implementation is passed an ID that was previously registered within this process, the implementation can ignore the other metadata parameters and assume they are identical to the previously registered metadata. The application metadata consists of the following fields: app_name and the arm_subbuffer_app_identity_t sub-buffer passed in buffer4.
[in] flags Contains 32-bit flags. No values are currently defined. The field should be zero (ARM_FLAG_NONE).
[in] buffer4 Pointer to the optional buffer, if any. If the pointer is null (ARM_BUF4_NONE), buffer4 there is no buffer. The sub-buffer formats that might be used are:

  • arm_subbuffer_app_identity_t
  • arm_subbuffer_encoding_t
[in] output_app_id Pointer to a 16-byte field. ARM will store a 16-byte value. There are no requirements on what value it is set to, except that it must be possible to pass it on other calls, such as arm_start_application(), without the application needing to do any error checking.
Returns:
The returned code is a status that may indicate whether an error was detected. If the return code is negative, an error occurred. If the return code is not negative, an error may or may not have occurred - the determination of what is an error and whether an error code is returned is at the discretion of the ARM implementation. The application can test the return code if it wants to provide its own error logging. See ARM error handling and error codes for further information about error handling.
See also:
arm_destroy_application(), arm_register_transaction(), arm_start_application()
arm_register_metric ( const arm_id_t *  app_id,
const arm_char_t *  metric_name,
const arm_metric_format_t  metric_format,
const arm_metric_usage_t  metric_usage,
const arm_char_t *  metric_unit,
const arm_id_t *  input_metric_id,
const arm_int32_t  flags,
const arm_buffer4_t *  buffer4,
arm_id_t *  output_metric_id 
)

describes and register metrics with ARM

arm_register_metric() describes metadata about a metric.

The application uses arm_register_metric() to inform the ARM library of metadata about each metric the application provides.

ARM generates an ID that is passed in the metric binding sub-buffer (arm_subbuffer_metric_bindings_t) to arm_register_transaction().

Parameters:
[in] app_id Application ID returned from an arm_register_application() call in the same process.
[in] metric_name Pointer to a null-terminated string containing the name of the metric. The maximum name length of the string is 128 characters, including the termination character. It serves no purpose and is illegal to make this call if the pointer is null. The name should not contain trailing blank characters or consist of only blank characters.
The name can be any string, with one exception. Strings beginning with the four characters "ARM:" are reserved for the ARM specification. The specification will define names with known semantics using this prefix. One name format is currently defined. Any name beginning with the eight character prefix "ARM:CIM:" represents a name defined using the DMTF CIM (Distributed Management Task Force Common Information Model) naming rules. For example,"ARM:CIM:CIM_SoftwareElement.Name" indicates that the metric value has the semantics of the Name property of the CIM_SoftwareElement class. It is anticipated that additional naming semantics are likely to be added in the future.
[in] metric_format Describes the data type. The value must be one of the following:

[in] metric_usage Describes how the metric is used. The value must be one of the following values, or usage a negative value (any negative value is specific to the application; the negative values are not expected to be widely used).

[in] metric_unit Pointer to a null-terminated string containing the units (such as "files transferred") of the metric. The maximum length of the string is 128 characters, including the termination character. The pointer may be null.
[in] input_metric_id Pointer to an optional 128-bit ID (16 bytes) that is unique and that can be treated as an alias for the other metadata. It can be any value except all zeros or all ones. If the pointer is null (ARM_ID_NONE), no ID is provided. See Unique ARM ID for further information.
If an ARM implementation is passed an ID that was previously registered within this process, the implementation can ignore the other metadata parameters and assume they are identical to the previously registered metadata. The metric metadata consists of the following fields: app_id, metric_name, metric_format, metric_usage, and metric_unit.
[in] flags Contains 32-bit flags. No values are currently defined. The field should be zero (ARM_FLAG_NONE).
[in] buffer4 Pointer to the optional buffer, if any. If the pointer is null, there is no buffer. No sub-buffer types are currently valid with this function call, so the pointer should be null (ARM_BUF4_NONE).
[out] output_metric_id Pointer to a 16-byte field. ARM will store a 16-byte value. There are no requirements on the value it is set to, except that it must be possible to pass it in the metric binding sub-buffer (arm_subbuffer_metric_bindings_t) on the arm_register_transaction() call, without the application needing to do any error checking.
Returns:
The returned code is a status that may indicate whether an error was detected. If the return code is negative, an error occurred. If the return code is not negative, an error may or may not have occurred - the determination of what is an error and whether an error code is returned is at the discretion of the ARM implementation. The application can test the return code if it wants to provide its own error logging. See ARM error handling and error codes for further information about error handling.
See also:
arm_register_application(), arm_register_transaction()
arm_register_transaction ( const arm_id_t *  app_id,
const arm_char_t *  tran_name,
const arm_id_t *  input_tran_id,
const arm_int32_t  flags,
const arm_buffer4_t *  buffer4,
arm_id_t *  output_tran_id 
)

describes and register a transaction with ARM

arm_register_transaction() describes metadata about a transaction.

The application uses arm_register_transaction() to inform the ARM library of metadata about the transaction measured by the application. This metadata does not change from one application instance to another. It is the equivalent of the ARM 2.0 call arm_getid().

ARM generates an ID that is passed in arm_start_transaction() and arm_report_transaction().

Parameters:
[in] app_id Application ID returned from an arm_register_application() call in the same process.
[in] tran_name Pointer to a null-terminated string containing the name of the transaction. Each transaction registered by an application must have a unique name. The maximum length of the string is 128 characters, including the termination character. It serves no purpose and is illegal to make this call if the pointer is null. The name should not contain trailing blank characters or consist of only blank characters.
[in] input_tran_id Pointer to an optional 128-bit ID (16 bytes) that is unique and that can be treated as an alias for the other metadata. It can be any value except all zeros or all ones. If the pointer is null (ARM_ID_NONE), no ID is provided. See Unique ARM ID for further information.
If an ARM implementation is passed an ID that was previously registered within this process, the implementation can ignore the other metadata parameters and assume they are identical to the previously registered metadata. The transaction metadata consists of the following fields: app_id, tran_name, and the arm_subbuffer_metric_bindings_t and arm_subbuffer_tran_identity_t sub-buffers passed in buffer4.
[in] flags Contains 32-bit flags. No values are currently defined. The field should be zero (ARM_FLAG_NONE).
[in] buffer4 Pointer to the optional buffer, if any. If the pointer is null (ARM_BUF4_NONE), buffer4 there is no buffer. The sub-buffers that may be used are:

  • arm_subbuffer_metric_bindings_t
  • arm_subbuffer_tran_identity_t

The names of any transaction context properties are supplied in the arm_subbuffer_tran_identity_t sub-buffer. They do not change afterwards; that is, the names are immutable. The transaction context values may change with each arm_start_transaction(), arm_report_transaction(), or arm_generate_correlator().

[in] output_tran_id Pointer to a 16-byte field. ARM will store a 16-byte value. There are no requirements on the value it is set to, except that it must be possible to pass it on other calls, such as arm_start_transaction(), without the application needing to do any error checking.
See also:
arm_register_application(), arm_report_transaction(), arm_start_transaction()
arm_report_transaction ( const arm_app_start_handle_t  app_handle,
const arm_id_t *  tran_id,
const arm_tran_status_t  tran_status,
const arm_response_time_t  response_time,
const arm_stop_time_t  stop_time,
const arm_correlator_t *  parent_correlator,
const arm_correlator_t *  current_correlator,
const arm_int32_t  flags,
const arm_buffer4_t *  buffer4 
)

report transaction statistics

arm_report_transaction() is used to report statistics about a transaction that has already completed.

arm_report_transaction() may be used instead of a paired arm_start_transaction() and arm_stop_transaction() call. The application would have measured the response time. The transaction could have executed on the local system or on a remote system. If it executes on a remote system, the System Address sub-buffer passed on the arm_start_application() provides the addressing information for the remote system.

If the transaction represented by the arm_report_transaction() call is the correlation parent of another transaction, arm_generate_correlator() must be used to get a parent correlator, prior to invoking the child transaction (because it must be passed to the child). In this case, the sequence is the following:

  1. arm_generate_correlator() to get a correlator for this transaction.
  2. Invoke the child transaction, passing the correlator returned in step (1) to the child.
  3. When this transaction is complete, invoke arm_report_transaction() to report the statistics about the transaction.

When used, it prevents certain types of proactive management - such as monitoring for hung transactions or adjusting priorities - because the ARM implementation is not invoked when the transaction is started. Because of this, the use of arm_start_transction() and arm_stop_transaction() is preferred over arm_report_transaction().

The intended use is to report status and response time about transactions that recently completed (typically several seconds ago) in the absence of an ARM-enabled application and/or ARM implementation on the system on which the transaction executed.

Parameters:
[in] app_handle A handle returned in an out parameter from an arm_start_application() call in the same process.
[in] tran_id A transaction ID returned in an out parameter from an arm_register_transaction() call in the same process.
[in] tran_status Indicates the status of the transaction. The following values are allowed:

[in] response_time Response time in nanoseconds.
[in] stop_time An arm_int64_t that contains the number of milliseconds since Jan 1, 1970 using stop_time the Gregorian calendar. The time base is GMT (Greenwich Mean Time). There is one special value, ARM_USE_CURRENT_TIME, which means use the current time.
[in] parent_correlator Pointer to a parent correlator, if any. If the pointer is null (ARM_CORR_NONE), there is no parent correlator.
[out] current_correlator Pointer to the correlator for the transaction that has completed, if any. If the pointer is null (ARM_CORR_NONE), there is no current correlator.
[in] flags Contains 32-bit flags.

[in] buffer4 Pointer to the optional buffer, if any. If the pointer is null (ARM_BUF4_NONE), there is no buffer. The sub-buffers that may be used are:

  • arm_subbuffer_diag_detail_t
  • arm_subbuffer_diag_properties_t
  • arm_subbuffer_metric_values_t
  • arm_subbuffer_tran_context_t
  • arm_subbuffer_user_t
Returns:
The returned code is a status that may indicate whether an error was detected. If the return code is negative, an error occurred. If the return code is not negative, an error may or may not have occurred - the determination of what is an error and whether an error code is returned is at the discretion of the ARM implementation. The application can test the return code if it wants to provide its own error logging. See ARM error handling and error codes for further information about error handling.
See also:
arm_generate_correlator(), arm_register_transaction(), arm_start_application(), arm_start_transaction(), arm_stop_transaction()
arm_start_application ( const arm_id_t *  app_id,
const arm_char_t *  app_group,
const arm_char_t *  app_instance,
const arm_int32_t  flags,
const arm_buffer4_t *  buffer4,
arm_app_start_handle_t *  app_handle 
)

indicates that an instance of an application has started running

arm_start_application() indicates that an instance of an application has started running and is prepared to make ARM calls.

In many cases, there will be only one application instance in a process, but there are cases in which there could be multiple instances. An example of multiple application instances in the same process is if several Java applications run in the same JVM (Java Virtual Machine) in the same process, and they each call the ARM 4.0 C interface (either directly, or indirectly via an implementation of the ARM 4.0 Java interface). They might share the same application ID or they might be separately registered.

Application context properties may be used to differentiate between instances. The values do not have to be different from other instances, though making them unique is suggested. The context properties are provided through function parameters and/or a sub-buffer.

The group and instance names are provided as function parameters.

Up to twenty (name,value) pairs of context properties may be provided in a sub-buffer.

ARM 4.1 added a new capability for controlling the level of instrumentation that the ARM implementation prefers. It uses the Application Control sub-buffer (arm_subbuffer_app_control_t).

There is a special case in which a System Address sub-buffer is provided. The System Address sub-buffer is provided when arm_report_transaction() will be used to report data about transactions that executed on a different system. In this case, the arm_start_application() provides a scoping context for the transaction instances, but does not indicate that the application instance is running on the local system. If the System Address sub-buffer is provided, it is meaningless to use arm_start_transaction() or arm_stop_transaction(), or any of the API calls that are used after arm_start_transaction() and before arm_stop_transaction().

The combination of arm_register_application() and arm_start_application() is equivalent to the ARM 2.0 call arm_init().

Parameters:
[in] app_id Pointer to a 16-byte ID returned by an arm_register_application() call.
[in] app_group Pointer to a null-terminated string containing the identity of a group of application instances, if any. Application instances for a given software product that are started for a common runtime purpose are typically very good candidates for using the same group name. For example, identical replica instances of a product started across multiple processes or servers to address a specific transaction workload objective can be, advantageously to the ARM agent, commonly identified by the group name. The maximum length of the string is ARM_PROPERTY_VALUE_MAX_CHARS characters, including the termination character. A null pointer indicates that there is no group.
[in] app_instance Pointer to a null-terminated string containing the identity of this instance of the application. It might contain the process ID, or a UUID in printable characters, for example. The maximum length of the string is ARM_PROPERTY_VALUE_MAX_CHARS characters, including the termination character. A null pointer indicates that there is no instance value.
[in] flags Contains 32-bit flags. No values are currently defined. The field should be zero (ARM_FLAG_NONE).
[in] buffer4 Pointer to the optional buffer, if any. If the pointer is null (ARM_BUF4_NONE), there is no buffer. The sub-buffer formats that might be used are:

  • arm_subbuffer_app_context_t
  • arm_subbuffer_app_control_t
  • arm_subbuffer_system_address_t
    • If no System Address sub-buffer is provided on arm_start_application(), all transactions reported by this application instance execute in the current process.
    • If a System Address sub-buffer is provided on arm_start_application(), all transactions execute in a different process.
    • If a System Address sub-buffer is provided in which the system address length is zero, or the system address pointer is null, the system is the "local" system, as determined by the ARM implementation.
    • If a System Address sub-buffer is provided in which there is a non-null systemaddress and length, the system may be the local system or a remote system. Interpretation of what is local versus remote is at the discretion of the ARM implementation.
[out] app_handle Pointer to an arm_int64_t into which the ARM library will store the value of the handle that will represent the application instance in all calls, up to and including the arm_stop_application() that indicates that the instance has completed executing. The scope of the handle is the process in which the arm_start_application() is executed. There are no requirements on the value it is set to, except that it must be possible to pass it on other calls, such as arm_start_transaction(), without the application needing to do any error checking. Whether the data is meaningful, or partially meaningful, is at the discretion of the ARM implementation.
Returns:
The returned code is a status that may indicate whether an error was detected. If the return code is negative, an error occurred. If the return code is not negative, an error may or may not have occurred - the determination of what is an error and whether an error code is returned is at the discretion of the ARM implementation. The application can test the return code if it wants to provide its own error logging. See ARM error handling and error codes for further information about error handling.
See also:
arm_register_application(), arm_report_transaction(), arm_start_transaction(), arm_stop_application()
arm_start_transaction ( const arm_app_start_handle_t  app_handle,
const arm_id_t *  tran_id,
const arm_correlator_t *  parent_correlator,
const arm_int32_t  flags,
const arm_buffer4_t *  buffer4,
arm_tran_start_handle_t *  tran_handle,
arm_correlator_t *  current_correlator 
)

start transaction

arm_start_transaction() is used to indicate that a transaction is beginning execution.

Call arm_start_transaction() just prior to a transaction beginning execution. arm_start_transaction() signals the ARM library to start timing the transaction response time. There is one exception: when arm_get_arrival_time() is used to get a start time before arm_start_transaction() executes. See arm_get_arrival_time() to understand this usage.

arm_start_transaction() is also the means to pass to ARM the correlation token (called a "correlator" in ARM) from a caller - the "parent" - and to request a correlator that can be passed to transactions called by this transaction. The correlation token may be used to establish a calling hierarchy across processes and systems. A correlator contains a two-byte length field, a one-byte format ID, a one-byte flag field, plus it may contain other data that is used to uniquely identify an instance of a transaction. Applications do not need to understand correlator internals. The maximum length of a correlator is ARM_CORR_MAX_LENGTH bytes. (In ARM 2.0 it was 168 bytes.)

Parameters:
[in] app_handle A handle returned in an out parameter from an arm_start_application() call in the same process.
[in] tran_id A transaction ID returned in an out parameter from an arm_register_transaction() call in the same process.
[in] parent_correlator Pointer to the parent correlator, if any. The pointer may be null (ARM_CORR_NONE).
[in] flags Contains 32-bit flags.

[in] buffer4 Pointer to the optional buffer, if any. If the pointer is null (ARM_BUF4_NONE), there is no buffer. The sub-buffers that may be used are:

  • arm_subbuffer_arrival_time_t
  • arm_subbuffer_prep_stats_t
  • arm_subbuffer_prep_time_t
  • arm_subbuffer_formatted_arrival_time_msecJan1970_t
  • arm_subbuffer_formatted_arrival_time_strings_t
  • arm_subbuffer_message_rcvd_event_t
  • arm_subbuffer_message_sent_event_t
  • arm_subbuffer_metric_values_t
  • arm_subbuffer_tran_context_t
  • arm_subbuffer_user_t
[out] tran_handle Pointer to an arm_int64_t into which the ARM library will store the value of the handle that will represent the transaction instance in all calls, up to and including the arm_stop_transaction() that indicates that the instance has completed executing. The scope of the handle is the process in which the arm_start_transaction() is executed.
There are no defined behaviors for the value returned - it is implementation-defined. Note that the returned value will always be a value that the application can use in future calls that take a handle [arm_bind_thread(), arm_block_transaction(), arm_stop_transaction(), arm_unbind_thread(), arm_unblock_transaction(), and arm_arm_update_transaction()].
[out] current_correlator Pointer to a buffer into which the ARM implementation will store a correlator for the transaction instance, if any. The length of the buffer should be (at least) ARM_CORR_MAX_LENGTH) bytes.
If the pointer is null (ARM_CORR_NONE), the application is not requesting that a correlator be created.
If the pointer is not null, the application is requesting that a correlator be created. In this case the ARM implementation may (but need not) create a correlator in the buffer. It may not create a correlator if it does not support the function or if it is configured to not create a correlator.
After arm_start_transaction() completes, the application tests the length field using arm_get_correlator_length() to determine whether a correlator has been stored. If the length is still zero, no correlator has been stored. The ARM implementation must store zero in the length field if it does not generate a correlator.
Returns:
The returned code is a status that may indicate whether an error was detected. If the return code is negative, an error occurred. If the return code is not negative, an error may or may not have occurred - the determination of what is an error and whether an error code is returned is at the discretion of the ARM implementation. The application can test the return code if it wants to provide its own error logging. See ARM error handling and error codes for further information about error handling.
See also:
arm_bind_thread(), arm_block_transaction(), arm_get_arrival_time(), arm_get_correlator_length(), arm_register_transaction(), arm_start_application(), arm_stop_transaction(), arm_unbind_thread(), arm_unblock_transaction(), arm_update_transaction()
arm_stop_application ( const arm_app_start_handle_t  app_handle,
const arm_int32_t  flags,
const arm_buffer4_t *  buffer4 
)

stop application

arm_stop_application() indicates that the application instance has finished making ARM calls. It typically means that the instance is ending, such as just prior to the process exiting or a thread that represents an application instance terminating.

For any transactions that are still in-process [arm_start_transaction() executed without a matching arm_stop_transaction()], an implicit arm_discard_transaction() is executed.

If the arm_start_application() used the System Address sub-buffer to indicate that the ARM calls would be about an application instance on a different system, arm_stop_application() indicates that no more calls about that application instance and its transactions will be made.

After executing arm_stop_application(), no further calls should be made for this application, including calls for transactions created by this application, until a new instance "session" isstarted using arm_start_application(). Data from any other calls that are made will be ignored. This function is the equivalent of the ARM 2.0 function arm_end().

Parameters:
[in] app_handle A handle returned in an out parameter from an arm_start_application() call in the same process.
[in] flags Contains 32-bit flags. No values are currently defined. The field should be zero (ARM_FLAG_NONE).
[in] buffer4 Pointer to the optional buffer, if any. If the pointer is null, there is no buffer. No sub-buffer types are currently valid with this function call, so the pointer should be null (ARM_BUF4_NONE).
Returns:
The returned code is a status that may indicate whether an error was detected. If the return code is negative, an error occurred. If the return code is not negative, an error may or may not have occurred - the determination of what is an error and whether an error code is returned is at the discretion of the ARM implementation. The application can test the return code if it wants to provide its own error logging. See ARM error handling and error codes for further information about error handling.
See also:
arm_discard_transaction(), arm_start_application(), arm_start_transaction(), arm_stop_transaction()
arm_stop_transaction ( const arm_tran_start_handle_t  tran_handle,
const arm_tran_status_t  tran_status,
const arm_int32_t  flags,
const arm_buffer4_t *  buffer4 
)

stop transaction

arm_stop_transaction() signals the end of a transaction.

Call arm_stop_transaction() just after a transaction completes. arm_start_transaction() signals the ARM library to start timing the transaction response time. arm_stop_transaction() signals the ARM library to stop timing the transaction response time. It can be called from any thread in the process that executed the arm_start_transaction().

Implicit arm_unbind_thread() and arm_unblock_transaction() calls are made for any pending arm_bind_thread() and arm_block_transaction() calls, respectively, that have not been explicitly unbound or unblocked with arm_unbind_thread() and arm_unblock_transaction().

Parameters:
[in] tran_handle A handle returned in an out parameter from an arm_start_transaction() call in the same process.
[in] tran_status Indicates the status of the transaction. The following values are allowed:

[in] flags Contains 32-bit flags. No values are currently defined. The field should be zero (ARM_FLAG_NONE).
[in] buffer4 Pointer to the optional buffer, if any. If the pointer is null (ARM_BUF4_NONE), there is no buffer. The sub-buffers that may be used are:

  • arm_subbuffer_diag_detail_t
  • arm_subbuffer_diag_properties_t
  • arm_subbuffer_message_rcvd_event_t
  • arm_subbuffer_message_sent_event_t
  • arm_subbuffer_metric_values_t
Returns:
The returned code is a status that may indicate whether an error was detected. If the return code is negative, an error occurred. If the return code is not negative, an error may or may not have occurred - the determination of what is an error and whether an error code is returned is at the discretion of the ARM implementation. The application can test the return code if it wants to provide its own error logging. See ARM error handling and error codes for further information about error handling.
See also:
arm_bind_thread(), arm_block_transaction(), arm_start_transaction(), arm_unbind_thread(), arm_unblock_transaction()
arm_unbind_thread ( const arm_tran_start_handle_t  tran_handle,
const arm_int32_t  flags,
const arm_buffer4_t *  buffer4 
)

unbind a transaction from the excuting thread

arm_unbind_thread() indicates that the thread from which it is called is no longer performing on behalf of the transaction identified by the start handle.

Call arm_unbind_thread() when a thread is no longer executing a transaction. The thread binding is useful for managing computing resources at a finer level of granularity than the process. It should be called when, for this transaction and this thread, either:

arm_stop_transaction() is an implicit arm_unbind_thread() for any threads still bound to the transaction instance [arm_bind_thread() issued without a matching arm_unbind_thread()]. As long as the transaction is bound to the thread when the arm_stop_transaction() executes, there is no need nor any value in calling arm_unbind_thread() before calling arm_stop_transaction().

Parameters:
[in] tran_handle A handle returned in an out parameter from an arm_start_transaction() call in the same process.
[in] flags Contains 32-bit flags. No values are currently defined. The field should be zero (ARM_FLAG_NONE).
[in] buffer4 Pointer to the optional buffer, if any. If the pointer is null, there is no buffer. No sub-buffer types are currently valid with this function call, so the pointer should be null (ARM_BUF4_NONE).
Returns:
The returned code is a status that may indicate whether an error was detected. If the return code is negative, an error occurred. If the return code is not negative, an error may or may not have occurred - the determination of what is an error and whether an error code is returned is at the discretion of the ARM implementation. The application can test the return code if it wants to provide its own error logging. See ARM error handling and error codes for further information about error handling.
See also:
arm_bind_thread(), arm_start_transaction(), arm_stop_transaction()
arm_unblock_transaction ( const arm_tran_start_handle_t  tran_handle,
const arm_tran_block_handle_t  block_handle,
const arm_int32_t  flags,
const arm_buffer4_t *  buffer4 
)

unblock transaction

arm_unblock_transaction() indicates that the suspension indicated by the block_handle for the transaction identified by the start handle is no longer waiting for a downstream transaction to complete.

Call arm_unblock_transaction() when a transaction is no longer blocked on an external event. It should be called when arm_block_transaction() was previously called and the blocking condition no longer exists. Knowledge of when a transaction is blocked can be useful for better understanding response times. It is useful to separate out this "blocked" time from the elapsed start-to-stop time. The unblocked call is paired with a block call for finer grained analysis.

arm_stop_transaction() is an implicit arm_unblock_transaction() for any blocking condition for the transaction instance that has not been cleared yet [arm_block_transaction() issued without a matching arm_unblock_transaction()]. It should only be called without calling arm_unblock_transaction() first when the blocking condition ends immediately prior to the transaction ending.

Parameters:
[in] tran_handle A handle returned in an out parameter from an arm_start_transaction() call in the same process.
[in] block_handle A handle returned in an out parameter from an arm_block_transaction() call in the same process.
[in] flags Contains 32-bit flags. No values are currently defined. The field should be zero (ARM_FLAG_NONE).
[in] buffer4 Pointer to the optional buffer, if any. If the pointer is null, there is no buffer. The sub-buffers that may be used are:

  • arm_subbuffer_message_rcvd_event_t
  • arm_subbuffer_message_sent_event_t
Returns:
The returned code is a status that may indicate whether an error was detected. If the return code is negative, an error occurred. If the return code is not negative, an error may or may not have occurred - the determination of what is an error and whether an error code is returned is at the discretion of the ARM implementation. The application can test the return code if it wants to provide its own error logging. See ARM error handling and error codes for further information about error handling.
See also:
arm_block_transaction(), arm_start_transaction(), arm_stop_transaction()
arm_update_transaction ( const arm_tran_start_handle_t  tran_handle,
const arm_int32_t  flags,
const arm_buffer4_t *  buffer4 
)

update transaction status

arm_update_transaction() signals that a transaction is still processing.

arm_update_transaction() is useful as a heartbeat. It is also used to pass additional data about a transaction. It can be called from any thread in the process that executed the arm_start_transaction().

Parameters:
[in] tran_handle A handle returned in an out parameter from an arm_start_transaction() call in the same process.
[in] flags Contains 32-bit flags. No values are currently defined. The field should be zero (ARM_FLAG_NONE).
[in] buffer4 Pointer to the optional buffer, if any. If the pointer is null, there is no buffer. The sub-buffers that may be used are:

  • arm_subbuffer_message_rcvd_event_t
  • arm_subbuffer_message_sent_event_t
  • arm_subbuffer_metric_values_t
Returns:
The returned code is a status that may indicate whether an error was detected. If the return code is negative, an error occurred. If the return code is not negative, an error may or may not have occurred - the determination of what is an error and whether an error code is returned is at the discretion of the ARM implementation. The application can test the return code if it wants to provide its own error logging. See ARM error handling and error codes for further information about error handling.
See also:
arm_start_transaction(), arm_stop_transaction()
 All Data Structures Files Functions Variables Typedefs Defines
MyARM
Documentation generated on Thu May 24 2018 22:24:14. © 2018 by MyARM GmbH