ARM 4.0 Sub-buffers [ARM 4.0]

Data Structures
struct	arm_subbuffer
	Generic sub-buffer structure. More...
struct	arm_buffer4
	User data buffer used to pass different kind of data to a function. More...
struct	arm_subbuffer_charset
	used to specify which charset the application uses. More...
struct	arm_subbuffer_app_identity
	used to specify additional identity properties for an application More...
struct	arm_subbuffer_app_context
	used to associate context properties to an application instance. More...
struct	arm_subbuffer_tran_identity
	used to specify additional identity properties for a transaction More...
struct	arm_subbuffer_tran_context
	used to associate context properties to a transaction instance. More...
struct	arm_subbuffer_arrival_time
	used to pass the arrival time for a transaction instance. More...
struct	arm_subbuffer_metric_bindings
	used to associate metrics to a transaction More...
struct	arm_subbuffer_metric_values
	used to pass a metric values to the ARM implementation. More...
struct	arm_subbuffer_user
	used to associate an user name and/or ID to a transaction instance. More...
struct	arm_subbuffer_system_address
	used to specify a different system than the one on which the call is executed. More...
struct	arm_subbuffer_diag_detail
	used to provide diagnostic detail information for not good transactions. More...
Defines
#define	ARM_SB(x)   (&((x).header))
	used to cast a specific sub-buffer to a pointer to arm_subbuffer_t.
Typedefs
typedef struct arm_subbuffer	arm_subbuffer_t
	Generic sub-buffer structure.
typedef struct arm_buffer4	arm_buffer4_t
	User data buffer used to pass different kind of data to a function.
typedef struct arm_subbuffer_charset	arm_subbuffer_charset_t
	used to specify which charset the application uses.
typedef struct arm_subbuffer_app_identity	arm_subbuffer_app_identity_t
	used to specify additional identity properties for an application
typedef struct arm_subbuffer_app_context	arm_subbuffer_app_context_t
	used to associate context properties to an application instance.
typedef struct arm_subbuffer_tran_identity	arm_subbuffer_tran_identity_t
	used to specify additional identity properties for a transaction
typedef struct arm_subbuffer_tran_context	arm_subbuffer_tran_context_t
	used to associate context properties to a transaction instance.
typedef struct arm_subbuffer_arrival_time	arm_subbuffer_arrival_time_t
	used to pass the arrival time for a transaction instance.
typedef struct arm_subbuffer_metric_bindings	arm_subbuffer_metric_bindings_t
	used to associate metrics to a transaction
typedef struct arm_subbuffer_metric_values	arm_subbuffer_metric_values_t
	used to pass a metric values to the ARM implementation.
typedef struct arm_subbuffer_user	arm_subbuffer_user_t
	used to associate an user name and/or ID to a transaction instance.
typedef struct arm_subbuffer_system_address	arm_subbuffer_system_address_t
	used to specify a different system than the one on which the call is executed.
typedef struct arm_subbuffer_diag_detail	arm_subbuffer_diag_detail_t
	used to provide diagnostic detail information for not good transactions.
#define	ARM_SUBBUFFER_USER   3
	User sub-buffer format see arm_subbuffer_user_t.
#define	ARM_SUBBUFFER_ARRIVAL_TIME   4
	Arrival time sub-buffer format see arm_subbuffer_arrival_time_t.
#define	ARM_SUBBUFFER_METRIC_VALUES   5
	Metric values sub-buffer format see arm_subbuffer_metric_values_t.
#define	ARM_SUBBUFFER_SYSTEM_ADDRESS   6
	System address sub-buffer format see arm_subbuffer_system_address_t.
#define	ARM_SUBBUFFER_DIAG_DETAIL   7
	Diagnostic detail sub-buffer format see arm_subbuffer_diag_detail_t.
#define	ARM_SUBBUFFER_APP_IDENTITY   102
	Application identity sub-buffer format see arm_subbuffer_app_identity_t.
#define	ARM_SUBBUFFER_APP_CONTEXT   103
	Application context sub-buffer format see arm_subbuffer_app_context_t.
#define	ARM_SUBBUFFER_TRAN_IDENTITY   104
	Transaction identity sub-buffer format see arm_subbuffer_tran_identity_t.
#define	ARM_SUBBUFFER_TRAN_CONTEXT   105
	Transaction context sub-buffer format see arm_subbuffer_tran_context_t.
