Changeset 15


Ignore:
Timestamp:
21.04.2012 17:14:46 (8 years ago)
Author:
stefan.ruppert@…
Message:

#9 added ARM 4.1 C header files, ARM 4.1 java interfaces, renamed arm4agent.h to arm4sdkagent.h, implemented NOPs for new ARM 4.1 java methods of existing interfaces

Location:
arm4sdk/trunk
Files:
18 added
1 deleted
65 edited
1 copied
1 moved

Legend:

Unmodified
Added
Removed
  • arm4sdk/trunk/c/arm4sdk/Makefile

    r10 r15  
    2121HEADER    = $(TOP)/c/include/arm4.h \ 
    2222            $(TOP)/c/include/arm4os.h \ 
    23             $(TOP)/c/include/arm4agent.h \ 
     23            $(TOP)/c/include/arm4sdkagent.h \ 
    2424            $(TOP)/c/include/arm4sdk.h \ 
    2525            $(TOP)/c/include/arm4sdk.i 
  • arm4sdk/trunk/c/include/arm4.h

    r13 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2222/*                                                                           */ 
    2323/* ------------------------------------------------------------------------- */ 
    24 /* arm4.h - ARM4 standard header file                              */ 
    25 /*                                                                 */ 
    26 /* This header file defines all defines, typedefs, structures,     */ 
    27 /* and API functions visible for an application which uses an ARM  */ 
    28 /* agent. All compiler/platform specifics are handled in a         */ 
    29 /* separate header file named <arm4os.h>.                          */ 
    30 /*                                                                 */ 
    31 /* NOTE: The ARM4 C language binding differs completely from       */ 
    32 /* ARM1 and ARM2 bindings.                                         */ 
    33 /* --------------------------------------------------------------- */ 
     24/*                                                                           */ 
     25/* This file corresponds to following documentation:                         */ 
     26/*                                                                           */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - C Binding                                           */ 
     30/*                                                                           */ 
     31/* ------------------------------------------------------------------------- */ 
     32 
     33/** 
     34 * @file arm4.h 
     35 * @brief ARM 4.0 standard header file 
     36 *                                                                  
     37 * This header file defines all defines, typedefs, structures,      
     38 * and API functions visible for an application which uses an ARM   
     39 * agent. All compiler/platform specifics are handled in a          
     40 * separate header file named <arm4os.h>.                           
     41 *                                                                  
     42 * @note The ARM 4.0 C language binding differs completely from        
     43 * ARM 1.0 and ARM 2.0 bindings.                                          
     44 */ 
    3445 
    3546#ifndef ARM4_H_INCLUDED 
     
    4455#endif /* __cplusplus */ 
    4556 
    46 /* --------------------------------------------------------------- */ 
    47 /* ---------------------- defines section ------------------------ */ 
    48 /* --------------------------------------------------------------- */ 
    49  
    50 /* Boolean values */ 
     57/* ------------------------------------------------------------------------- */ 
     58/* ---------------------------- defines section ---------------------------- */ 
     59/* ------------------------------------------------------------------------- */ 
     60 
     61/** @{ @ingroup ARM40Defs */ 
     62 
     63/* ----------------------------- Boolean values ----------------------------- */ 
     64 
     65/** 
     66 * @brief ARM false boolean 
     67 */ 
    5168#define ARM_FALSE                               0 
     69/** 
     70 * @brief ARM true boolean 
     71 */ 
    5272#define ARM_TRUE                                1 
    5373 
    54 /* Transaction status */ 
     74/* --------------------------- Transaction status --------------------------- */ 
     75 
     76/** 
     77 * @brief transaction completed successfully 
     78 */ 
    5579#define ARM_STATUS_GOOD                         0 
     80/** 
     81 * @brief transaction was aborted before it completed. 
     82 * 
     83 * For example, the user might have pressed "Stop" or "Back" on a browser while 
     84 * a transaction was in process, causing the transaction, as measured at the 
     85 * browser, to be aborted. 
     86 */ 
    5687#define ARM_STATUS_ABORTED                      1 
     88/** 
     89 * @brief transaction completed in error 
     90 */ 
    5791#define ARM_STATUS_FAILED                       2 
     92/** 
     93 * @brief transaction completed but the status was unknown. 
     94 * 
     95 * This would most likely occur if middleware or some other form of proxy 
     96 * instrumentation measured the transaction. This instrumentation may know 
     97 * enough to know when the transaction starts and stops, but does not understand 
     98 * the application-specific semantics sufficiently well to know whether the 
     99 * transaction was successful. 
     100 */ 
    58101#define ARM_STATUS_UNKNOWN                      3 
    59102 
    60 /* -------------- reserved error codes range --------------------- */ 
    61  
     103/* ----------------------- Reserved error codes range ----------------------- */ 
     104 
     105/** 
     106 * @brief reserved error code minimum start 
     107 */ 
    62108#define ARM_ERROR_CODE_RESERVED_MIN        -20999 
     109/** 
     110 * @brief reserved error code maximum end 
     111 */ 
    63112#define ARM_ERROR_CODE_RESERVED_MAX        -20000 
    64113 
    65 /* --------------- known sub-buffer formats ---------------------- */ 
    66  
     114/* ------------------------ known sub-buffer formats ------------------------ */ 
     115 
     116/** 
     117 * @brief User sub-buffer format see arm_subbuffer_user_t. 
     118 * @ingroup ARM40Subbuffers 
     119 */ 
    67120#define ARM_SUBBUFFER_USER                      3 
     121/** 
     122 * @brief Arrival time sub-buffer format see arm_subbuffer_arrival_time_t. 
     123 * @ingroup ARM40Subbuffers 
     124 */ 
    68125#define ARM_SUBBUFFER_ARRIVAL_TIME              4 
     126/** 
     127 * @brief Metric values sub-buffer format see arm_subbuffer_metric_values_t. 
     128 * @ingroup ARM40Subbuffers 
     129 */ 
    69130#define ARM_SUBBUFFER_METRIC_VALUES             5 
     131/** 
     132 * @brief System address sub-buffer format see arm_subbuffer_system_address_t. 
     133 * @ingroup ARM40Subbuffers 
     134 */ 
    70135#define ARM_SUBBUFFER_SYSTEM_ADDRESS            6 
     136/** 
     137 * @brief Diagnostic detail sub-buffer format see arm_subbuffer_diag_detail_t. 
     138 * @ingroup ARM40Subbuffers 
     139 */ 
    71140#define ARM_SUBBUFFER_DIAG_DETAIL               7 
    72141 
     142/** 
     143 * @brief Application identity sub-buffer format see arm_subbuffer_app_identity_t. 
     144 * @ingroup ARM40Subbuffers 
     145 */ 
    73146#define ARM_SUBBUFFER_APP_IDENTITY            102 
     147/** 
     148 * @brief Application context sub-buffer format see arm_subbuffer_app_context_t. 
     149 * @ingroup ARM40Subbuffers 
     150 */ 
    74151#define ARM_SUBBUFFER_APP_CONTEXT             103 
     152/** 
     153 * @brief Transaction identity sub-buffer format see arm_subbuffer_tran_identity_t. 
     154 * @ingroup ARM40Subbuffers 
     155 */ 
    75156#define ARM_SUBBUFFER_TRAN_IDENTITY           104 
     157/** 
     158 * @brief Transaction context sub-buffer format see arm_subbuffer_tran_context_t. 
     159 * @ingroup ARM40Subbuffers 
     160 */ 
    76161#define ARM_SUBBUFFER_TRAN_CONTEXT            105 
     162/** 
     163 * @brief Metric bindings sub-buffer format see arm_subbuffer_metric_bindings_t. 
     164 * @ingroup ARM40Subbuffers 
     165 */ 
    77166#define ARM_SUBBUFFER_METRIC_BINDINGS         106 
     167/** 
     168 * @brief Character set encoding sub-buffer format see arm_subbuffer_charset_t. 
     169 * @ingroup ARM40Subbuffers 
     170 */ 
    78171#define ARM_SUBBUFFER_CHARSET                 107 
    79172 
    80 /* -------------------- metric defines --------------------------- */ 
    81  
     173/* ----------------------------- metric defines ----------------------------- */ 
     174 
     175/** 
     176 * @brief Reserved metric format 
     177 * @ingroup ARM40Metrics 
     178 */ 
    82179#define ARM_METRIC_FORMAT_RESERVED              0 
     180/** 
     181 * @brief arm_int32_t counter 
     182 * @ingroup ARM40Metrics 
     183 */ 
    83184#define ARM_METRIC_FORMAT_COUNTER32             1 
     185/** 
     186 * @brief arm_int64_t counter 
     187 * @ingroup ARM40Metrics 
     188 */ 
    84189#define ARM_METRIC_FORMAT_COUNTER64             2 
     190/** 
     191 * @brief arm_int32_t counter + arm_int32_t divisor 
     192 * @ingroup ARM40Metrics 
     193 */ 
    85194#define ARM_METRIC_FORMAT_CNTRDIVR32            3 
     195/** 
     196 * @brief arm_int32_t gauge 
     197 * @ingroup ARM40Metrics 
     198 */ 
    86199#define ARM_METRIC_FORMAT_GAUGE32               4 
     200/** 
     201 * @brief arm_int64_t gauge 
     202 * @ingroup ARM40Metrics 
     203 */ 
    87204#define ARM_METRIC_FORMAT_GAUGE64               5 
     205/** 
     206 * @brief arm_int32_t gauge + arm_int32_t divisor 
     207 * @ingroup ARM40Metrics 
     208 */ 
    88209#define ARM_METRIC_FORMAT_GAUGEDIVR32           6 
     210/** 
     211 * @brief arm_int32_t numeric ID 
     212 * @ingroup ARM40Metrics 
     213 */ 
    89214#define ARM_METRIC_FORMAT_NUMERICID32           7 
     215/** 
     216 * @brief arm_int64_t numeric ID 
     217 * @ingroup ARM40Metrics 
     218 */ 
    90219#define ARM_METRIC_FORMAT_NUMERICID64           8 
    91220/* format 9 (string8) is deprecated */ 
     221/** 
     222 * @brief string (null-terminated) of a maximum length of 32 characters 
     223 *     (33 including the null termination character) 
     224 * @ingroup ARM40Metrics 
     225 */ 
    92226#define ARM_METRIC_FORMAT_STRING32             10 
    93227 
     228/** 
     229 * @brief a metric without a specified usage. 
     230 * 
     231 * Most metrics are described with a GENERAL usage. 
     232 * @ingroup ARM40Metrics 
     233 */ 
    94234#define ARM_METRIC_USE_GENERAL                  0 
     235/** 
     236 * @brief a metric that indicates the "size" of a transaction. 
     237 * 
     238 * The "size" is something that would be expected to affect the response 
     239 * time, such as the number of bytes in a file transfer or the number of 
     240 * files backed up by a "backup" transaction. ARM implementations can use 
     241 * this knowledge to better interpret the response time. 
     242 * @ingroup ARM40Metrics 
     243 */ 
    95244#define ARM_METRIC_USE_TRAN_SIZE                1 
     245/** 
     246 * @brief a metric that further explains the transaction status such as a 
     247 *     sense code that explains why a transaction failed. 
     248 * 
     249 * The metric is a status code (numeric ID) or text message (string). It would 
     250 * typically be used with arm_stop_transaction() or arm_report_transaction() to 
     251 * provide additional details about a transaction status of Failed. 
     252 * @ingroup ARM40Metrics 
     253 */ 
    96254#define ARM_METRIC_USE_TRAN_STATUS              2 
    97255 
     256/** 
     257 * @brief minimum array index for metric values and bindings. 
     258 * @ingroup ARM40Metrics 
     259 */ 
    98260#define ARM_METRIC_MIN_ARRAY_INDEX              0 
     261/** 
     262 * @brief maximum array index for metric values and bindings. 
     263 * @ingroup ARM40Metrics 
     264 */ 
    99265#define ARM_METRIC_MAX_ARRAY_INDEX              6 
     266/** 
     267 * @brief maximum array count for metric values and bindings. 
     268 * @ingroup ARM40Metrics 
     269 */ 
    100270#define ARM_METRIC_MAX_COUNT                    7 
    101271 
     272/** 
     273 * @brief maximum characters for a string metric 
     274 * @ingroup ARM40Metrics 
     275 */ 
    102276#define ARM_METRIC_STRING32_MAX_CHARS          31 
     277/** 
     278 * @brief maximum bytes for a string metric 
     279 * @ingroup ARM40Metrics 
     280 */ 
    103281#define ARM_METRIC_STRING32_MAX_LENGTH \ 
    104282    (ARM_METRIC_STRING32_MAX_CHARS*3+1) 
    105283 
    106 /* ------------------- misc string defines ----------------------- */ 
    107  
     284/* -------------------------- misc string defines --------------------------- */ 
     285 
     286/** 
     287 * @brief maximum characters for names 
     288 */ 
    108289#define ARM_NAME_MAX_CHARS                    127 
     290/** 
     291 * @brief maximum number of bytes for names 
     292 */ 
    109293#define ARM_NAME_MAX_LENGTH (ARM_NAME_MAX_CHARS*3+1) 
    110294 
     295/** 
     296 * @brief maximum characters for diagnostic detail string 
     297 */ 
    111298#define ARM_DIAG_DETAIL_MAX_CHARS            4095 
     299/** 
     300 * @brief maximum number of bytes for diagnostic detail string 
     301 */ 
    112302#define ARM_DIAG_DETAIL_MAX_LENGTH (ARM_DIAG_DETAIL_MAX_CHARS*3+1) 
    113303 
     304/** 
     305 * @brief maximum characters for message buffers 
     306 */ 
    114307#define ARM_MSG_BUFFER_CHARS                  255 
     308/** 
     309 * @brief maximum number of bytes for message buffers 
     310 */ 
    115311#define ARM_MSG_BUFFER_LENGTH (ARM_MSG_BUFFER_CHARS*3+1) 
    116312 
    117 /* ------------------- properties defines ------------------------ */ 
    118  
     313 
     314/* --------------------------- properties defines --------------------------- */ 
     315 
     316/** 
     317 * @brief minimum array index for property names and values 
     318 * @ingroup ARM40Props 
     319 */ 
    119320#define ARM_PROPERTY_MIN_ARRAY_INDEX            0 
     321/** 
     322 * @brief maximum array index for property names and values 
     323 * @ingroup ARM40Props 
     324 */ 
    120325#define ARM_PROPERTY_MAX_ARRAY_INDEX           19 
     326/** 
     327 * @brief maximum array count for property names and values 
     328 * @ingroup ARM40Props 
     329 */ 
    121330#define ARM_PROPERTY_MAX_COUNT                 20 
    122331 
     332/** 
     333 * @brief maximum characters for property names 
     334 * @ingroup ARM40Props 
     335 */ 
    123336#define ARM_PROPERTY_NAME_MAX_CHARS (ARM_NAME_MAX_CHARS) 
     337/** 
     338 * @brief maximum number of bytes for property names 
     339 * @ingroup ARM40Props 
     340 */ 
    124341#define ARM_PROPERTY_NAME_MAX_LENGTH \ 
    125342    (ARM_PROPERTY_NAME_MAX_CHARS*3+1) 
     343/** 
     344 * @brief maximum characters for property values 
     345 * @ingroup ARM40Props 
     346 */ 
    126347#define ARM_PROPERTY_VALUE_MAX_CHARS          255 
     348/** 
     349 * @brief maximum number of bytes for property values 
     350 * @ingroup ARM40Props 
     351 */ 
    127352#define ARM_PROPERTY_VALUE_MAX_LENGTH \ 
    128353    (ARM_PROPERTY_VALUE_MAX_CHARS*3+1) 
    129354 
     355/** 
     356 * @brief maximum characters for a uri property 
     357 * @ingroup ARM40Props 
     358 */ 
    130359#define ARM_PROPERTY_URI_MAX_CHARS           4095 
     360/** 
     361 * @brief maximum number of bytes for a uri property 
     362 * @ingroup ARM40Props 
     363 */ 
    131364#define ARM_PROPERTY_URI_MAX_LENGTH (ARM_PROPERTY_URI_MAX_CHARS*3+1) 
    132365 
    133 /* -------------- system address format values ------------------- */ 
    134  
     366 
     367/* ---------------------- system address format values ---------------------- */ 
     368 
     369/** 
     370 * @brief reserved by the standard 
     371 */ 
    135372#define ARM_SYSADDR_FORMAT_RESERVED             0 
     373/** 
     374 * @brief IP address 
     375 * 
     376 * @li Bytes 0:3 = 4-byte IP address 
     377 */ 
    136378#define ARM_SYSADDR_FORMAT_IPV4                 1 
     379/** 
     380 * @brief IP address and port number 
     381 * 
     382 * @li Bytes 0:3 = 4-byte IP address 
     383 * @li Bytes 4:5 = 2-byte IP port number 
     384 */ 
    137385#define ARM_SYSADDR_FORMAT_IPV4PORT             2 
     386/** 
     387 * @brief IP v6 address 
     388 * 
     389 * @li Bytes 0:15 = 16-byte IP address 
     390 */ 
    138391#define ARM_SYSADDR_FORMAT_IPV6                 3 
     392/** 
     393 * @brief IP v6 address and port number 
     394 * 
     395 * @li Bytes 0:15 = 16-byte IP address 
     396 * @li Bytes 16:17 = 2-byte IP port number 
     397 */ 
    139398#define ARM_SYSADDR_FORMAT_IPV6PORT             4 
     399/** 
     400 * @brief SNA address 
     401 * 
     402 * @li Bytes 0:7 = EBCDIC-encoded network ID 
     403 * @li Bytes 8:15 = EBCDIC-encoded network accessible unit (control point or LU) 
     404 */ 
    140405#define ARM_SYSADDR_FORMAT_SNA                  5 
     406/** 
     407 * @brief X25 address 
     408 * 
     409 * @li Bytes 0:15 = the X.25 address (also referred to as an X.121 address). 
     410 *     This is up to 16 ASCII character digits ranging from 0-9. 
     411 */ 
    141412#define ARM_SYSADDR_FORMAT_X25                  6 
     413/** 
     414 * @brief hostname string 
     415 * 
     416 * @li Bytes 0:?? = hostname (characters, not null-terminated), where ?? is 
     417 *     determined based on the arm_int16_t address_length field. 
     418 */ 
    142419#define ARM_SYSADDR_FORMAT_HOSTNAME             7 
     420/** 
     421 * @brief UUID address alias 
     422 * 
     423 * @li Bytes 0:15 = UUID in binary. This is useful for applications that define 
     424 *     their system by a UUID rather than a network address or hostname or some 
     425 *     other address form. 
     426 */ 
    143427#define ARM_SYSADDR_FORMAT_UUID                 8 
    144428 
    145 /* ------------------ mandatory charsets ------------------------- */ 
     429/* ------------------------ mandatory charsets ------------------------------ */ 
    146430 
    147431/* IANA charset MIBenum numbers (http://www.iana.org/) */ 
    148 #define ARM_CHARSET_ASCII                       3  /* mandatory */ 
    149 #define ARM_CHARSET_UTF8                      106  /* mandatory */ 
     432/** 
     433 * @brief ASCII-7 (US-ASCII) mandatory on all systems 
     434 */ 
     435#define ARM_CHARSET_ASCII                       3 
     436/** 
     437 * @brief UTF-8 (UCS-2 characters only) mandatory on all systems 
     438 */ 
     439#define ARM_CHARSET_UTF8                      106 
     440/** 
     441 * @brief UTF-16 Big Endian (UCS-2 characters only) 
     442 */ 
    150443#define ARM_CHARSET_UTF16BE                  1013 
     444/** 
     445 * @brief UTF-16 Little Endian (UCS-2 characters only) mandatory on  
     446 *     Microsoft Windows 
     447 */ 
    151448#define ARM_CHARSET_UTF16LE                  1014 
    152     /* mandatory on Windows */ 
     449/** 
     450 * @brief UTF-16 Little and Big Endian (UCS-2 characters only) 
     451 */ 
    153452#define ARM_CHARSET_UTF16                    1015 
     453/** 
     454 * @brief IBM037 mandatory on IBM iSeries 
     455 */ 
    154456#define ARM_CHARSET_IBM037                   2028 
    155     /* mandatory on iSeries */ 
     457/** 
     458 * @brief IBM1047 mandatory on IBM zSeries 
     459 */ 
    156460#define ARM_CHARSET_IBM1047                  2102 
    157     /* mandatory on zSeries */ 
    158  
    159 /* ------------- flags to be passed on API calls ----------------- */ 
    160  
    161 /* Use ARM_FLAG_NONE instead of zero to be more readable.          */ 
     461 
     462/* -------------------- flags to be passed on API calls --------------------- */ 
     463 
     464/** 
     465 * @brief use instead of zero to be more readable. 
     466 */ 
    162467#define ARM_FLAG_NONE                (0x00000000) 
    163  
    164 /* ARM_FLAG_TRACE_REQUEST could be used in the following calls to  */ 
    165 /* request a trace:                                                */ 
    166 /*   - arm_generate_correlator()                                   */ 
    167 /*   - arm_start_transaction()                                     */ 
    168 /*   - arm_report_transaction()                                    */ 
    169 /* NOTE: The agent need not support instance tracing, so to be     */ 
    170 /* sure check the generated correlator using the                   */ 
    171 /* arm_get_correlator_flags() function.                            */ 
     468/** 
     469 * @brief is set to 1 if the application requests/suggests a trace. 
     470 * 
     471 * Could be used in the following calls to request a trace: 
     472 * <ul> 
     473 * <li>arm_generate_correlator()</li> 
     474 * <li>arm_start_transaction()</li> 
     475 * <li>arm_report_transaction()</li> 
     476 * </ul> 
     477 * 
     478 * @note The agent need not support instance tracing, so to be sure check the 
     479 * generated correlator using the arm_get_correlator_flags() function. 
     480 */ 
    172481#define ARM_FLAG_TRACE_REQUEST       (0x00000001) 
    173  
    174 /* ARM_FLAG_BIND_THREAD could be used on arm_start_transaction()   */ 
    175 /* call to do an implicit arm_bind_thread().                       */ 
     482/** 
     483 * @brief is set to 1 if the started transaction is bound to this thread. 
     484 * 
     485 * Setting this flag is equivalent to immediately calling arm_bind_thread() 
     486 * after the arm_start_transaction() completes, except the timing is a little 
     487 * more accurate and the extra call is avoided. 
     488 */ 
    176489#define ARM_FLAG_BIND_THREAD         (0x00000002) 
    177  
    178 /* ARM_FLAG_CORR_IN_PROCESS indicates that a correlator will only  */ 
    179 /* be used within the process it was created. So an ARM            */ 
    180 /* implementation may optimize the generation of a correlator      */ 
    181 /* for that special usage. This flag can be passed to:             */ 
    182 /*   - arm_generate_correlator()                                   */ 
    183 /*   - arm_start_transaction()                                     */ 
    184 /* NOTE: The agent need not support in-process correlation at all. */ 
     490/** 
     491 * @brief is set to 1 if the application is stating that it will not send 
     492 *     the correlator outside the current process. 
     493 * 
     494 * This flag can be passed to: 
     495 * <ul> 
     496 * <li>arm_generate_correlator()</li> 
     497 * <li>arm_start_transaction()</li> 
     498 * <li>arm_report_transaction()</li> 
     499 * </ul> 
     500 * 
     501 * An ARM implementation may be able to optimize correlator handling if it 
     502 * knows this, because it may be able to avoid serialization to create the 
     503 * correlator. 
     504 * @note The agent need not support in-process correlation at all. 
     505 */ 
    185506#define ARM_FLAG_CORR_IN_PROCESS     (0x00000004) 
    186507 
    187 /* --------------- correlator defines ---------------------------- */ 
    188  
     508/* --------------------------- correlator defines --------------------------- */ 
     509 
     510/** 
     511 * @brief total maximal length of an ARM 4.x correlator. 
     512 */ 
    189513#define ARM_CORR_MAX_LENGTH                   512 
    190     /* total max length */ 
    191  
    192 /* Correlator interface flag numbers. See                          */ 
    193 /* arm_get_correlator_flags().                                     */ 
     514 
     515/** 
     516 * @brief Application trace flag number 
     517 * @see arm_get_correlator_flags() 
     518 */ 
    194519#define ARM_CORR_FLAGNUM_APP_TRACE              1 
     520/** 
     521 * @brief Agent trace flag number 
     522 * @see arm_get_correlator_flags() 
     523 */ 
    195524#define ARM_CORR_FLAGNUM_AGENT_TRACE            2 
    196525 
    197  
    198 /* Use if no correlator should be provided (e.g., in               */ 
    199 /* arm_start_transaction().                                        */ 
     526/** 
     527 * @brief Used to pass no correlator to various functions calls (e.g. 
     528 *     arm_start_transaction()) 
     529 */ 
    200530#define ARM_CORR_NONE ((arm_correlator_t *) NULL) 
    201531 
    202 /* --- current time for arm_report_transaction() stop time ------- */ 
    203  
     532/* ---------- current time for arm_report_transaction() stop time ----------- */ 
     533 
     534/** 
     535 * @brief short cut for capturing the current time within  
     536 *     arm_report_transaction(). 
     537 */ 
    204538#define ARM_USE_CURRENT_TIME ((arm_stop_time_t)-1) 
    205539 
    206 /* ------------------ misc defines ------------------------------- */ 
    207  
    208 /* Use ARM_BUF4_NONE instead of a NULL to be more readable.        */ 
     540/* ------------------------------ misc defines ------------------------------ */ 
     541 
     542/** 
     543 * @brief to be used instead of a NULL to be more readable for arm_buffer4_t 
     544 *     null pointers. 
     545 */ 
    209546#define ARM_BUF4_NONE ((arm_buffer4_t*) NULL) 
    210547 
    211 /* Use ARM_ID_NONE instead of a NULL to be more readable.          */ 
     548/** 
     549 * @brief to be used instead of a NULL to be more readable for arm_id_t 
     550 *     null pointers. 
     551 */ 
    212552#define ARM_ID_NONE ((arm_id_t *) NULL) 
    213553 
    214 /* Use ARM_STRING_NONE instead of a NULL to be more readable.      */ 
     554/** 
     555 * @brief to be used instead of a NULL to be more readable. 
     556 */ 
    215557#define ARM_STRING_NONE ((arm_char_t *) NULL) 
    216558 
    217 /* --------------------------------------------------------------- */ 
    218 /* --------------- basic typedef section ------------------------- */ 
    219 /* --------------------------------------------------------------- */ 
    220  
    221 /* Generic data types */ 
    222 /* ARM4_*INT* defines are set in the <arm4os.h> header file.       */ 
    223 /* They are platform/compiler-specific.                            */ 
    224 typedef ARM4_CHAR arm_char_t; 
    225  
    226 typedef ARM4_INT8 arm_int8_t; 
    227 typedef ARM4_UINT8 arm_uint8_t; 
    228     /* used to define an opaque byte array */ 
    229  
    230 typedef ARM4_INT16 arm_int16_t; 
    231 typedef ARM4_UINT16 arm_uint16_t; 
    232  
    233 typedef ARM4_INT32 arm_int32_t; 
    234 typedef ARM4_UINT32 arm_uint32_t; 
    235  
    236 typedef ARM4_INT64 arm_int64_t; 
    237 typedef ARM4_UINT64 arm_uint64_t; 
    238  
    239 /* ARM-specific simple types */ 
    240 typedef arm_int32_t arm_boolean_t; 
    241 typedef arm_int32_t arm_error_t; 
    242  
    243 typedef arm_int64_t arm_arrival_time_t;  /* opaque arrival time */ 
    244 typedef arm_int64_t arm_stop_time_t;  /* stop time in milli secs */ 
    245 typedef arm_int64_t arm_response_time_t; 
    246     /* response time in nano secs */ 
    247  
    248 typedef arm_int32_t arm_tran_status_t;  /* ARM_TRAN_STATUS_* values */ 
    249 typedef arm_int32_t arm_charset_t;  /* IANA MIBenum values */ 
    250 typedef arm_int32_t arm_sysaddr_format_t;  /* ARM_SYSADDR_* values */ 
    251  
    252 /* ARM string buffer types */ 
     559/** @} */ 
     560 
     561/* -------------------------------------------------------------------------- */ 
     562/* ------------------------- basic typedef section -------------------------- */ 
     563/* -------------------------------------------------------------------------- */ 
     564 
     565/* ARM4_*INT* defines are set in the <arm4os.h> header file.        
     566   They are platform/compiler-specific.                                       */ 
     567typedef ARM4_CHAR arm_char_t;        /**< defines an ARM character. */ 
     568 
     569typedef ARM4_INT8 arm_int8_t;        /**< 8-bit signed integer */ 
     570typedef ARM4_UINT8 arm_uint8_t;      /**< used to define an opaque byte array */ 
     571 
     572typedef ARM4_INT16 arm_int16_t;      /**< 16-bit signed integer */ 
     573typedef ARM4_UINT16 arm_uint16_t;    /**< 16-bit unsigned integer */ 
     574 
     575typedef ARM4_INT32 arm_int32_t;      /**< 32-bit signed integer */ 
     576typedef ARM4_UINT32 arm_uint32_t;    /**< 32-bit unsigned integer */ 
     577 
     578typedef ARM4_INT64 arm_int64_t;      /**< 64-bit signed integer */ 
     579typedef ARM4_UINT64 arm_uint64_t;    /**< 64-bit unsigned integer */ 
     580 
     581typedef arm_int32_t arm_boolean_t;           /**< ARM boolean type */ 
     582typedef arm_int32_t arm_error_t;             /**< API call return type */ 
     583 
     584typedef arm_int64_t arm_arrival_time_t;      /**< opaque arrival time */ 
     585typedef arm_int64_t arm_stop_time_t;         /**< stop time in milli secs */ 
     586typedef arm_int64_t arm_response_time_t;     /**< response time in nano secs */ 
     587 
     588typedef arm_int32_t arm_tran_status_t;       /**< ARM_TRAN_STATUS_* values */ 
     589typedef arm_int32_t arm_charset_t;           /**< IANA MIBenum values */ 
     590typedef arm_int32_t arm_sysaddr_format_t;    /**< ARM_SYSADDR_* values */ 
     591 
     592/** 
     593 * ARM string buffer type used by arm_get_error_message() 
     594 */ 
    253595typedef arm_char_t arm_message_buffer_t[ARM_MSG_BUFFER_LENGTH]; 
    254596 
    255 /* subbuffer types */ 
    256 typedef arm_int32_t arm_subbuffer_format_t; 
    257  
    258 /* metric types */ 
    259 typedef arm_uint8_t arm_metric_format_t; 
    260 typedef arm_uint8_t arm_metric_slot_t; 
    261 typedef arm_int16_t arm_metric_usage_t; 
    262  
    263 /* handle types */ 
    264 typedef arm_int64_t arm_app_start_handle_t; 
    265 typedef arm_int64_t arm_tran_start_handle_t; 
    266 typedef arm_int64_t arm_tran_block_handle_t; 
    267  
    268 /* correlator types */ 
    269 typedef arm_int16_t arm_correlator_length_t; 
    270  
    271 /* --------------------------------------------------------------- */ 
    272 /* ---------------- compound typedefs section -------------------- */ 
    273 /* --------------------------------------------------------------- */ 
    274  
    275 /* All IDs are 16 bytes on an 8-byte boundary. */ 
     597 
     598typedef arm_int32_t arm_subbuffer_format_t;  /**< sub-buffer format type */ 
     599 
     600typedef arm_uint8_t arm_metric_format_t;     /**< metric format type */ 
     601typedef arm_uint8_t arm_metric_slot_t;       /**< metric slot type */ 
     602typedef arm_int16_t arm_metric_usage_t;      /**< metric usage type */ 
     603 
     604typedef arm_int64_t arm_app_start_handle_t;  /**< application start handle type */ 
     605typedef arm_int64_t arm_tran_start_handle_t; /**< transaction start handle type */ 
     606typedef arm_int64_t arm_tran_block_handle_t; /**< transaction block handle type */ 
     607 
     608typedef arm_int16_t arm_correlator_length_t; /**< correlator length type */ 
     609 
     610/* -------------------------------------------------------------------------- */ 
     611/* ----------------------- compound typedefs section ------------------------ */ 
     612/* -------------------------------------------------------------------------- */ 
     613 
     614/** 
     615 * @brief An ID is a 16-byte binary value, such as a UUID. 
     616 * 
     617 * All IDs are 16 bytes on an 8-byte boundary. 
     618 * @see ARMID. 
     619 */ 
    276620typedef struct arm_id 
    277621{ 
     622    /** 
     623     * union used to align the ID apropriate. 
     624     */ 
    278625    union 
    279626    { 
     
    284631} arm_id_t; 
    285632 
    286 /* Correlator */ 
     633/** 
     634 * @brief ARM 4.0 correlator structure. 
     635 */ 
    287636typedef struct arm_correlator 
    288637{ 
     638    /** 
     639     * @brief Opaque byte array with @ref ARM_CORR_MAX_LENGTH bytes. */ 
    289640    arm_uint8_t opaque[ARM_CORR_MAX_LENGTH]; 
    290641} arm_correlator_t; 
    291642 
    292 /* User-defined metrics */ 
     643/* ----------------------- user defined metric types ------------------------ */ 
     644 
     645/** 
     646 * @brief 32-bit integer metric counter type 
     647 * @ingroup ARM40MetricCounter 
     648 */ 
    293649typedef arm_int32_t arm_metric_counter32_t; 
     650/** 
     651 * @brief 64-bit integer metric counter type 
     652 * @ingroup ARM40MetricCounter 
     653 */ 
    294654typedef arm_int64_t arm_metric_counter64_t; 
     655/** 
     656 * @brief 32-bit integer metric divisor type 
     657 * @ingroup ARM40Metrics 
     658 */ 
    295659typedef arm_int32_t arm_metric_divisor32_t; 
     660/** 
     661 * @brief 32-bit integer metric gauge type 
     662 * @ingroup ARM40MetricGauge 
     663 */ 
    296664typedef arm_int32_t arm_metric_gauge32_t; 
     665/** 
     666 * @brief 64-bit integer metric gauge type 
     667 * @ingroup ARM40MetricGauge 
     668 */ 
    297669typedef arm_int64_t arm_metric_gauge64_t; 
     670/** 
     671 * @brief 32-bit integer metric numeric id type 
     672 * @ingroup ARM40MetricNumericID 
     673 */ 
    298674typedef arm_int32_t arm_metric_numericID32_t; 
     675/** 
     676 * @brief 64-bit integer metric numeric id type 
     677 * @ingroup ARM40MetricNumericID 
     678 */ 
    299679typedef arm_int64_t arm_metric_numericID64_t; 
     680/** 
     681 * @brief 32 character wide string type. 
     682 * @ingroup ARM40MetricString 
     683 */ 
    300684typedef const arm_char_t *arm_metric_string32_t; 
     685 
     686/** 
     687 * @brief 32-bit integer plus a 32-bit divisor, used to simulate  
     688 *     floating-point counter. 
     689 * @ingroup ARM40MetricCounter ARM40Metrics 
     690 */ 
    301691typedef struct arm_metric_cntrdivr32 
    302692{ 
     693    /** 
     694     * value part of the counter. 
     695     */ 
    303696    arm_metric_counter32_t counter; 
     697    /** 
     698     * divisor part of the counter. 
     699     */ 
    304700    arm_metric_divisor32_t divisor; 
    305701} arm_metric_cntrdivr32_t; 
     702/** 
     703 * @brief 32-bit integer plus a 32-bit divisor, used to simulate  
     704 *     floating-point gauge. 
     705 * @ingroup ARM40MetricGauge ARM40Metrics 
     706 */ 
    306707typedef struct arm_metric_gaugedivr32 
    307708{ 
     709    /** 
     710     * value part of the gauge. 
     711     */ 
    308712    arm_metric_gauge32_t gauge; 
     713    /** 
     714     * divisor part of the gauge. 
     715     */ 
    309716    arm_metric_divisor32_t divisor; 
    310717} arm_metric_gaugedivr32_t; 
    311718 
     719/** 
     720 * @brief used to pass a metric value to the ARM implementation. 
     721 * 
     722 * @see arm_subbuffer_metric_values_t 
     723 * @ingroup ARM40Metrics 
     724 */ 
    312725typedef struct arm_metric 
    313726{ 
     727    /** 
     728     * A single-byte slot number. Valid values are 0 to 6. The slot number 
     729     * must be the same as the corresponding entry in the Metric Bindings 
     730     * sub-buffer (arm_subbuffer_metric_bindings_t). Each slot number should 
     731     * be used at most once; if a slot number is re-used, the first entry is 
     732     * used and all others are ignored. 
     733     */ 
    314734    arm_metric_slot_t slot; 
     735    /** 
     736     * A single-byte format indicator. Valid formats are are listed below. 
     737     * @ref ARM_METRIC_FORMAT_STRING32 is only valid in slot 6. All other 
     738     * formats are valid in slots 0-5. This is a carry-over from ARM 2.0. 
     739     * The format must be the same as the corresponding entry in the 
     740     * Metric Bindings sub-buffer (arm_subbuffer_metric_bindings_t): 
     741     * @li @ref ARM_METRIC_FORMAT_COUNTER32 
     742     * @li @ref ARM_METRIC_FORMAT_COUNTER64 
     743     * @li @ref ARM_METRIC_FORMAT_CNTRDIVR32 
     744     * @li @ref ARM_METRIC_FORMAT_GAUGE32 
     745     * @li @ref ARM_METRIC_FORMAT_GAUGE64 
     746     * @li @ref ARM_METRIC_FORMAT_GAUGEDIVR32 
     747     * @li @ref ARM_METRIC_FORMAT_NUMERICID32 
     748     * @li @ref ARM_METRIC_FORMAT_NUMERICID64 
     749     * @li @ref ARM_METRIC_FORMAT_STRING32 
     750     */ 
    315751    arm_metric_format_t format; 
     752    /** 
     753     * An usage indicating how the metric is used. The usage must be the same 
     754     * as the usage parameter passed on the arm_register_metric() call that 
     755     * registered the metric ID with the same slot number that is in the  
     756     * Metric Bindings sub-buffer (arm_subbuffer_metric_bindings_t). 
     757     * @li @ref ARM_METRIC_USE_GENERAL 
     758     * @li @ref ARM_METRIC_USE_TRAN_SIZE 
     759     * @li @ref ARM_METRIC_USE_TRAN_STATUS 
     760     */ 
    316761    arm_metric_usage_t usage; 
     762    /** 
     763     * A boolean that indicates whether the data in the "Metric value" field 
     764     * is currently valid. 
     765     */ 
    317766    arm_boolean_t valid; 
     767    /** 
     768     * A union containing the metric value. The data type matches the metric format 
     769     * indicator (above). 
     770     */ 
    318771    union 
    319772    { 
     
    330783} arm_metric_t; 
    331784 
     785/** 
     786 * @brief binds a metric definition (id) to a certain transaction  
     787 *     metric slot. 
     788 * @see arm_subbuffer_metric_bindings_t 
     789 */ 
    332790typedef struct arm_metric_binding 
    333791{ 
     792    /** 
     793     * A byte slot number. Valid values are 0 to 6 (replacing the ARM 2.0 
     794     * numbering standard). If a slot number is repeated, the first time it 
     795     * appears is the only one processed; all others are ignored. 
     796     */ 
    334797    arm_metric_slot_t slot; 
     798    /** 
     799     * A 16-byte array for the ID of this metric definition. The ID must have  
     800     * been previously returned as an out parameter from arm_register_metric(). 
     801     */ 
    335802    arm_id_t id; 
    336803} arm_metric_binding_t; 
    337804 
     805/** 
     806 * @brief defines a name value property pair. 
     807 * 
     808 * @ingroup ARM40Props 
     809 */ 
    338810typedef struct arm_property 
    339811{ 
     812    /** 
     813     * A null-terminated string representing the name part of the (name,value) 
     814     * pair. Each string has a maximum length of 128 characters, including the 
     815     * termination character. If the pointer is null or points to a zero-length 
     816     * string, the (name,value) pair is ignored. Names should not contain 
     817     * trailing blank characters or consist of only blank characters. 
     818     */ 
    340819    const arm_char_t *name; 
     820    /** 
     821     * A null-terminated string representing the value part of the (name,value) 
     822     * pair. Each string has a maximum length of 256 characters, including the 
     823     * termination character. If the pointer is null or points to a zero-length 
     824     * string, the (name,value) pair is ignored. Values should not contain  
     825     * trailing blank characters or consist of only blank characters. 
     826     */ 
    341827    const arm_char_t *value; 
    342828} arm_property_t; 
    343829 
    344 /* ------------------------------------------------------------- */ 
    345 /* -------------- sub-buffer typedefs section ------------------ */ 
    346 /* ------------------------------------------------------------- */ 
    347  
     830/* ------------------------------------------------------------------------- */ 
     831/* ---------------------- sub-buffer typedefs section ---------------------- */ 
     832/* ------------------------------------------------------------------------- */ 
     833 
     834/** 
     835 * @brief Generic sub-buffer structure 
     836 * 
     837 * Each sub-buffer has a sub-buffer format which specifies the specific 
     838 * sub-buffer. 
     839 */ 
    348840typedef struct arm_subbuffer { 
     841    /** 
     842     * format of the sub-buffer 
     843     */ 
    349844    arm_subbuffer_format_t format; 
    350     /* Format-specific data fields follow here. */ 
    351845} arm_subbuffer_t; 
    352846 
    353 /* This macro could be used avoid a compiler warning if you      */ 
    354 /* direct one of the following arm_subbuffer_*_t structure       */ 
    355 /* pointers to a function accepting sub-buffer pointers. Any     */ 
    356 /* sub-buffer is passed to the ARM API call as a                 */ 
    357 /* (arm_subbuffer_t *) pointer. Use this macro if you pass a     */ 
    358 /* "real" subbuffer to an API function. Note for the special     */ 
    359 /* ARM SDK subbuffers the ARM_SDKSB() macro has to be used.      */ 
     847/** 
     848 * @brief used to cast a specific sub-buffer to a pointer to arm_subbuffer_t. 
     849 * 
     850 * This macro could be used to cast a specific (arm_subbuffer_*_t) sub-buffer 
     851 * to an arm_subbuffer_t pointer compiler friendly. 
     852 * 
     853 * Note for the special ARM SDK subbuffers the ARM_SDKSB() macro has to be used. 
     854 * 
     855 * @ingroup ARM40Subbuffers 
     856 */ 
    360857#define ARM_SB(x)  (&((x).header)) 
    361858 
    362 /* The user data buffer */ 
     859/** 
     860 * @brief User data buffer used to pass different kind of data to a function. 
     861 * 
     862 * Many of the ARM function calls provide a way for the application and ARM 
     863 * implementation to exchange optional data, in addition to the required data 
     864 * in other function parameters. This buffer describes the format of the 
     865 * exchanged data. 
     866 * 
     867 * Almost all functions define a *buffer4 parameter. When the value is not 
     868 * null, the value points to a buffer in the following format. It differs from 
     869 * the ARM 2.0 format in that the buffer contains pointers to sub-buffers, 
     870 * rather than inline contiguous data. The sub-buffers contain the meaningful 
     871 * data. 
     872 * 
     873 * Each sub-buffer may be in the optional buffer once. If there is more than 
     874 * one instance of a sub-buffer in the buffer, all instances after the first 
     875 * will be ignored. 
     876 * 
     877 * The buffer is aligned on a pointer boundary for the platform. The byte 
     878 * layout depends on the platform. 
     879 * 
     880 * @ingroup ARM40Subbuffers 
     881 */ 
    363882typedef struct arm_buffer4 
    364883{ 
     884    /** 
     885     * Count of sub-buffers in the following array. 
     886     */ 
    365887    arm_int32_t count; 
     888    /** 
     889     * A pointer to an array of pointers to sub-buffers. The array is aligned 
     890     * on a pointer boundary for the platform. A null pointer indicates that 
     891     * this element in the array is not used on this call; later elements in 
     892     * the array may be non-null. 
     893     */ 
    366894    arm_subbuffer_t **subbuffer_array; 
    367895} arm_buffer4_t; 
    368896 
     897/* ------------------------------------------------------------------------- */ 
     898 
     899/** 
     900 * @brief used to specify which charset the application uses. 
     901 * 
     902 * Applications may specify on arm_register_application() the character set 
     903 * encoding for all strings passed by the application. An ARM library must 
     904 * support certain encodings, depending on the platform. The application may 
     905 * always use one of the mandatory encodings. The \<arm4.h\> file defines 
     906 * names of the form ARM_CHARSET_* for all the mandatory encodings. The 
     907 * application may optionally ask the ARM library if another encoding is 
     908 * supported using arm_is_charset_supported(). 
     909 * 
     910 * When the application registers with arm_register_application(), it may 
     911 * optionally provide the Character Set Encoding sub-buffer. In the sub-buffer, 
     912 * the application specifies the MIBenum value of a character set encoding that 
     913 * has been assigned by the IANA (Internet Assigned Numbers Authority - see 
     914 * www.iana.org). The MIBenum value in the sub-buffer should only be either a 
     915 * mandatory encoding for the platform or a MIBenum value for which support has 
     916 * been verified using arm_is_charset_supported(). 
     917 * 
     918 * The encoding must comply with the following constraints: 
     919 * <ul> 
     920 * <li> 
     921 * The character set must not contain any embedded null bytes. Exceptions are 
     922 * permitted for character sets that have fixed-length characters (e.g., two 
     923 * bytes) and that do not allow a character of all zeros (e.g., 0x0000). These 
     924 * include UTF-16LE, UTF-16BE, and UTF-16 (MIBenum values 1013, 1014, 1015). 
     925 * For these encodings, there will be a convention that a character of all 
     926 * zeros is the null-termination character. 
     927 * </li> 
     928 * <li> 
     929 * No more than three bytes may be used to encode each character. 
     930 * </li> 
     931 * </ul> 
     932 * 
     933 * For any encodings that are of a fixed size greater than one byte, such as 
     934 * UTF-16 (all characters are two bytes in length), the characters must be 
     935 * aligned on the natural boundary for the system (e.g., two-byte characters 
     936 * on a 16-bit boundary, etc.). 
     937 * 
     938 * If an ARM implementation supports characters that are longer than one byte, 
     939 * the application and implementation are both responsible to cast (virtually, 
     940 * at least) the characters to wide characters, but the function signature 
     941 * does not change. For example, if UTF-16 is supported, the application must 
     942 * write pairs of characters into the arm_char_t* array (there would always be 
     943 * an even number of characters), and the implementation must process the data 
     944 * in pairs (looking for 0x0000 as a termination character rather than 0x00, 
     945 * for example). 
     946 * 
     947 * @ingroup ARM40Subbuffers 
     948 */ 
    369949typedef struct arm_subbuffer_charset 
    370950{ 
    371     arm_subbuffer_t header;  /* ARM_SUBBUFFER_CHARSET */ 
    372  
    373     arm_charset_t charset;  /* One of the IANA MIBenum values */ 
     951    /** 
     952     * header.format must be set to @ref ARM_SUBBUFFER_CHARSET 
     953     */ 
     954    arm_subbuffer_t header; 
     955 
     956    /** 
     957     * An arm_int32_t containing a MIBenum value assigned by the IANA 
     958     */ 
     959    arm_charset_t charset; 
     960    /** 
     961     * An arm_int32_t containing bit flags. The field is currently reserved 
     962     * for future use. 
     963     */ 
    374964    arm_int32_t flags; 
    375965} arm_subbuffer_charset_t; 
    376966 
     967/** 
     968 * @brief used to specify additional identity properties for an application 
     969 * 
     970 * Applications are identified by a name and an optional set of identity 
     971 * attribute (name,value) pairs. Application instances are further identified 
     972 * by an optional set of context (name,value) pairs. The optional context 
     973 * property names are provided in this sub-buffer on the 
     974 * arm_register_application() call. The optional context property values are  
     975 * provided on the arm_start_application() call. The sub-buffer is ignored if 
     976 * it is passed on any other call. 
     977 * 
     978 * The names of identity and context properties can be any string, with one 
     979 * exception. Strings beginning with the four characters "ARM:" are reserved 
     980 * for the ARM specification. The specification will define names with known 
     981 * semantics using this prefix. One name format is currently defined. Any name 
     982 * beginning with the eight-character prefix "ARM:CIM:" represents a name 
     983 * defined using the DMTF CIM (Distributed Management Task Force Common 
     984 * Information Model) naming rules. For example,  
     985 * "ARM:CIM:CIM_SoftwareElement.Name" indicates that the property value has 
     986 * the semantics of the Name property of the CIM_SoftwareElement class. It is 
     987 * anticipated that additional naming semantics are likely to be added in the 
     988 * future. 
     989 * 
     990 * @ingroup ARM40Subbuffers, ARM40IdentProps 
     991 */ 
    377992typedef struct arm_subbuffer_app_identity 
    378993{ 
    379     arm_subbuffer_t header;  /* ARM_SUBBUFFER_APP_IDENTITY */ 
    380  
     994    /** 
     995     * header.format must be set to @ref ARM_SUBBUFFER_APP_IDENTITY 
     996     */ 
     997    arm_subbuffer_t header; 
     998    /** 
     999     * count of property values in the following array. 
     1000     */ 
    3811001    arm_int32_t identity_property_count; 
     1002    /** 
     1003     * An array of C structures containing the property names and values. 
     1004     * 
     1005     * The array index of a property value in the value array is bound to 
     1006     * the property name at the same index in the name array. Moving the 
     1007     * (name,value) pair to a different index does not affect the identity 
     1008     * of the application. For example, if an application registers once 
     1009     * with a name A and a value X in array indices 0 and once with the 
     1010     * same name and value in array indices 1, the registered identity has 
     1011     * not changed. 
     1012     * 
     1013     * If a name is repeated in the array, the name and its corresponding 
     1014     * value are ignored, and the first instance of the name and value in 
     1015     * the array is used. The implementation may return an error code but 
     1016     * is not obliged to do so. 
     1017     * 
     1018     * Each structure is aligned as required for the C compiler on the 
     1019     * platform. 
     1020     */ 
    3821021    const arm_property_t *identity_property_array; 
     1022    /** 
     1023     * count of context names in the following array. 
     1024     */ 
    3831025    arm_int32_t context_name_count; 
     1026    /** 
     1027     * An array of character pointers to the context property names. 
     1028     * 
     1029     * If a name is repeated in the array, the name and its corresponding 
     1030     * value (in the application context sub-buffer) are ignored, and the 
     1031     * first instance of the name in the array (and its corresponding value) 
     1032     * is used. The implementation may return an error code but is not  
     1033     * obliged to do so. 
     1034     * 
     1035     * Each pointer in the array is aligned as required for the C compiler 
     1036     * on the platform. Each array element contains: 
     1037     * 
     1038     * @li @b name: A null-terminated string representing the name part of 
     1039     * the (name,value) pair. Each string has a maximum length of 128 
     1040     * characters, including the termination character. If any pointer is null 
     1041     * or points to a zero-length string, the (name,value) pair is ignored. 
     1042     * The values are provided in the Application Context Values sub-buffer 
     1043     * (arm_subbuffer_app_context_t). Names should not contain trailing 
     1044     * blank characters or consist of only blank characters. 
     1045     */ 
    3841046    const arm_char_t **context_name_array; 
    3851047} arm_subbuffer_app_identity_t; 
    3861048 
     1049/** 
     1050 * @brief used to associate context properties to an application instance. 
     1051 * 
     1052 * Applications are identified by a name and an optional set of identity 
     1053 * attribute (name,value) pairs. Application instances are further identified 
     1054 * by an optional set of context (name,value) pairs. These properties could 
     1055 * indicate something about the runtime instance of the application, such as 
     1056 * the instance identifier and the name of a configuration file used. 
     1057 * 
     1058 * The optional context property names are provided in the Application  
     1059 * Identity sub-buffer (arm_subbuffer_app_identity_t) on the 
     1060 * arm_register_application() call. The optional context property values are 
     1061 * provided in this sub-buffer on the arm_start_application() call. 
     1062 * The sub-buffer is ignored if it is passed on any other call. 
     1063 * 
     1064 * @ingroup ARM40Subbuffers, ARM40ContextProps 
     1065 */ 
    3871066typedef struct arm_subbuffer_app_context 
    3881067{ 
    389     arm_subbuffer_t header;  /* ARM_SUBBUFFER_APP_CONTEXT */ 
    390  
     1068    /** 
     1069     * header.format must be set to @ref ARM_SUBBUFFER_APP_CONTEXT 
     1070     */ 
     1071    arm_subbuffer_t header; 
     1072 
     1073    /** 
     1074     * count of context values in the following array. 
     1075     */ 
    3911076    arm_int32_t context_value_count; 
     1077    /** 
     1078     * An array of pointers to character strings containing the property values. 
     1079     * The values in the array are position-sensitive; each must align with the 
     1080     * corresponding context property name in the Application Identity  
     1081     * (arm_subbuffer_app_identity_t) sub-buffer. If the corresponding property 
     1082     * name pointer is null or points to a zero-length string, the value is 
     1083     * ignored. Each pointer is aligned as required for the C compiler on the 
     1084     * platform. Each array element contains: 
     1085     * @li @b Value: A null-terminated string representing the value part of the 
     1086     *     (name,value) pair. Each string has a maximum length of 256 characters, 
     1087     *     including the termination character. If any pointer is null or points 
     1088     *     to a zero-length string, the meaning is that there is no value for 
     1089     *     this instance. The value should not contain trailing blank characters 
     1090     *     or consist of only blank characters. 
     1091     */ 
    3921092    const arm_char_t **context_value_array; 
    3931093} arm_subbuffer_app_context_t; 
    3941094 
     1095/** 
     1096 * @brief used to specify additional identity properties for a transaction 
     1097 * 
     1098 * Transactions are identified by a name, an optional URI value, and an optional 
     1099 * set of attribute (name,value) pairs. The URI and optional (name,value) pairs 
     1100 * are provided in this sub-buffer on the arm_register_transaction() call. The 
     1101 * sub-buffer is ignored if it is passed on any other call. The identity is 
     1102 * scoped to a single application. 
     1103 * 
     1104 * The names of identity and context properties can be any string, with one 
     1105 * exception. Strings beginning with the four characters "ARM:" are reserved 
     1106 * for the ARM specification. The specification will define names with known 
     1107 + semantics using this prefix. One name format is currently defined. Any name 
     1108 * beginning with the eight-character prefix "ARM:CIM:" represents a name 
     1109 * defined using the DMTF CIM (Distributed Management Task Force Common 
     1110 * Information Model) naming rules. For example,  
     1111 * "ARM:CIM:CIM_SoftwareElement.Name" indicates that the property value has 
     1112 * the semantics of the Name property of the CIM_SoftwareElement class. It is 
     1113 * anticipated that additional naming semantics are likely to be added in the 
     1114 * future. 
     1115 * 
     1116 * @ingroup ARM40Subbuffers, ARM40IdentProps 
     1117 */ 
    3951118typedef struct arm_subbuffer_tran_identity 
    3961119{ 
    397     arm_subbuffer_t header;  /* ARM_SUBBUFFER_TRAN_IDENTITY */ 
    398  
     1120    /** 
     1121     * header.format must be set to @ref ARM_SUBBUFFER_TRAN_IDENTITY 
     1122     */ 
     1123    arm_subbuffer_t header; 
     1124 
     1125    /** 
     1126     * count of property values in the following array.# 
     1127     */ 
    3991128    arm_int32_t identity_property_count; 
     1129    /** 
     1130     * An array of C structures containing the property names and values. 
     1131     * 
     1132     * The array index of a property value in the value array is bound to 
     1133     * the property name at the same index in the name array. Moving the 
     1134     * (name,value) pair to a different index does not affect the identity 
     1135     * of the transaction. For example, if an application registers once 
     1136     * with a name A and a value X in array indices 0 and once with the 
     1137     * same name and value in array indices 1, the registered identity has 
     1138     * not changed. 
     1139     * 
     1140     * If a name is repeated in the array, the name and its corresponding 
     1141     * value are ignored, and the first instance of the name and value in 
     1142     * the array is used. The implementation may return an error code but 
     1143     * is not obliged to do so. 
     1144     * 
     1145     * Each structure is aligned as required for the C compiler on the 
     1146     * platform. 
     1147     */ 
    4001148    const arm_property_t *identity_property_array; 
     1149    /** 
     1150     * count of context names in the following array. 
     1151     */ 
    4011152    arm_int32_t context_name_count; 
     1153    /** 
     1154     * An array of character pointers to the context property names. 
     1155     * 
     1156     * If a name is repeated in the array, the name and its corresponding 
     1157     * value (in the transaction context sub-buffer) are ignored, and the 
     1158     * first instance of the name in the array (and its corresponding value) 
     1159     * is used. The implementation may return an error code but is not  
     1160     * obliged to do so. 
     1161     * 
     1162     * Each pointer in the array is aligned as required for the C compiler 
     1163     * on the platform. Each array element contains: 
     1164     * 
     1165     * @li @b name: A null-terminated string representing the name part of 
     1166     * the (name,value) pair. Each string has a maximum length of 128 
     1167     * characters, including the termination character. If any pointer is null 
     1168     * or points to a zero-length string, the (name,value) pair is ignored. 
     1169     * The values are provided in the Transaction Context Values sub-buffer 
     1170     * (arm_subbuffer_tran_context_t). Names should not contain trailing 
     1171     * blank characters or consist of only blank characters. 
     1172     */ 
    4021173    const arm_char_t **context_name_array; 
     1174    /** 
     1175     * Pointer to a string containing a URI, with a maximum of 4096 characters, 
     1176     * including the termination character. The string is null terminated. The 
     1177     * pointer may be null. A zero-length string is treated as a null value. 
     1178     */ 
    4031179    const arm_char_t *uri; 
    4041180} arm_subbuffer_tran_identity_t; 
    4051181 
     1182/** 
     1183 * @brief used to associate context properties to a transaction instance. 
     1184 * 
     1185 * In addition to the identity properties, a transaction may be described with 
     1186 * additional context properties. Context properties differ from identity 
     1187 * properties in that although the name is provided when the transaction is 
     1188 * registered [arm_register_transaction()], the values are provided when a 
     1189 * transaction is measured [arm_start_transaction() or  
     1190 * arm_report_transaction()]. The value of an identity property never changes, 
     1191 * whereas the value of a context property may change every time a transaction 
     1192 * executes. 
     1193 * 
     1194 * Context properties are of two forms. There may be one URI value and up to 
     1195 * twenty (name,value) pairs. No name may duplicate the name of a transaction 
     1196 * identity property. 
     1197 * 
     1198 * @ingroup ARM40Subbuffers, ARM40ContextProps 
     1199 */ 
    4061200typedef struct arm_subbuffer_tran_context 
    4071201{ 
    408     arm_subbuffer_t header;  /* ARM_SUBBUFFER_TRAN_CONTEXT */ 
    409  
     1202    /** 
     1203     * header.format must be set to @ref ARM_SUBBUFFER_TRAN_CONTEXT 
     1204     */ 
     1205    arm_subbuffer_t header; 
     1206 
     1207    /** 
     1208     * count of context values in the following array. 
     1209     */ 
    4101210    arm_int32_t context_value_count; 
     1211    /** 
     1212     * An array of pointers to character strings containing the property values. 
     1213     * The values in the array are position-sensitive; each must align with the 
     1214     * corresponding context property name in the Transaction Identity  
     1215     * (arm_subbuffer_tran_identity_t) sub-buffer. If the corresponding property 
     1216     * name pointer is null or points to a zero-length string, the value is 
     1217     * ignored. Each pointer is aligned as required for the C compiler on the 
     1218     * platform. Each array element contains: 
     1219     * @li @b Value: A null-terminated string representing the value part of the 
     1220     *     (name,value) pair. Each string has a maximum length of 256 characters, 
     1221     *     including the termination character. If any pointer is null or points 
     1222     *     to a zero-length string, the meaning is that there is no value for 
     1223     *     this instance. The value should not contain trailing blank characters 
     1224     *     or consist of only blank characters. 
     1225     */ 
    4111226    const arm_char_t **context_value_array; 
     1227    /** 
     1228     * Pointer to a string containing a URI, with a maximum of 4096 characters, 
     1229     * including the termination character. The string is null terminated. The 
     1230     * pointer may be null. 
     1231     * 
     1232     * If a URI is provided in both the Transaction Identity sub-buffer and in 
     1233     * the Transaction Context sub-buffer, the URI in the Transaction Identity 
     1234     * sub-buffer must be the same as the URI provided in the Transaction 
     1235     * Context sub-buffer, or a truncated subset. 
     1236     */ 
    4121237    const arm_char_t *uri; 
    4131238} arm_subbuffer_tran_context_t; 
    4141239 
     1240/** 
     1241 * @brief used to pass the arrival time for a transaction instance. 
     1242 * 
     1243 * Some applications may start processing a transaction before all the context 
     1244 * information that identifies the transaction is known. For example, it might 
     1245 * by necessary to retrieve the context information as the first step in 
     1246 * processing the transaction. 
     1247 * 
     1248 * When the application can call ARM when the transaction starts but not call 
     1249 * arm_start_transaction() because it does not yet have all the data it needs, 
     1250 * the application can call arm_get_arrival_time() to receive a timestamp value 
     1251 * for the current time from the ARM implementation. This timestamp value is 
     1252 * known as the "arrival time". When the transaction context data is all 
     1253 * known, arm_start_transaction() is called, passing the optional arrival time 
     1254 * value in the Arrival Time sub-buffer, to indicate when the transaction 
     1255 * actually started executing. 
     1256 * 
     1257 * The arrival time field is a 64-bit integer containing the value returned by 
     1258 * the arm_get_arrival_time() function. The format of the data is 
     1259 * implementation-defined. 
     1260 * 
     1261 * @ingroup ARM40Subbuffers ARM4PrepTime 
     1262 */ 
    4151263typedef struct arm_subbuffer_arrival_time 
    4161264{ 
    417     arm_subbuffer_t header;  /* ARM_SUBBUFFER_ARRIVAL_TIME */ 
    418  
     1265    /** 
     1266     * header.format must be set to @ref ARM_SUBBUFFER_ARRIVAL_TIME 
     1267     */ 
     1268    arm_subbuffer_t header; 
     1269    /** 
     1270     * An arm_int64_t value containing an opaque time indicator generated by 
     1271     * and recognizable by the ARM implementation. 
     1272     */ 
    4191273    arm_arrival_time_t opaque_time; 
    4201274} arm_subbuffer_arrival_time_t; 
    4211275 
     1276/** 
     1277 * @brief used to associate metrics to a transaction 
     1278 * 
     1279 * Applications may provide additional data about a transaction when the  
     1280 * transaction starts, while it is executing, and/or after it has stopped. 
     1281 * This additional data may serve several purposes, such as indicating the 
     1282 * size of a transaction (e.g., the number of bytes in a file for a file 
     1283 * transfer transaction), the state of the system (e.g., the number of queued 
     1284 * up transactions when this transaction arrived), or an error code. The 
     1285 * metadata describing each metric is provided with the arm_register_metric() 
     1286 * function. 
     1287 * 
     1288 * Each transaction definition may define zero to seven metrics for which 
     1289 * data values may be provided on arm_start_transaction(),  
     1290 * arm_update_transaction(), arm_stop_transaction(), or 
     1291 * arm_report_transaction(). Each metric is assigned to an array slot 
     1292 * numbered 0 to 6 (they were numbered 1 to 7 in ARM 2.0). This sub-buffer 
     1293 * is passed on the arm_register_transaction() function to indicate which 
     1294 * metrics are assigned to which slots. 
     1295 * 
     1296 * The combination of this sub-buffer plus the arm_register_metric() 
     1297 * function replaces ARM 2.0 format = 101. Unlike ARM 2.0, the metric 
     1298 * definitions do not influence the transaction identity. Any properties 
     1299 * besides the transaction name that affect identity are provided in the 
     1300 * Transaction Identity Properties (arm_subbuffer_tran_identity_t) sub-buffer. 
     1301 * 
     1302 * @ingroup ARM40Subbuffers ARM40Metrics 
     1303 */ 
    4221304typedef struct arm_subbuffer_metric_bindings 
    4231305{ 
    424     arm_subbuffer_t header;  /* ARM_SUBBUFFER_METRIC_BINDINGS */ 
    425  
     1306    /** 
     1307     * header.format must be set to @ref ARM_SUBBUFFER_METRIC_BINDINGS 
     1308     */ 
     1309    arm_subbuffer_t header; 
     1310 
     1311    /** 
     1312     * count of metric values in the following array. 
     1313     */ 
    4261314    arm_int32_t count; 
     1315    /** 
     1316     * An array of C structures containing the metric bindings. Each  
     1317     * structure is aligned as required for the C compiler on the platform. 
     1318     */ 
    4271319    const arm_metric_binding_t *metric_binding_array; 
    4281320} arm_subbuffer_metric_bindings_t; 
    4291321 
     1322/** 
     1323 * @brief used to pass a metric values to the ARM implementation. 
     1324 * 
     1325 * The buffer is used to pass metric values on any of arm_start_transaction(), 
     1326 * arm_update_transaction(), arm_stop_transaction(), and 
     1327 * arm_report_transaction(). 
     1328 * 
     1329 * @ingroup ARM40Subbuffers ARM40Metrics 
     1330 */ 
    4301331typedef struct arm_subbuffer_metric_values 
    4311332{ 
    432     arm_subbuffer_t header;  /* ARM_SUBBUFFER_METRIC_VALUES */ 
    433  
     1333    /** 
     1334     * header.format must be set to @ref ARM_SUBBUFFER_METRIC_VALUES 
     1335     */ 
     1336    arm_subbuffer_t header; 
     1337 
     1338    /** 
     1339     * count of metric values in the following array 
     1340     */ 
    4341341    arm_int32_t count; 
     1342    /** 
     1343     * Pointer to an array of metric values. The number of metric values in the 
     1344     * array is specified by the previous count value. 
     1345     */ 
    4351346    const arm_metric_t *metric_value_array; 
    4361347} arm_subbuffer_metric_values_t; 
    4371348 
     1349/** 
     1350 * @brief used to associate an user name and/or ID to a transaction instance. 
     1351 * 
     1352 * An user name and/or ID may be optionally associated with each transaction 
     1353 * instance. A name is a null-terminated character string. An ID is a 16-byte 
     1354 * binary value, such as a UUID. Either or both may be provided. 
     1355 * 
     1356 * @ingroup ARM40Subbuffers 
     1357 */ 
    4381358typedef struct arm_subbuffer_user 
    4391359{ 
    440     arm_subbuffer_t header;  /* ARM_SUBBUFFER_USER */ 
    441  
     1360    /** 
     1361     * header.format must be set to @ref ARM_SUBBUFFER_USER 
     1362     */ 
     1363    arm_subbuffer_t header; 
     1364 
     1365    /** 
     1366     * A null-terminated character string with a maximum length of 128 
     1367     * characters, including the termination character. A null value 
     1368     * indicates no name is provided. 
     1369     */ 
    4421370    const arm_char_t *name; 
     1371    /** 
     1372     * A boolean indicating whether the ID field contains a valid ID. 
     1373     */ 
    4431374    arm_boolean_t id_valid; 
     1375    /** 
     1376     * 16-byte ID (16 bytes) that is associated with and can be used as 
     1377     * an alias for the user name. 
     1378     */ 
    4441379    arm_id_t id; 
    4451380} arm_subbuffer_user_t; 
    4461381 
     1382/** 
     1383 * @brief used to specify a different system than the one on which the 
     1384 *     call is executed. 
     1385 * 
     1386 * The System Address sub-buffer is used with arm_start_application() when the 
     1387 * transactions that will be reported execute on a different system than the one 
     1388 * on which they will be reported. 
     1389 * 
     1390 * <ul> 
     1391 * <li> 
     1392 * If no System Address sub-buffer is provided on arm_start_application(), all 
     1393 * transactions reported by this application instance execute in the current 
     1394 * process. 
     1395 * </li> 
     1396 * <li> 
     1397 * If a System Address sub-buffer is provided on arm_start_application(), all 
     1398 * transactions execute in a different process. 
     1399 * </li> 
     1400 * <li> 
     1401 * If a System Address sub-buffer is provided in which the system address length 
     1402 * is zero, or the system address pointer is null, the system is the "local" 
     1403 * system, as determined by the ARM implementation. 
     1404 * </li> 
     1405 * <li> 
     1406 * If a System Address sub-buffer is provided in which there is a non-null 
     1407 * system address and length, the system may be the local system or a remote 
     1408 * system. Interpretation of what is local versus remote is at the discretion 
     1409 * of the ARM implementation. 
     1410 * </li> 
     1411 * </ul> 
     1412 * 
     1413 * @ingroup ARM40Subbuffers 
     1414 */ 
    4471415typedef struct arm_subbuffer_system_address 
    4481416{ 
    449     arm_subbuffer_t header;  /* ARM_SUBBUFFER_SYSTEM_ADDRESS */ 
    450  
     1417    /** 
     1418     * header.format must be set to @ref ARM_SUBBUFFER_SYSTEM_ADDRESS 
     1419     */ 
     1420    arm_subbuffer_t header; 
     1421 
     1422    /** 
     1423     * An arm_int16_t format of the system address field. The following formats 
     1424     * are defined: 
     1425     * @li @ref ARM_SYSADDR_FORMAT_IPV4 
     1426     * @li @ref ARM_SYSADDR_FORMAT_IPV4PORT 
     1427     * @li @ref ARM_SYSADDR_FORMAT_IPV6 
     1428     * @li @ref ARM_SYSADDR_FORMAT_IPV6PORT 
     1429     * @li @ref ARM_SYSADDR_FORMAT_SNA 
     1430     * @li @ref ARM_SYSADDR_FORMAT_X25 
     1431     * @li @ref ARM_SYSADDR_FORMAT_HOSTNAME 
     1432     * @li @ref ARM_SYSADDR_FORMAT_UUID 
     1433     */ 
    4511434    arm_int16_t address_format; 
     1435    /** 
     1436     * An arm_int16_t length of system address in bytes. 
     1437     * @li There is no maximum length. 
     1438     * @li A length of zero refers to the local system. 
     1439     */ 
    4521440    arm_int16_t address_length; 
     1441    /** 
     1442     * A pointer to a byte array containing the system address. 
     1443     * @li The byte array is the length specified by the "Length of system  
     1444     *     address" field. Note that it could have a length of zero bytes, 
     1445     *     or be a null pointer, indicating that it is the local system. 
     1446     */ 
    4531447    const arm_uint8_t *address; 
     1448    /** 
     1449     * A boolean indicating whether the system address ID field contains 
     1450     * a valid ID. 
     1451     */ 
    4541452    arm_boolean_t id_valid; 
     1453    /** 
     1454     * A 16-byte character array containing an ID that can be used as a  
     1455     * synonym for the tuple of (format, length, system address). If the 
     1456     * "System Address" format is a UUID, and a "System Address ID" is 
     1457     * provided, it is a coincidence if the values are identical. Nothing 
     1458     * precludes or requires that they be the same. 
     1459     * @li The ID is an optional identifier that is mapped to the other 
     1460     *     fields. If the value is all zeros, the ID is not being provided. 
     1461     */ 
    4551462    arm_id_t id; 
    4561463} arm_subbuffer_system_address_t; 
    4571464 
     1465/** 
     1466 * @brief used to provide diagnostic detail information for not good  
     1467 *     transactions. 
     1468 * 
     1469 * When a transaction completion is reported with arm_stop_transaction() or 
     1470 * arm_report_transaction(), and the transaction status is not  
     1471 * @ref ARM_STATUS_GOOD, the application may provide a character string  
     1472 * containing any arbitrary diagnostic data. The string may not be longer 
     1473 * than 4096 characters, including the null-termination character. For  
     1474 * example, the application might provide the SQL query text for a failing 
     1475 * database transaction. 
     1476 * 
     1477 * @ingroup ARM40Subbuffers 
     1478 */ 
    4581479typedef struct arm_subbuffer_diag_detail 
    4591480{ 
    460     arm_subbuffer_t header;  /* ARM_SUBBUFFER_DIAG_DETAIL */ 
    461  
     1481    /** 
     1482     * header.format must be set to @ref ARM_SUBBUFFER_DIAG_DETAIL 
     1483     */ 
     1484    arm_subbuffer_t header; 
     1485 
     1486    /** 
     1487     * A null-terminated string containing the diagnostic data. Each string has 
     1488     * a maximum length of 4096 characters, including the termination character. 
     1489     * If the pointer is null, it is equivalent to not providing the sub-buffer 
     1490     * at all. 
     1491     */ 
    4621492    const arm_char_t *diag_detail; 
    4631493} arm_subbuffer_diag_detail_t; 
    4641494 
    465 /* --------------------------------------------------------------- */ 
    466 /* ------------------ ARM4 API section --------------------------- */ 
    467 /* --------------------------------------------------------------- */ 
    468  
    469 /* register metadata API functions */ 
     1495/* -------------------------------------------------------------------------- */ 
     1496/* ---------------------------- ARM4 API section ---------------------------- */ 
     1497/* -------------------------------------------------------------------------- */ 
     1498 
     1499/* -------------------- register metadata API functions --------------------- */ 
     1500 
     1501/** 
     1502 * @brief describes and registers the application with ARM 
     1503 * 
     1504 * arm_register_application() describes metadata about an application. 
     1505 * 
     1506 * The application uses arm_register_application() to inform the ARM library of 
     1507 * metadata about the application. This metadata does not change from one 
     1508 * application instance to another. It contains part of the function of the 
     1509 * ARM 2.0 call arm_init(); arm_start_application() contains the other part. 
     1510 * 
     1511 * ARM generates an ID that is passed in arm_register_transaction() and  
     1512 * arm_start_application(). 
     1513 * 
     1514 * @return The returned code is a status that may indicate whether an error 
     1515 *     was detected. If the return code is negative, an error occurred. If the 
     1516 *     return code is not negative, an error may or may not have occurred - the 
     1517 *     determination of what is an error and whether an error code is returned is 
     1518 *     at the discretion of the ARM implementation. The application can test the 
     1519 *     return code if it wants to provide its own error logging. 
     1520 * 
     1521 * @param [in] app_name       Pointer to a null-terminated string containing the 
     1522 *     name of the application. The maximum length of the name is 128 characters, 
     1523 *     including the termination character. It serves no purpose and is illegal 
     1524 *     to make this call if the pointer is null. A name should be chosen that is 
     1525 *     unique, so generic names that might be used by a different development 
     1526 *     team, such as "Payroll Application", should not be used. The name should 
     1527 *     not contain trailing blank characters or consist of only blank characters. 
     1528 *     If the application has a copyrighted product name, the copyrighted name 
     1529 *     would be a good choice. 
     1530 * @param [in] input_app_id   Pointer to an optional 128-bit ID (16 bytes) that 
     1531 *     is unique and that can be treated as an alias for the other metadata. It 
     1532 *     can be any value except all zeros or all ones. If the pointer is null 
     1533 *     (@ref ARM_ID_NONE), no ID is provided. See @ref ARMID for further information. 
     1534 *     @n  
     1535 *     If an ARM implementation is passed an ID that was previously registered 
     1536 *     within this process, the implementation can ignore the other metadata 
     1537 *     parameters and assume they are identical to the previously registered 
     1538 *     metadata. The application metadata consists of the following fields: 
     1539 *     @a app_name and the arm_subbuffer_app_identity_t sub-buffer passed in 
     1540 *     @a buffer4. 
     1541 * @param [in] flags        Contains 32-bit flags. No values are currently 
     1542 *     defined. The field should be zero (@ref ARM_FLAG_NONE). 
     1543 * @param [in] buffer4      Pointer to the optional buffer, if any. If the 
     1544 *     pointer is null (@ref ARM_BUF4_NONE), buffer4 there is no buffer. The 
     1545 *     sub-buffer formats that might be used are: 
     1546 *     <ul> 
     1547 *     <li>arm_subbuffer_app_identity_t</li> 
     1548 *     <li>arm_subbuffer_encoding_t</li> 
     1549 *     </ul> 
     1550 * @param [in] output_app_id  Pointer to a 16-byte field. ARM will store a 
     1551 *     16-byte value. There are no requirements on what value it is set to, 
     1552 *     except that it must be possible to pass it on other calls, such as 
     1553 *     arm_start_application(), without the application needing to do any 
     1554 *     error checking. 
     1555 *  
     1556 * @return The returned code is a status that may indicate whether an error 
     1557 *     was detected. If the return code is negative, an error occurred. If the 
     1558 *     return code is not negative, an error may or may not have occurred - the 
     1559 *     determination of what is an error and whether an error code is returned 
     1560 *     is at the discretion of the ARM implementation. The application can test 
     1561 *     the return code if it wants to provide its own error logging. See 
     1562 *     @ref ARMERROR for further information about error handling. 
     1563 * 
     1564 * @see arm_destroy_application(), arm_register_transaction(), 
     1565 *      arm_start_application() 
     1566 * @ingroup ARM40Funcs  
     1567 */ 
    4701568ARM4_API_DYNAMIC(arm_error_t) 
    4711569arm_register_application( 
     
    4761574    arm_id_t *output_app_id); 
    4771575 
     1576/** 
     1577 * @brief destroy any registered ARM application data 
     1578 * 
     1579 * arm_destroy_application() indicates that the registration data about an 
     1580 * application previously registered with arm_register_application() is no 
     1581 * longer needed. 
     1582 * 
     1583 * The purpose of this call is to signal the ARM implementation so that it can 
     1584 * release any storage it is holding. Ending a process or unloading the ARM 
     1585 * library results in an implicit arm_destroy_application() for any previously 
     1586 * registered applications. 
     1587 * 
     1588 * It is possible for multiple arm_register_application() calls to be made in 
     1589 * the same process with identical identity data. When this is done, 
     1590 * arm_destroy_application() is assumed to be paired with one  
     1591 * arm_register_application(). For example, if arm_register_application() is 
     1592 * executed twice with the same output ID, and arm_destroy_application() is 
     1593 * executed once using this ID, it is assumed that an instance of the  
     1594 * application is still active and it is not safe to discard the application 
     1595 * registration data associated with the ID. 
     1596 * 
     1597 * @param [in] app_id       Application ID returned from an 
     1598 *     arm_register_application() call in the same process. 
     1599 * @param [in] flags        Contains 32-bit flags. No values are currently 
     1600 *     defined. The field should be zero (@ref ARM_FLAG_NONE). 
     1601 * @param [in] buffer4      Pointer to the optional buffer, if any. If the 
     1602 *     pointer is null, there is no buffer. No sub-buffer types are currently 
     1603 *     valid with this function call, so the pointer should be null 
     1604 *     (@ref ARM_BUF4_NONE). 
     1605 * 
     1606 * @return The returned code is a status that may indicate whether an error 
     1607 *     was detected. If the return code is negative, an error occurred. If the 
     1608 *     return code is not negative, an error may or may not have occurred - the 
     1609 *     determination of what is an error and whether an error code is returned 
     1610 *     is at the discretion of the ARM implementation. The application can test 
     1611 *     the return code if it wants to provide its own error logging. See 
     1612 *     @ref ARMERROR for further information about error handling. 
     1613 * 
     1614 * @see arm_register_application() 
     1615 * @ingroup ARM40Funcs 
     1616 */ 
    4781617ARM4_API_DYNAMIC(arm_error_t) 
    4791618arm_destroy_application( 
     
    4821621    const arm_buffer4_t *buffer4); 
    4831622 
     1623/** 
     1624 * @brief describes and register a transaction with ARM 
     1625 * 
     1626 * arm_register_transaction() describes metadata about a transaction. 
     1627 * 
     1628 * The application uses arm_register_transaction() to inform the ARM library of 
     1629 * metadata about the transaction measured by the application. This metadata 
     1630 * does not change from one application instance to another. It is the 
     1631 * equivalent of the ARM 2.0 call arm_getid(). 
     1632 * 
     1633 * ARM generates an ID that is passed in arm_start_transaction() and  
     1634 * arm_report_transaction(). 
     1635 * 
     1636 * @param [in] app_id         Application ID returned from an 
     1637 *     arm_register_application() call in the same process. 
     1638 * @param [in] tran_name      Pointer to a null-terminated string containing the 
     1639 *     name of the transaction. Each transaction registered by an application 
     1640 *     must have a unique name. The maximum length of the string is 128 
     1641 *     characters, including the termination character. It serves no purpose and 
     1642 *     is illegal to make this call if the pointer is null. The name should not 
     1643 *     contain trailing blank characters or consist of only blank characters. 
     1644 * @param [in] input_tran_id  Pointer to an optional 128-bit ID (16 bytes) that 
     1645 *     is unique and that can be treated as an alias for the other metadata. It 
     1646 *     can be any value except all zeros or all ones. If the pointer is null 
     1647 *     (@ref ARM_ID_NONE), no ID is provided. See @ref ARMID for further information. 
     1648 *     @n 
     1649 *     If an ARM implementation is passed an ID that was previously registered 
     1650 *     within this process, the implementation can ignore the other metadata 
     1651 *     parameters and assume they are identical to the previously registered 
     1652 *     metadata. The transaction metadata consists of the following fields: 
     1653 *     @a app_id, @a tran_name, and the arm_subbuffer_metric_bindings_t and 
     1654 *     arm_subbuffer_tran_identity_t sub-buffers passed in buffer4. 
     1655 * @param [in] flags        Contains 32-bit flags. No values are currently 
     1656 *     defined. The field should be zero (@ref ARM_FLAG_NONE). 
     1657 * @param [in] buffer4        Pointer to the optional buffer, if any. If the 
     1658 *     pointer is null (@ref ARM_BUF4_NONE), buffer4 there is no buffer. The 
     1659 *     sub-buffers that may be used are: @n 
     1660 *     <ul> 
     1661 *     <li>arm_subbuffer_metric_bindings_t</li> 
     1662 *     <li>arm_subbuffer_tran_identity_t</li> 
     1663 *     </ul> 
     1664 *     The names of any transaction context properties are supplied in the 
     1665 *     arm_subbuffer_tran_identity_t sub-buffer. They do not change afterwards; 
     1666 *     that is, the names are immutable. The transaction context values may 
     1667 *     change with each arm_start_transaction(), arm_report_transaction(), or 
     1668 *     arm_generate_correlator(). 
     1669 * @param [in] output_tran_id  Pointer to a 16-byte field. ARM will store a 
     1670 *     16-byte value. There are no requirements on the value it is set to, 
     1671 *     except that it must be possible to pass it on other calls, such as 
     1672 *     arm_start_transaction(), without the application needing to do any error 
     1673 *     checking. 
     1674 * 
     1675 * @see arm_register_application(), arm_report_transaction(), 
     1676 *      arm_start_transaction() 
     1677 * @ingroup ARM40Funcs 
     1678 */ 
    4841679ARM4_API_DYNAMIC(arm_error_t) 
    4851680arm_register_transaction( 
     
    4911686    arm_id_t *output_tran_id); 
    4921687 
     1688/** 
     1689 * @brief describes and register metrics with ARM 
     1690 * 
     1691 * arm_register_metric() describes metadata about a metric. 
     1692 * 
     1693 * The application uses arm_register_metric() to inform the ARM library of 
     1694 * metadata about each metric the application provides. 
     1695 * 
     1696 * ARM generates an ID that is passed in the metric binding sub-buffer  
     1697 * (arm_subbuffer_metric_bindings_t) to arm_register_transaction(). 
     1698 * 
     1699 * @param [in] app_id         Application ID returned from an 
     1700 *     arm_register_application() call in the same process. 
     1701 * @param [in] metric_name    Pointer to a null-terminated string containing 
     1702 *     the name of the metric. The maximum name length of the string is 128 
     1703 *     characters, including the termination character. It serves no purpose 
     1704 *     and is illegal to make this call if the pointer is null. The name  
     1705 *     should not contain trailing blank characters or consist of only blank 
     1706 *     characters. @n 
     1707 *     The name can be any string, with one exception. Strings beginning with 
     1708 *     the four characters "ARM:" are reserved for the ARM specification. The 
     1709 *     specification will define names with known semantics using this prefix. 
     1710 *     One name format is currently defined. Any name beginning with the eight 
     1711 *     character prefix "ARM:CIM:" represents a name defined using the DMTF 
     1712 *     CIM (Distributed Management Task Force Common Information Model) naming 
     1713 *     rules. For example,"ARM:CIM:CIM_SoftwareElement.Name" indicates that the 
     1714 *     metric value has the semantics of the Name property of the 
     1715 *     CIM_SoftwareElement class. It is anticipated that additional naming 
     1716 *     semantics are likely to be added in the future. 
     1717 * @param [in] metric_format  Describes the data type. The value must be one 
     1718 *     of the following: 
     1719 *    <ul> 
     1720 *    <li>@ref ARM_METRIC_FORMAT_COUNTER32</li> 
     1721 *    <li>@ref ARM_METRIC_FORMAT_COUNTER64</li> 
     1722 *    <li>@ref ARM_METRIC_FORMAT_CNTRDIVR32</li> 
     1723 *    <li>@ref ARM_METRIC_FORMAT_GAUGE32</li> 
     1724 *    <li>@ref ARM_METRIC_FORMAT_GAUGE64</li> 
     1725 *    <li>@ref ARM_METRIC_FORMAT_GAUGEDIVR32</li> 
     1726 *    <li>@ref ARM_METRIC_FORMAT_NUMERICID32</li> 
     1727 *    <li>@ref ARM_METRIC_FORMAT_NUMERICID64</li> 
     1728 *    <li>@ref ARM_METRIC_FORMAT_STRING32</li> 
     1729 *    </ul> 
     1730 * @param [in] metric_usage   Describes how the metric is used. The value must 
     1731 *    be one of the following values, or usage a negative value (any negative 
     1732 *    value is specific to the application; the negative values are not 
     1733 *    expected to be widely used). 
     1734 *    <ul> 
     1735 *    <li>@ref ARM_METRIC_USE_GENERAL</li> 
     1736 *    <li>@ref ARM_METRIC_USE_TRAN_SIZE</li> 
     1737 *    <li>@ref ARM_METRIC_USE_TRAN_STATUS</li> 
     1738 *    </ul> 
     1739 * @param [in] metric_unit    Pointer to a null-terminated string containing 
     1740 *     the units (such as "files transferred") of the metric. The maximum 
     1741 *     length of the string is 128 characters, including the termination 
     1742 *     character. The pointer may be null. 
     1743 * @param [in] input_metric_id  Pointer to an optional 128-bit ID (16 bytes) that 
     1744 *     is unique and that can be treated as an alias for the other metadata. It 
     1745 *     can be any value except all zeros or all ones. If the pointer is null 
     1746 *     (@ref ARM_ID_NONE), no ID is provided. See @ref ARMID for further 
     1747 *     information. 
     1748 *     @n 
     1749 *     If an ARM implementation is passed an ID that was previously registered 
     1750 *     within this process, the implementation can ignore the other metadata 
     1751 *     parameters and assume they are identical to the previously registered 
     1752 *     metadata. The metric metadata consists of the following fields:  
     1753 *     @a app_id, @a metric_name, @a metric_format, @a metric_usage, and 
     1754 *     @a metric_unit. 
     1755 * @param [in] flags        Contains 32-bit flags. No values are currently 
     1756 *     defined. The field should be zero (@ref ARM_FLAG_NONE). 
     1757 * @param [in] buffer4      Pointer to the optional buffer, if any. If the 
     1758 *     pointer is null, there is no buffer. No sub-buffer types are currently 
     1759 *     valid with this function call, so the pointer should be null 
     1760 *     (@ref ARM_BUF4_NONE). 
     1761 * @param [out] output_metric_id  Pointer to a 16-byte field. ARM will store 
     1762 *     a 16-byte value. There are no requirements on the value it is set to, 
     1763 *     except that it must be possible to pass it in the metric binding 
     1764 *     sub-buffer (arm_subbuffer_metric_bindings_t) on the 
     1765 *     arm_register_transaction() call, without the application needing to do 
     1766 *     any error checking. 
     1767 * 
     1768 * @return The returned code is a status that may indicate whether an error 
     1769 *     was detected. If the return code is negative, an error occurred. If the 
     1770 *     return code is not negative, an error may or may not have occurred - the 
     1771 *     determination of what is an error and whether an error code is returned 
     1772 *     is at the discretion of the ARM implementation. The application can test 
     1773 *     the return code if it wants to provide its own error logging. See 
     1774 *     @ref ARMERROR for further information about error handling. 
     1775 * 
     1776 * @see arm_register_application(), arm_register_transaction() 
     1777 * @ingroup ARM40Funcs 
     1778 */ 
    4931779ARM4_API_DYNAMIC(arm_error_t) 
    4941780arm_register_metric( 
     
    5031789    arm_id_t *output_metric_id); 
    5041790 
    505 /* application instance API functions */ 
     1791/** 
     1792 * @brief indicates that an instance of an application has started running 
     1793 * 
     1794 * arm_start_application() indicates that an instance of an application has 
     1795 * started running and is prepared to make ARM calls. 
     1796 * 
     1797 * In many cases, there will be only one application instance in a process, 
     1798 * but there are cases in which there could be multiple instances. An example 
     1799 * of multiple application instances in the same process is if several Java 
     1800 * applications run in the same JVM (Java Virtual Machine) in the same 
     1801 * process, and they each call the ARM 4.0 C interface (either directly, or 
     1802 * indirectly via an implementation of the ARM 4.0 Java interface). They might 
     1803 * share the same application ID or they might be separately registered. 
     1804 * 
     1805 * Application context properties may be used to differentiate between 
     1806 * instances. The values do not have to be different from other instances, 
     1807 * though making them unique is suggested. The context properties are provided 
     1808 * through function parameters and/or a sub-buffer. 
     1809 * 
     1810 * The group and instance names are provided as function parameters. 
     1811 * 
     1812 * Up to twenty (name,value) pairs of context properties may be provided in 
     1813 * a sub-buffer. 
     1814 * 
     1815 * ARM 4.1 added a new capability for controlling the level of instrumentation 
     1816 * that the ARM implementation prefers. It uses the Application Control 
     1817 * sub-buffer (arm_subbuffer_app_control_t). 
     1818 * 
     1819 * There is a special case in which a System Address sub-buffer is provided. 
     1820 * The System Address sub-buffer is provided when arm_report_transaction() will 
     1821 * be used to report data about transactions that executed on a different 
     1822 * system. In this case, the arm_start_application() provides a scoping context 
     1823 * for the transaction instances, but does not indicate that the application 
     1824 * instance is running on the local system. If the System Address sub-buffer is 
     1825 * provided, it is meaningless to use arm_start_transaction() or  
     1826 * arm_stop_transaction(), or any of the API calls that are used after 
     1827 * arm_start_transaction() and before arm_stop_transaction(). 
     1828 * 
     1829 * The combination of arm_register_application() and arm_start_application() is 
     1830 * equivalent to the ARM 2.0 call arm_init(). 
     1831 * 
     1832 * @param [in] app_id         Pointer to a 16-byte ID returned by an  
     1833 *     arm_register_application() call. 
     1834 * @param [in] app_group      Pointer to a null-terminated string containing the 
     1835 *     identity of a group of application instances, if any. Application 
     1836 *     instances for a given software product that are started for a common 
     1837 *     runtime purpose are typically very good candidates for using the same 
     1838 *     group name. For example, identical replica instances of a product started 
     1839 *     across multiple processes or servers to address a specific transaction 
     1840 *     workload objective can be, advantageously to the ARM agent, commonly 
     1841 *     identified by the group name. The maximum length of the string is 
     1842 *     @ref ARM_PROPERTY_VALUE_MAX_CHARS characters, including the termination 
     1843 *     character. A null pointer indicates that there is no group. 
     1844 * @param [in] app_instance   Pointer to a null-terminated string containing the 
     1845 *     identity of this instance of the application. It might contain the 
     1846 *     process ID, or a UUID in printable characters, for example. The maximum 
     1847 *     length of the string is @ref ARM_PROPERTY_VALUE_MAX_CHARS characters,  
     1848 *     including the termination character. A null pointer indicates that there 
     1849 *     is no instance value. 
     1850 * @param [in] flags          Contains 32-bit flags. No values are currently  
     1851 *     defined. The field should be zero (@ref ARM_FLAG_NONE). 
     1852 * @param [in] buffer4        Pointer to the optional buffer, if any. If the 
     1853 *     pointer is null (@ref ARM_BUF4_NONE), there is no buffer. The sub-buffer 
     1854 *     formats that might be used are: 
     1855 *     <ul> 
     1856 *     <li>arm_subbuffer_app_context_t</li> 
     1857 *     <li>arm_subbuffer_app_control_t</li> 
     1858 *     <li>arm_subbuffer_system_address_t 
     1859 *        <ul> 
     1860 *        <li>If no System Address sub-buffer is provided on  
     1861 *        arm_start_application(), all transactions reported by this application 
     1862 *        instance execute in the current process.</li> 
     1863 *        <li>If a System Address sub-buffer is provided on 
     1864 *        arm_start_application(), all transactions execute in a different 
     1865 *        process.</li> 
     1866 *        <li>If a System Address sub-buffer is provided in which the system 
     1867 *        address length is zero, or the system address pointer is null, the 
     1868 *        system is the "local" system, as determined by the ARM 
     1869 *        implementation.</li> 
     1870 *        <li>If a System Address sub-buffer is provided in which there is a 
     1871 *        non-null systemaddress and length, the system may be the local system 
     1872 *        or a remote system. Interpretation of what is local versus remote is 
     1873 *        at the discretion of the ARM implementation.</li> 
     1874 *        </ul> 
     1875 *     </li> 
     1876 *     </ul> 
     1877 * @param [out] app_handle    Pointer to an arm_int64_t into which the ARM 
     1878 *     library will store the value of the handle that will represent the 
     1879 *     application instance in all calls, up to and including the 
     1880 *     arm_stop_application() that indicates that the instance has completed 
     1881 *     executing. The scope of the handle is the process in which the 
     1882 *     arm_start_application() is executed. There are no requirements on the 
     1883 *     value it is set to, except that it must be possible to pass it on other 
     1884 *     calls, such as arm_start_transaction(), without the application needing 
     1885 *     to do any error checking. Whether the data is meaningful, or partially 
     1886 *     meaningful, is at the discretion of the ARM implementation. 
     1887 * 
     1888 * @return The returned code is a status that may indicate whether an error 
     1889 *     was detected. If the return code is negative, an error occurred. If the 
     1890 *     return code is not negative, an error may or may not have occurred - the 
     1891 *     determination of what is an error and whether an error code is returned 
     1892 *     is at the discretion of the ARM implementation. The application can test 
     1893 *     the return code if it wants to provide its own error logging. See 
     1894 *     @ref ARMERROR for further information about error handling. 
     1895 * 
     1896 * @see arm_register_application(), arm_report_transaction(), 
     1897 *      arm_start_transaction(), arm_stop_application() 
     1898 * @ingroup ARM40Funcs 
     1899 */ 
    5061900ARM4_API_DYNAMIC(arm_error_t) 
    5071901arm_start_application( 
     
    5131907    arm_app_start_handle_t *app_handle); 
    5141908 
     1909/** 
     1910 * @brief stop application 
     1911 * 
     1912 * arm_stop_application() indicates that the application instance has finished 
     1913 * making ARM calls. It typically means that the instance is ending, such as 
     1914 * just prior to the process exiting or a thread that represents an application 
     1915 * instance terminating. 
     1916 * 
     1917 * For any transactions that are still in-process [arm_start_transaction() 
     1918 * executed without a matching arm_stop_transaction()], an implicit  
     1919 * arm_discard_transaction() is executed. 
     1920 * 
     1921 * If the arm_start_application() used the System Address sub-buffer to indicate 
     1922 * that the ARM calls would be about an application instance on a different 
     1923 * system, arm_stop_application() indicates that no more calls about that 
     1924 * application instance and its transactions will be made. 
     1925 * 
     1926 * After executing arm_stop_application(), no further calls should be made for 
     1927 * this application, including calls for transactions created by this 
     1928 * application, until a new instance "session" isstarted using 
     1929 * arm_start_application(). Data from any other calls that are made will be 
     1930 * ignored. This function is the equivalent of the ARM 2.0 function arm_end(). 
     1931 * 
     1932 * @param [in] app_handle     A handle returned in an out parameter from an 
     1933 *     arm_start_application() call in the same process. 
     1934 * @param [in] flags        Contains 32-bit flags. No values are currently 
     1935 *     defined. The field should be zero (@ref ARM_FLAG_NONE). 
     1936 * @param [in] buffer4      Pointer to the optional buffer, if any. If the 
     1937 *     pointer is null, there is no buffer. No sub-buffer types are currently 
     1938 *     valid with this function call, so the pointer should be null 
     1939 *     (@ref ARM_BUF4_NONE). 
     1940 * 
     1941 * @return The returned code is a status that may indicate whether an error 
     1942 *     was detected. If the return code is negative, an error occurred. If the 
     1943 *     return code is not negative, an error may or may not have occurred - the 
     1944 *     determination of what is an error and whether an error code is returned 
     1945 *     is at the discretion of the ARM implementation. The application can test 
     1946 *     the return code if it wants to provide its own error logging. See 
     1947 *     @ref ARMERROR for further information about error handling. 
     1948 * 
     1949 * @see arm_discard_transaction(), arm_start_application(), 
     1950 *      arm_start_transaction(), arm_stop_transaction() 
     1951 * @ingroup ARM40Funcs 
     1952 */ 
    5151953ARM4_API_DYNAMIC(arm_error_t) 
    5161954arm_stop_application( 
     
    5191957    const arm_buffer4_t *buffer4); 
    5201958 
    521 /* transaction instance API functions */ 
     1959/** 
     1960 * @brief start transaction 
     1961 * 
     1962 * arm_start_transaction() is used to indicate that a transaction is beginning 
     1963 * execution. 
     1964 * 
     1965 * Call arm_start_transaction() just prior to a transaction beginning 
     1966 * execution. arm_start_transaction() signals the ARM library to start timing 
     1967 * the transaction response time. There is one exception: when 
     1968 * arm_get_arrival_time() is used to get a start time before 
     1969 * arm_start_transaction() executes. See arm_get_arrival_time() to understand 
     1970 * this usage. 
     1971 * 
     1972 * arm_start_transaction() is also the means to pass to ARM the correlation 
     1973 * token (called a "correlator" in ARM) from a caller - the "parent" - and to 
     1974 * request a correlator that can be passed to transactions called by this 
     1975 * transaction. The correlation token may be used to establish a calling 
     1976 * hierarchy across processes and systems. A correlator contains a two-byte 
     1977 * length field, a one-byte format ID, a one-byte flag field, plus it may 
     1978 * contain other data that is used to uniquely identify an instance of a 
     1979 * transaction. Applications do not need to understand correlator internals. 
     1980 * The maximum length of a correlator is @ref ARM_CORR_MAX_LENGTH bytes. 
     1981 * (In ARM 2.0 it was 168 bytes.) 
     1982 * 
     1983 * @param [in] app_handle     A handle returned in an out parameter from an 
     1984 *     arm_start_application() call in the same process. 
     1985 * @param [in] tran_id        A transaction ID returned in an out parameter 
     1986 *      from an arm_register_transaction() call in the same process. 
     1987 * @param [in] parent_correlator  Pointer to the parent correlator, if any. 
     1988 *     The pointer may be null (@ref ARM_CORR_NONE). 
     1989 * @param [in] flags          Contains 32-bit flags. 
     1990 *     <ul> 
     1991 *     <li>@ref ARM_FLAG_TRACE_REQUEST</li> 
     1992 *     <li>@ref ARM_FLAG_BIND_THREAD</li> 
     1993 *     <li>@ref ARM_FLAG_CORR_IN_PROCESS</li> 
     1994 *     </ul> 
     1995 * @param [in] buffer4        Pointer to the optional buffer, if any. If the 
     1996 *     pointer is null (@ref ARM_BUF4_NONE), there is no buffer. The sub-buffers 
     1997 *     that may be used are: 
     1998 *     <ul> 
     1999 *     <li>arm_subbuffer_arrival_time_t</li> 
     2000 *     <li>arm_subbuffer_prep_stats_t</li> 
     2001 *     <li>arm_subbuffer_prep_time_t</li> 
     2002 *     <li>arm_subbuffer_formatted_arrival_time_msecJan1970_t</li> 
     2003 *     <li>arm_subbuffer_formatted_arrival_time_strings_t</li> 
     2004 *     <li>arm_subbuffer_message_rcvd_event_t</li> 
     2005 *     <li>arm_subbuffer_message_sent_event_t</li> 
     2006 *     <li>arm_subbuffer_metric_values_t</li> 
     2007 *     <li>arm_subbuffer_tran_context_t</li> 
     2008 *     <li>arm_subbuffer_user_t</li> 
     2009 *     </ul> 
     2010 * @param [out] tran_handle   Pointer to an arm_int64_t into which the ARM 
     2011 *     library will store the value of the handle that will represent the 
     2012 *     transaction instance in all calls, up to and including the 
     2013 *     arm_stop_transaction() that indicates that the instance has completed 
     2014 *     executing. The scope of the handle is the process in which the 
     2015 *     arm_start_transaction() is executed. 
     2016 *     @n 
     2017 *     There are no defined behaviors for the value returned - it is 
     2018 *     implementation-defined. Note that the returned value will always be a 
     2019 *     value that the application can use in future calls that take a handle 
     2020 *     [arm_bind_thread(), arm_block_transaction(), arm_stop_transaction(), 
     2021 *     arm_unbind_thread(), arm_unblock_transaction(), and 
     2022 *     arm_arm_update_transaction()]. 
     2023 * @param [out] current_correlator  Pointer to a buffer into which the ARM 
     2024 *     implementation will store a correlator for the transaction instance, 
     2025 *     if any. The length of the buffer should be (at least) 
     2026 *     @ref ARM_CORR_MAX_LENGTH) bytes. 
     2027 *     @n 
     2028 *     If the pointer is null (@ref ARM_CORR_NONE), the application is not 
     2029 *     requesting that a correlator be created. 
     2030 *     @n 
     2031 *     If the pointer is not null, the application is requesting that a 
     2032 *     correlator be created. In this case the ARM implementation may (but need 
     2033 *     not) create a correlator in the buffer. It may not create a correlator 
     2034 *     if it does not support the function or if it is configured to not create 
     2035 *     a correlator. 
     2036 *     @n 
     2037 *     After arm_start_transaction() completes, the application tests the length 
     2038 *     field using arm_get_correlator_length() to determine whether a correlator 
     2039 *     has been stored. If the length is still zero, no correlator has been  
     2040 *     stored. The ARM implementation must store zero in the length field if it 
     2041 *     does not generate a correlator. 
     2042 * 
     2043 * @return The returned code is a status that may indicate whether an error 
     2044 *     was detected. If the return code is negative, an error occurred. If the 
     2045 *     return code is not negative, an error may or may not have occurred - the 
     2046 *     determination of what is an error and whether an error code is returned 
     2047 *     is at the discretion of the ARM implementation. The application can test 
     2048 *     the return code if it wants to provide its own error logging. See 
     2049 *     @ref ARMERROR for further information about error handling. 
     2050 * 
     2051 * @see arm_bind_thread(), arm_block_transaction(), arm_get_arrival_time(), 
     2052 *      arm_get_correlator_length(), arm_register_transaction(), 
     2053 *      arm_start_application(), arm_stop_transaction(), arm_unbind_thread(), 
     2054 *      arm_unblock_transaction(), arm_update_transaction() 
     2055 * @ingroup ARM40Funcs 
     2056 */ 
    5222057ARM4_API_DYNAMIC(arm_error_t) 
    5232058arm_start_transaction( 
     
    5302065    arm_correlator_t *current_correlator); 
    5312066 
     2067/** 
     2068 * @brief stop transaction 
     2069 * 
     2070 * arm_stop_transaction() signals the end of a transaction. 
     2071 * 
     2072 * Call arm_stop_transaction() just after a transaction completes. 
     2073 * arm_start_transaction() signals the ARM library to start timing the  
     2074 * transaction response time. arm_stop_transaction() signals the ARM library 
     2075 * to stop timing the transaction response time. It can be called from any 
     2076 * thread in the process that executed the arm_start_transaction(). 
     2077 * 
     2078 * Implicit arm_unbind_thread() and arm_unblock_transaction() calls are made 
     2079 * for any pending arm_bind_thread() and arm_block_transaction() calls, 
     2080 * respectively, that have not been explicitly unbound or unblocked with 
     2081 * arm_unbind_thread() and arm_unblock_transaction(). 
     2082 * 
     2083 * @param [in] tran_handle    A handle returned in an out parameter from an  
     2084 *     arm_start_transaction() call in the same process. 
     2085 * @param [in] tran_status    Indicates the status of the transaction. The 
     2086 *     following values are allowed: 
     2087 *     <ul> 
     2088 *     <li>@ref ARM_STATUS_GOOD</li> 
     2089 *     <li>@ref ARM_STATUS_ABORTED</li> 
     2090 *     <li>@ref ARM_STATUS_FAILED</li> 
     2091 *     <li>@ref ARM_STATUS_UNKNOWN</li> 
     2092 *     </ul> 
     2093 * @param [in] flags          Contains 32-bit flags. No values are currently  
     2094 *     defined. The field should be zero (@ref ARM_FLAG_NONE). 
     2095 * @param [in] buffer4        Pointer to the optional buffer, if any. If the 
     2096 *     pointer is null (@ref ARM_BUF4_NONE), there is no buffer. The sub-buffers 
     2097 *     that may be used are: 
     2098 *     <ul> 
     2099 *     <li>arm_subbuffer_diag_detail_t</li> 
     2100 *     <li>arm_subbuffer_diag_properties_t</li> 
     2101 *     <li>arm_subbuffer_message_rcvd_event_t</li> 
     2102 *     <li>arm_subbuffer_message_sent_event_t</li> 
     2103 *     <li>arm_subbuffer_metric_values_t</li> 
     2104 *     </ul> 
     2105 * 
     2106 * @return The returned code is a status that may indicate whether an error 
     2107 *     was detected. If the return code is negative, an error occurred. If the 
     2108 *     return code is not negative, an error may or may not have occurred - the 
     2109 *     determination of what is an error and whether an error code is returned 
     2110 *     is at the discretion of the ARM implementation. The application can test 
     2111 *     the return code if it wants to provide its own error logging. See 
     2112 *     @ref ARMERROR for further information about error handling. 
     2113 * 
     2114 * @see arm_bind_thread(), arm_block_transaction(), arm_start_transaction(), 
     2115 *      arm_unbind_thread(), arm_unblock_transaction() 
     2116 * @ingroup ARM40Funcs 
     2117 */ 
    5322118ARM4_API_DYNAMIC(arm_error_t) 
    5332119arm_stop_transaction( 
     
    5372123    const arm_buffer4_t *buffer4); 
    5382124 
     2125/** 
     2126 * @brief update transaction status 
     2127 * 
     2128 * arm_update_transaction() signals that a transaction is still processing. 
     2129 * 
     2130 * arm_update_transaction() is useful as a heartbeat. It is also used to pass 
     2131 * additional data about a transaction. It can be called from any thread in 
     2132 * the process that executed the arm_start_transaction(). 
     2133 * 
     2134 * @param [in] tran_handle    A handle returned in an out parameter from an  
     2135 *     arm_start_transaction() call in the same process. 
     2136 * @param [in] flags          Contains 32-bit flags. No values are currently  
     2137 *     defined. The field should be zero (@ref ARM_FLAG_NONE). 
     2138 * @param [in] buffer4        Pointer to the optional buffer, if any. If the 
     2139 *     pointer is null, there is no buffer. The sub-buffers that may be used 
     2140 *     are: 
     2141 *     <ul> 
     2142 *     <li>arm_subbuffer_message_rcvd_event_t</li> 
     2143 *     <li>arm_subbuffer_message_sent_event_t</li> 
     2144 *     <li>arm_subbuffer_metric_values_t</li> 
     2145 *     </ul> 
     2146 * 
     2147 * @return The returned code is a status that may indicate whether an error 
     2148 *     was detected. If the return code is negative, an error occurred. If the 
     2149 *     return code is not negative, an error may or may not have occurred - the 
     2150 *     determination of what is an error and whether an error code is returned 
     2151 *     is at the discretion of the ARM implementation. The application can test 
     2152 *     the return code if it wants to provide its own error logging. See 
     2153 *     @ref ARMERROR for further information about error handling. 
     2154 * 
     2155 * @see arm_start_transaction(), arm_stop_transaction() 
     2156 * @ingroup ARM40Funcs 
     2157 */ 
    5392158ARM4_API_DYNAMIC(arm_error_t) 
    5402159arm_update_transaction( 
     
    5432162    const arm_buffer4_t *buffer4); 
    5442163 
     2164/** 
     2165 * @brief discard a started transaction. 
     2166 * 
     2167 * arm_discard_transaction() signals that the referenced  
     2168 * arm_start_transaction() should be ignored and treated as if it never 
     2169 * happened. Measurements associated with a transaction that is processing 
     2170 * should be discarded. Either arm_discard_transaction() or  
     2171 * arm_stop_transaction() is used - never both. 
     2172 * 
     2173 * An example of when a transaction would be discarded could happen is if proxy 
     2174 * instrumentation believes a transaction is starting, but then learns that it 
     2175 * did not. It can be called from any thread in the process that executed the 
     2176 * arm_start_transaction(). In general, the use of arm_discard_transaction() is 
     2177 * discouraged, but experience has shown a few use cases that require the 
     2178 * functionality. 
     2179 * 
     2180 * arm_discard_transaction() clears any thread bindings [arm_bind_thread()] and 
     2181 * blocking conditions [arm_block_transaction()]. 
     2182 * 
     2183 * @param [in] tran_handle    A handle returned in an out parameter from an  
     2184 *     arm_start_transaction() call in the same process. 
     2185 * @param [in] flags          Contains 32-bit flags. No values are currently  
     2186 *     defined. The field should be zero (@ref ARM_FLAG_NONE). 
     2187 * @param [in] buffer4      Pointer to the optional buffer, if any. If the 
     2188 *     pointer is null, there is no buffer. No sub-buffer types are currently 
     2189 *     valid with this function call, so the pointer should be null 
     2190 *     (@ref ARM_BUF4_NONE). 
     2191 * 
     2192 * @return The returned code is a status that may indicate whether an error 
     2193 *     was detected. If the return code is negative, an error occurred. If the 
     2194 *     return code is not negative, an error may or may not have occurred - the 
     2195 *     determination of what is an error and whether an error code is returned 
     2196 *     is at the discretion of the ARM implementation. The application can test 
     2197 *     the return code if it wants to provide its own error logging. See 
     2198 *     @ref ARMERROR for further information about error handling. 
     2199 * 
     2200 * @see arm_bind_thread(), arm_block_transaction(), arm_start_transaction(), 
     2201 *      arm_stop_transaction() 
     2202 * @ingroup ARM40Funcs 
     2203 */ 
    5452204ARM4_API_DYNAMIC(arm_error_t) 
    5462205arm_discard_transaction( 
     
    5492208    const arm_buffer4_t *buffer4); 
    5502209 
     2210/** 
     2211 * @brief indicates that a transaction is blocked. 
     2212 * 
     2213 * arm_block_transaction() is used to indicate that the transaction instance 
     2214 * is blocked waiting on an external transaction (which may or may not be 
     2215 * instrumented with ARM) or some other event to complete. It has been found 
     2216 * useful to separate out this "blocked" time from the elapsed time between 
     2217 * the arm_start_transaction() and arm_stop_transaction(). 
     2218 * 
     2219 * A transaction remains blocked until arm_unblock_transaction() is executed 
     2220 * passing the same tran_block_handle, or either an arm_discard_transaction() 
     2221 * or arm_stop_transaction() is executed passing the same tran_handle. 
     2222 *  
     2223 * The blocking conditions of most interest are those that could result in a 
     2224 * significant and/or variable length delay relative to the response time of 
     2225 * the transaction. For example, a remote procedure call would be a good 
     2226 * situation to indicate with arm_block_transaction() or 
     2227 * arm_unblock_transaction(), whereas a disk I/O would not. 
     2228 * 
     2229 * A transaction may be blocked by multiple conditions simultaneously. In many 
     2230 * application architectures arm_block_transaction() would be called just prior 
     2231 * to a thread suspending, because the thread is waiting to be signaled that an 
     2232 * event has occurred. In other application architectures there would not be a 
     2233 * tight relationship between the thread behavior and the blocking conditions. 
     2234 * arm_bind_thread() and arm_block_transaction() are used independently of each 
     2235 * other. 
     2236 * 
     2237 * A description of the blocking cause can be provided in the optional Block  
     2238 * Cause sub-buffer. 
     2239 * 
     2240 * @param [in] tran_handle    A handle returned in an out parameter from an  
     2241 *     arm_start_transaction() call in the same process. 
     2242 * @param [in] flags          Contains 32-bit flags. No values are currently  
     2243 *     defined. The field should be zero (@ref ARM_FLAG_NONE). 
     2244 * @param [in] buffer4        Pointer to the optional buffer, if any. If the 
     2245 *     pointer is null, there is no buffer. The sub-buffers that may be used 
     2246 *     are: 
     2247 *     <ul> 
     2248 *     <li>arm_subbuffer_block_cause_t</li> 
     2249 *     <li>arm_subbuffer_message_rcvd_event_t</li> 
     2250 *     <li>arm_subbuffer_message_sent_event_t</li> 
     2251 *     </ul> 
     2252 * @param [out] block_handle  Pointer to a handle that is passed on 
     2253 *     arm_unblock_transaction() calls in the same process. There are no 
     2254 *     requirements on what value it is set to, except that it must be 
     2255 *     possible to pass it on arm_unblock_transaction() without the application 
     2256 *     needing to do any error checking. 
     2257 * 
     2258 * @return The returned code is a status that may indicate whether an error 
     2259 *     was detected. If the return code is negative, an error occurred. If the 
     2260 *     return code is not negative, an error may or may not have occurred - the 
     2261 *     determination of what is an error and whether an error code is returned 
     2262 *     is at the discretion of the ARM implementation. The application can test 
     2263 *     the return code if it wants to provide its own error logging. See 
     2264 *     @ref ARMERROR for further information about error handling. 
     2265 * 
     2266 * @see arm_bind_thread(), arm_discard_transaction(), arm_start_transaction(), 
     2267 *      arm_stop_transaction(), arm_unblock_transaction() 
     2268 * @ingroup ARM40Funcs 
     2269 */ 
    5512270ARM4_API_DYNAMIC(arm_error_t) 
    5522271arm_block_transaction( 
     
    5562275    arm_tran_block_handle_t *block_handle); 
    5572276 
     2277/** 
     2278 * @brief unblock transaction 
     2279 * 
     2280 * arm_unblock_transaction() indicates that the suspension indicated by the 
     2281 * @a block_handle for the transaction identified by the start handle is no 
     2282 * longer waiting for a downstream transaction to complete. 
     2283 * 
     2284 * Call arm_unblock_transaction() when a transaction is no longer blocked on 
     2285 * an external event. It should be called when arm_block_transaction() was 
     2286 * previously called and the blocking condition no longer exists. Knowledge 
     2287 * of when a transaction is blocked can be useful for better understanding 
     2288 * response times. It is useful to separate out this "blocked" time from the 
     2289 * elapsed start-to-stop time. The unblocked call is paired with a block call 
     2290 * for finer grained analysis. 
     2291 * 
     2292 * arm_stop_transaction() is an implicit arm_unblock_transaction() for any 
     2293 * blocking condition for the transaction instance that has not been cleared 
     2294 * yet [arm_block_transaction() issued without a matching  
     2295 * arm_unblock_transaction()]. It should only be called without calling 
     2296 * arm_unblock_transaction() first when the blocking condition ends immediately 
     2297 * prior to the transaction ending. 
     2298 * 
     2299 * @param [in] tran_handle    A handle returned in an out parameter from an  
     2300 *     arm_start_transaction() call in the same process. 
     2301 * @param [in] block_handle   A handle returned in an out parameter from an 
     2302 *     arm_block_transaction() call in the same process. 
     2303 * @param [in] flags          Contains 32-bit flags. No values are currently 
     2304 *     defined. The field should be zero (@ref ARM_FLAG_NONE). 
     2305 * @param [in] buffer4        Pointer to the optional buffer, if any. If the 
     2306 *     pointer is null, there is no buffer. The sub-buffers that may be used 
     2307 *     are: 
     2308 *     <ul> 
     2309 *     <li>arm_subbuffer_message_rcvd_event_t</li> 
     2310 *     <li>arm_subbuffer_message_sent_event_t</li> 
     2311 *     </ul> 
     2312 * 
     2313 * @return The returned code is a status that may indicate whether an error 
     2314 *     was detected. If the return code is negative, an error occurred. If the 
     2315 *     return code is not negative, an error may or may not have occurred - the 
     2316 *     determination of what is an error and whether an error code is returned 
     2317 *     is at the discretion of the ARM implementation. The application can test 
     2318 *     the return code if it wants to provide its own error logging. See 
     2319 *     @ref ARMERROR for further information about error handling. 
     2320 * 
     2321 * @see arm_block_transaction(), arm_start_transaction(), arm_stop_transaction() 
     2322 * @ingroup ARM40Funcs 
     2323 */ 
    5582324ARM4_API_DYNAMIC(arm_error_t) 
    5592325arm_unblock_transaction( 
     
    5642330 
    5652331/* thread support API functions */ 
     2332/** 
     2333 * @brief bind a transaction to the excuting thread 
     2334 * 
     2335 * arm_bind_thread() indicates that the thread from which it is called is 
     2336 * performing on behalf of the transaction identified by the start handle. 
     2337 * 
     2338 * The thread binding could be useful for managing computing resources at 
     2339 * a finer level of granularity than a process. There can be any number 
     2340 * of threads simultaneously bound to the same transaction. 
     2341 * 
     2342 * A transaction remains bound to a thread until either an  
     2343 * arm_discard_transaction(), arm_stop_transaction(), or arm_unbind_thread() 
     2344 * is executed passing the same start handle. 
     2345 * 
     2346 * arm_bind_thread() and arm_block_transaction() are used independently  
     2347 * of each other. 
     2348 * 
     2349 * @param [in] tran_handle  A handle returned in an out parameter from an  
     2350 *     arm_start_transaction() call in the same process. 
     2351 * @param [in] flags        Contains 32-bit flags. No values are currently 
     2352 *     defined. The field should be zero (@ref ARM_FLAG_NONE). 
     2353 * @param [in] buffer4      Pointer to the optional buffer, if any. If the 
     2354 *     pointer is null, there is no buffer. No sub-buffer types are currently 
     2355 *     valid with this function call, so the pointer should be null 
     2356 *     (@ref ARM_BUF4_NONE). 
     2357 * 
     2358 * @return The returned code is a status that may indicate whether an error 
     2359 *     was detected. If the return code is negative, an error occurred. If the 
     2360 *     return code is not negative, an error may or may not have occurred - the 
     2361 *     determination of what is an error and whether an error code is returned 
     2362 *     is at the discretion of the ARM implementation. The application can test 
     2363 *     the return code if it wants to provide its own error logging. See 
     2364 *     @ref ARMERROR for further information about error handling. 
     2365 * 
     2366 * @see arm_block_transaction(), arm_discard_transaction(),  
     2367 *     arm_start_transaction(), arm_stop_transaction(), arm_unbind_thread() 
     2368 * @ingroup ARM40Funcs 
     2369 */ 
    5662370ARM4_API_DYNAMIC(arm_error_t) 
    5672371arm_bind_thread( 
     
    5702374    const arm_buffer4_t *buffer4); 
    5712375 
     2376/** 
     2377 * @brief unbind a transaction from the excuting thread 
     2378 * 
     2379 * arm_unbind_thread() indicates that the thread from which it is called is no 
     2380 * longer performing on behalf of the transaction identified by the start  
     2381 * handle. 
     2382 * 
     2383 * Call arm_unbind_thread() when a thread is no longer executing a transaction. 
     2384 * The thread binding is useful for managing computing resources at a finer 
     2385 * level of granularity than the process. It should be called when, for this 
     2386 * transaction and this thread, either: 
     2387 * <ul> 
     2388 * <li>arm_bind_thread() was previously called.</li> 
     2389 * <li>The @ref ARM_FLAG_BIND_THREAD flag was on in the arm_start_transaction() 
     2390 * call.</li> 
     2391 * </ul> 
     2392 * 
     2393 * arm_stop_transaction() is an implicit arm_unbind_thread() for any threads 
     2394 * still bound to the transaction instance [arm_bind_thread() issued without 
     2395 * a matching arm_unbind_thread()]. As long as the transaction is bound to the 
     2396 * thread when the arm_stop_transaction() executes, there is no need nor any 
     2397 * value in calling arm_unbind_thread() before calling arm_stop_transaction(). 
     2398 * 
     2399 * @param [in] tran_handle  A handle returned in an out parameter from an  
     2400 *     arm_start_transaction() call in the same process. 
     2401 * @param [in] flags        Contains 32-bit flags. No values are currently defined. 
     2402 *     The field should be zero (@ref ARM_FLAG_NONE). 
     2403 * @param [in] buffer4      Pointer to the optional buffer, if any. If the pointer 
     2404 *     is null, there is no buffer. No sub-buffer types are currently valid 
     2405 *     with this function call, so the pointer should be null (@ref ARM_BUF4_NONE). 
     2406 * 
     2407 * @return The returned code is a status that may indicate whether an error 
     2408 *     was detected. If the return code is negative, an error occurred. If the 
     2409 *     return code is not negative, an error may or may not have occurred - the 
     2410 *     determination of what is an error and whether an error code is returned 
     2411 *     is at the discretion of the ARM implementation. The application can test 
     2412 *     the return code if it wants to provide its own error logging. See 
     2413 *     @ref ARMERROR for further information about error handling. 
     2414 * 
     2415 * @see arm_bind_thread(), arm_start_transaction(), arm_stop_transaction() 
     2416 * @ingroup ARM40Funcs 
     2417 */ 
    5722418ARM4_API_DYNAMIC(arm_error_t) 
    5732419arm_unbind_thread( 
     
    5762422    const arm_buffer4_t *buffer4); 
    5772423 
    578 /* report transaction data API function */ 
     2424/** 
     2425 * @brief report transaction statistics 
     2426 * 
     2427 * arm_report_transaction() is used to report statistics about a transaction 
     2428 * that has already completed. 
     2429 * 
     2430 * arm_report_transaction() may be used instead of a paired 
     2431 * arm_start_transaction() and arm_stop_transaction() call. The application 
     2432 * would have measured the response time. The transaction could have executed 
     2433 * on the local system or on a remote system. If it executes on a remote system, 
     2434 * the System Address sub-buffer passed on the arm_start_application() provides 
     2435 * the addressing information for the remote system. 
     2436 * 
     2437 * If the transaction represented by the arm_report_transaction() call is the 
     2438 * correlation parent of another transaction, arm_generate_correlator() must be 
     2439 * used to get a parent correlator, prior to invoking the child transaction 
     2440 * (because it must be passed to the child). In this case, the sequence is the 
     2441 * following: 
     2442 * 
     2443 * <ol> 
     2444 * <li>arm_generate_correlator() to get a correlator for this transaction.</li> 
     2445 * <li>Invoke the child transaction, passing the correlator returned in step (1) 
     2446 *     to the child.</li> 
     2447 * <li>When this transaction is complete, invoke arm_report_transaction() to 
     2448 *     report the statistics about the transaction.</li> 
     2449 * </ol> 
     2450 * 
     2451 * When used, it prevents certain types of proactive management - such as  
     2452 * monitoring for hung transactions or adjusting priorities - because the ARM 
     2453 * implementation is not invoked when the transaction is started. Because of 
     2454 * this, the use of arm_start_transction() and arm_stop_transaction() is 
     2455 * preferred over arm_report_transaction(). 
     2456 * 
     2457 * The intended use is to report status and response time about transactions 
     2458 * that recently completed (typically several seconds ago) in the absence of an 
     2459 * ARM-enabled application and/or ARM implementation on the system on which the 
     2460 * transaction executed. 
     2461 * 
     2462 * @param [in] app_handle     A handle returned in an out parameter from an 
     2463 *     arm_start_application() call in the same process. 
     2464 * @param [in] tran_id        A transaction ID returned in an out parameter 
     2465 *     from an arm_register_transaction() call in the same process. 
     2466 * @param [in] tran_status    Indicates the status of the transaction. The 
     2467 *     following values are allowed: 
     2468 *     <ul> 
     2469 *     <li>@ref ARM_STATUS_GOOD</li> 
     2470 *     <li>@ref ARM_STATUS_ABORTED</li> 
     2471 *     <li>@ref ARM_STATUS_FAILED</li> 
     2472 *     <li>@ref ARM_STATUS_UNKNOWN</li> 
     2473 *     </ul> 
     2474 * @param [in] response_time  Response time in nanoseconds. 
     2475 * @param [in] stop_time      An arm_int64_t that contains the number of 
     2476 *     milliseconds since Jan 1, 1970 using stop_time the Gregorian calendar. 
     2477 *     The time base is GMT (Greenwich Mean Time). There is one special value, 
     2478 *     @ref ARM_USE_CURRENT_TIME, which means use the current time. 
     2479 * @param [in] parent_correlator  Pointer to a parent correlator, if any. If 
     2480 *     the pointer is null (@ref ARM_CORR_NONE), there is no parent correlator. 
     2481 * @param [out] current_correlator  Pointer to the correlator for the  
     2482 *     transaction that has completed, if any. If the pointer is null 
     2483 *     (@ref ARM_CORR_NONE), there is no current correlator. 
     2484 * @param [in] flags          Contains 32-bit flags. 
     2485 *     <ul> 
     2486 *     <li>@ref ARM_FLAG_TRACE_REQUEST</li> 
     2487 *     </ul> 
     2488 * @param [in] buffer4        Pointer to the optional buffer, if any. If the 
     2489 *     pointer is null (@ref ARM_BUF4_NONE), there is no buffer. The sub-buffers 
     2490 *     that may be used are: 
     2491 *     <ul> 
     2492 *     <li>arm_subbuffer_diag_detail_t</li> 
     2493 *     <li>arm_subbuffer_diag_properties_t</li> 
     2494 *     <li>arm_subbuffer_metric_values_t</li> 
     2495 *     <li>arm_subbuffer_tran_context_t</li> 
     2496 *     <li>arm_subbuffer_user_t</li> 
     2497 *     </ul> 
     2498 * 
     2499 * @return The returned code is a status that may indicate whether an error 
     2500 *     was detected. If the return code is negative, an error occurred. If the 
     2501 *     return code is not negative, an error may or may not have occurred - the 
     2502 *     determination of what is an error and whether an error code is returned 
     2503 *     is at the discretion of the ARM implementation. The application can test 
     2504 *     the return code if it wants to provide its own error logging. See 
     2505 *     @ref ARMERROR for further information about error handling. 
     2506 * 
     2507 * @see arm_generate_correlator(), arm_register_transaction(),  
     2508 *      arm_start_application(), arm_start_transaction(), arm_stop_transaction() 
     2509 * @ingroup ARM40Funcs 
     2510 */ 
    5792511ARM4_API_DYNAMIC(arm_error_t) 
    5802512arm_report_transaction( 
     
    5902522 
    5912523/* correlator API functions */ 
     2524/** 
     2525 * @brief generate a correlator or pass instrumentation control information. 
     2526 * 
     2527 * arm_generate_correlator() is used for two very different purposes: 
     2528 * <ol> 
     2529 * <li> 
     2530 * It is used to generate a correlator for use with arm_report_transaction(). 
     2531 * </li> 
     2532 * <li> 
     2533 * It is used (beginning with ARM 4.1) to exchange control information that 
     2534 * indicates the level of instrumentation for this transaction that is desired 
     2535 * by the ARM implementation. 
     2536 * </li> 
     2537 * </ol> 
     2538 * 
     2539 * <h2>Generating a Correlator</h2> 
     2540 * 
     2541 * A correlator is a correlation token passed from a calling transaction to a 
     2542 * called transaction. The correlation token may be used to establish a calling 
     2543 * hierarchy across processes and systems. A correlator contains a two-byte 
     2544 * length field, a one-byte format ID, a one-byte flag field, plus it may  
     2545 * contain other data that is used to uniquely identify an instance of a 
     2546 * transaction. Applications do not need to understand correlator internals. 
     2547 * The maximum length is 512 (@ref ARM_CORR_MAX_LENGTH) bytes. 
     2548 * 
     2549 * It is useful to think about its use in the context of what 
     2550 * arm_start_transaction() and arm_stop_transaction() do: 
     2551 * 
     2552 * <ul> 
     2553 * <li> 
     2554 * arm_start_transaction() performs two functions. It establishes the identity 
     2555 * of a transaction instance (encapsulated in the current correlator) and 
     2556 * begins the measurements of the instance. arm_stop_transaction() causes the 
     2557 * measurements to be captured. The start handle links an  
     2558 * arm_start_transaction() and an arm_stop_transaction(). 
     2559 * </li> 
     2560 * <li> 
     2561 * arm_generate_correlator() establishes the identity of a transaction 
     2562 * instance - like arm_start_transaction() - also encapsulating it in a 
     2563 * correlator. It has no relationship to measurements about the transaction 
     2564 * instance. arm_report_transaction() combines the measurement function of both 
     2565 * arm_start_transaction() and arm_stop_transaction(). 
     2566 * </li> 
     2567 * </ul> 
     2568 * 
     2569 * Based on this positioning, it should be clear that arm_generate_correlator() 
     2570 * can be used whenever an arm_start_transaction() can be used. More 
     2571 * specifically, the following calls must have been executed first: 
     2572 * arm_register_application(), arm_register_transaction(), and 
     2573 * arm_start_application(). The same parameters are also used, except there is 
     2574 * no need for a start handle, and there is no need for the Arrival Time or 
     2575 * Metric Values sub-buffers. The other sub-buffers may be used. The correlator 
     2576 * that is output can be used in the same way that a correlator output from 
     2577 * arm_start_transaction() is used. 
     2578 * 
     2579 * <h2>Controlling the Level of Instrumentation for a Transaction</h2> 
     2580 * 
     2581 * There is a special use of arm_generate_correlator() that is not intuitive 
     2582 * because it is unrelated to generating a correlator. It is used because this 
     2583 * allowed a new capability to be added without adding any new function calls, 
     2584 * which would have impacted backwards-compatibility with ARM libraries that 
     2585 * support ARM 4.0 but not ARM 4.1 or later ARM 4.x versions. Further details  
     2586 * are available in the descriptions of the Application Control sub-buffer 
     2587 * (see arm_subbuffer_app_control_t) and Transaction Instance Control 
     2588 * sub-buffer (see arm_subbuffer_tran_instance_control_t). 
     2589 * 
     2590 * When used for this special purpose, the meaningful parameters are: 
     2591 * <ul> 
     2592 * <li>app_handle</li> 
     2593 * <li>buffer4 
     2594 *   <ul> 
     2595 *   <li>arm_subbuffer_app_control_t</li> 
     2596 *   <li>arm_subbuffer_tran_id_control_t</li> 
     2597 *   <li>arm_subbuffer_tran_instance_control_t</li> 
     2598 *   </ul> 
     2599 * <li>current_correlator = NULL</li> 
     2600 * </ul> 
     2601 * 
     2602 * This special form is recognized by setting the current_correlator pointer to 
     2603 * null, which renders the call meaningless for the purpose of generating a 
     2604 * correlator. 
     2605 * 
     2606 * @param [in] app_handle     Value returned from an arm_start_application() 
     2607 *     call in the same process. The ARM implementation may use this handle to 
     2608 *     access application instance data that may become part of the correlator; 
     2609 *     e.g., the arm_subbuffer_system_address_t. 
     2610 * @param [in] tran_id        A transaction ID returned in an out parameter 
     2611 *     from an arm_register_transaction() call in the same process. If 
     2612 *     arm_generate_correlator() is being used for purposes of instrumentation 
     2613 *     control, tran_id is ignored. 
     2614 * @param [in] parent_correlator   A pointer to the parent correlator, if any. 
     2615 *     The pointer may be null (@ref ARM_CORR_NONE). If arm_generate_correlator() 
     2616 *     is being used for purposes of instrumentation control, parent_correlator 
     2617 *     is ignored. 
     2618 * @param [in] flags          Contains 32-bit flags. 
     2619 *     <ul> 
     2620 *     <li>@ref ARM_FLAG_TRACE_REQUEST</li> 
     2621 *     <li>@ref ARM_FLAG_CORR_IN_PROCESS</li> 
     2622 *     </ul> 
     2623 * @param [in] buffer4        Pointer to the optional buffer, if any. If the 
     2624 *     pointer is null (@ref ARM_BUF4_NONE), buffer4 there is no buffer. The 
     2625 *     sub-buffers that may be used are: 
     2626 *     <ul> 
     2627 *     <li>arm_subbuffer_app_control_t</li> 
     2628 *     <li>arm_subbuffer_tran_context_t</li> 
     2629 *     <li>arm_subbuffer_tran_id_control_t</li> 
     2630 *     <li>arm_subbuffer_tran_instance_control_t</li> 
     2631 *     <li>arm_subbuffer_user_t</li> 
     2632 *     </ul> 
     2633 * @param [out] current_correlator  A pointer to a buffer into which the ARM 
     2634 *     implementation will store a correlator for the transaction instance, if 
     2635 *     any. The length of the buffer should be (at least) @ref ARM_CORR_MAX_LENGTH. 
     2636 *     The value must be non-null if arm_generate_correlator() is being used to 
     2637 *     generate a correlator. If arm_generate_correlator() is being used to pass 
     2638 *     the Application Control, Transaction ID Control, or Transaction Instance 
     2639 *     Control sub-buffer, then current_correlator must be set to null. 
     2640 * 
     2641 * @return The returned code is a status that may indicate whether an error 
     2642 *     was detected. If the return code is negative, an error occurred. If the 
     2643 *     return code is not negative, an error may or may not have occurred - the 
     2644 *     determination of what is an error and whether an error code is returned 
     2645 *     is at the discretion of the ARM implementation. The application can test 
     2646 *     the return code if it wants to provide its own error logging. See 
     2647 *     @ref ARMERROR for further information about error handling. 
     2648 * 
     2649 * @see arm_register_application(), arm_register_transaction(), 
     2650 *      arm_report_transaction(), arm_start_application(),  
     2651 *      arm_start_transaction(), arm_stop_transaction() 
     2652 * @ingroup ARM40Funcs 
     2653 */ 
    5922654ARM4_API_DYNAMIC(arm_error_t) 
    5932655arm_generate_correlator( 
     
    5992661    arm_correlator_t *current_correlator); 
    6002662 
     2663/** 
     2664 * @brief get length of correlator 
     2665 * 
     2666 * arm_get_correlator_length() returns the length of a correlator, based on the 
     2667 * length field within the correlator header. Note that this length is not 
     2668 * necessarily the length of the buffer containing the correlator. 
     2669 * 
     2670 * A correlator header contains a length field. arm_get_correlator_length() is 
     2671 * used to return the length. The function handles any required conversion from 
     2672 * the network byte order used in the header and the endian (big versus little) 
     2673 * of the platform. See arm_generate_correlator() for a description of a 
     2674 * correlator. 
     2675 * 
     2676 * @param [in] correlator     Pointer to a buffer containing a correlator. It 
     2677 *     serves no purpose to make the call if the pointer is null. 
     2678 * @param [out] length        Pointer to an arm_correlator_length_t (a 16-bit 
     2679 *     integer) into which the ARM implementation will store the length. It 
     2680 *     serves no purpose to make the call if the pointer is null. If the 
     2681 *     pointer is not null, some value will be stored. The stored value will be 
     2682 *     the actual value if the value is apparently correct; otherwise, it will 
     2683 *     be zero. Examples of when zero would be stored are when the input 
     2684 *     correlator pointer is null or the length field is invalid, such as being 
     2685 *     greater than @ref ARM_CORR_MAX_LENGTH bytes. 
     2686 * 
     2687 * @return The returned code is a status that may indicate whether an error 
     2688 *     was detected. If the return code is negative, an error occurred. If the 
     2689 *     return code is not negative, an error may or may not have occurred - the 
     2690 *     determination of what is an error and whether an error code is returned 
     2691 *     is at the discretion of the ARM implementation. The application can test 
     2692 *     the return code if it wants to provide its own error logging. See 
     2693 *     @ref ARMERROR for further information about error handling. 
     2694 * 
     2695 * @see arm_generate_correlator(), arm_start_transaction() 
     2696 * @ingroup ARM40Funcs 
     2697 */ 
    6012698ARM4_API_DYNAMIC(arm_error_t) 
    6022699arm_get_correlator_length( 
     
    6042701    arm_correlator_length_t *length); 
    6052702 
     2703/** 
     2704 * @brief get value of correlator flag 
     2705 * 
     2706 * arm_get_correlator_flags() returns the value of a specified flag in the 
     2707 * correlator header. 
     2708 * 
     2709 * A correlator header contains bit flags. arm_get_correlator_flags() is used 
     2710 * to test the value of those flags. See arm_generate_correlator() for a 
     2711 * description of a correlator. 
     2712 * 
     2713 * @param [in] correlator     Pointer to a buffer containing a correlator. It 
     2714 *     serves no purpose to make the call if the pointer is null. 
     2715 * @param [in] corr_flag_num  An enumerated value that indicates which flag's 
     2716 *     value is requested. The enumerated values are: 
     2717 *     <ul> 
     2718 *     <li>@ref ARM_CORR_FLAGNUM_APP_TRACE -- Application trace flag</li> 
     2719 *     <li>@ref ARM_CORR_FLAGNUM_AGENT_TRACE -- Agent trace flag</li> 
     2720 *     <li>@ref ARM_CORR_FLAGNUM_ASYNCH -- mark asynchronous control flow</li> 
     2721 *     <li>@ref ARM_CORR_FLAGNUM_INDEPENDENT -- mark child transaction as 
     2722 *         independent</li> 
     2723 *     </ul> 
     2724 * @param [out] flag          Pointer to a boolean that is output indicating 
     2725 *     whether the flag is set. 
     2726 * 
     2727 * @return The returned code is a status that may indicate whether an error 
     2728 *     was detected. If the return code is negative, an error occurred. If the 
     2729 *     return code is not negative, an error may or may not have occurred - the 
     2730 *     determination of what is an error and whether an error code is returned 
     2731 *     is at the discretion of the ARM implementation. The application can test 
     2732 *     the return code if it wants to provide its own error logging. See 
     2733 *     @ref ARMERROR for further information about error handling. 
     2734 * 
     2735 * @see arm_generate_correlator(), arm_start_transaction() 
     2736 * @ingroup ARM40Funcs 
     2737 */ 
    6062738ARM4_API_DYNAMIC(arm_error_t) 
    6072739arm_get_correlator_flags( 
     
    6102742    arm_boolean_t *flag); 
    6112743 
    612 /* miscellaneous API functions */ 
     2744/* ---------------------- miscellaneous API functions ---------------------- */ 
     2745 
     2746/** 
     2747 * @brief gets current time in opaque format. 
     2748 * 
     2749 * arm_get_arrival_time() stores a 64-bit integer representing the current time. 
     2750 * 
     2751 * There are situations in which there is a significant delay between the time 
     2752 * when processing of a transaction begins and when all the context property 
     2753 * values that are needed before arm_start_transaction() can be executed are 
     2754 * known. In order to get a more accurate response time, arm_get_arrival_time() 
     2755 * can be used to capture an implementation-defined representation of the 
     2756 * current time. This integer value is later stored in the Arrival Time 
     2757 * sub-buffer (arm_subbuffer_arrival_time_t) when arm_start_transaction() 
     2758 * executes. The ARM library will use the "arrival time" as the start time 
     2759 * rather than the moment when the arm_start_transaction() executes. 
     2760 * 
     2761 * @param [out] opaque_time   Pointer to an arm_int64_t that will contain the 
     2762 *     arrival time value. Note that the value is implementation-defined so the 
     2763 *     application should not make any conclusions based on its contents. 
     2764 * 
     2765 * @return The returned code is a status that may indicate whether an error 
     2766 *     was detected. If the return code is negative, an error occurred. If the 
     2767 *     return code is not negative, an error may or may not have occurred - the 
     2768 *     determination of what is an error and whether an error code is returned 
     2769 *     is at the discretion of the ARM implementation. The application can test 
     2770 *     the return code if it wants to provide its own error logging. See 
     2771 *     @ref ARMERROR for further information about error handling. 
     2772 * 
     2773 * @see arm_start_transaction() 
     2774 * @ingroup ARM40Funcs 
     2775 */ 
    6132776ARM4_API_DYNAMIC(arm_error_t) 
    6142777arm_get_arrival_time( 
    6152778    arm_arrival_time_t *opaque_time); 
    6162779 
     2780/** 
     2781 * @brief get an error message 
     2782 * 
     2783 * arm_get_error_message() stores a string containing an error message for the 
     2784 * specified error code. 
     2785 * 
     2786 * ARM implementations return values that are specific to the implementation.  
     2787 * The only enforced convention is that a return code of zero indicates that no 
     2788 * errors are reported (though an error could have occurred), and a negative 
     2789 * return code indicates that some error occurred. Some implementations may 
     2790 * report an error at times when another implementation would not. 
     2791 * 
     2792 * To help an application developer or administrator understand what a negative 
     2793 * error code means, arm_get_error_message() can be used to store a string 
     2794 * containing an error message for the specified error code. The ARM library is 
     2795 * not obliged to return a message, even if it returned a non-zero return code. 
     2796 * 
     2797 * @param [in] charset        An IANA (Internet Assigned Numbers Authority -  
     2798 *      see http://www.iana.org) MIBenum charset value  
     2799 *      [see arm_is_charset_supported()]. If a non-null message is returned,  
     2800 *      it will be in this encoding. It is strongly recommended that no value 
     2801 *      be used for charset that has not been tested for support by the library 
     2802 *      using arm_is_charset_supported(). 
     2803 * @param [in] code           An error code returned as arm_error_t from an 
     2804 *      API call. 
     2805 * @param [out] msg           Pointer to a buffer that can contains 256 
     2806 *      characters (including the termination character) into which the 
     2807 *      null-terminated error message will be copied. The message will be in 
     2808 *      the encoding specified by the charset parameter. If the implementation 
     2809 *      cannot honor the request, the implementation must store at least the 
     2810 *      null termination character (i.e., which it would do if it does not 
     2811 *      return a message or does not recognize the error code or cannot return 
     2812 *      the message in the application's encoding). The function is ignored if 
     2813 *      the pointer is null and an error status may be returned. 
     2814 * 
     2815 * @return The returned code is a status that may indicate whether an error 
     2816 *     was detected. If the return code is negative, an error occurred. If the 
     2817 *     return code is not negative, an error may or may not have occurred - the 
     2818 *     determination of what is an error and whether an error code is returned 
     2819 *     is at the discretion of the ARM implementation. The application can test 
     2820 *     the return code if it wants to provide its own error logging. See 
     2821 *     @ref ARMERROR for further information about error handling. 
     2822 * 
     2823 * @see arm_is_charset_supported() 
     2824 * @ingroup ARM40Funcs 
     2825 */ 
    6172826ARM4_API_DYNAMIC(arm_error_t) 
    6182827arm_get_error_message( 
     
    6212830    arm_message_buffer_t msg); 
    6222831 
     2832/** 
     2833 * @brief check supported character encoding 
     2834 * 
     2835 * arm_is_charset_supported() indicates whether an ARM library supports a 
     2836 * specified character encoding. 
     2837 * 
     2838 * The default encoding for all strings provided by the application on all 
     2839 * operating systems is UTF-8. An application may specify an alternate encoding 
     2840 * when executing arm_register_application(), and then use it for all strings it 
     2841 * provides on all calls including but should never do so without first issuing 
     2842 * arm_register_application(), arm_is_charset_supported() to test whether the 
     2843 * value is supported. 
     2844 * 
     2845 * An ARM library on the operating systems listed in the following table must 
     2846 * support the specified encodings. Applications are encouraged to use one of 
     2847 * these encodings to ensure that any ARM implementation will support the 
     2848 * application's ARM instrumentation. Another alternative is to use one of these 
     2849 * encodings along with a preferred encoding. If the ARM library supports the 
     2850 * preferred encoding, it is used; otherwise, one of the mandatory encodings is 
     2851 * used. 
     2852 * 
     2853 * <table> 
     2854 * <tr><th>IANA MIBenum</th><th>Character Set Common Name</th> 
     2855 *     <th>UNIX \& Linux</th><th>Microsoft Windows</th> 
     2856 *     <th>IBM I5/OS</th><th>IBM zOS</th></tr> 
     2857 * <tr><td>@ref ARM_CHARSET_ASCII</td>  <td>ASCII-7 (US-ASCII)</td> 
     2858 *     <td>Yes</td><td>Yes</td><td>Yes</td><td>Yes</td></tr> 
     2859 * <tr><td>@ref ARM_CHARSET_UTF8</td>   <td>UTF-8 (UCS-2 characters only)</td> 
     2860 *     <td>Yes</td><td>Yes</td><td>Yes</td><td>Yes</td></tr> 
     2861 * <tr><td>@ref ARM_CHARSET_UTF16LE</td><td>UTF-16 Little Endian (UCS-2 characters only)</td> 
     2862 *     <td>&nbsp;</td><td>Yes</td><td>&nbsp;</td><td>&nbsp;</td></tr> 
     2863 * <tr><td>@ref ARM_CHARSET_IBM037</td> <td>IBM037</td> 
     2864 *      <td>&nbsp;</td><td>&nbsp;</td><td>Yes</td><td>&nbsp;</td></tr> 
     2865 * <tr><td>@ref ARM_CHARSET_IBM1047</td><td>IBM1047</td> 
     2866 *      <td>&nbsp;</td><td>&nbsp;</td><td>&nbsp;</td><td>Yes</td></tr> 
     2867 * </table> 
     2868 
     2869 * @param [in] charset        An IANA (Internet Assigned Numbers Authority - 
     2870 *     see www.iana.org) MIBenum charset value. Support for some values is 
     2871 *     mandatory by any ARM implementation on a specified platform, as shown 
     2872 *     in the table. 
     2873 * @param [out] supported     Pointer to a boolean value that is set to @ref ARM_TRUE 
     2874 *     or @ref ARM_FALSE to indicate whether charset is a supported encoding. 
     2875 * 
     2876 * @return The returned code is a status that may indicate whether an error 
     2877 *     was detected. If the return code is negative, an error occurred. If the 
     2878 *     return code is not negative, an error may or may not have occurred - the 
     2879 *     determination of what is an error and whether an error code is returned 
     2880 *     is at the discretion of the ARM implementation. The application can test 
     2881 *     the return code if it wants to provide its own error logging. See 
     2882 *     @ref ARMERROR for further information about error handling. 
     2883 * 
     2884 * @see arm_get_error_message(), arm_register_application() 
     2885 * @ingroup ARM40Funcs 
     2886 */ 
    6232887ARM4_API_DYNAMIC(arm_error_t) 
    6242888arm_is_charset_supported( 
  • arm4sdk/trunk/c/include/arm4agent.h

    r14 r15  
    1 /* Copyright (c) 2004 The Open Group                                         */ 
     1/* ------------------------------------------------------------------------- */ 
     2/*                                                                           */ 
     3/* Copyright (c) 2004-2007 The Open Group                                    */ 
    24/*                                                                           */ 
    35/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2123/* ------------------------------------------------------------------------- */ 
    2224/*                                                                           */ 
    23 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2426/*                                                                           */ 
    25 /* $Source: /arm4/sdk4/c/include/arm4agent.h,v $    */ 
    26 /* $Revision: 1.0 $  */ 
    27 /* $Date: 2004/05/09 13:55:14 $      */ 
    28  
    29 /* ------------------------------------------------------------------------- */ 
    30 /* arm4agent.h - ARM Agent Specific API Definitions                          */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - C Binding                                           */ 
    3130/*                                                                           */ 
    32 /* This header contains defines that are explicitly hidden from the          */ 
    33 /* application instrumentation and most be known to an ARM Agent.            */ 
    34 /*                                                                           */ 
    35 /* ARM4 C agent implementors must include this header and may also           */ 
    36 /* modify this header to define an agent specific correlator. The total      */ 
    37 /* length of this correlator cannot exceed ARM_CORR_MAX_LENGTH bytes.        */ 
    3831/* ------------------------------------------------------------------------- */ 
    3932 
    40 #if !defined(ARM4AGENT_H_INCLUDED) 
     33/** 
     34 * @file arm4agent.h 
     35 * @brief ARM 4.0 Agent Specific API Definitions 
     36 * 
     37 * This header contains defines that are explicitly hidden from the 
     38 * application instrumentation and most be known to an ARM Agent. 
     39 * 
     40 * ARM4 C agent implementors must include this header and may also 
     41 * modify this header to define an agent specific correlator. The total 
     42 * length of this correlator cannot exceed ARM_CORR_MAX_LENGTH bytes. 
     43 */ 
     44 
     45#ifndef ARM4AGENT_H_INCLUDED 
    4146#define ARM4AGENT_H_INCLUDED 
    4247 
     
    4853 
    4954/* Correlator flag bit definitions */ 
    50 #define ARM_CORR_FLAG_APP_TRACE         (0x40) /* Application instance trace */ 
    51                                                /* requested                  */ 
    52 #define ARM_CORR_FLAG_AGENT_TRACE       (0x80) /* Agent transaction instance */ 
    53                                                /* trace requested            */ 
     55#define ARM_CORR_FLAG_APP_TRACE       (0x40) /**< Application instance trace  
     56                                                 requested                  */ 
     57#define ARM_CORR_FLAG_AGENT_TRACE     (0x80) /**< Agent transaction instance 
     58                                                 trace requested            */ 
    5459 
    5560/* Known ARM correlator formats: Vendor reserved arena 1-127 */ 
    56 #define ARM_CORR_FORMAT_VERSION2           1   /* ARM2 Correlator format     */ 
    57 #define ARM_CORR_FORMAT_VERSION3           2   /* ARM3 Correlator format     */ 
    58 #define ARM_CORR_FORMAT_HP                28   /* HP's ARM correlator        */ 
    59 #define ARM_CORR_FORMAT_BMC               82   /* BMC's ARM correlator       */ 
    60 #define ARM_CORR_FORMAT_IBM              103   /* IBM's ARM correlator       */ 
    61 #define ARM_CORR_FORMAT_TANG_IT          122   /* tang-IT's ARM correlator   */ 
    62 #define ARM_CORR_FORMAT_SDK4_OUT_PROC    125   /* ARM4SDK out of process corr*/ 
    63 #define ARM_CORR_FORMAT_SDK4_IN_PROC     126   /* ARM4SDK in process corr    */ 
     61#define ARM_CORR_FORMAT_VERSION2           1 /**< ARM2 Correlator format     */ 
     62#define ARM_CORR_FORMAT_VERSION3           2 /**< ARM3 Correlator format     */ 
     63#define ARM_CORR_FORMAT_HP                28 /**< HP's ARM correlator        */ 
     64#define ARM_CORR_FORMAT_BMC               82 /**< BMC's ARM correlator       */ 
     65#define ARM_CORR_FORMAT_IBM              103 /**< IBM's ARM correlator       */ 
     66#define ARM_CORR_FORMAT_TANG_IT          122 /**< tang-IT's ARM correlator   */ 
     67#define ARM_CORR_FORMAT_SDK4_OUT_PROC    125 /**< ARM4SDK out of process corr*/ 
     68#define ARM_CORR_FORMAT_SDK4_IN_PROC     126 /**< ARM4SDK in process corr    */ 
    6469 
    65 #define ARM_CORR_FORMAT_INVALID          127   /* Indicates an invalid corr. */ 
     70#define ARM_CORR_FORMAT_INVALID          127 /**< Indicates an invalid corr. */ 
    6671 
    6772/* Known ARM correlator formats: Vendor playground arena 128-256 */ 
    68 #define ARM_CORR_FORMAT_HP_128           128   /* HP                         */ 
    69 #define ARM_CORR_FORMAT_IBM_203          203   /* IBM                        */ 
    70 #define ARM_CORR_FORMAT_IBM_204          204   /* IBM                        */ 
     73#define ARM_CORR_FORMAT_HP_128           128 /**< HP                         */ 
     74#define ARM_CORR_FORMAT_IBM_203          203 /**< IBM                        */ 
     75#define ARM_CORR_FORMAT_IBM_204          204 /**< IBM                        */ 
    7176 
    7277/* ------------------------------------------------------------------------- */ 
     
    7479/* ------------------------------------------------------------------------- */ 
    7580 
    76 /* Correlator header which must be the same across all implementations       */ 
     81/** 
     82 * @brief Correlator header which must be the same across all implementations 
     83 */ 
    7784typedef struct arm_correlator_header { 
    78     arm_uint8_t         length[2];      /* Length of correlator              */ 
    79     arm_uint8_t         format;         /* Format of the correlator          */ 
    80     arm_uint8_t         flags;          /* Flags                             */ 
     85    arm_uint8_t         length[2];      /**< Length of correlator            */ 
     86    arm_uint8_t         format;         /**< Format of the correlator        */ 
     87    arm_uint8_t         flags;          /**< Flags                           */ 
    8188} arm_correlator_header_t; 
    8289 
    83 /* Correlator structure definitions */ 
     90/** 
     91 * @brief ARM 2.0 correlator structure definitions 
     92 */ 
    8493typedef struct arm2_correlator {        /* ---- ARM 2 Correlator format ---- */ 
    85     arm_uint8_t         length[2];      /* Length of correlator              */ 
    86     arm_uint8_t         format;         /* Format of the correlator          */ 
    87     arm_uint8_t         flags;          /* Flags                             */ 
    88     arm_uint16_t        addr_format;    /* Format of the address             */ 
    89     arm_uint16_t        vendor_id;      /* IANA Vendor id                    */ 
    90     arm_uint16_t        agent_version;  /* Agent version number              */ 
    91     arm_uint16_t        agent_instance; /* Agent instance number             */ 
    92     arm_int32_t         start_handle;   /* Transaction start handle          */ 
    93     arm_int32_t         tran_id;        /* Transaction id                    */ 
    94     arm_uint16_t        addr_length;    /* Length of the address             */ 
    95     arm_uint8_t         address[146];   /* Agent contact info                */ 
     94    arm_uint8_t         length[2];      /**< Length of correlator            */ 
     95    arm_uint8_t         format;         /**< Format of the correlator        */ 
     96    arm_uint8_t         flags;          /**< Flags                           */ 
     97    arm_uint16_t        addr_format;    /**< Format of the address           */ 
     98    arm_uint16_t        vendor_id;      /**< IANA Vendor id                  */ 
     99    arm_uint16_t        agent_version;  /**< Agent version number            */ 
     100    arm_uint16_t        agent_instance; /**< Agent instance number           */ 
     101    arm_int32_t         start_handle;   /**< Transaction start handle        */ 
     102    arm_int32_t         tran_id;        /**< Transaction id                  */ 
     103    arm_uint16_t        addr_length;    /**< Length of the address           */ 
     104    arm_uint8_t         address[146];   /**< Agent contact info              */ 
    96105} arm2_correlator_t; 
    97106 
     107/** 
     108 * @brief ARM 3.0 correlator structure definitions 
     109 */ 
    98110typedef struct arm3_correlator {        /* ---- ARM 3 Correlator format ---- */ 
    99     arm_uint8_t         length[2];      /* Length of correlator              */ 
    100     arm_uint8_t         format;         /* Format of the correlator          */ 
    101     arm_uint8_t         flags;          /* Flags                             */ 
    102     arm_uint16_t        addr_format;    /* Format of the address             */ 
    103     arm_uint16_t        vendor_id;      /* IANA Vendor id                    */ 
    104     arm_uint16_t        agent_version;  /* Agent version number              */ 
    105     arm_uint16_t        agent_instance; /* Agent instance number             */ 
    106     arm_int64_t         tran_handle;    /* Transaction handle                */ 
    107     arm_id_t            tran_id;        /* Transaction uuid                  */ 
    108     arm_uint16_t        addr_length;    /* Length of the address             */ 
    109     arm_uint8_t         address[130];   /* Agent contact info                */ 
     111    arm_uint8_t         length[2];      /**< Length of correlator            */ 
     112    arm_uint8_t         format;         /**< Format of the correlator        */ 
     113    arm_uint8_t         flags;          /**< Flags                           */ 
     114    arm_uint16_t        addr_format;    /**< Format of the address           */ 
     115    arm_uint16_t        vendor_id;      /**< IANA Vendor id                  */ 
     116    arm_uint16_t        agent_version;  /**< Agent version number            */ 
     117    arm_uint16_t        agent_instance; /**< Agent instance number           */ 
     118    arm_int64_t         tran_handle;    /**< Transaction handle              */ 
     119    arm_id_t            tran_id;        /**< Transaction uuid                */ 
     120    arm_uint16_t        addr_length;    /**< Length of the address           */ 
     121    arm_uint8_t         address[130];   /**< Agent contact info              */ 
    110122} arm3_correlator_t; 
    111123 
    112 /* define an agent implementation's correlator format here */ 
     124/** 
     125 * @brief Define an agent implementation's correlator format here 
     126 */ 
    113127typedef struct arm_your_correlator {    /* -- Your Agent Correlator format - */ 
    114     arm_correlator_header_t  header;    /* Common correlator header          */ 
    115     arm_uint8_t              opaque[ARM_CORR_MAX_LENGTH-4];       /* REPLACE */ 
     128    arm_correlator_header_t  header;    /**< Common correlator header        */ 
     129    arm_uint8_t              opaque[ARM_CORR_MAX_LENGTH-4];     /**< REPLACE */ 
    116130} arm_your_correlator_t; 
    117131 
  • arm4sdk/trunk/c/include/arm4dyn.h

    r1 r15  
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
    26 /*                                                                           */ 
    27 /* $Source: /tang_cvs/arm4/sdk4/c/include/arm4dyn.h,v $    */ 
    28 /* $Revision: 1.2 $  */ 
    29 /* $Date: 2003/12/03 13:55:14 $      */ 
     25/* This file corresponds to following documentation:                         */ 
     26/*                                                                           */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - C Binding                                           */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
  • arm4sdk/trunk/c/include/arm4sdkagent.h

    r14 r15  
    2424 
    2525/* ------------------------------------------------------------------------- */ 
    26 /* arm4agent.h - ARM Agent Specific API Definitions                          */ 
     26/* arm4sdkagent.h - ARM Agent Specific API Definitions                       */ 
    2727/*                                                                           */ 
    2828/* This header contains defines that are explicitly hidden from the          */ 
     
    3434/* ------------------------------------------------------------------------- */ 
    3535 
    36 #if !defined(ARM4AGENT_H_INCLUDED) 
    37 #define ARM4AGENT_H_INCLUDED 
     36#if !defined(ARM4SDKAGENT_H_INCLUDED) 
     37#define ARM4SDKAGENT_H_INCLUDED 
    3838 
    39 #include "arm4.h"                              /* ARM API definitions        */ 
    40  
    41 /* ------------------------------------------------------------------------- */ 
    42 /* ------------------------- ARM agent definitions ------------------------- */ 
    43 /* ------------------------------------------------------------------------- */ 
    44  
    45 /* Correlator flag bit definitions */ 
    46 #define ARM_CORR_FLAG_APP_TRACE         (0x40) /* Application instance trace */ 
    47                                                /* requested                  */ 
    48 #define ARM_CORR_FLAG_AGENT_TRACE       (0x80) /* Agent transaction instance */ 
    49                                                /* trace requested            */ 
    50  
    51 /* Known ARM correlator formats: Vendor reserved arena 1-127 */ 
    52 #define ARM_CORR_FORMAT_VERSION2           1   /* ARM2 Correlator format     */ 
    53 #define ARM_CORR_FORMAT_VERSION3           2   /* ARM3 Correlator format     */ 
    54 #define ARM_CORR_FORMAT_HP                28   /* HP's ARM4 correlator       */ 
    55 #define ARM_CORR_FORMAT_IBM              103   /* IBM's ARM correlator       */ 
    56 #define ARM_CORR_FORMAT_TANG_IT          122   /* tang-IT's ARM4 correlator  */ 
    57 #define ARM_CORR_FORMAT_SDK4_OUT_PROC    125   /* ARM4SDK out of process corr*/ 
    58 #define ARM_CORR_FORMAT_SDK4_IN_PROC     126   /* ARM4SDK in process corr    */ 
    59  
    60 #define ARM_CORR_FORMAT_INVALID          127   /* Indicates an invalid corr. */ 
    61  
    62 /* Known ARM correlator formats: Vendor playground arena 128-256 */ 
    63 #define ARM_CORR_FORMAT_HP_128           128   /* HP                         */ 
    64 #define ARM_CORR_FORMAT_IBM_203          203   /* IBM                        */ 
    65 #define ARM_CORR_FORMAT_IBM_204          204   /* IBM                        */ 
     39#include "arm4agent.h"                         /* ARM API definitions        */ 
    6640 
    6741/* ------------------------------------------------------------------------- */ 
    6842/* ---------------------------- data definitions --------------------------- */ 
    6943/* ------------------------------------------------------------------------- */ 
    70  
    71 /* Correlator header which must be the same across all implementations       */ 
    72 typedef struct arm_correlator_header { 
    73     arm_uint8_t         length[2];      /* Length of correlator              */ 
    74     arm_uint8_t         format;         /* Format of the correlator          */ 
    75     arm_uint8_t         flags;          /* Flags                             */ 
    76 } arm_correlator_header_t; 
    77  
    78 /* Correlator structure definitions */ 
    79 typedef struct arm2_correlator {        /* ---- ARM 2 Correlator format ---- */ 
    80     arm_uint8_t         length[2];      /* Length of correlator              */ 
    81     arm_uint8_t         format;         /* Format of the correlator          */ 
    82     arm_uint8_t         flags;          /* Flags                             */ 
    83     arm_uint16_t        addr_format;    /* Format of the address             */ 
    84     arm_uint16_t        vendor_id;      /* IANA Vendor id                    */ 
    85     arm_uint16_t        agent_version;  /* Agent version number              */ 
    86     arm_uint16_t        agent_instance; /* Agent instance number             */ 
    87     arm_int32_t         start_handle;   /* Transaction start handle          */ 
    88     arm_int32_t         tran_id;        /* Transaction id                    */ 
    89     arm_uint16_t        addr_length;    /* Length of the address             */ 
    90     arm_uint8_t         address[146];   /* Agent contact info                */ 
    91 } arm2_correlator_t; 
    92  
    93 typedef struct arm3_correlator {        /* ---- ARM 3 Correlator format ---- */ 
    94     arm_uint8_t         length[2];      /* Length of correlator              */ 
    95     arm_uint8_t         format;         /* Format of the correlator          */ 
    96     arm_uint8_t         flags;          /* Flags                             */ 
    97     arm_uint16_t        addr_format;    /* Format of the address             */ 
    98     arm_uint16_t        vendor_id;      /* IANA Vendor id                    */ 
    99     arm_uint16_t        agent_version;  /* Agent version number              */ 
    100     arm_uint16_t        agent_instance; /* Agent instance number             */ 
    101     arm_int64_t         tran_handle;    /* Transaction handle                */ 
    102     arm_id_t            tran_id;        /* Transaction uuid                  */ 
    103     arm_uint16_t        addr_length;    /* Length of the address             */ 
    104     arm_uint8_t         address[130];   /* Agent contact info                */ 
    105 } arm3_correlator_t; 
    10644 
    10745/* define an agent implementation's correlator format here */ 
  • arm4sdk/trunk/c/sample/Makefile

    r1 r15  
    2121HEADER    = $(TOP)/c/include/arm4.h \ 
    2222            $(TOP)/c/include/arm4os.h \ 
    23             $(TOP)/c/include/arm4agent.h \ 
     23            $(TOP)/c/include/arm4sdkagent.h \ 
    2424            $(TOP)/c/include/arm4sdk.h \ 
    2525            $(TOP)/c/include/arm4sdk.i 
  • arm4sdk/trunk/c/tests/Makefile

    r1 r15  
    2121HEADER    = $(TOP)/c/include/arm4.h \ 
    2222            $(TOP)/c/include/arm4os.h \ 
    23             $(TOP)/c/include/arm4agent.h \ 
     23            $(TOP)/c/include/arm4sdkagent.h \ 
    2424            $(TOP)/c/include/arm4sdk.h \ 
    2525            $(TOP)/c/include/arm4sdk.i 
  • arm4sdk/trunk/java/jni/Makefile

    r10 r15  
    2929LIBLDFLAGS= $(LDFLAGS) $(SHAREDLDFLAGS) 
    3030 
     31JNIHEADER = org_opengroup_arm40_sdk_ArmJNITransaction_ArmJNIHandle.h \ 
     32        org_opengroup_arm40_sdk_ArmJNITransaction_ArmJNITranParams.h \ 
     33        org_opengroup_arm40_sdk_ArmJNITransaction.h 
    3134 
    3235#target for generating the jni lib 
     
    8992 
    9093clean: 
    91         rm -f *.o $(LIBARMJNI) jni_corr_results jni_metr_results jni_prop_results jni_simp_results 
     94        rm -f *.o $(LIBARMJNI) $(JNIHEADER) jni_corr_results jni_metr_results jni_prop_results jni_simp_results 
  • arm4sdk/trunk/java/jni/arm40_java_sdk_jni.c

    r1 r15  
    5454 
    5555/* only for correlator testing purposes, remove again later */ 
    56 #include "arm4agent.h" 
     56#include "arm4sdkagent.h" 
    5757 
    5858/* ------------------------------------------------------------------------- */ 
  • arm4sdk/trunk/java/org/opengroup/arm40/metric/ArmMetric.java

    r1 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/metric/ArmMetric.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
  • arm4sdk/trunk/java/org/opengroup/arm40/metric/ArmMetricCounter32.java

    r1 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/metric/ArmMetricCounter32.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
  • arm4sdk/trunk/java/org/opengroup/arm40/metric/ArmMetricCounter32Definition.java

    r1 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/metric/ArmMetricCounter32Definition.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
  • arm4sdk/trunk/java/org/opengroup/arm40/metric/ArmMetricCounter64.java

    r1 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/metric/ArmMetricCounter64.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
  • arm4sdk/trunk/java/org/opengroup/arm40/metric/ArmMetricCounter64Definition.java

    r1 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/metric/ArmMetricCounter64Definition.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
  • arm4sdk/trunk/java/org/opengroup/arm40/metric/ArmMetricCounterFloat32.java

    r1 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/metric/ArmMetricCounterFloat32.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
  • arm4sdk/trunk/java/org/opengroup/arm40/metric/ArmMetricCounterFloat32Definition.java

    r1 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/metric/ArmMetricCounterFloat32Definition.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
  • arm4sdk/trunk/java/org/opengroup/arm40/metric/ArmMetricDefinition.java

    r6 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/metric/ArmMetricDefinition.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
  • arm4sdk/trunk/java/org/opengroup/arm40/metric/ArmMetricFactory.java

    r1 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
    26 /*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/metric/ArmMetricFactory.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     25/* This file corresponds to following documentation:                         */ 
     26/*                                                                           */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
     
    4242/** 
    4343 * Provides methods to create instances of the classes in  
    44  * the org.opengroup.arm40.metric package. An error callback method can  
     44 * the org.opengroup.arm40.metric package. 
     45 * <p/> 
     46 * Factory Version: The org.opengroup.arm40.metric package contains the 
     47 * interfaces defined in both ARM 4.0 and ARM 4.1. Applications that use 
     48 * ARM 4.1 could instantiate classes that implement ARM 4.0 but not ARM 4.1. 
     49 * See the Technical Standard - Application Response Measurement (ARM) -  
     50 * Issue 4.1 Version 1 - Java Binding Section 8.2.1 "Version Compatibility"  
     51 * for an explanation of how to handle this situation to avoid runtime errors. 
     52 * <p/> 
     53 * An error callback method can  
    4554 * be registered for objects created with this factory (see  
    4655 * {@link #setErrorCallback(ArmErrorCallback)}). For additional  
     
    437446     *    
    438447     * @param errorCallback an application object implementing the 
    439      * <code>ArmErrorCallback> interface. 
     448     * {@link ArmErrorCallback} interface. 
    440449     * @return <code>true</code> if registration is accepted. 
    441450     * @see org.opengroup.arm40.transaction.ArmTransactionFactory#setErrorCallback 
  • arm4sdk/trunk/java/org/opengroup/arm40/metric/ArmMetricGauge32.java

    r1 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/metric/ArmMetricGauge32.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
  • arm4sdk/trunk/java/org/opengroup/arm40/metric/ArmMetricGauge32Definition.java

    r1 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/metric/ArmMetricGauge32Definition.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
  • arm4sdk/trunk/java/org/opengroup/arm40/metric/ArmMetricGauge64.java

    r1 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/metric/ArmMetricGauge64.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
  • arm4sdk/trunk/java/org/opengroup/arm40/metric/ArmMetricGauge64Definition.java

    r1 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/metric/ArmMetricGauge64Definition.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
  • arm4sdk/trunk/java/org/opengroup/arm40/metric/ArmMetricGaugeFloat32.java

    r1 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/metric/ArmMetricGaugeFloat32.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
  • arm4sdk/trunk/java/org/opengroup/arm40/metric/ArmMetricGaugeFloat32Definition.java

    r1 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/metric/ArmMetricGaugeFloat32Definition.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
  • arm4sdk/trunk/java/org/opengroup/arm40/metric/ArmMetricGroup.java

    r1 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/metric/ArmMetricGroup.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
  • arm4sdk/trunk/java/org/opengroup/arm40/metric/ArmMetricGroupDefinition.java

    r1 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/metric/ArmMetricGroupDefinition.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
  • arm4sdk/trunk/java/org/opengroup/arm40/metric/ArmMetricNumericId32.java

    r1 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/metric/ArmMetricNumericId32.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
  • arm4sdk/trunk/java/org/opengroup/arm40/metric/ArmMetricNumericId32Definition.java

    r1 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/metric/ArmMetricNumericId32Definition.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
  • arm4sdk/trunk/java/org/opengroup/arm40/metric/ArmMetricNumericId64.java

    r1 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/metric/ArmMetricNumericId64.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
  • arm4sdk/trunk/java/org/opengroup/arm40/metric/ArmMetricNumericId64Definition.java

    r1 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/metric/ArmMetricNumericId64Definition.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
  • arm4sdk/trunk/java/org/opengroup/arm40/metric/ArmMetricString32.java

    r1 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/metric/ArmMetricString32.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
  • arm4sdk/trunk/java/org/opengroup/arm40/metric/ArmMetricString32Definition.java

    r1 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/metric/ArmMetricString32Definition.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
  • arm4sdk/trunk/java/org/opengroup/arm40/metric/ArmTranReportWithMetrics.java

    r1 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/metric/ArmTranReportWithMetrics.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
  • arm4sdk/trunk/java/org/opengroup/arm40/metric/ArmTransactionWithMetrics.java

    r1 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/metric/ArmTransactionWithMetrics.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
  • arm4sdk/trunk/java/org/opengroup/arm40/metric/ArmTransactionWithMetricsDefinition.java

    r1 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/metric/ArmTransactionWithMetricsDefinition.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
  • arm4sdk/trunk/java/org/opengroup/arm40/nullsdk/ArmApplicationImpl.java

    r1 r15  
    100100                return "org.opengroup.arm40.transaction.ArmApplication"; 
    101101        } 
     102 
     103    public ArmApplicationControl getApplicationControl() { 
     104        return null; 
     105    } 
     106 
     107    public ArmTransactionDefinitionControl getTransactionDefinitionControl(ArmID tranID) { 
     108        return null; 
     109    } 
    102110} 
    103 //d 
  • arm4sdk/trunk/java/org/opengroup/arm40/nullsdk/ArmCorrelatorImpl.java

    r1 r15  
    6565         } 
    6666 
     67    public boolean isAsychronous() { 
     68        return false; 
     69    } 
     70    public boolean isIndependentTran() { 
     71        return false; 
     72    } 
     73    public int     setAsychronous(boolean b) { 
     74        return -1; 
     75    } 
     76    public int     setIndependentTran(boolean b) { 
     77        return -1; 
     78    } 
     79 
    6780} 
    6881 
  • arm4sdk/trunk/java/org/opengroup/arm40/nullsdk/ArmTranReportImpl.java

    r1 r15  
    113113 
    114114   public int report(int status, long respTime) { 
    115       return report(status, respTime, 0, null); 
     115       return 0; 
    116116   } 
    117117 
    118118   public int report(int status, long respTime, String diagnosticDetail) { 
    119       return report(status, respTime, 0, diagnosticDetail); 
     119       return 0; 
    120120   } 
    121121 
    122122   public int report(int status, long respTime, long stopTime) { 
    123       return report(status, respTime, stopTime, null); 
     123       return 0; 
    124124   } 
    125125 
     
    168168   } 
    169169 
     170    public int report(int status, long respTimeNanos, 
     171        org.opengroup.arm40.transaction.ArmDiagnosticProperties props) { 
     172        return -1; 
     173    } 
     174 
     175    public int report(int status, long respTimeNanos, long stopTime,  
     176        org.opengroup.arm40.transaction.ArmDiagnosticProperties props) { 
     177        return -1; 
     178    } 
    170179} 
    171 //dd 
  • arm4sdk/trunk/java/org/opengroup/arm40/nullsdk/ArmTransactionFactoryImpl.java

    r1 r15  
    7474        } 
    7575 
     76    public ArmBlockCause newArmBlockCause() { 
     77        return null; 
     78    } 
     79    public ArmMessageEventGroup newMessageEventGroup() { 
     80        return null; 
     81    } 
     82    public ArmMessageReceivedEvent newMessageReceivedEvent() { 
     83        return null; 
     84    } 
     85    public ArmMessageSentEvent newMessageSentEvent() { 
     86        return null; 
     87    } 
     88    public ArmPrestartTimeStats newArmPrestartTimeStats() { 
     89        return null; 
     90    } 
     91    public ArmTimestampOpaque newArmTimestampOpaque() { 
     92        return null; 
     93    } 
     94    public ArmTimestampStrings newArmTimestampStrings() { 
     95        return null; 
     96    } 
     97    public ArmTimestampUsecJan1970 newArmTimestampUsecJan1970() { 
     98        return null; 
     99    } 
     100 
    76101} 
  • arm4sdk/trunk/java/org/opengroup/arm40/nullsdk/ArmTransactionImpl.java

    r1 r15  
    179179 
    180180   public int stop(int status) { 
    181       return stop(status, null); 
     181       return stop(status, (String)null); 
    182182   } 
    183183 
     
    210210   } 
    211211 
     212    public long blocked(ArmBlockCause cause) { 
     213        return 0; 
     214    } 
     215    public ArmCorrelator getCorrelator(boolean localOnly) { 
     216        return null; 
     217    } 
     218    public ArmTransactionControl getControl(ArmCorrelator parent) { 
     219        return null; 
     220    } 
     221    public boolean isAutomaticBindThread() { 
     222        return false; 
     223    } 
     224    public int setAutomaticBindThread(boolean b) { 
     225        return -1; 
     226    } 
     227    public int setMessageEventGroup(ArmMessageEventGroup group) { 
     228        return -1; 
     229    } 
     230    public int setPrestartTimeValue(long nanos) { 
     231        return -1; 
     232    } 
     233    public int setPrestartTimeValue(ArmPrestartTimeStats stats) { 
     234        return -1; 
     235    } 
     236    public int setPrestartTimeValue(ArmTimestamp timestamp) { 
     237        return -1; 
     238    } 
     239    public int stop(int status, ArmDiagnosticProperties props) { 
     240        return -1; 
     241    } 
    212242} 
  • arm4sdk/trunk/java/org/opengroup/arm40/sdk/ArmApplicationImpl.java

    r1 r15  
    127127      return "org.opengroup.arm40.transaction.ArmApplication"; 
    128128   } 
     129 
     130    public ArmApplicationControl getApplicationControl() { 
     131        return null; 
     132    } 
     133 
     134    public ArmTransactionDefinitionControl getTransactionDefinitionControl(ArmID tranID) { 
     135        return null; 
     136    } 
     137 
    129138} 
  • arm4sdk/trunk/java/org/opengroup/arm40/sdk/ArmCorrelatorImpl.java

    r1 r15  
    6363                          return false; 
    6464                return ((array[3] & FLAG_APP_TRACE_REQ) != 0); 
    65          } 
     65         }     
    6666 
     67    public boolean isAsychronous() { 
     68        return false; 
     69    } 
     70    public boolean isIndependentTran() { 
     71        return false; 
     72    } 
     73 
     74    public int setAsychronous(boolean b) { 
     75        return -1; 
     76    } 
     77 
     78    public int setIndependentTran(boolean independent) { 
     79        return -1; 
     80    }     
    6781} 
    6882 
  • arm4sdk/trunk/java/org/opengroup/arm40/sdk/ArmTranReportImpl.java

    r1 r15  
    155155 
    156156   public int report(int status, long respTime) { 
    157       return report(status, respTime, 0, null); 
     157      String diagDetail = null; 
     158      return report(status, respTime, 0, diagDetail); 
    158159   } 
    159160 
     
    163164 
    164165   public int report(int status, long respTime, long stopTime) { 
    165       return report(status, respTime, stopTime, null); 
     166      String diagDetail = null; 
     167      return report(status, respTime, stopTime, diagDetail); 
    166168   } 
    167169 
     
    254256   } 
    255257 
     258    public int report(int status, long respTimeNanos, 
     259        org.opengroup.arm40.transaction.ArmDiagnosticProperties props) { 
     260        return -1; 
     261    } 
     262 
     263    public int report(int status, long respTimeNanos, long stopTime,  
     264        org.opengroup.arm40.transaction.ArmDiagnosticProperties props) { 
     265        return -1; 
     266    } 
    256267} 
  • arm4sdk/trunk/java/org/opengroup/arm40/sdk/ArmTransactionFactoryImpl.java

    r1 r15  
    8585   } 
    8686 
     87    public ArmBlockCause newArmBlockCause() { 
     88        return null; 
     89    } 
     90    public ArmMessageEventGroup newMessageEventGroup() { 
     91        return null; 
     92    } 
     93    public ArmMessageReceivedEvent newMessageReceivedEvent() { 
     94        return null; 
     95    } 
     96    public ArmMessageSentEvent newMessageSentEvent() { 
     97        return null; 
     98    } 
     99    public ArmPrestartTimeStats newArmPrestartTimeStats() { 
     100        return null; 
     101    } 
     102    public ArmTimestampOpaque newArmTimestampOpaque() { 
     103        return null; 
     104    } 
     105    public ArmTimestampStrings newArmTimestampStrings() { 
     106        return null; 
     107    } 
     108    public ArmTimestampUsecJan1970 newArmTimestampUsecJan1970() { 
     109        return null; 
     110    } 
     111 
    87112} 
  • arm4sdk/trunk/java/org/opengroup/arm40/sdk/ArmTransactionImpl.java

    r1 r15  
    276276 
    277277   public int stop(int status) { 
    278       return stop(status, null); 
     278      String diagDetail = null; 
     279      return stop(status, diagDetail); 
    279280   } 
    280281 
     
    315316   } 
    316317 
     318    public long blocked(ArmBlockCause cause) { 
     319        return 0; 
     320    } 
     321    public ArmCorrelator getCorrelator(boolean localOnly) { 
     322        return null; 
     323    } 
     324    public ArmTransactionControl getControl(ArmCorrelator parent) { 
     325        return null; 
     326    } 
     327    public boolean isAutomaticBindThread() { 
     328        return false; 
     329    } 
     330    public int setAutomaticBindThread(boolean b) { 
     331        return -1; 
     332    } 
     333    public int setMessageEventGroup(ArmMessageEventGroup group) { 
     334        return -1; 
     335    } 
     336    public int setPrestartTimeValue(long nanos) { 
     337        return -1; 
     338    } 
     339    public int setPrestartTimeValue(ArmPrestartTimeStats stats) { 
     340        return -1; 
     341    } 
     342    public int setPrestartTimeValue(ArmTimestamp timestamp) { 
     343        return -1; 
     344    } 
     345    public int stop(int status, ArmDiagnosticProperties props) { 
     346        return -1; 
     347    } 
     348 
    317349} 
  • arm4sdk/trunk/java/org/opengroup/arm40/sdk/test/Arm4TranReportTest.java

    r1 r15  
    9999 
    100100                        tranReport.report(ArmConstants.STATUS_GOOD,  
    101                                                                         /* response time must be nanoseconds */ 
    102                                                                         (stopTime-startTime)*1000000, 
    103                                                                         stopTime, 
    104                                                                         /* no diagnostic detail */ 
    105                                                                         null); 
     101                                          /* response time must be nanoseconds */ 
     102                                          (stopTime-startTime)*1000000, 
     103                                          stopTime, 
     104                                          /* no diagnostic detail */ 
     105                                          (String)null); 
    106106 
    107107                        System.out.println("\nnew report() called on ArmTranRreport"); 
  • arm4sdk/trunk/java/org/opengroup/arm40/tranreport/ArmApplicationRemote.java

    r6 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/tranreport/ArmApplicationRemote.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
     
    4141 * local system. 
    4242 * <p/> 
    43  * ArmApplicationRemote provides an anchor point for associating  
    44  * <code>ArmTranReport</code> objects with a system's network address.  
     43 * <code>ArmApplicationRemote</code> provides an anchor point for associating  
     44 * {@link ArmTranReport} objects with a system's network address.  
    4545 * It adds the following attribute to those in <code>ArmApplication</code>: 
    4646 * <ul> 
  • arm4sdk/trunk/java/org/opengroup/arm40/tranreport/ArmSystemAddress.java

    r1 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/tranreport/ArmSystemAddress.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
  • arm4sdk/trunk/java/org/opengroup/arm40/tranreport/ArmTranReport.java

    r6 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
    26 /*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/tranreport/ArmTranReport.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     25/* This file corresponds to following documentation:                         */ 
     26/*                                                                           */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
     
    144144public interface ArmTranReport extends ArmInterface { 
    145145 
    146 // No Public Constructors 
    147  
    148 // Public Instance Methods 
     146    // No Public Constructors 
     147 
     148    // Public Instance Methods 
    149149 
    150150    /** 
     
    190190    public ArmCorrelator getParentCorrelator(); 
    191191 
    192         /** 
    193         * returns the last response time set on a <code>report()</code> method.  
    194         * If <code>report()</code> has never executed, the return value 
    195         * is implementation dependent. 
    196         * @return the response time as of the last <code>report()</code> call.  
    197         */ 
     192    /** 
     193    * returns the last response time set on a <code>report()</code> method.  
     194    * If <code>report()</code> has never executed, the return value 
     195    * is implementation dependent. 
     196    * @return the response time as of the last <code>report()</code> call.  
     197    */ 
    198198    public long getResponseTime(); 
    199199 
    200         /** 
    201         * returns the last status value set on a <code>report()</code> method.  
    202         * If <code>report()</code> has never executed, it returns  
    203         * <code>STATUS_INVALID</code>. 
    204         * @return one of the status values defined in  
    205         *         {@link org.opengroup.arm40.transaction.ArmConstants}.  
    206         */ 
     200    /** 
     201    * returns the last status value set on a <code>report()</code> method.  
     202    * If <code>report()</code> has never executed, it returns  
     203    * <code>STATUS_INVALID</code>. 
     204    * @return one of the status values defined in  
     205    *         {@link org.opengroup.arm40.transaction.ArmConstants}.  
     206    */ 
    207207    public int getStatus(); 
    208208 
     
    228228     * @param respTimeNanos response time (in nanoseconds) 
    229229     * @return 0 on sucess; otherwise, a non-zero error code is returned (as 
    230         *         specified in  
    231         *         {@link org.opengroup.arm40.transaction.ArmInterface}). 
     230    *         specified in  
     231    *         {@link org.opengroup.arm40.transaction.ArmInterface}). 
    232232     */ 
    233233    public int report(int status, long respTimeNanos); 
     
    242242     * @param stopTime stop time (milliseconds since January 1, 1970)  
    243243     * @return 0 on sucess; otherwise, a non-zero error code is returned (as 
    244         *         specified in  
    245         *         {@link org.opengroup.arm40.transaction.ArmInterface}). 
     244    *         specified in  
     245    *         {@link org.opengroup.arm40.transaction.ArmInterface}). 
    246246     */ 
    247247    public int report(int status, long respTimeNanos, long stopTime); 
     
    257257     *                         <code>ArmConstants.STATUS_GOOD</code> 
    258258     * @return 0 on sucess; otherwise, a non-zero error code is returned (as 
    259         *         specified in  
    260         *         {@link org.opengroup.arm40.transaction.ArmInterface}). 
     259    *         specified in  
     260    *         {@link org.opengroup.arm40.transaction.ArmInterface}). 
    261261     */ 
    262262    public int report(int status, long respTimeNanos, String diagnosticDetail); 
     
    273273     *                         <code>ArmConstants.STATUS_GOOD</code>  
    274274     * @return 0 on sucess; otherwise, a non-zero error code is returned (as 
    275         *         specified in  
    276         *         {@link org.opengroup.arm40.transaction.ArmInterface}). 
     275    *         specified in  
     276    *         {@link org.opengroup.arm40.transaction.ArmInterface}). 
    277277     */ 
    278278    public int report(int status, long respTimeNanos, long stopTime, String diagnosticDetail); 
     279 
     280    /** 
     281     * provide measurements about a completed transaction. See 
     282     * the discussion of this method in the interface description above. 
     283     *  
     284     * @param status transaction status.  
     285     *               See {@link org.opengroup.arm40.transaction.ArmConstants}. 
     286     * @param respTimeNanos response time (in nanoseconds) 
     287     * @param props  additional diagnostic propertoes, used when status other than 
     288     *                         <code>ArmConstants.STATUS_GOOD</code>  
     289     * @return 0 on sucess; otherwise, a non-zero error code is returned (as 
     290     *         specified in  
     291     *         {@link org.opengroup.arm40.transaction.ArmInterface}). 
     292     * @since ARM 4.1 
     293     */ 
     294    public int report(int status, long respTimeNanos, 
     295        org.opengroup.arm40.transaction.ArmDiagnosticProperties props); 
     296 
     297    /** 
     298     * provide measurements about a completed transaction. See 
     299     * the discussion of this method in the interface description above. 
     300     *  
     301     * @param status transaction status.  
     302     *               See {@link org.opengroup.arm40.transaction.ArmConstants}. 
     303     * @param respTimeNanos response time (in nanoseconds) 
     304     * @param stopTime stop time (milliseconds since January 1, 1970) 
     305     * @param props  additional diagnostic propertoes, used when status other than 
     306     *                         <code>ArmConstants.STATUS_GOOD</code>  
     307     * @return 0 on sucess; otherwise, a non-zero error code is returned (as 
     308     *         specified in  
     309     *         {@link org.opengroup.arm40.transaction.ArmInterface}). 
     310     * @since ARM 4.1 
     311     */ 
     312    public int report(int status, long respTimeNanos, long stopTime,  
     313        org.opengroup.arm40.transaction.ArmDiagnosticProperties props); 
    279314 
    280315    /** 
     
    282317     * @param value the new URI context value. 
    283318     * @return 0 on sucess; otherwise, a non-zero error code is returned (as 
    284         *         specified in  
    285         *         {@link org.opengroup.arm40.transaction.ArmInterface}). 
     319    *         specified in  
     320    *         {@link org.opengroup.arm40.transaction.ArmInterface}). 
    286321     */ 
    287322    public int setContextURIValue(String value); 
     
    299334     * @param value the new context value. 
    300335     * @return 0 on sucess; otherwise, a non-zero error code is returned (as 
    301         *         specified in  
    302         *         {@link org.opengroup.arm40.transaction.ArmInterface}). 
     336    *         specified in  
     337    *         {@link org.opengroup.arm40.transaction.ArmInterface}). 
    303338     */ 
    304339    public int setContextValue(int index, String value); 
     
    310345     *               <code>null</code>. 
    311346     * @return 0 on sucess; otherwise, a non-zero error code is returned (as 
    312         *         specified in  
    313         *         {@link org.opengroup.arm40.transaction.ArmInterface}). 
     347    *         specified in  
     348    *         {@link org.opengroup.arm40.transaction.ArmInterface}). 
    314349     */ 
    315350    public int setParentCorrelator(ArmCorrelator parent); 
     
    324359     * @param user an <code>ArmUser</code>, or <code>null</code> 
    325360     * @return 0 on sucess; otherwise, a non-zero error code is returned (as 
    326         *         specified in  
    327         *         {@link org.opengroup.arm40.transaction.ArmInterface}). 
     361    *         specified in  
     362    *         {@link org.opengroup.arm40.transaction.ArmInterface}). 
    328363     */ 
    329364    public int setUser(ArmUser user); 
  • arm4sdk/trunk/java/org/opengroup/arm40/tranreport/ArmTranReportFactory.java

    r1 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/tranreport/ArmTranReportFactory.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
     
    4242/** 
    4343 * Provides methods to create instances of the classes in  
    44  * the org.opengroup.arm40.tranreport package. An error callback method can  
    45  * be registered for objects created with this factory (see  
    46  * {@link #setErrorCallback(ArmErrorCallback)}). For additional  
    47  * details about error handling philosophy see the description 
    48  * of {@link org.opengroup.arm40.transaction.ArmTransactionFactory}. 
     44 * the org.opengroup.arm40.tranreport package. 
     45 * <p/> 
     46 * Factory Version: The org.opengroup.arm40.tranreport package contains the 
     47 * interfaces defined in both ARM 4.0 and ARM 4.1. Applications that use 
     48 * ARM 4.1 could instantiate classes that implement ARM 4.0 but not ARM 4.1. 
     49 * See the Technical Standard - Application Response Measurement (ARM) -  
     50 * Issue 4.1 Version 1 - Java Binding Section 8.2.1 "Version Compatibility"  
     51 * for an explanation of how to handle this situation to avoid runtime errors. 
     52 * <p/> 
     53 * An error callback method can be registered for objects created 
     54 * with this factory (see {@link #setErrorCallback(ArmErrorCallback)}). 
     55 * For additional details about error handling philosophy see the 
     56 * description of {@link org.opengroup.arm40.transaction.ArmTransactionFactory}. 
    4957 * <p/> 
    5058 * Semantics of the factory methods are provided in the description  
  • arm4sdk/trunk/java/org/opengroup/arm40/transaction/ArmApplication.java

    r6 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/transaction/ArmApplication.java,v $    */ 
    28 /* $Revision: 1.1 $  */ 
    29 /* $Date: 2005/03/14 15:14:53 $      */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
     
    116116 * not respect the specification.  
    117117 * <p/> 
     118 * <code>getApplicationControl()</code> and <code>getTransactionDefinitionControl()</code> 
     119 * may be used by applications to understand the ARM implementation's 
     120 * preferences for instrumentation details that apply at the scope of all 
     121 * transactions in the entire application or all transactions of a registered 
     122 * transaction ID, respectively. The getter methods in the returned control 
     123 * blocks, if any, may be queried to learn the details. If null is returned,  
     124 * the application should use its default level of instrumentation. It is a 
     125 * good practice to use <code>getApplicationControl()</code> and 
     126 * <code>getTransactionDefinitionControl()</code> periodically, such as after 
     127 * every 1000 transactions or every 15 minutes, to refresh the settings. 
     128 * <p/> 
    118129 * Objects implementing this interface are created using  
    119130 * {@link ArmTransactionFactory#newArmApplication}. 
     
    132143     * comments in the interface description above. 
    133144     *  
    134      * @return 0 on sucess; otherwise, a non-zero error code is returned  
     145     * @return 0 on success; otherwise, a non-zero error code is returned  
    135146     * (as specified in {@link org.opengroup.arm40.transaction.ArmInterface}). 
    136147     */ 
    137148    public int end(); 
    138          
     149 
     150    /** 
     151     * @return the application control data which controls all transactions  
     152     * of the application 
     153     * @since ARM 4.1 
     154     */ 
     155    public ArmApplicationControl getApplicationControl(); 
     156 
    139157    /** 
    140158     * retrieves a context property value. 
     
    162180     */ 
    163181    public String getInstance(); 
     182 
     183    /** 
     184     * @param tranID transaction ID to get the control data 
     185     * @return the transaction control data for the specified transaction ID 
     186     * @since ARM 4.1 
     187     */ 
     188    public ArmTransactionDefinitionControl getTransactionDefinitionControl(ArmID tranID); 
    164189} 
    165190 
  • arm4sdk/trunk/java/org/opengroup/arm40/transaction/ArmApplicationDefinition.java

    r1 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/transaction/ArmApplicationDefinition.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
  • arm4sdk/trunk/java/org/opengroup/arm40/transaction/ArmConstants.java

    r1 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/transaction/ArmConstants.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
     
    3434 
    3535 
    36 /** Constants that are widely used in the ARM 4.0 interfaces.  
     36/** 
     37 * Constants that are widely used in the ARM 4.0 interfaces.  
    3738 * They are declared in one interface as a matter of convenience  
    3839 * (instead of duplicating them in multiple interfaces).  
     
    4647 
    4748// Constants 
     49    /** 
     50     * A synchronous event caused the block        (=1) 
     51     * @since ARM 4.1 
     52     */ 
     53    public static final int BLOCK_CAUSE_SYNCHRONOUS_EVENT = 1; 
     54    /** 
     55     * An asynchronous event caused the block      (=2) 
     56     * @since ARM 4.1 
     57     */ 
     58    public static final int BLOCK_CAUSE_ASYNCHRONOUS_EVENT = 2; 
     59 
     60    /** 
     61     * Collection depth = None                     (=0) 
     62     * @since ARM 4.1 
     63     */ 
     64    public static final int COLLECTION_DEPTH_NONE = 0; 
     65    /** 
     66     * Collection depth = Process granularity      (=1) 
     67     * @since ARM 4.1 
     68     */ 
     69    public static final int COLLECTION_DEPTH_PROCESS = 1; 
     70    /** 
     71     * Collection depth = Container granularity    (=2) 
     72     * @since ARM 4.1 
     73     */ 
     74    public static final int COLLECTION_DEPTH_CONTAINER = 2; 
     75    /** 
     76     * Collection depth = Maximum granularity      (=3) 
     77     * @since ARM 4.1 
     78     */ 
     79    public static final int COLLECTION_DEPTH_MAX = 3; 
    4880 
    4981    /** 
     
    6799     */ 
    68100    public static final int ID_LENGTH = 16; 
     101 
     102    /** 
     103     * Max number of events in ArmMessageEventGroup (currently=32) 
     104     * @since ARM 4.1 
     105     */ 
     106    public static final int MESSAGE_EVENT_MAX_COUNT = 32; 
    69107 
    70108    /** 
  • arm4sdk/trunk/java/org/opengroup/arm40/transaction/ArmCorrelator.java

    r6 r15  
    11/* ------------------------------------------------------------------------- */ 
    22/*                                                                           */ 
    3 /* Copyright (c) 2003 The Open Group                                         */ 
     3/* Copyright (c) 2003-2007 The Open Group                                    */ 
    44/*                                                                           */ 
    55/* Permission is hereby granted, free of charge, to any person obtaining a   */ 
     
    2323/* ------------------------------------------------------------------------- */ 
    2424/*                                                                           */ 
    25 /* File revision information                                                 */ 
     25/* This file corresponds to following documentation:                         */ 
    2626/*                                                                           */ 
    27 /* $Source: /mnt/cvslocal/sdk4/java/org/opengroup/arm40/transaction/ArmCorrelator.java,v $ */ 
    28 /* $Revision: 1.1 $ */ 
    29 /* $Date: 2005/03/14 15:14:53 $ */ 
     27/* Technical Standard                                                        */ 
     28/* Application Response Measurement (ARM)                                    */ 
     29/* Issue 4.1 Version 1 - Java Binding                                        */ 
    3030/*                                                                           */ 
    3131/* ------------------------------------------------------------------------- */ 
     
    6868 * <code>ArmToken</code>, <code>ArmCorrelator</code>'s parent interface. 
    6969 * <p/> 
     70 * ARM 4.1 introduced the "asynchronous" and "independent transaction" flags. 
     71 * These are notably different from the "agent trace" and "application trace" 
     72 * flag because the values are set directly by the instrumented application. 
     73 * A typical sequence would be the following: 
     74 * <pre> 
     75 * ArmTransaction tran; ArmCorrelator corr; 
     76 * corr      = tran.getCorrelator(); 
     77 * status = corr.setAsynchronous(True); 
     78 * status = corr.setIndependentTran(False); 
     79 * // pass correlator to child transactions... 
     80 * </pre> 
     81 * <p/> 
    7082 * Implementations of this interface should also override  
    7183 * <code>equals()</code> and <code>hashCode()</code> from  
     
    91103     */ 
    92104    public boolean isApplicationTrace(); 
     105 
     106    /** 
     107     * indicates whether the "asynchronous" flag is on in the correlator. 
     108     * @return the status of the asynchronous flag. 
     109     * @since ARM 4.1 
     110     */ 
     111    public boolean isAsychronous(); 
     112    /** 
     113     * indicates whether the "independent transaction" flag is on in the 
     114     * correlator. 
     115     * @return the status of the independent flag. 
     116     * @since ARM 4.1 
     117     */ 
     118    public boolean isIndependentTran(); 
     119    /** 
     120     * causes the "asynchronous" flag to be set to the specified boolean value. 
     121     * @param b  the new status of the asynchronous flag. 
     122     * @return 0 on success; otherwise, a non-zero error code is returned  
     123     * (as specified in {@link org.opengroup.arm40.transaction.ArmInterface}). 
     124     * @since ARM 4.1 
     125     */ 
     126    public int     setAsychronous(boolean b); 
     127    /**