Python language bindings for the Application Response Measurement (ARM) Version 4.0 standard.
 
This module provides a Python language implementation of the ARM 4.0
standard. At it's simplest, it's a straight exposure of the C language
bindings with enough concessions to make it fit the Python language.
 
Usage:
 
  import arm4
 
  # Register
  app_id = arm4.register_application ("Python test")
  tran_id = arm4.register_transaction (app_id, "Python hello world")
 
  # Start our application and transaction measurements
  app_handle = arm4.start_application (app_id, "Example")
  tran_handle = arm4.start_transaction (app_handle, tran_id)
 
  # Do our work
  print 'Hello, world!'
 
  # Stop our measurements
  arm4.stop_transaction (tran_handle) # Default status is arm4.ARM_STATUS_GOOD
  arm4.stop_application (app_handle)
 
  # Finish up
  arm4.destroy_application (app_id)
 
This is a simple example that doesn't make use of ARM's advanced
correlators or metrics. More examples can be found at http://www.arm4.org
 
This module is based on the ARM Issue 4.0, Version 2 - C Binding standard. More information
can be found at http://www.opengroup.org/management/arm.htm

Classes
		__builtin__.object ArmArrivalTime ArmBuffer ArmCorrelator ArmHandle ArmID ArmSubbufferAppContext ArmSubbufferAppIdentity ArmSubbufferArrivalTime ArmSubbufferCharset ArmSubbufferDiagDetail ArmSubbufferMetricBindings ArmSubbufferMetricValues ArmSubbufferSystemAddress ArmSubbufferTranContext ArmSubbufferTranIdentity ArmSubbufferUser exceptions.Exception error   class ArmArrivalTime(__builtin__.object)     Opaque wrapper for an ARM 4 arrival time structure. This is created by calling get_arrival_time ()       class ArmBuffer(__builtin__.object)     Many of the ARM function calls provide a way for the application and ARM implementation to exchange optional data, in addition to the required data in other function parameters. This buffer describes the format of the exchanged data.   Almost all functions define a ArmBuffer parameter. When the value is provided, the value points to a buffer containing a number of sub-buffers. It differs from the ARM 2.0 format in that the buffer contains  pointers to sub-buffers, rather than inline contiguous data. The sub-buffers contain the meaningful data. The internals of this buffer are hidden in the ArmBuffer object.   Each sub-buffer may be in the user data buffer once. If there is more than one instance of a sub- buffer in the buffer, all instances after the first will be ignored.     Methods defined here: add_subbuffer(...) add_subbuffer(sub_buffer): add a sub-buffer   DESCRIPTION   Adds a sub-buffer object to the user data buffer. This can then be passed to any of the arm4   methods as required and appropriate.     This abstracts the ARM 4 arm_buffer4_t internals PARAMETERS   sub_buffer   A valid ArmSubbuffer* object RETURN VALUE   None Data and other attributes defined here: __new__ = <built-in method __new__ of type object> T.__new__(S, ...) -> a new object with type S, a subtype of T   class ArmCorrelator(__builtin__.object)     Opaque wrapper for an ARM 4 correlator structure.     Methods defined here: __str__(...) x.__str__() <==> str(x) from_string(...) from_string (hex): Set the user name   DESCRIPTION   Sets correlator value from its hexadecimal representation.     This is useful for correlators passed into the application from an external source, such as   the Apache web server. PARAMETERS   hex   A string containing a hexadecimal representation of a correlator. This is the same         as produced by str(). RETURN VALUE   None get_flags(...) get_flags(flags): get value of flag   DESCRIPTION   get_flags() returns the value of a specified flag in the correlator.     A correlator contains bit flags, and get_flags() is used to test the value of   those flags. See generate_correlator() for a description of a correlator. PARAMETERS   flags     An enumerated value that indicates which flag's value is requested. The             enumerated values are:             ARM_CORR_FLAGNUM_APP_TRACE = Application trace flag             ARM_CORR_FLAGNUM_AGENT_TRACE = Agent trace flag RETURN VALUE   Boolean object indicating whether the flag is set. length(...) length(): get length of correlator   DESCRIPTION   length() returns the length of a correlator, based on the length field within   the correlator header. Note that this length is not necessarily the length of the   buffer containing the correlator.     A correlator header contains a length field. length() is used to return the length. The function   handles any required conversion from the network byte order used in the header and the endian   (big versus little) of the platform. See generate_correlator() for a description of a correlator. PARAMETERS   None RETURN VALUE   The length of the correlator Data and other attributes defined here: __new__ = <built-in method __new__ of type object> T.__new__(S, ...) -> a new object with type S, a subtype of T   class ArmHandle(__builtin__.object)     Opaque wrapper for an ARM 4 handle structure.     Data and other attributes defined here: __new__ = <built-in method __new__ of type object> T.__new__(S, ...) -> a new object with type S, a subtype of T   class ArmID(__builtin__.object)     Opaque wrapper for an ARM 4 ID structure.     Data and other attributes defined here: __new__ = <built-in method __new__ of type object> T.__new__(S, ...) -> a new object with type S, a subtype of T   class ArmSubbufferAppContext(__builtin__.object)     Applications are identified by a name and an optional set of identity attribute (name,value) pairs. Application instances are further identified by an optional set of context (name,value) pairs. These properties could indicate something about the runtime instance of the application, such as the instance identifier and the name of a configuration file used.   The optional context property names are provided in the application identity sub-buffer on the register_application() call. The optional context property values are provided in this sub- buffer on the start_application() call. The sub-buffer is ignored if it is passed on any other call.   Context Values   The values in the array are position-sensitive; each must align with the corresponding context   property name in the application identity sub-buffer. If the corresponding property name string   is zero-length, the value is ignored.     Each array element contains:   o   Value: A string representing the value part of the (name,value) pair. Each string has a maximum           length of 255 characters. If any string is zero-length, the meaning is that there is no value           for this instance. The value should not contain trailing blank characters or consist of only           blank characters.     Methods defined here: set_context_value(...) set_context_value(index, value): Set an application context value   DESCRIPTION   set_context_value() sets the value in the specified index. PARAMETERS   index     The array index of a property value between 0 and 19               The values in the array are position-sensitive; each must align with the corresponding context             property name in the application identity sub-buffer. If the corresponding property name string             is zero-length, the value is ignored.   name      A string representing the name part of the (name,value) pair. Each string has a maximum             length of 255 characters. If any string is zero-length, the meaning is that there is no value             for this instance. The value should not contain trailing blank characters or consist of only             blank characters. RETURN VALUE   None Data and other attributes defined here: __new__ = <built-in method __new__ of type object> T.__new__(S, ...) -> a new object with type S, a subtype of T   class ArmSubbufferAppIdentity(__builtin__.object)     Applications are identified by a name and an optional set of identity attribute (name,value) pairs. Application instances are further identified by an optional set of context (name,value) pairs. The optional context property names are provided in this sub-buffer on the register_application() call. The optional context property values are provided on the start_application() call. The sub-buffer is ignored if it is passed on any other call.   The names of identity and context properties can be any string, with one exception. Strings beginning with the four characters "ARM:" are reserved for the ARM specification. The specification will define names with known semantics using this prefix. One name format is currently defined. Any name beginning with the eight-character prefix "ARM:CIM:" represents a name defined using the DMTF CIM (Distributed Management Task Force Common Information Model) naming rules. For example, "ARM:CIM:CIM_SoftwareElement.Name" indicates that the property value has the semantics of the Name property of the CIM_SoftwareElement class. It is anticipated that additional naming semantics are likely to be added in the future.   Identity Properties   The array index of a property value in the value array is bound to the property name at the   same index in the name array. Moving the (name,value) pair to a different index does not   affect the identity of the application. For example, if an application registers once with a   name A and a value X in array indices 0 and once with the same name and value in array   indices 1, the registered identity has not changed.     If a name is repeated in the array, the name and its corresponding value are ignored, and   the first instance of the name and value in the array is used. The implementation may   return an error code but is not obliged to do so.     Each structure contains:   o   Name: A string representing the name part of the (name,value) pair. Each string has a maximum           length of 127 characters. If the string is zero-length, the (name,value) pair is ignored.           Names should not contain trailing blank characters or consist of only blank characters.   o   Value: A string representing the value part of the (name,value) pair. Each string has a maximum           length of 255 characters. If the string is zero-length, the (name,value) pair is ignored.           Values should not contain trailing blank characters or consist of only blank characters.   Context Properties   If a name is repeated in the array, the name and its corresponding value (in the application   context sub-buffer) are ignored, and the first instance of the name in the array (and its   corresponding value) is used. The implementation may return an error code but is not   obliged to do so.     Each array element contains:   o   Name: A string representing the name part of the (name,value) pair. Each string has a maximum               length of 127 characters. If the string is zero-length, the (name,value) pair is ignored.               The values are provided in the ArmSubbufferApplicationContext object. Names should not contain               trailing blank characters or consist of only blank characters.     Methods defined here: set_context_name(...) set_context_name(index, name): Set an application context name   DESCRIPTION   set_context_name() sets the name in the specified index. PARAMETERS   index     The array index of a property value between 0 and 19               If a name is repeated in the array, the name and its corresponding value (in the application             context sub-buffer) are ignored, and the first instance of the name in the array (and its             corresponding value) is used.   name      A string representing the name part of the (name,value) pair. Each string has a maximum             length of 127 characters. If the string is zero-length, the (name,value) pair is ignored.             The values are provided in the ArmSubbufferApplicationContext object. Names should not contain             trailing blank characters or consist of only blank characters. RETURN VALUE   None set_property(...) set_property(index, name, value): Set an application identity name/value pair   DESCRIPTION   set_property() sets the name/value pair in the specified index. PARAMETERS   index     The array index of a property value between 0 and 19             The array index of a property value in the value array is bound to the property name at the             same index in the name array. Moving the (name,value) pair to a different index does not             affect the identity of the application. For example, if an application registers once with a             name A and a value X in array indices 0 and once with the same name and value in array             indices 1, the registered identity has not changed.   name      A string representing the name part of the (name,value) pair. Each string has a maximum             length of 127 characters. If the string is zero-length, the (name,value) pair is ignored.             Names should not contain trailing blank characters or consist of only blank characters.   value     A string representing the value part of the (name,value) pair. Each string has a maximum             length of 255 characters. If the string is zero-length, the (name,value) pair is ignored.             Values should not contain trailing blank characters or consist of only blank characters. RETURN VALUE   None Data and other attributes defined here: __new__ = <built-in method __new__ of type object> T.__new__(S, ...) -> a new object with type S, a subtype of T   class ArmSubbufferArrivalTime(__builtin__.object)     Some applications may start processing a transaction before all the context information that identifies the transaction is known. For example, it might by necessary to retrieve the context information as the first step in processing the transaction. For these cases, the application can call get_arrival_time() to receive a timestamp value for the current time from the ARM implementation. This timestamp value is known as the "arrival time". When the transaction context data is all known, start_transaction() is called, passing the optional arrival time value in a sub-buffer, to indicate when the transaction actually started executing. The arrival time is provided in this sub-buffer.   The arrival time field is an ArmArrivalTime object containing the value returned by the get_arrival_time() function.     Methods defined here: set_arrival_time(...) set_arrival_time(arrival_time): Sets the transaction arrival time   DESCRIPTION   set_arrival_time() sets the arrival time for the transaction. PARAMETERS   arrival_time  an ArmArrivalTime object containing the value returned by the                 get_arrival_time() function. RETURN VALUE   None Data and other attributes defined here: __new__ = <built-in method __new__ of type object> T.__new__(S, ...) -> a new object with type S, a subtype of T   class ArmSubbufferCharset(__builtin__.object)     Applications may specify on register_application() the character set encoding for all strings passed by the application. An ARM library must support certain encodings, depending on the platform (see Table 1). The application may always use one of the mandatory encodings. This module defines names of the form ARM_CHARSET_* for all the mandatory encodings. The application may optionally ask the ARM library if another encoding is supported using is_charset_supported().   When the application registers with register_application(), it may optionally provide the character set encoding sub-buffer. In the sub-buffer, the application specifies the MIBenum value of a character set encoding that has been assigned by the IANA (Internet Assigned Numbers Authority - see www.iana.org). The MIBenum value in the sub-buffer should only be either a mandatory encoding for the platform or a MIBenum value for which support has been verified using is_charset_supported().   The list of supported encodings must restrict itself to those that do not contain any embedded null bytes. Exceptions are permitted for character sets that have fixed-length characters (e.g., two bytes) and that do not allow a character of all zeros (e.g., 0x0000). These include UTF- 16LE, UTF-16BE, and UTF-16 (MIBenum values 1013, 1014, 1015). For these encodings, there will be a convention that a character of all zeros is the null-termination character.     Methods defined here: __init__(...) x.__init__(...) initializes x; see x.__class__.__doc__ for signature Data and other attributes defined here: __new__ = <built-in method __new__ of type object> T.__new__(S, ...) -> a new object with type S, a subtype of T   class ArmSubbufferDiagDetail(__builtin__.object)     When a transaction completion is reported with stop_transaction() or report_transaction(), and the transaction status is not ARM_STATUS_GOOD, the application may provide a character string containing any arbitrary diagnostic data. The string may not be longer than 4095 characters. For example,the application might provide the SQL query text for a failing database transaction.     Methods defined here: set_detail(...) set_detail (detail): Set the diagnostic detail string   DESCRIPTION   set_detail() sets the diagnostic detail string. PARAMETERS   detail    A string containing the diagnostic data. Each string has a maximum length             of 4095 characters. RETURN VALUE   None Data and other attributes defined here: __new__ = <built-in method __new__ of type object> T.__new__(S, ...) -> a new object with type S, a subtype of T   class ArmSubbufferMetricBindings(__builtin__.object)     Applications may provide additional data about a transaction when the transaction starts, while it is executing, and/or after it has stopped. This additional data may serve several purposes, such as indicating the size of a transaction (e.g., the number of bytes in a file for a file transfer transaction), the state of the system (e.g., the number of queued up transactions when this transaction arrived), or an error code. The metadata describing each metric is provided with the register_metric() function.   Each transaction definition may define zero to seven metrics for which data values may be provided on start_transaction(), update_transaction(), stop_transaction(), or report_transaction(). Each metric is assigned to an array slot numbered 0 to 6 (they were numbered 1 to 7 in ARM 2.0). This sub-buffer is passed on the register_transaction() function to indicate which metrics are assigned to which slots.   Metric Bindings   An array of ArmID objects containing the metric bindings.     Each structure contains:   o   Slot number: A byte slot number. Valid values are 0 to 6. If a slot number is repeated,           the first time it appears is the only one processed; all others are ignored.   o   ID: An ArmID object for this metric definition. The ID must have been previously returned from           register_metric().     Methods defined here: bind(...) bind(index, metric_id): Set a transaction context value   DESCRIPTION   bind() binds a metric to the specified index. PARAMETERS   index     The array index of a metric between 0 and 7   metric_id An ArmID object for this metric definition. The ID must have been previously returned from             register_metric(). RETURN VALUE   None Data and other attributes defined here: __new__ = <built-in method __new__ of type object> T.__new__(S, ...) -> a new object with type S, a subtype of T   class ArmSubbufferMetricValues(__builtin__.object)     The buffer is used to pass metric values on any of start_transaction(), update_transaction(), stop_transaction(), and report_transaction().   Metric Values   Each structure is in the following format:   o   Slot number: A single-byte slot number. Valid values are 0 to 6. The slot number           must be the same as the corresponding entry in the metric bindings sub-buffer. Each           slot number should be used at most once; if a slot number is reused, the first entry is           used and all others are ignored.   o   Metric format: A single-byte format indicator. Valid values are 1 to 10 and are the           same as ARM 2.0. Only values 1 to 8 are valid in slots 0-5. Only value 10 is valid in           slot 6. This is a carry-over from ARM 2.0. The format must be the same as the           corresponding entry in the metric bindings sub-buffer.             1 (ARM_METRIC_FORMAT_COUNTER32) = arm_int32_t counter           2 (ARM_METRIC_FORMAT_COUNTER64) = arm_int64_t counter           3 (ARM_METRIC_FORMAT_CNTRDIVR32) = arm_int32_t counter + arm_int32_t divisor           4 (ARM_METRIC_FORMAT_GAUGE32) = arm_int32_t gauge           5 (ARM_METRIC_FORMAT_GAUGE64) = arm_int64_t gauge           6 (ARM_METRIC_FORMAT_GAUGEDIVR32) = arm_int32_t gauge + arm_int32_t divisor           7 (ARM_METRIC_FORMAT_NUMERICID32) = arm_int32_t numeric ID           8 (ARM_METRIC_FORMAT_NUMERICID64) = arm_int64_t numeric ID           9 = (DEPRECATED)           10 (ARM_METRIC_FORMAT_STRING32) = string of a maximum length of 32 characters   o   Usage: An arm_metric_usage_t indicating how the metric is used. The usage must           be the same as the usage parameter passed on the register_metric() call that           registered the metric ID with the same slot number that is in the metric bindings sub-           buffer.             0 (ARM_METRIC_USE_GENERAL) = no usage is declared           1 (ARM_METRIC_USE_TRAN_SIZE) = the metric indicates the transaction size (e.g., the size                 of a file or the number of jobs in a network backup operation)           2 (ARM_METRIC_USE_TRAN_STATUS) = the metric is a status code (numeric ID) or text message                 (string). It would typically be used with stop_transaction() or report_transaction()                 to provide additional details about a transaction status of Failed.           3:32767 = Reserved.           -32768:-1 = available for implementation-defined purposes.   o   Valid flag: A boolean that indicates whether the data in the metric value field is           currently valid.   o   Metric value: A metric value where the data type matches the metric format indicator (above).     Methods defined here: set_value(...) set_value(slot, format, usage, value): Set a single numeric value set_value(slot, format, usage, value, divisor): Set a value with a divisor set_value(slot, usage, string_value): Set a string value   DESCRIPTION   set_value() sets a metric value for the specified slot. PARAMETERS   slot      The array index of a metric between 0 and 7   format    A single-byte format indicator. Valid values are 1 to 8 and are the             same as ARM 2.0. Only values 1 to 8 are valid in slots 0-5. Only value 10 is valid in             slot 6. This is a carry-over from ARM 2.0. The format must be the same as the             corresponding entry in the metric bindings sub-buffer. This is not required for a string             value.               1 (ARM_METRIC_FORMAT_COUNTER32) = arm_int32_t counter             2 (ARM_METRIC_FORMAT_COUNTER64) = arm_int64_t counter             3 (ARM_METRIC_FORMAT_CNTRDIVR32) = arm_int32_t counter + arm_int32_t divisor             4 (ARM_METRIC_FORMAT_GAUGE32) = arm_int32_t gauge             5 (ARM_METRIC_FORMAT_GAUGE64) = arm_int64_t gauge             6 (ARM_METRIC_FORMAT_GAUGEDIVR32) = arm_int32_t gauge + arm_int32_t divisor             7 (ARM_METRIC_FORMAT_NUMERICID32) = arm_int32_t numeric ID             8 (ARM_METRIC_FORMAT_NUMERICID64) = arm_int64_t numeric ID   usage     An arm_metric_usage_t indicating how the metric is used. The usage must             be the same as the usage parameter passed on the register_metric() call that             registered the metric ID with the same slot number that is in the metric bindings sub-             buffer.               0 (ARM_METRIC_USE_GENERAL) = no usage is declared             1 (ARM_METRIC_USE_TRAN_SIZE) = the metric indicates the transaction size (e.g., the size                 of a file or the number of jobs in a network backup operation)             2 (ARM_METRIC_USE_TRAN_STATUS) = the metric is a status code (numeric ID) or text message                 (string). It would typically be used with stop_transaction() or report_transaction()                 to provide additional details about a transaction status of Failed.             3:32767 = Reserved.             -32768:-1 = available for implementation-defined purposes.   value     A metric value where the data type matches the metric format indicator (above).   divisor   A divisor as required by the ARM_METRIC_FORMAT_CNTRDIVR and ARM_METRIC_FORMAT_GAUGEDIVR32 formats.   string_value             A 32 character string. For this value type, a format of ARM_METRIC_FORMAT_STRING32 is assumed. RETURN VALUE   None Data and other attributes defined here: __new__ = <built-in method __new__ of type object> T.__new__(S, ...) -> a new object with type S, a subtype of T   class ArmSubbufferSystemAddress(__builtin__.object)     The system address sub-buffer is used with start_application() when the transactions that will be reported execute on a different system than the one on which they will be reported.     o   If no system address sub-buffer is provided on start_application(), all transactions           reported by this application instance execute in the current process.   o   If a system address sub-buffer is provided on start_application(), all transactions           execute in a different process.   o   If a system address sub-buffer is provided in which the system address length is zero, or           the system address pointer is null, the system is the local system, as determined by the           ARM implementation.   o   If a system address sub-buffer is provided in which there is a non-null system address and           length, the system may be the local system or a remote system. Interpretation of what is           local versus remote is at the discretion of the ARM implementation.   Address Formats   The following formats are defined:   o   0 = Reserved.   o   1 (ARM_SYSADDR_FORMAT_IPV4) = IPv4           Bytes 0:3 = 4-byte IP address   o   2 (ARM_SYSADDR_FORMAT_IPV4PORT) = IPv4 + port number           Bytes 0:3 = 4-byte IP address           Bytes 4:5 = 2-byte IP port number   o   3 (ARM_SYSADDR_FORMAT_IPV6) = IPv6           Bytes 0:15 = 16-byte IP address   o   4 (ARM_SYSADDR_FORMAT_IPV6PORT) = IPv6 + port number           Bytes 0:15 = 16-byte IP address           Bytes 16:17 = 2-byte IP port number   o   5 (ARM_SYSADDR_FORMAT_SNA) = SNA           Bytes 0:7 = EBCDIC-encoded network ID           Bytes 8:15 = EBCDIC-encoded network accessible unit (control point or LU)   o   6 (ARM_SYSADDR_FORMAT_X25) = X.25           Bytes 0:15 = The X.25 address (also referred to as an X.121 address). This is up to 16           ASCII character digits ranging from 0-9.   o   7 (ARM_SYSADDR_FORMAT_HOSTNAME) = hostname (characters, not null-terminated)           Bytes 0:?? = hostname   o   8 (ARM_SYSADDR_FORMAT_UUID) = Universally-unique ID           Bytes 0:15 = UUID in binary. This is useful for applications that define their system           by a UUID rather than a network address or hostname or some other address form.   o   9:32767 = Reserved.   o   -32768:-1 = Available for implementation-defined use.             There are no semantics associated with the address format. It will be an unusual           situation where a new format is needed, but this provides a solution if this is needed.           The preferred approach is to get a new format defined that is in the 0-32767 range.           There is a risk that two different agent developers will choose the same ID, but this           risk is deemed small.   Address Length   An 16 bit integer length of system address in bytes.   o   There is no maximum length.   o   A length of zero refers to the local system.     Methods defined here: set_hostname(...) set_hostname (name): Set the system hostname   DESCRIPTION   set_hostname() sets the system address with a host name. PARAMETERS   name   A string giving the hostname. RETURN VALUE   None set_local(...) set_local (): Set the system address to be the local host   DESCRIPTION   set_local() sets the system address to be the local host. PARAMETERS   None RETURN VALUE   None Data and other attributes defined here: __new__ = <built-in method __new__ of type object> T.__new__(S, ...) -> a new object with type S, a subtype of T   class ArmSubbufferTranContext(__builtin__.object)     In addition to the identity properties, a transaction may be described with additional context properties. Context properties differ from identity properties in that although the name is provided when the transaction is registered [register_transaction()], the values are provided when a transaction is measured [start_transaction() or report_transaction()]. The value of an identity property never changes, whereas the value of a context property may change every time a transaction executes.   Context properties are of two forms. There may be one URI value and up to twenty (name,value) pairs. No name may duplicate the name of a transaction identity property.   Context Values   An array strings containing the property values. The values in the array are position-sensitive;   each must align with the corresponding context property name in the ArmSubbufferTranIdentity   object. If the corresponding property name is a zero-length string, the value is ignored.     Each array element contains:   o   Value: A string representing the value part of the (name,value) pair. Each string has a maximum           length of 255 characters. If any string is zero-length, the meaning is that there is no value           for this instance. Values should not contain trailing blank characters or consist of only           blank characters.   URI   A string containing a URI, with a maximum of 4095 characters.     If a URI is provided in both the transaction identity sub-buffer and in the transaction   context sub-buffer, the URI in the transaction identity sub-buffer must be the same as the   URI provided in the transaction context sub-buffer, or a truncated subset.     Methods defined here: set_context_value(...) set_context_value(index, value): Set a transaction context value   DESCRIPTION   set_context_value() sets the value in the specified index. PARAMETERS   index     The array index of a property value between 0 and 19               If a value is repeated in the array, the value and its corresponding value (in the transaction             context sub-buffer) are ignored, and the first instance of the value in the array (and its             corresponding value) is used.   value     A string representing the value part of the (name,value) pair. Each string has a maximum             length of 255 characters. If the string is zero-length, the (name,value) pair is ignored. RETURN VALUE   None set_uri(...) set_uri(uri): Set a transaction uri   DESCRIPTION   set_uri() sets the uri for the transaction. PARAMETERS   uri       A string representing the the uri of the transaction. This string has a maximum             length of 4095 characters. If the string is zero-length, the uri is ignored. RETURN VALUE   None Data and other attributes defined here: __new__ = <built-in method __new__ of type object> T.__new__(S, ...) -> a new object with type S, a subtype of T   class ArmSubbufferTranIdentity(__builtin__.object)     Transactions are identified by a name, an optional URI value, and an optional set of attribute (name,value) pairs. The URI and optional (name,value) pairs are provided in this sub-buffer on the register_transaction() call. The sub-buffer is ignored if it is passed on any other call. The identity is scoped to a single application.   The names of identity and context properties can be any string, with one exception. Strings beginning with the four characters "ARM:" are reserved for the ARM specification. The specification will define names with known semantics using this prefix. One name format is currently defined. Any name beginning with the eight-character prefix "ARM:CIM:" represents a name defined using the DMTF CIM (Distributed Management Task Force Common Information Model) naming rules. For example, "ARM:CIM:CIM_SoftwareElement.Name" indicates that the property value has the semantics of the Name property of the CIM_SoftwareElement class. It is anticipated that additional naming semantics are likely to be added in the future.   Idenitity Properties   The array index of a property value in the value array is bound to the property name at the   same index in the name array. Moving the (name,value) pair to a different index does not   affect the identity of the transaction. For example, if an application is registered once with   a name A and a value X in array indices 0 and once with the same name and value in array   indices 1, the registered identity has not changed.     If a name is repeated in the array, the name and its corresponding value (in the transaction   context sub-buffer) are ignored, and the first instance of the name in the array (and its   corresponding value) is used. The implementation may return an error code but is not   obliged to do so.     Each structure contains:   o   Name: A string representing the name part of the (name,value) pair. Each string has a maximum           length of 127 characters. If the string is zero-length, the (name,value) pair is ignored.           Names should not contain trailing blank characters or consist of only blank characters.   o   Value: A string representing the value part of the (name,value) pair. Each string has a maximum           length of 255 characters. If the string is zero-length, the (name,value) pair is ignored.           Values should not contain trailing blank characters or consist of only blank characters.   Context Properties   An array of strings, each containing a context property name. Each array element is a string   representing the name part of the (name,value) pair. Each string has a maximum length of 127   characters. The name is passed on register_transaction().     If a name is repeated in the array, the name and its corresponding value (in the transaction   context sub-buffer) are ignored, and the first instance of the name in the array (and its   corresponding value) is used     Each array element contains:   o   Name: A string representing the name part of the (name,value) pair. Each string has a maximum               length of 127 characters. If the string is zero-length, the (name,value) pair is ignored.           The values are provided in the ArmSubbufferTransactionContext object. Names should not           contain trailing blank characters or consist of only blank characters.   URI   A string containing a URI, with a maximum of 4095 characters.     Methods defined here: set_context_name(...) set_context_name(index, name): Set a transaction context name   DESCRIPTION   set_context_name() sets the name in the specified index. PARAMETERS   index     The array index of a property value between 0 and 19               If a name is repeated in the array, the name and its corresponding value (in the transaction             context sub-buffer) are ignored, and the first instance of the name in the array (and its             corresponding value) is used.   name      A string representing the name part of the (name,value) pair. Each string has a maximum             length of 127 characters. If the string is zero-length, the (name,value) pair is ignored.             The values are provided in the ArmSubbufferTranContext object. Names should not contain             trailing blank characters or consist of only blank characters. RETURN VALUE   None set_property(...) set_property(index, name, value): Set a transaction identity name/value pair   DESCRIPTION   set_property() sets the name/value pair in the specified index. PARAMETERS   index     The array index of a property value between 0 and 19               The array index of a property value in the value array is bound to the property name at the             same index in the name array. Moving the (name,value) pair to a different index does not             affect the identity of the transaction. For example, if a transaction registers once with a             name A and a value X in array indices 0 and once with the same name and value in array             indices 1, the registered identity has not changed.   name      A string representing the name part of the (name,value) pair. Each string has a maximum             length of 127 characters. If the string is zero-length, the (name,value) pair is ignored.             Names should not contain trailing blank characters or consist of only blank characters.   value     A string representing the value part of the (name,value) pair. Each string has a maximum             length of 255 characters. If the string is zero-length, the (name,value) pair is ignored.             Values should not contain trailing blank characters or consist of only blank characters. RETURN VALUE   None set_uri(...) set_uri(uri): Set a transaction uri   DESCRIPTION   set_uri() sets the uri for the transaction. PARAMETERS   uri       A string representing the the uri of the transaction. This string has a maximum             length of 4095 characters. If the string is zero-length, the uri is ignored. RETURN VALUE   None Data and other attributes defined here: __new__ = <built-in method __new__ of type object> T.__new__(S, ...) -> a new object with type S, a subtype of T   class ArmSubbufferUser(__builtin__.object)     A user name and/or ID may be optionally associated with each transaction instance. A name is a character string. An ID is a 16-byte binary value, such as a UUID. Either or both may be provided.     Methods defined here: set_user(...) set_user (name): Set the user name   DESCRIPTION   Sets the user name. PARAMETERS   name   A string with a maximum length of 127 characters. RETURN VALUE   None Data and other attributes defined here: __new__ = <built-in method __new__ of type object> T.__new__(S, ...) -> a new object with type S, a subtype of T   class error(exceptions.Exception)       Methods inherited from exceptions.Exception: __getitem__(...) __init__(...) __str__(...)