#define	ARM_SUBBUFFER_METRIC_BINDINGS   106
	Metric bindings sub-buffer format see arm_subbuffer_metric_bindings_t.
#define	ARM_SUBBUFFER_CHARSET   107
	Character set encoding sub-buffer format see arm_subbuffer_charset_t.

---

Define Documentation

#define ARM_SB

(

x

)

(&((x).header))

used to cast a specific sub-buffer to a pointer to arm_subbuffer_t.

This macro could be used to cast a specific (arm_subbuffer_*_t) sub-buffer to an arm_subbuffer_t pointer compiler friendly.

Note for the special ARM SDK subbuffers the ARM_SDKSB() macro has to be used.

---

Typedef Documentation

typedef struct arm_buffer4 arm_buffer4_t

User data buffer used to pass different kind of data to a function.

Many of the ARM function calls provide a way for the application and ARM implementation to exchange optional data, in addition to the required data in other function parameters. This buffer describes the format of the exchanged data.

Almost all functions define a *buffer4 parameter. When the value is not null, the value points to a buffer in the following format. It differs from the ARM 2.0 format in that the buffer contains pointers to sub-buffers, rather than inline contiguous data. The sub-buffers contain the meaningful data.

Each sub-buffer may be in the optional buffer once. If there is more than one instance of a sub-buffer in the buffer, all instances after the first will be ignored.

The buffer is aligned on a pointer boundary for the platform. The byte layout depends on the platform.

typedef struct arm_subbuffer_app_context arm_subbuffer_app_context_t

used to associate context properties to an application instance.

Applications are identified by a name and an optional set of identity attribute (name,value) pairs. Application instances are further identified by an optional set of context (name,value) pairs. These properties could indicate something about the runtime instance of the application, such as the instance identifier and the name of a configuration file used.

The optional context property names are provided in the Application Identity sub-buffer (arm_subbuffer_app_identity_t) on the arm_register_application() call. The optional context property values are provided in this sub-buffer on the arm_start_application() call. The sub-buffer is ignored if it is passed on any other call.

typedef struct arm_subbuffer_app_identity arm_subbuffer_app_identity_t

used to specify additional identity properties for an application

Applications are identified by a name and an optional set of identity attribute (name,value) pairs. Application instances are further identified by an optional set of context (name,value) pairs. The optional context property names are provided in this sub-buffer on the arm_register_application() call. The optional context property values are provided on the arm_start_application() call. The sub-buffer is ignored if it is passed on any other call.

The names of identity and context properties 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 property 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.

typedef struct arm_subbuffer_arrival_time arm_subbuffer_arrival_time_t

used to pass the arrival time for a transaction instance.

Some applications may start processing a transaction before all the context information that identifies the transaction is known. For example, it might by necessary to retrieve the context information as the first step in processing the transaction.

When the application can call ARM when the transaction starts but not call arm_start_transaction() because it does not yet have all the data it needs, the application can call arm_get_arrival_time() to receive a timestamp value for the current time from the ARM implementation. This timestamp value is known as the "arrival time". When the transaction context data is all known, arm_start_transaction() is called, passing the optional arrival time value in the Arrival Time sub-buffer, to indicate when the transaction actually started executing.

The arrival time field is a 64-bit integer containing the value returned by the arm_get_arrival_time() function. The format of the data is implementation-defined.

typedef struct arm_subbuffer_charset arm_subbuffer_charset_t

used to specify which charset the application uses.

Applications may specify on arm_register_application() the character set encoding for all strings passed by the application. An ARM library must support certain encodings, depending on the platform. The application may always use one of the mandatory encodings. The <arm4.h> file defines names of the form ARM_CHARSET_* for all the mandatory encodings. The application may optionally ask the ARM library if another encoding is supported using arm_is_charset_supported().

When the application registers with arm_register_application(), it may optionally provide the Character Set Encoding sub-buffer. In the sub-buffer, the application specifies the MIBenum value of a character set encoding that has been assigned by the IANA (Internet Assigned Numbers Authority - see www.iana.org). The MIBenum value in the sub-buffer should only be either a mandatory encoding for the platform or a MIBenum value for which support has been verified using arm_is_charset_supported().

The encoding must comply with the following constraints:

• The character set must not contain any embedded null bytes. Exceptions are permitted for character sets that have fixed-length characters (e.g., two bytes) and that do not allow a character of all zeros (e.g., 0x0000). These include UTF-16LE, UTF-16BE, and UTF-16 (MIBenum values 1013, 1014, 1015). For these encodings, there will be a convention that a character of all zeros is the null-termination character.
• No more than three bytes may be used to encode each character.

