arm4.h

Go to the documentation of this file.

/* ------------------------------------------------------------------------- */
/*                                                                           */
/* Copyright (c) 2003-2007 The Open Group                                    */
/*                                                                           */
/* Permission is hereby granted, free of charge, to any person obtaining a   */
/* copy of this software (the "Software"), to deal in the Software without   */
/* restriction, including without limitation the rights to use, copy,        */
/* modify, merge, publish, distribute, sublicense, and/or sell copies of     */
/* the Software, and to permit persons to whom the Software is furnished     */
/* to do so, subject to the following conditions:                            */
/*                                                                           */
/* The above copyright notice and this permission notice shall be included   */
/* in all copies or substantial portions of the Software.                    */
/*                                                                           */
/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS   */
/* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF                */
/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.    */
/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY      */
/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT */
/* OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR  */
/* THE USE OR OTHER DEALINGS IN THE SOFTWARE.                                */
/*                                                                           */
/* ------------------------------------------------------------------------- */
/*                                                                           */
/* This file corresponds to following documentation:                         */
/*                                                                           */
/* Technical Standard                                                        */
/* Application Response Measurement (ARM)                                    */
/* Issue 4.1 Version 1 - C Binding                                           */
/*                                                                           */
/* ------------------------------------------------------------------------- */

#ifndef ARM4_H_INCLUDED
#define ARM4_H_INCLUDED

#ifndef ARM4OS_H_INCLUDED
#include "arm4os.h"
#endif /* ARM4OS_H_INCLUDED */

#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

/* ------------------------------------------------------------------------- */
/* ---------------------------- defines section ---------------------------- */
/* ------------------------------------------------------------------------- */

/* ----------------------------- Boolean values ----------------------------- */

#define ARM_FALSE                               0

#define ARM_TRUE                                1

/* --------------------------- Transaction status --------------------------- */

#define ARM_STATUS_GOOD                         0

#define ARM_STATUS_ABORTED                      1

#define ARM_STATUS_FAILED                       2

#define ARM_STATUS_UNKNOWN                      3

/* ----------------------- Reserved error codes range ----------------------- */

#define ARM_ERROR_CODE_RESERVED_MIN        -20999

#define ARM_ERROR_CODE_RESERVED_MAX        -20000

/* ------------------------ known sub-buffer formats ------------------------ */

#define ARM_SUBBUFFER_USER                      3

#define ARM_SUBBUFFER_ARRIVAL_TIME              4

#define ARM_SUBBUFFER_METRIC_VALUES             5

#define ARM_SUBBUFFER_SYSTEM_ADDRESS            6

#define ARM_SUBBUFFER_DIAG_DETAIL               7

#define ARM_SUBBUFFER_APP_IDENTITY            102

#define ARM_SUBBUFFER_APP_CONTEXT             103

#define ARM_SUBBUFFER_TRAN_IDENTITY           104

#define ARM_SUBBUFFER_TRAN_CONTEXT            105

#define ARM_SUBBUFFER_METRIC_BINDINGS         106

#define ARM_SUBBUFFER_CHARSET                 107

/* ----------------------------- metric defines ----------------------------- */

#define ARM_METRIC_FORMAT_RESERVED              0

#define ARM_METRIC_FORMAT_COUNTER32             1

#define ARM_METRIC_FORMAT_COUNTER64             2

#define ARM_METRIC_FORMAT_CNTRDIVR32            3

#define ARM_METRIC_FORMAT_GAUGE32               4

#define ARM_METRIC_FORMAT_GAUGE64               5

#define ARM_METRIC_FORMAT_GAUGEDIVR32           6

#define ARM_METRIC_FORMAT_NUMERICID32           7

#define ARM_METRIC_FORMAT_NUMERICID64           8
/* format 9 (string8) is deprecated */
#define ARM_METRIC_FORMAT_STRING32             10

#define ARM_METRIC_USE_GENERAL                  0

#define ARM_METRIC_USE_TRAN_SIZE                1

#define ARM_METRIC_USE_TRAN_STATUS              2

#define ARM_METRIC_MIN_ARRAY_INDEX              0

#define ARM_METRIC_MAX_ARRAY_INDEX              6

#define ARM_METRIC_MAX_COUNT                    7

#define ARM_METRIC_STRING32_MAX_CHARS          31

