arm_subbuffer_app_control Struct Reference [ARM 4.1 Sub-buffers]

The sub-buffer is used by applications to request the type and scope of instrumentation the ARM implementation prefers. More...

#include <arm41.h>

Data Fields
arm_subbuffer_t	header
arm_int32_t	control_count_app
arm_int32_t	control_count_arm
arm_boolean_t	app_control_used
arm_boolean_t	tran_id_control_used
arm_boolean_t	tran_instance_control_used
arm_int32_t	collection_depth
arm_boolean_t	show_private
arm_boolean_t	show_secure
arm_boolean_t	use_bind_thread
arm_boolean_t	use_block
arm_boolean_t	use_diagnostic
arm_boolean_t	use_message_event
arm_boolean_t	use_metric
arm_boolean_t	use_user

---

Detailed Description

The sub-buffer is used by applications to request the type and scope of instrumentation the ARM implementation prefers.

Its use is optional for both applications and ARM implementations. Further, the control settings represent preferences; they are not binding on the application.

The scope of the settings applies to all transactions registered by this application. These settings, except for app_control_used, tran_id_control_used, tran_instance_control_used, show_private, and show_secure may be overridden for specific transaction IDs and/or instances.

The Application Control sub-buffer is passed on arm_start_applicaiton() or with a special form of arm_generate_correlator(). This special form sets current_correlator = Null. Setting current_correlator = Null renders the arm_generate_correlator() call meaningless for the purpose of generating a correlator.

Note:

Some ARM 4.0 implementations do not expect to find a null current correlator value in arm_generate_correlator() and set the return code to –1012. See the Note in the arm_generate_correlator() description for an explanation of how to proceed.

The app_control_used setting is used as a handshake to determine whether both the application and the ARM implementation are using instrumentation control. Both must agree if instrumentation control is to be used. This provides protection for applications and implementations that do not support the capability.

Note:

A return value of app_control_used=False does not indicate that the ARM library is not collecting data. The application should continue to make ARM calls using its default assumptions about the appropriate amount of transaction detail.

---

Field Documentation

arm_boolean_t arm_subbuffer_app_control::app_control_used

A boolean that indicates whether instrumentation control is being used. This in/out value provides a handshake between the application and the ARM implementation to determine whether controls are used. This value must be set to False by the application. The ARM implementation leaves the value False if it is not using controls, such as if it does not recognize the sub-buffer or chooses not to use it. The meaning upon return from the API call is as follows:

• True = The other flags in the Application Control sub-buffer are set to meaningful values.
• False = All other values in the Application Control sub-buffer must be ignored and the Transaction ID Control and Transaction Instance Control sub-buffers must be ignored if either is passed.

arm_int32_t arm_subbuffer_app_control::collection_depth

A 32-bit integer that indicates the granularity of transactions that the ARM implementation prefers. This setting is orthogonal to other control settings, such as use_bind_thread and use_block. It influences only whether and how often start/update/stop API calls are used. If set to a value >0, then the following ARM capabilities should be used if the application supports them:

• arm_start_transaction()
• arm_update_transaction()
• arm_stop_transaction()
• Parent correlator
• Current correlator
• Application Identity sub-buffer (arm_subbuffer_app_identity_t)
• Application Context sub-buffer (arm_subbuffer_app_context_t)
• Transaction Identity sub-buffer (arm_subbuffer_tran_identity_t)
• Transaction Context sub-buffer (arm_subbuffer_tran_context_t) There are four possible values:
• ARM_COLLECTION_DEPTH_NONE
• ARM_COLLECTION_DEPTH_PROCESS
• ARM_COLLECTION_DEPTH_CONTAINER
• ARM_COLLECTION_DEPTH_MAX

arm_int32_t arm_subbuffer_app_control::control_count_app

A 32-bit integer constant that indicates the sub-buffer version used by the application. This provides a way to add new controls in later versions of ARM without breaking backwards compatibility. The version number equals the number of controls starting with app_control_used. For ARM 4.1 this value is ARM41_APP_CONTROL_COUNT.

arm_int32_t arm_subbuffer_app_control::control_count_arm

A 32-bit integer constant that indicates the sub-buffer version used by the ARM implementation. This provides a way to add new controls in later versions of ARM without breaking backwards compatibility. The version number equals the number of controls starting with app_control_used. For ARM 4.1 this value is ARM41_APP_CONTROL_COUNT.

