ARM 4.0 standard header file. More...

#include "arm4os.h"
#include "arm4dyn.h"

Data Structures
struct	arm_id
	An ID is a 16-byte binary value, such as a UUID. More...
struct	arm_correlator
	ARM 4.0 correlator structure. More...
struct	arm_metric_cntrdivr32
	32-bit integer plus a 32-bit divisor, used to simulate floating-point counter. More...
struct	arm_metric_gaugedivr32
	32-bit integer plus a 32-bit divisor, used to simulate floating-point gauge. More...
struct	arm_metric
	used to pass a metric value to the ARM implementation. More...
struct	arm_metric_binding
	binds a metric definition (id) to a certain transaction metric slot. More...
struct	arm_property
	defines a name value property pair. More...
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.


#define	ARM_FALSE 0
	ARM false boolean.
#define	ARM_TRUE 1
	ARM true boolean.
#define	ARM_STATUS_GOOD 0
	transaction completed successfully
#define	ARM_STATUS_ABORTED 1
	transaction was aborted before it completed.
#define	ARM_STATUS_FAILED 2
	transaction completed in error
#define	ARM_STATUS_UNKNOWN 3
	transaction completed but the status was unknown.
#define	ARM_ERROR_CODE_RESERVED_MIN -20999
	reserved error code minimum start
#define	ARM_ERROR_CODE_RESERVED_MAX -20000
	reserved error code maximum end
#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	ARM_METRIC_FORMAT_RESERVED 0
	Reserved metric format.
#define	ARM_METRIC_FORMAT_COUNTER32 1
	arm_int32_t counter
#define	ARM_METRIC_FORMAT_COUNTER64 2
	arm_int64_t counter
#define	ARM_METRIC_FORMAT_CNTRDIVR32 3
	arm_int32_t counter + arm_int32_t divisor
#define	ARM_METRIC_FORMAT_GAUGE32 4
	arm_int32_t gauge
#define	ARM_METRIC_FORMAT_GAUGE64 5
	arm_int64_t gauge
#define	ARM_METRIC_FORMAT_GAUGEDIVR32 6
	arm_int32_t gauge + arm_int32_t divisor
#define	ARM_METRIC_FORMAT_NUMERICID32 7
	arm_int32_t numeric ID
#define	ARM_METRIC_FORMAT_NUMERICID64 8
	arm_int64_t numeric ID
#define	ARM_METRIC_FORMAT_STRING32 10
	string (null-terminated) of a maximum length of 32 characters (33 including the null termination character)
#define	ARM_METRIC_USE_GENERAL 0
	a metric without a specified usage.
#define	ARM_METRIC_USE_TRAN_SIZE 1
	a metric that indicates the "size" of a transaction.
#define	ARM_METRIC_USE_TRAN_STATUS 2
	a metric that further explains the transaction status such as a sense code that explains why a transaction failed.
#define	ARM_METRIC_MIN_ARRAY_INDEX 0
	minimum array index for metric values and bindings.
#define	ARM_METRIC_MAX_ARRAY_INDEX 6
	maximum array index for metric values and bindings.
#define	ARM_METRIC_MAX_COUNT 7
	maximum array count for metric values and bindings.
#define	ARM_METRIC_STRING32_MAX_CHARS 31
	maximum characters for a string metric
#define	ARM_METRIC_STRING32_MAX_LENGTH (ARM_METRIC_STRING32_MAX_CHARS*3+1)
	maximum bytes for a string metric
#define	ARM_NAME_MAX_CHARS 127
	maximum characters for names
#define	ARM_NAME_MAX_LENGTH (ARM_NAME_MAX_CHARS*3+1)
	maximum number of bytes for names
#define	ARM_DIAG_DETAIL_MAX_CHARS 4095
	maximum characters for diagnostic detail string
#define	ARM_DIAG_DETAIL_MAX_LENGTH (ARM_DIAG_DETAIL_MAX_CHARS*3+1)
	maximum number of bytes for diagnostic detail string