#define ARM_METRIC_STRING32_MAX_LENGTH \
    (ARM_METRIC_STRING32_MAX_CHARS*3+1)

/* -------------------------- misc string defines --------------------------- */

#define ARM_NAME_MAX_CHARS                    127

#define ARM_NAME_MAX_LENGTH (ARM_NAME_MAX_CHARS*3+1)

#define ARM_DIAG_DETAIL_MAX_CHARS            4095

#define ARM_DIAG_DETAIL_MAX_LENGTH (ARM_DIAG_DETAIL_MAX_CHARS*3+1)

#define ARM_MSG_BUFFER_CHARS                  255

#define ARM_MSG_BUFFER_LENGTH (ARM_MSG_BUFFER_CHARS*3+1)


/* --------------------------- properties defines --------------------------- */

#define ARM_PROPERTY_MIN_ARRAY_INDEX            0

#define ARM_PROPERTY_MAX_ARRAY_INDEX           19

#define ARM_PROPERTY_MAX_COUNT                 20

#define ARM_PROPERTY_NAME_MAX_CHARS (ARM_NAME_MAX_CHARS)

#define ARM_PROPERTY_NAME_MAX_LENGTH \
    (ARM_PROPERTY_NAME_MAX_CHARS*3+1)

#define ARM_PROPERTY_VALUE_MAX_CHARS          255

#define ARM_PROPERTY_VALUE_MAX_LENGTH \
    (ARM_PROPERTY_VALUE_MAX_CHARS*3+1)

#define ARM_PROPERTY_URI_MAX_CHARS           4095

#define ARM_PROPERTY_URI_MAX_LENGTH (ARM_PROPERTY_URI_MAX_CHARS*3+1)


/* ---------------------- system address format values ---------------------- */

#define ARM_SYSADDR_FORMAT_RESERVED             0

#define ARM_SYSADDR_FORMAT_IPV4                 1

#define ARM_SYSADDR_FORMAT_IPV4PORT             2

#define ARM_SYSADDR_FORMAT_IPV6                 3

#define ARM_SYSADDR_FORMAT_IPV6PORT             4

#define ARM_SYSADDR_FORMAT_SNA                  5

#define ARM_SYSADDR_FORMAT_X25                  6

#define ARM_SYSADDR_FORMAT_HOSTNAME             7

#define ARM_SYSADDR_FORMAT_UUID                 8

/* ------------------------ mandatory charsets ------------------------------ */

/* IANA charset MIBenum numbers (http://www.iana.org/) */
#define ARM_CHARSET_ASCII                       3

#define ARM_CHARSET_UTF8                      106

#define ARM_CHARSET_UTF16BE                  1013

#define ARM_CHARSET_UTF16LE                  1014

#define ARM_CHARSET_UTF16                    1015

#define ARM_CHARSET_IBM037                   2028

#define ARM_CHARSET_IBM1047                  2102

/* -------------------- flags to be passed on API calls --------------------- */

#define ARM_FLAG_NONE                (0x00000000)

#define ARM_FLAG_TRACE_REQUEST       (0x00000001)

#define ARM_FLAG_BIND_THREAD         (0x00000002)

#define ARM_FLAG_CORR_IN_PROCESS     (0x00000004)

/* --------------------------- correlator defines --------------------------- */

#define ARM_CORR_MAX_LENGTH                   512

#define ARM_CORR_FLAGNUM_APP_TRACE              1

#define ARM_CORR_FLAGNUM_AGENT_TRACE            2

#define ARM_CORR_NONE ((arm_correlator_t *) NULL)

/* ---------- current time for arm_report_transaction() stop time ----------- */

#define ARM_USE_CURRENT_TIME ((arm_stop_time_t)-1)

/* ------------------------------ misc defines ------------------------------ */

#define ARM_BUF4_NONE ((arm_buffer4_t*) NULL)

#define ARM_ID_NONE ((arm_id_t *) NULL)

#define ARM_STRING_NONE ((arm_char_t *) NULL)

/* -------------------------------------------------------------------------- */
/* ------------------------- basic typedef section -------------------------- */
/* -------------------------------------------------------------------------- */

/* ARM4_*INT* defines are set in the <arm4os.h> header file.       
   They are platform/compiler-specific.                                       */
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; 
/* -------------------------------------------------------------------------- */
/* ----------------------- compound typedefs section ------------------------ */
/* -------------------------------------------------------------------------- */