Functions
		bind_thread(...) bind_thread(tran_handle): bind thread   DESCRIPTION   bind_thread() indicates that the thread from which it is called is performing on behalf of   the transaction identified by the start handle.   The thread binding could be useful for managing computing resources at a finer level of   granularity than a process. There can be any number of threads simultaneously bound to the   same transaction.   A transaction remains bound to a thread until either a _discard_transaction(),   stop_transaction(), or unbind_thread() is executed passing the same start handle.   bind_thread() and block_transaction() are used independently of each other. PARAMETERS   tran_handle   A handle returned a start_transaction() call in the same process. RETURN VALUE   None. block_transaction(...) block_transaction(tran_handle): block transaction   DESCRIPTION   block_transaction() is used to indicate that the transaction instance is blocked waiting on   an external transaction (which may or may not be instrumented with ARM) or some other event   to complete. It has been found useful to separate out this blocked time from the elapsed time   between the start_transaction() and stop_transaction().   A transaction remains blocked until unblock_transaction() is executed passing the same   block_handle, or either a discard_transaction() or stop_transaction() is executed passing the   same tran_handle.   The blocking conditions of most interest are those that could result in a significant and/or   variable length delay relative to the response time of the transaction. For example, a remote   procedure call would be a good situation to indicate with block_transaction() or   unblock_transaction(), whereas a disk I/O would not.   A transaction may be blocked by multiple conditions simultaneously. In many application   architectures block_transaction() would be called just prior to a thread suspending, because   the thread is waiting to be signaled that an event has occurred. In other application architectures   there would not be a tight relationship between the thread behavior and the blocking conditions.   bind_thread() and block_transaction() are used independently of each other. PARAMETERS   tran_handle   An ArmHandle object returned from an start_transaction() call in the same process. RETURN VALUE   block_handle  An ArmHandle object that is passed on to unblock_transaction() calls in the same                 process. destroy_application(...) destroy_application(app_id): destroy application data   DESCRIPTION   destroy_application() indicates that the registration data about an application previously   registered with register_application() is no longer needed.   The purpose of this call is to signal the ARM implementation so it can release any storage it is   holding. Ending a process or unloading the ARM library results in an implicit   destroy_application() for any previously registered applications.   It is possible for multiple register_application() calls to be made in the same process with   identical identity data. When this is done, destroy_application() is assumed to be paired   with one register_application(). For example, if register_application() is executed   twice with the same output ID, and destroy_application() is executed once using this ID, it   is assumed that an instance of the application is still active and it is not safe to discard the   application registration data associated with the ID. PARAMETERS   app_id        ArmID object returned from a register_application() call in the same                 process. RETURN VALUE   None discard_transaction(...) discard_transaction(tran_handle): discard transaction   DESCRIPTION   discard_transaction() signals that the referenced start_transaction() should be   ignored and treated as if it never happened. Measurements associated with a transaction that is   processing should be discarded. Either discard_transaction() or stop_transaction() is   used - never both.   An example of when a transaction would be discarded could happen is if proxy instrumentation   believes a transaction is starting, but then learns that it did not. It can be called from any thread   in the process that executed the start_transaction(). In general, the use of   discard_transaction() is discouraged, but experience has shown a few use cases that   require the functionality.   discard_transaction() clears any thread bindings [bind_thread()] and blocking   conditions [block_transaction()]. PARAMETERS   tran_handle   A handle returned from an start_transaction() call in the same process. RETURN VALUE   None enable_exceptions(...) enable_exceptions(enable): enable exception generation   DESCRIPTION   enable_exceptions() is used to control the generation of exceptions by the arm4 module. One of   the key principles of the ARM standard is that errors in the measurement of applications shouldn't   affect the applications themselves. In the Python world, this means that no exceptions should   be generated when the ARM routines encounter an error. Unfortunately this can make debugging   difficult.     To give the programmer/developer the best of both worlds, exception processing can be turned on   or off programatically. When debugging the instrumentation, it is best to have the exceptions   turned on, while production dictates that no exceptions be generated.     By default, exception generation is turned off. PARAMETERS   enable       A integer boolean value indicating wether exceptions should be generated. RETURN VALUE   None. generate_correlator(...) generate_correlator(app_handle, tran_id, [parent, flags, buffer]): generate a correlator   DESCRIPTION   generate_correlator() is used to generate a correlator for use with report_transaction().     A correlator is a correlation token passed from a calling transaction to a called transaction. The   correlation token may be used to establish a calling hierarchy across processes and systems.   Applications do not need to understand correlator internals.     It is useful to think about its use in the context of what start_transaction() and   stop_transaction() do:   o      start_transaction() performs two functions. It establishes the identity of a transaction          instance (encapsulated in the current correlator) and begins the measurements of the          instance. stop_transaction() causes the measurements to be captured. The start          handle links a start_transaction() and a stop_transaction().   o      generate_correlator() establishes the identity of a transaction instance, like          start_transaction(), also encapsulating it in a correlator. It has no relationship to          measurements about the transaction instance. report_transaction() combines the          measurement function of both start_transaction() and stop_transaction().     Based on this positioning, it should be clear that generate_correlator() can be used   whenever an start_transaction() can be used. More specifically, the following calls must   have been executed first: register_application(), register_transaction(), and   start_application(). The same parameters are also used, except there's no need for a start   handle, and there's no need for the arrival time or metric values sub-buffers. The other sub-   buffers may be used. The correlator that is returned can be used in the same way that a correlator   returned from start_transaction() is used. PARAMETERS   app_handle The ArmHandle object returned from a start_application() call in the same process. The              ARM implementation may use this handle to access application instance data that              may become part of the correlator; e.g., the ArmSubbufferSystemAddress object.   buffer     The ArmBuffer object, if any. The sub-buffers that may be used are              ArmSubbufferTranContext, and ArmSubbufferUser.   flags      Contains 32-bit flags. The may be or'ed together as required.              ARM_FLAG_TRACE_REQUEST is specified if the application requests/suggests a trace.              ARM_FLAG_CORR_IN_PROCESS is specified if the application is stating that it will not                     send the correlator outside the current process. An ARM implementation may be                     able to optimize correlator handling if it knows this, because it may be able                     to avoid serialization to create the correlator.   parent_correlator              An ArmCorrelator object refferring to the parent correlator, if any.   tran_id    An ArmID transaction ID returned from a register_transaction() call in the same process. RETURN VALUE              A ArmCorrelator object which contains a correlator for the transaction instance. get_arrival_time(...) get_arrival_time(): store current time   DESCRIPTION   get_arrival_time() stores an opaque representation of the current time.     There are situations in which there is a significant delay between the time when processing of a   transaction begins and when all the context property values that are needed before   start_transaction() can be executed are known. In order to get a more accurate response   time, get_arrival_time() can be used to capture an implementation-defined representation   of the current time. This value is later stored in the ArmSubbufferArrivalTime sub-buffer when   start_transaction() executes. The ARM library will use the arrival time as the start time   rather than the moment when start_transaction() executes. PARAMETERS   None RETURN VALUE   An ArmArrivalTime object that will contain the arrival time value. Note that the   value is implementation-defined so the application should not make any   conclusions based on its contents. is_charset_supported(...) is_charset_supported(charset): check character encoding   DESCRIPTION   is_charset_supported() indicates whether an ARM library supports a specified character   encoding.     The default encoding for all strings provided by the application on all operating systems is   UTF-8. An application may specify an alternate encoding when executing register_application(),   and then use it for all strings it provides on all calls including register_application(), but   should never do so without first issuing is_charset_supported() to test whether the value is   supported.     An ARM library on the operating systems listed in Table 1 must support the specified   encodings. Applications are encouraged to use one of these encodings to ensure that any ARM   implementation will support the application's ARM instrumentation. Another alternative is to   use one of these encodings along with a preferred encoding. If the ARM library supports the   preferred encoding, it is used; otherwise, one of the mandatory encodings is used.     IANA                                  Character Set Common       UNIX     Microsoft   IBM      IBM   MIBenum                                      Name                 and      Windows   OS/400    zOS                                                                    Linux      3       ARM_CHARSET_ASCII             ASCII-7 (US-ASCII)         Yes      Yes         Yes      Yes      106     ARM_CHARSET_UTF8              UTF-8                      Yes      Yes         Yes      Yes                                          (UCS-2 characters only)      1014    ARM_CHARSET_UTF16LE           UTF-16 Little Endian                Yes                                          (UCS-2 characters only)      2028    ARM_CHARSET_IBM037            IBM037                                          Yes      2102    ARM_CHARSET_IBM1047           IBM1047                                                  Yes   PARAMETERS   charset      An IANA (Internet Assigned Numbers Authority - see http://www.iana.org) MIBenum                value. Support for some values is mandatory by any ARM implementation on a                specified platform, as shown in the table. RETURN VALUE   Boolean object that is set to true or false to indicate whether charset is a supported encoding. register_application(...) register_application(app_name, [buffer]): describe application   DESCRIPTION   register_application() describes metadata about an application.     The application uses register_application() to inform the ARM library of metadata about   the application. This metadata does not change from one application instance to another. It   contains part of the function of the ARM 2.0 call arm_init(); start_application() contains   the other part.     ARM generates an ID that is passed in register_transaction() and start_application(). PARAMETERS   app_name     Pointer to a null-terminated string containing the name of the application. The                maximum length of the name is 128 characters, including the termination character.                It serves no purpose and is illegal to make this call if the pointer is null. A name                should be chosen that is unique, so generic names that might be used by a different                development team, such as "Payroll Application", should not be used. The name                should not contain trailing blank characters or consist of only blank characters. If                the application has a copyrighted product name, the copyrighted name would be a                good choice.   buffer       An ArmBuffer object, if any. The sub-buffer formats that might be used are                ArmSubbufferAppIdentity and ArmSubbufferEncoding. RETURN VALUE   An ArmID object app_id. register_metric(...) register_metric(app_id, name, format, usage, [units]): describe metrics   DESCRIPTION   register_metric() describes metadata about a metric.     The application uses register_metric() to inform the ARM library of metadata about each   metric the application provides.     ARM generates an ArmID object that is passed in the ArmSubbufferMetricBindings object   to register_transaction(). PARAMETERS   app_id       ArmID object returned from a register_application() call in the same process.   format       Describes the data type. The value must be one of the following values.                      ARM_METRIC_FORMAT_COUNTER32) = arm_int32_t counter                      ARM_METRIC_FORMAT_COUNTER64) = arm_int64_t counter                      ARM_METRIC_FORMAT_CNTRDIVR) = arm_int32_t counter + arm_int32_t divisor                      ARM_METRIC_FORMAT_GAUGE32) = arm_int32_t gauge                      ARM_METRIC_FORMAT_GAUGE64) = arm_int64_t gauge                      ARM_METRIC_FORMAT_GAUGEDIVR32) = arm_int32_t gauge + arm_int32_t divisor                      ARM_METRIC_FORMAT_NUMERICID32) = arm_int32_t numeric ID                      ARM_METRIC_FORMAT_NUMERICID64) = arm_int64_t numeric ID                      ARM_METRIC_FORMAT_STRING32) = string of a maximum length of 32 characters   name         A string containing the name of the metric. The maximum length of the string is                127 characters. The name should not contain trailing blank characters or consist                of only blank characters.                  The name can be any string, with one exception. Strings beginning with the four                characters "ARM:" are reserved for the ARM specification. The specification will                define names with known semantics using this prefix. One name format is currently                defined. Any name beginning with the eight character prefix "ARM:CIM:"                represents a name defined using the DMTF CIM (Distributed Management Task                Force Common Information Model) naming rules. For example,                "ARM:CIM:CIM_SoftwareElement.Name" indicates that the metric value has the                semantics of the Name property of the CIM_SoftwareElement class. It is anticipated                that additional naming semantics are likely to be added in the future.   units        Pointer to a null-terminated string containing the units (such as "files transferred")                of the metric. The maximum length of the string is 127 characters   usage        Describes how the metric is used. The value must be one of the following values, or                a negative value (any negative value is specific to the application; the negative                values are not expected to be widely used).                     ARM_METRIC_USE_GENERAL = a metric without a specified usage. Most                                              metrics are described with a GENERAL usage.                     ARM_METRIC_USE_TRAN_SIZE = a metric that indicates the size of a transaction. The size                                              is something that would be expected to affect the response                                              time, such as the number of bytes in a file transfer or the                                              number of files backed up by a backup transaction. ARM                                              implementations can use this knowledge to better                                              interpret the response time.                     ARM_METRIC_USE_TRAN_STATUS = a metric that further explains the transaction status                                              passed on stop_transaction(), such as a sense code that                                              explains why a transaction failed. RETURN VALUE   An ArmID object metric_id. register_transaction(...) register_transaction(app_id, name, [buffer]): describe transaction   DESCRIPTION   register_transaction() describes metadata about a transaction.     The application uses register_transaction() to inform the ARM library of metadata about   the transaction measured by the application. This metadata does not change from one application   instance to another. It is the equivalent of the ARM 2.0 call arm_getid().     ARM generates an ID that is passed in start_transaction() and report_transaction(). PARAMETERS   app_id        Application ID returned from an arm_register_application() call in the same                 process.   buffer        ArmBuffer object, if any. The sub-buffers that may be used are ArmSubbufferMetricBindings                 and ArmSubbufferTranIdentity. The names of any transaction context properties are supplied                 in the ArmSubbufferTranIdentity sub-buffer. They do not change afterwards; that is, the                 names are immutable. The transaction context values may change with each start_transaction()                 or report_transaction().   tran_name     A string containing the name of the transaction. Each transaction registered by an application                 must have a unique name. The maximum length of the string is 127 characters. The name should                 not contain trailing blank characters or consist of only blank characters. RETURN VALUE   An ArmID object tran_id. report_transaction(...) report_transaction(app_handle, tran_id, response_time, stop_time, [status, parent, correlator, flags, buffer):                     report transaction statistics   DESCRIPTION   report_transaction() is used to report statistics about a transaction that has already   completed.     report_transaction() may be used instead of a paired start_transaction() and   stop_transaction() call. The application would have measured the response time. The   transaction could have executed on the local system or on a remote system. If it executes on a   remote system, the system address sub-buffer passed on the start_application() provides   the addressing information for the remote system.     If the transaction represented by the report_transaction() call is the correlation parent of   another transaction, generate_correlator() must be used to get a parent correlator, prior to   invoking the child transaction (because it must be passed to the child). In this case, the sequence   is the following:         1. generate_correlator() to get a correlator for this transaction.       2. Invoke the child transaction, passing the correlator returned in step (1) to the child.       3. When this transaction is complete, invoke report_transaction() to report the          statistics about the transaction.     When used, it prevents certain types of proactive management, such as monitoring for hung   transactions or adjusting priorities, because the ARM implementation is not invoked when the   transaction is started. Because of this, the use of start_transction() and stop_transaction()   is preferred over report_transaction().     The intended use is to report status and response time about transactions that recently completed   (typically several seconds ago) in the absence of an ARM-enabled application and/or ARM   implementation on the system on which the transaction executed. PARAMETERS   app_handle  A ArmID object returned from a start_application() call in the same process.   buffer      An ArmBuffer object, if any. The sub-buffers that may be used are               ArmSubbufferDiagDetail, ArmSubbufferMetricValues, ArmSubbufferTranContext, and               ArmSubbufferUser.   correlator  An ArmCorrelator object returned from generate_correlator(), if any.   flags       ARM_FLAG_TRACE_REQUEST is the only valid flag if the application requests/suggests a               trace.   parent      An ArmCorrelator object for the parent transaction, if any.   response_time               Response time in nanoseconds.   stop_time   A long integer that contains the number of milliseconds since Jan 1, 1970 using               the Gregorian calendar. The time base is GMT (Greenwich Mean Time). There is               one special value, ARM_USE_CURRENT_TIME, which means use the current time.   tran_id     An ArmID transaction ID returned from a register_transaction() call in the same process.   status      Indicates the status of the transaction. The following values are allowed:                     ARM_STATUS_GOOD = transaction completed successfully. This is the default value.                     ARM_STATUS_ABORTED = transaction was aborted before it completed. For example,                         the user might have pressed Stop or Back on a browser while a transaction was                         in process, causing the transaction, as measured at the browser, to be aborted.                     ARM_STATUS_FAILED = transaction completed in error                     ARM_STATUS_UNKNOWN = transaction completed but the status was unknown. This would                         most likely occur if middleware or some other form of proxy instrumentation                         measured the transaction. This instrumentation may know enough to know when                         the transaction starts and stops, but does not understand the application-specific                         semantics sufficiently well to know whether the transaction was successful. RETURN VALUE   None start_application(...) start_application(app_id, [group_name, instance_name, buffer]): check application is running   DESCRIPTION   start_application() indicates that an instance of an application has started running and is   prepared to make ARM calls. In many cases, there will be only one application instance in a   process, but there are cases in which there could be multiple instances. An example of multiple   application instances in the same process is if several Java applications run in the same JVM   (Java Virtual Machine) in the same process, and they each call the ARM 4.0 C interface (either   directly, or indirectly via an implementation of the ARM 4.0 Java interface). They might share   the same application ID or they might be separately registered.     Application context properties may be used to differentiate between instances. The values do not   have to be different from other instances, though making them unique is suggested. The context   properties are provided through function parameters and/or a sub-buffer.     The group and instance names are provided as function parameters.     Up to twenty (name,value) pairs of context properties may be provided in a sub-buffer.     There is a special case in which a system address sub-buffer is provided. The system address   sub-buffer is provided when report_transaction() will be used to report data about   transactions that executed on a different system. In this case, the start_application()   provides a scoping context for the transaction instances, but does not indicate that the   application instance is running on the local system.     The combination of register_application() and start_application() is equivalent to the   ARM 2.0 call arm_init(). PARAMETERS   app_group A string containing the identity of a group of application instances, if any. Application             instances for a given software product that are started for a common runtime purpose are             typically very good candidates for using the same group name. For example, identical             replica instances of a product started across multiple processes or servers to address             a specific transaction workload objective can be, advantageously to the ARM agent,             commonly identified by the group name. The maximum length of the string is 255             characters.   app_id    An ArmID object returned by a register_application() call.   app_instance             A string containing the identity of this instance of the application. It might contain             the process ID, or a UUID in printable characters, for example. The maximum length of             the string is 255.   buffer    An ArmBuffer object containing the user data buffer, if any. The sub-buffer formats that             might be used are ArmSubbufferAppContext and ArmSubbufferSystemAddress.               If no system address sub-buffer is provided on start_application(), all             transactions reported by this application instance execute in the current process.               If a system address sub-buffer is provided on start_application(), all             transactions execute in a different process.               If a system address sub-buffer is provided in which the system address length is             zero, or the system address pointer is null, the system is the local system, as             determined by the ARM implementation.               If a system address sub-buffer is provided in which there is a non-null system             address and length, the system may be the local system or a remote system.             Interpretation of what is local versus remote is at the discretion of the ARM             implementation. RETURN VALUE   An ArmID object app_handle. start_transaction(...) start_transaction(app_handle, tran_id, [parent, correlator, flags, buffer]): start transaction   DESCRIPTION   start_transaction() is used to indicate that a transaction is beginning execution.     Call start_transaction() just prior to a transaction beginning execution. start_transaction()   signals the ARM library to start timing the transaction response time. There is one exception: when   get_arrival_time() is used to get a start time before start_transaction() executes. See   get_arrival_time() to understand this usage.     start_transaction() is also the means to pass to ARM the correlation token (called a correlator in   ARM) from a caller - the parent - and to request a correlator that can be passed to transactions   called by this transaction. The correlation token may be used to establish a calling hierarchy across   processes and systems. A correlator contains a two-byte length field, a one-byte format ID, a one-byte   flag field, plus it may contain other data that is used to uniquely identify an instance of a transaction.   Applications do not need to understand correlator internals. The maximum length of a correlator is 512   (ARM_CORR_MAX_LENGTH) bytes. (In ARM 2.0 it was 168 bytes.) PARAMETERS   app_handle   An ArmHandle object returned from a start_application() call in the same process.   buffer       An ArmBuffer object containing the user data buffer, if any. The sub-buffers that may be                used are ArmSubbufferArrivalTime, ArmSubbufferMetricValues, ArmSubbufferTranContext, and                ArmSubbufferUser.   correlator   An ArmCorrelator object into which the ARM implementation will store a correlator for                the transaction instance, if any. If this parameter is not provided, the application is                not requesting that a correlator be created.                  If the correlator object is provided, the application is requesting that a correlator be                created. In this case the ARM implementation may (but need not) create a correlator in the                object. It may not create a correlator if it does not support the function or if it is                configured to not create a correlator.                  After start_transaction() completes, the application tests the length field using                the ArmCorrelator length() method to determine whether a correlator has been stored. If                the length is still zero, no correlator has been stored. The ARM implementation                must store zero in the length field if it does not generate a correlator.     flags        Contains 32-bit flags which may be combined using a bitwise or. Three flags are defined:                    ARM_FLAG_TRACE_REQUEST = the application requests/suggests a trace.                    ARM_FLAG_BIND_THREAD = the started transaction is bound to this thread. Setting this                        flag is equivalent to immediately calling bind_thread() after the start_transaction()                        completes, except the timing is a little more accurate and the extra call is avoided.                    ARM_FLAG_CORR_IN_PROCESS = the application is stating that it will not send the correlator                            outside the current process. An ARM implementation may be able to optimize correlator                            handling if it knows this, because it may be able to avoid serialization to create                        the correlator.   parent       An ArmCorrelator object from the parent transaction.   tran_id      An ArmID transaction ID returned from a register_transaction() call in the same process. RETURN VALUE   An ArmHandle object that will represent the transaction instance in all calls, up to and including   the stop_transaction() that indicates that the instance has completed executing.     The scope of the handle is the process in which the start_transaction() is executed. stop_application(...) stop_application(app_handle): stop application   DESCRIPTION   stop_application() indicates that the application instance has finished making ARM calls. It   typically means that the instance is ending, such as just prior to the process exiting or a thread   that represents an application instance terminating.     For any transactions that are still in-process [start_transaction() executed without a   matching stop_transaction()], an implicit discard_transaction() is executed.     If the start_application() used the system address sub-buffer to indicate that the ARM calls   would be about an application instance on a different system, stop_application() indicates   that no more calls about that application instance and its transactions will be made.     After executing stop_application(), no further calls should be made for this application,   including calls for transactions created by this application, until a new instance session is   started using start_application(). Data from any other calls that are made will be ignored.   This function is the equivalent of the ARM 2.0 function arm_end(). PARAMETERS   app_handle   The handle returned from an start_application() call in the same process. RETURN VALUE   None stop_transaction(...) stop_transaction(tran_handle, [status, buffer]): stop transaction   DESCRIPTION   stop_transaction() signals the end of a transaction.     Call stop_transaction() just after a transaction completes. start_transaction() signals   the ARM library to start timing the transaction response time. stop_transaction() signals   the ARM library to stop timing the transaction response time. It can be called from any thread in   the process that executed the start_transaction().     Implicit unbind_thread() and unblock_transaction() calls are made for any pending   bind_thread() and block_transaction() calls, respectively, that have not been   explicitly unbound or unblocked with unbind_thread() and unblock_transaction(). PARAMETERS   buffer       An ArmBuffer user data buffer, if any. The sub-buffers that may be used are                ArmSubbufferDiagDetail and ArmSubbufferMetricValues.   tran_handle  An ArmHandle object returned from a start_transaction() call in the same process.   tran_status  Indicates the status of the transaction. The following values are allowed:                    ARM_STATUS_GOOD = transaction completed successfully. This is the default.                    ARM_STATUS_ABORTED = transaction was aborted before it completed. For                        example, the user might have pressed Stop or Back on a browser while a                        transaction was in process, causing the transaction, as measured at the browser, to                        be aborted.                    ARM_STATUS_FAILED = transaction completed in error                    ARM_STATUS_UNKNOWN = transaction completed but the status was unknown. This would                        most likely occur if middleware or some other form of proxy instrumentation                        measured the transaction. This instrumentation may know enough to know when the                        transaction starts and stops, but does not understand the application-specific                        semantics sufficiently well to know whether the transaction was successful. RETURN VALUE   None unbind_thread(...) unbind_thread(tran_handle): unbind a thread   DESCRIPTION   unbind_thread() indicates that the thread from which it is called is no longer performing on   behalf of the transaction identified by the start handle.     Call unbind_thread() when a thread is no longer executing a transaction. The thread   binding is useful for managing computing resources at a finer level of granularity than the   process. It should be called when, for this transaction and this thread, either:   o   bind_thread() was previously called, or   o   The ARM_FLAG_BIND_THREAD flag was on in the start_transaction() call.     stop_transaction() is an implicit unbind_thread() for any threads still bound to the   transaction instance [bind_thread() issued without a matching unbind_thread()]. As   long as the transaction is bound to the thread when the stop_transaction() executes, there is   no need nor any value in calling unbind_thread() before calling stop_transaction(). PARAMETERS   tran_handle   An ArmHandle object returned from a start_transaction() call in the same process. RETURN VALUE   None unblock_transaction(...) unblock_transaction(tran_handle, block_handle): unblock transaction   DESCRIPTION   unblock_transaction() indicates that the suspension indicated by the block_handle for the   transaction identified by the start handle is no longer waiting for a downstream transaction to   complete.     Call unblock_transaction() when a transaction is no longer blocked on an external event. It   should be called when block_transaction() was previously called and the blocking   condition no longer exists. Knowledge of when a transaction is blocked can be useful for better   understanding response times. It is useful to separate out this blocked time from the elapsed   start-to-stop time. The unblocked call is paired with a block call for finer grained analysis.     stop_transaction() is an implicit unblock_transaction() for any blocking condition for   the transaction instance that has not been cleared yet [block_transaction() issued without a   matching unblock_transaction()]. It should only be called without calling   unblock_transaction() first when the blocking condition ends immediately prior to the   transaction ending. PARAMETERS   block_handle  An ArmHandle object returned from a block_transaction() call in the same process.   tran_handle   An ArmHandle object returned from a start_transaction() call in the same process. RETURN VALUE   None update_transaction(...) update_transaction(tran_handle, [buffer]): get transaction status   DESCRIPTION   update_transaction() signals that a transaction is still processing.     update_transaction() is useful as a heartbeat. It is also used to pass additional data about a   transaction. It can be called from any thread in the process that executed the start_transaction(). PARAMETERS   buffer       An ArmBuffer object with the user data buffer, if any. The sub-buffer that might be used                is ArmSubbufferMetricValues.   tran_handle  An ArmHandle object returned from a start_transaction() call in the same process. RETURN VALUE   None