#define	ARM_MSG_BUFFER_CHARS 255
	maximum characters for message buffers
#define	ARM_MSG_BUFFER_LENGTH (ARM_MSG_BUFFER_CHARS*3+1)
	maximum number of bytes for message buffers
#define	ARM_PROPERTY_MIN_ARRAY_INDEX 0
	minimum array index for property names and values
#define	ARM_PROPERTY_MAX_ARRAY_INDEX 19
	maximum array index for property names and values
#define	ARM_PROPERTY_MAX_COUNT 20
	maximum array count for property names and values
#define	ARM_PROPERTY_NAME_MAX_CHARS (ARM_NAME_MAX_CHARS)
	maximum characters for property names
#define	ARM_PROPERTY_NAME_MAX_LENGTH (ARM_PROPERTY_NAME_MAX_CHARS*3+1)
	maximum number of bytes for property names
#define	ARM_PROPERTY_VALUE_MAX_CHARS 255
	maximum characters for property values
#define	ARM_PROPERTY_VALUE_MAX_LENGTH (ARM_PROPERTY_VALUE_MAX_CHARS*3+1)
	maximum number of bytes for property values
#define	ARM_PROPERTY_URI_MAX_CHARS 4095
	maximum characters for a uri property
#define	ARM_PROPERTY_URI_MAX_LENGTH (ARM_PROPERTY_URI_MAX_CHARS*3+1)
	maximum number of bytes for a uri property
#define	ARM_SYSADDR_FORMAT_RESERVED 0
	reserved by the standard
#define	ARM_SYSADDR_FORMAT_IPV4 1
	IP address.
#define	ARM_SYSADDR_FORMAT_IPV4PORT 2
	IP address and port number.
#define	ARM_SYSADDR_FORMAT_IPV6 3
	IP v6 address.
#define	ARM_SYSADDR_FORMAT_IPV6PORT 4
	IP v6 address and port number.
#define	ARM_SYSADDR_FORMAT_SNA 5
	SNA address.
#define	ARM_SYSADDR_FORMAT_X25 6
	X25 address.
#define	ARM_SYSADDR_FORMAT_HOSTNAME 7
	hostname string
#define	ARM_SYSADDR_FORMAT_UUID 8
	UUID address alias.
#define	ARM_CHARSET_ASCII 3
	ASCII-7 (US-ASCII) mandatory on all systems.
#define	ARM_CHARSET_UTF8 106
	UTF-8 (UCS-2 characters only) mandatory on all systems.
#define	ARM_CHARSET_UTF16BE 1013
	UTF-16 Big Endian (UCS-2 characters only).
#define	ARM_CHARSET_UTF16LE 1014
	UTF-16 Little Endian (UCS-2 characters only) mandatory on Microsoft Windows.
#define	ARM_CHARSET_UTF16 1015
	UTF-16 Little and Big Endian (UCS-2 characters only).
#define	ARM_CHARSET_IBM037 2028
	IBM037 mandatory on IBM iSeries.
#define	ARM_CHARSET_IBM1047 2102
	IBM1047 mandatory on IBM zSeries.
#define	ARM_FLAG_NONE (0x00000000)
	use instead of zero to be more readable.
#define	ARM_FLAG_TRACE_REQUEST (0x00000001)
	is set to 1 if the application requests/suggests a trace.
#define	ARM_FLAG_BIND_THREAD (0x00000002)
	is set to 1 if the started transaction is bound to this thread.
#define	ARM_FLAG_CORR_IN_PROCESS (0x00000004)
	is set to 1 if the application is stating that it will not send the correlator outside the current process.
#define	ARM_CORR_MAX_LENGTH 512
	total maximal length of an ARM 4.x correlator.
#define	ARM_CORR_FLAGNUM_APP_TRACE 1
	Application trace flag number.
#define	ARM_CORR_FLAGNUM_AGENT_TRACE 2
	Agent trace flag number.