typedef struct arm_id
{
    union
    {
        arm_uint8_t  uint8[16];
        arm_uint32_t uint32[4];
        arm_uint64_t uint64[2];
    } id_u;
} arm_id_t;

typedef struct arm_correlator
{
    arm_uint8_t opaque[ARM_CORR_MAX_LENGTH];
} arm_correlator_t;

/* ----------------------- user defined metric types ------------------------ */

typedef arm_int32_t arm_metric_counter32_t;
typedef arm_int64_t arm_metric_counter64_t;
typedef arm_int32_t arm_metric_divisor32_t;
typedef arm_int32_t arm_metric_gauge32_t;
typedef arm_int64_t arm_metric_gauge64_t;
typedef arm_int32_t arm_metric_numericID32_t;
typedef arm_int64_t arm_metric_numericID64_t;
typedef const arm_char_t *arm_metric_string32_t;

typedef struct arm_metric_cntrdivr32
{
    arm_metric_counter32_t counter;
    arm_metric_divisor32_t divisor;
} arm_metric_cntrdivr32_t;
typedef struct arm_metric_gaugedivr32
{
    arm_metric_gauge32_t gauge;
    arm_metric_divisor32_t divisor;
} arm_metric_gaugedivr32_t;

typedef struct arm_metric
{
    arm_metric_slot_t slot;
    arm_metric_format_t format;
    arm_metric_usage_t usage;
    arm_boolean_t valid;
    union
    {
        arm_metric_counter32_t counter32;
        arm_metric_counter64_t counter64;
        arm_metric_cntrdivr32_t counterdivisor32;
        arm_metric_gauge32_t gauge32;
        arm_metric_gauge64_t gauge64;
        arm_metric_gaugedivr32_t gaugedivisor32;
        arm_metric_numericID32_t numericid32;
        arm_metric_numericID64_t numericid64;
        arm_metric_string32_t string32;
    } metric_u;
} arm_metric_t;

typedef struct arm_metric_binding
{
    arm_metric_slot_t slot;
    arm_id_t id;
} arm_metric_binding_t;

typedef struct arm_property
{
    const arm_char_t *name;
    const arm_char_t *value;
} arm_property_t;

/* ------------------------------------------------------------------------- */
/* ---------------------- sub-buffer typedefs section ---------------------- */
/* ------------------------------------------------------------------------- */

typedef struct arm_subbuffer {
    arm_subbuffer_format_t format;
} arm_subbuffer_t;

#define ARM_SB(x)  (&((x).header))

typedef struct arm_buffer4
{
    arm_int32_t count;
    arm_subbuffer_t **subbuffer_array;
} arm_buffer4_t;

/* ------------------------------------------------------------------------- */

typedef struct arm_subbuffer_charset
{
    arm_subbuffer_t header;

    arm_charset_t charset;
    arm_int32_t flags;
} arm_subbuffer_charset_t;

typedef struct arm_subbuffer_app_identity
{
    arm_subbuffer_t header;
    arm_int32_t identity_property_count;
    const arm_property_t *identity_property_array;
    arm_int32_t context_name_count;
    const arm_char_t **context_name_array;
} arm_subbuffer_app_identity_t;

typedef struct arm_subbuffer_app_context
{
    arm_subbuffer_t header;

    arm_int32_t context_value_count;
    const arm_char_t **context_value_array;
} arm_subbuffer_app_context_t;

typedef struct arm_subbuffer_tran_identity
{
    arm_subbuffer_t header;

    arm_int32_t identity_property_count;
    const arm_property_t *identity_property_array;
    arm_int32_t context_name_count;
    const arm_char_t **context_name_array;
    const arm_char_t *uri;
} arm_subbuffer_tran_identity_t;

typedef struct arm_subbuffer_tran_context
{
    arm_subbuffer_t header;

    arm_int32_t context_value_count;
    const arm_char_t **context_value_array;
    const arm_char_t *uri;
} arm_subbuffer_tran_context_t;

typedef struct arm_subbuffer_arrival_time
{
    arm_subbuffer_t header;
    arm_arrival_time_t opaque_time;
} arm_subbuffer_arrival_time_t;

typedef struct arm_subbuffer_metric_bindings
{
    arm_subbuffer_t header;

    arm_int32_t count;
    const arm_metric_binding_t *metric_binding_array;
} arm_subbuffer_metric_bindings_t;