Data
		ARM_CHARSET_ASCII = 3 ARM_CHARSET_IBM037 = 2028 ARM_CHARSET_IBM1047 = 2102 ARM_CHARSET_UTF16 = 1015 ARM_CHARSET_UTF16BE = 1013 ARM_CHARSET_UTF16LE = 1014 ARM_CHARSET_UTF8 = 106 ARM_CORR_FLAGNUM_AGENT_TRACE = 2 ARM_CORR_FLAGNUM_APP_TRACE = 1 ARM_FLAG_BIND_THREAD = 2 ARM_FLAG_CORR_IN_PROCESS = 4 ARM_FLAG_NONE = 0 ARM_FLAG_TRACE_REQUEST = 1 ARM_METRIC_FORMAT_CNTRDIVR32 = 3 ARM_METRIC_FORMAT_COUNTER32 = 1 ARM_METRIC_FORMAT_COUNTER64 = 2 ARM_METRIC_FORMAT_GAUGE32 = 4 ARM_METRIC_FORMAT_GAUGE64 = 5 ARM_METRIC_FORMAT_GAUGEDIVR32 = 6 ARM_METRIC_FORMAT_NUMERICID32 = 7 ARM_METRIC_FORMAT_NUMERICID64 = 8 ARM_METRIC_FORMAT_RESERVED = 0 ARM_METRIC_FORMAT_STRING32 = 10 ARM_METRIC_USE_GENERAL = 0 ARM_METRIC_USE_TRAN_SIZE = 1 ARM_METRIC_USE_TRAN_STATUS = 2 ARM_STATUS_ABORTED = 1 ARM_STATUS_FAILED = 2 ARM_STATUS_GOOD = 0 ARM_STATUS_UNKNOWN = 3 ARM_SYSADDR_FORMAT_HOSTNAME = 7 ARM_SYSADDR_FORMAT_IPV4 = 1 ARM_SYSADDR_FORMAT_IPV4PORT = 2 ARM_SYSADDR_FORMAT_IPV6 = 3 ARM_SYSADDR_FORMAT_IPV6PORT = 4 ARM_SYSADDR_FORMAT_SNA = 5 ARM_SYSADDR_FORMAT_UUID = 8 ARM_SYSADDR_FORMAT_X25 = 6 ARM_USE_CURRENT_TIME = -1