For any encodings that are of a fixed size greater than one byte, such as UTF-16 (all characters are two bytes in length), the characters must be aligned on the natural boundary for the system (e.g., two-byte characters on a 16-bit boundary, etc.).

If an ARM implementation supports characters that are longer than one byte, the application and implementation are both responsible to cast (virtually, at least) the characters to wide characters, but the function signature does not change. For example, if UTF-16 is supported, the application must write pairs of characters into the arm_char_t* array (there would always be an even number of characters), and the implementation must process the data in pairs (looking for 0x0000 as a termination character rather than 0x00, for example).

typedef struct arm_subbuffer_diag_detail arm_subbuffer_diag_detail_t

used to provide diagnostic detail information for not good transactions.

When a transaction completion is reported with arm_stop_transaction() or arm_report_transaction(), and the transaction status is not ARM_STATUS_GOOD, the application may provide a character string containing any arbitrary diagnostic data. The string may not be longer than 4096 characters, including the null-termination character. For example, the application might provide the SQL query text for a failing database transaction.

typedef struct arm_subbuffer_metric_bindings arm_subbuffer_metric_bindings_t

used to associate metrics to a transaction

Applications may provide additional data about a transaction when the transaction starts, while it is executing, and/or after it has stopped. This additional data may serve several purposes, such as indicating the size of a transaction (e.g., the number of bytes in a file for a file transfer transaction), the state of the system (e.g., the number of queued up transactions when this transaction arrived), or an error code. The metadata describing each metric is provided with the arm_register_metric() function.

Each transaction definition may define zero to seven metrics for which data values may be provided on arm_start_transaction(), arm_update_transaction(), arm_stop_transaction(), or arm_report_transaction(). Each metric is assigned to an array slot numbered 0 to 6 (they were numbered 1 to 7 in ARM 2.0). This sub-buffer is passed on the arm_register_transaction() function to indicate which metrics are assigned to which slots.

The combination of this sub-buffer plus the arm_register_metric() function replaces ARM 2.0 format = 101. Unlike ARM 2.0, the metric definitions do not influence the transaction identity. Any properties besides the transaction name that affect identity are provided in the Transaction Identity Properties (arm_subbuffer_tran_identity_t) sub-buffer.

typedef struct arm_subbuffer_metric_values arm_subbuffer_metric_values_t

used to pass a metric values to the ARM implementation.

The buffer is used to pass metric values on any of arm_start_transaction(), arm_update_transaction(), arm_stop_transaction(), and arm_report_transaction().

typedef struct arm_subbuffer_system_address arm_subbuffer_system_address_t

used to specify a different system than the one on which the call is executed.

The System Address sub-buffer is used with arm_start_application() when the transactions that will be reported execute on a different system than the one on which they will be reported.

• 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 system address 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.

typedef struct arm_subbuffer arm_subbuffer_t

Generic sub-buffer structure.

Each sub-buffer has a sub-buffer format which specifies the specific sub-buffer.

typedef struct arm_subbuffer_tran_context arm_subbuffer_tran_context_t

used to associate context properties to a transaction instance.

In addition to the identity properties, a transaction may be described with additional context properties. Context properties differ from identity properties in that although the name is provided when the transaction is registered [arm_register_transaction()], the values are provided when a transaction is measured [arm_start_transaction() or arm_report_transaction()]. The value of an identity property never changes, whereas the value of a context property may change every time a transaction executes.

Context properties are of two forms. There may be one URI value and up to twenty (name,value) pairs. No name may duplicate the name of a transaction identity property.

typedef struct arm_subbuffer_tran_identity arm_subbuffer_tran_identity_t

used to specify additional identity properties for a transaction

Transactions are identified by a name, an optional URI value, and an optional set of attribute (name,value) pairs. The URI and optional (name,value) pairs are provided in this sub-buffer on the arm_register_transaction() call. The sub-buffer is ignored if it is passed on any other call. The identity is scoped to a single application.

The names of identity and context properties 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 property 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.

typedef struct arm_subbuffer_user arm_subbuffer_user_t

used to associate an user name and/or ID to a transaction instance.

An user name and/or ID may be optionally associated with each transaction instance. A name is a null-terminated character string. An ID is a 16-byte binary value, such as a UUID. Either or both may be provided.