#define	ARM_CORR_NONE ((arm_correlator_t *) NULL)
	Used to pass no correlator to various functions calls (e.g. arm_start_transaction()).
#define	ARM_USE_CURRENT_TIME ((arm_stop_time_t)-1)
	short cut for capturing the current time within arm_report_transaction().
#define	ARM_BUF4_NONE ((arm_buffer4_t*) NULL)
	to be used instead of a NULL to be more readable for arm_buffer4_t null pointers.
#define	ARM_ID_NONE ((arm_id_t *) NULL)
	to be used instead of a NULL to be more readable for arm_id_t null pointers.
#define	ARM_STRING_NONE ((arm_char_t *) NULL)
	to be used instead of a NULL to be more readable.
Typedefs
typedef ARM4_CHAR	arm_char_t
typedef ARM4_INT8	arm_int8_t
typedef ARM4_UINT8	arm_uint8_t
typedef ARM4_INT16	arm_int16_t
typedef ARM4_UINT16	arm_uint16_t
typedef ARM4_INT32	arm_int32_t
typedef ARM4_UINT32	arm_uint32_t
typedef ARM4_INT64	arm_int64_t
typedef ARM4_UINT64	arm_uint64_t
typedef arm_int32_t	arm_boolean_t
typedef arm_int32_t	arm_error_t
typedef arm_int64_t	arm_arrival_time_t
typedef arm_int64_t	arm_stop_time_t
typedef arm_int64_t	arm_response_time_t
typedef arm_int32_t	arm_tran_status_t
typedef arm_int32_t	arm_charset_t
typedef arm_int32_t	arm_sysaddr_format_t
typedef arm_char_t	arm_message_buffer_t [ARM_MSG_BUFFER_LENGTH]
typedef arm_int32_t	arm_subbuffer_format_t
typedef arm_uint8_t	arm_metric_format_t
typedef arm_uint8_t	arm_metric_slot_t
typedef arm_int16_t	arm_metric_usage_t
typedef arm_int64_t	arm_app_start_handle_t
typedef arm_int64_t	arm_tran_start_handle_t
typedef arm_int64_t	arm_tran_block_handle_t
typedef arm_int16_t	arm_correlator_length_t
typedef struct arm_id	arm_id_t
	An ID is a 16-byte binary value, such as a UUID.
typedef struct arm_correlator	arm_correlator_t
	ARM 4.0 correlator structure.
typedef arm_int32_t	arm_metric_counter32_t
	32-bit integer metric counter type
typedef arm_int64_t	arm_metric_counter64_t
	64-bit integer metric counter type
typedef arm_int32_t	arm_metric_divisor32_t
	32-bit integer metric divisor type
typedef arm_int32_t	arm_metric_gauge32_t
	32-bit integer metric gauge type
typedef arm_int64_t	arm_metric_gauge64_t
	64-bit integer metric gauge type
typedef arm_int32_t	arm_metric_numericID32_t
	32-bit integer metric numeric id type
typedef arm_int64_t	arm_metric_numericID64_t
	64-bit integer metric numeric id type
typedef const arm_char_t *	arm_metric_string32_t
	32 character wide string type.
typedef struct arm_metric_cntrdivr32	arm_metric_cntrdivr32_t
	32-bit integer plus a 32-bit divisor, used to simulate floating-point counter.
typedef struct arm_metric_gaugedivr32	arm_metric_gaugedivr32_t
	32-bit integer plus a 32-bit divisor, used to simulate floating-point gauge.
typedef struct arm_metric	arm_metric_t
	used to pass a metric value to the ARM implementation.
typedef struct arm_metric_binding	arm_metric_binding_t
	binds a metric definition (id) to a certain transaction metric slot.
typedef struct arm_property	arm_property_t
	defines a name value property pair.
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.
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

Detailed Description

ARM 4.0 standard header file.

This header file defines all defines, typedefs, structures, and API functions visible for an application which uses an ARM agent. All compiler/platform specifics are handled in a separate header file named <arm4os.h>.