arm_subbuffer_t arm_subbuffer_app_control::header

header.format must be set to ARM_SUBBUFFER_APP_CONTROL

arm_boolean_t arm_subbuffer_app_control::show_private

A boolean that indicates whether private data (e.g., account numbers) should be provided in any form, such as in a metric or diagnostic data, or in a correlator. The determination of what constitutes private data is made by the application.

• True = Provide private data
• False = Do not provide private data

arm_boolean_t arm_subbuffer_app_control::show_secure

A boolean that indicates whether secure data (e.g., passwords) should be provided in any form, such as in a metric or diagnostic data, or in a correlator. The determination of what constitutes secure data is made by the application.

• True = Provide secure data
• False = Do not provide secure data

arm_boolean_t arm_subbuffer_app_control::tran_id_control_used

A boolean that indicates whether the ARM implementation uses the Transaction ID Control sub-buffer. The Transaction ID Control sub-buffer is used to set the default collection parameters for all transaction instances for that registered ID.

• True = Preferences may be set at the (registered) transaction ID level, and therefore it would be useful to use the Transaction ID Control sub-buffer.
• False =The Transaction ID Control sub-buffer must be ignored if it is passed.

arm_boolean_t arm_subbuffer_app_control::tran_instance_control_used

A boolean that indicates whether the ARM implementation uses the Transaction Instance Control sub-buffer. The Transaction Instance Control sub-buffer is used to set the collection parameters for a single transaction instance.

• True = Preferences may be set at the transaction instance level, and therefore it would be useful to use the Transaction Instance Control sub-buffer.
• False = The Transaction Instance Control sub-buffer must be ignored if it is passed.

arm_boolean_t arm_subbuffer_app_control::use_bind_thread

A boolean that indicates that the implementation prefers that the application makes arm_bind_thread() and arm_unbind_thread() calls.

Note that this control is orthogonal to the collection_depth control for all values except ARM_COLLECTION_DEPTH_NONE if thread bindings are reported, then all thread bindings should be reported regardless of the number of arm_start_transaction() and arm_stop_transaction() calls.

• True = Call arm_bind_thread()/arm_unbind_thread() whenever a transaction is newly bound/unbound to/from a thread.
• False = The implementation will ignore any arm_bind_thread() and arm_unbind_thread() calls.

arm_boolean_t arm_subbuffer_app_control::use_block

A boolean that indicates that the implementation prefers that the application makes arm_block_transaction() and arm_unblock_transaction() calls, optionally passing the Block Cause sub-buffer on each call.

Note that this control is orthogonal to the collection_depth control for all values except ARM_COLLECTION_DEPTH_NONE if blocking conditions are reported then all blocking conditions should be reported regardless of the number of arm_start_transaction() and arm_stop_transaction() calls.

• True = Call arm_block_transaction()/arm_unblock_transaction() whenever a control flow is blocked waiting on an external event.
• False = The implementation will ignore any arm_block_transaction() and arm_unblock_transaction() calls.

arm_boolean_t arm_subbuffer_app_control::use_diagnostic

A boolean that indicates that the implementation prefers that the application use the Diagnostic Detail and/or Diagnostic Properties sub-buffers.

• True = Use the Diagnostic Detail and/or Diagnostic Properties sub-buffers whenever appropriate.
• False = The Diagnostic Detail and Diagnostic Properties sub-buffers will be ignored if they are passed.

arm_boolean_t arm_subbuffer_app_control::use_message_event

A boolean that indicates that the implementation prefers that the application inform it about message exchanges and other asynchronous flows.

• True = Use the Message Received and Message Sent sub-buffers, and use the ARM_SET_CORRELATOR_FLAG() macro to set the Asynchronous Flow and Independent Transaction flags.
• False = The Message Received and Message Sent sub-buffers will be ignored if they are passed.

arm_boolean_t arm_subbuffer_app_control::use_metric

A boolean that indicates that the implementation prefers that the application provide metric data.

• True = Use the Metric Values sub-buffer whenever appropriate.
• False = The Metric Values sub-buffer will be ignored if it is passed.

arm_boolean_t arm_subbuffer_app_control::use_user

A boolean that indicates that the implementation prefers that the application provide the identity of the user, if known.

• True = Use the User sub-buffer whenever appropriate.
• False = The User sub-buffer will be ignored if it is passed.

---

The documentation for this struct was generated from the following file:

• arm41.h