typedef struct arm_subbuffer_metric_values
{
    arm_subbuffer_t header;

    arm_int32_t count;
    const arm_metric_t *metric_value_array;
} arm_subbuffer_metric_values_t;

typedef struct arm_subbuffer_user
{
    arm_subbuffer_t header;

    const arm_char_t *name;
    arm_boolean_t id_valid;
    arm_id_t id;
} arm_subbuffer_user_t;

typedef struct arm_subbuffer_system_address
{
    arm_subbuffer_t header;

    arm_int16_t address_format;
    arm_int16_t address_length;
    const arm_uint8_t *address;
    arm_boolean_t id_valid;
    arm_id_t id;
} arm_subbuffer_system_address_t;

typedef struct arm_subbuffer_diag_detail
{
    arm_subbuffer_t header;

    const arm_char_t *diag_detail;
} arm_subbuffer_diag_detail_t;

/* -------------------------------------------------------------------------- */
/* ---------------------------- ARM4 API section ---------------------------- */
/* -------------------------------------------------------------------------- */

/* -------------------- register metadata API functions --------------------- */

ARM4_API_DYNAMIC(arm_error_t)
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);

ARM4_API_DYNAMIC(arm_error_t)
arm_destroy_application(
    const arm_id_t *app_id,
    const arm_int32_t flags,
    const arm_buffer4_t *buffer4);

ARM4_API_DYNAMIC(arm_error_t)
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);

ARM4_API_DYNAMIC(arm_error_t)
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);

ARM4_API_DYNAMIC(arm_error_t)
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);

ARM4_API_DYNAMIC(arm_error_t)
arm_stop_application(
    const arm_app_start_handle_t app_handle,
    const arm_int32_t flags,
    const arm_buffer4_t *buffer4);

ARM4_API_DYNAMIC(arm_error_t)
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);

ARM4_API_DYNAMIC(arm_error_t)
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);

ARM4_API_DYNAMIC(arm_error_t)
arm_update_transaction(
    const arm_tran_start_handle_t tran_handle,
    const arm_int32_t flags,
    const arm_buffer4_t *buffer4);

ARM4_API_DYNAMIC(arm_error_t)
arm_discard_transaction(
    const arm_tran_start_handle_t tran_handle,
    const arm_int32_t flags,
    const arm_buffer4_t *buffer4);

ARM4_API_DYNAMIC(arm_error_t)
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);

ARM4_API_DYNAMIC(arm_error_t)
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);

/* thread support API functions */
ARM4_API_DYNAMIC(arm_error_t)
arm_bind_thread(
    const arm_tran_start_handle_t tran_handle,
    const arm_int32_t flags,
    const arm_buffer4_t *buffer4);

ARM4_API_DYNAMIC(arm_error_t)
arm_unbind_thread(
    const arm_tran_start_handle_t tran_handle,
    const arm_int32_t flags,
    const arm_buffer4_t *buffer4);

ARM4_API_DYNAMIC(arm_error_t)
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);

/* correlator API functions */
ARM4_API_DYNAMIC(arm_error_t)
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);

ARM4_API_DYNAMIC(arm_error_t)
arm_get_correlator_length(
    const arm_correlator_t *correlator,
    arm_correlator_length_t *length);

ARM4_API_DYNAMIC(arm_error_t)
arm_get_correlator_flags(
    const arm_correlator_t *correlator,
    const arm_int32_t corr_flag_num,
    arm_boolean_t *flag);

/* ---------------------- miscellaneous API functions ---------------------- */

ARM4_API_DYNAMIC(arm_error_t)
arm_get_arrival_time(
    arm_arrival_time_t *opaque_time);

ARM4_API_DYNAMIC(arm_error_t)
arm_get_error_message(
    const arm_charset_t charset,
    const arm_error_t code, 
    arm_message_buffer_t msg);

ARM4_API_DYNAMIC(arm_error_t)
arm_is_charset_supported(
    const arm_charset_t charset,
    arm_boolean_t *supported);

#ifdef __cplusplus
}
#endif /* __cplusplus */

#ifndef ARM4DYN_H_INCLUDED
#include "arm4dyn.h"
#endif /* !ARM4DYN_H_INCLUDED */

#endif /* ARM4_H_INCLUDED */