C Language Binding

The ARM 4.0 C language binding defines error level return codes (negative) and warning level return codes (positive). The following sections describe the possible MyARM return codes:

Error return codes

MYARM_ERROR_NONE (0)

This is not really an error code; it indicates that the operation succeeded successfully.

MYARM_ERROR_NO_MEMORY (-1)

MyARM tried to allocate some memory but this failed.

MYARM_ERROR_NO_OUTPUT_ID (-2)

The pointer to the output arm_id_t is null in one the following API calls:

• arm_register_application()
• arm_register_transaction()
• arm_register_metric()

MYARM_ERROR_NO_OUTPUT_HANDLE (-3)

The output handle in one of the following API calls was null:

• arm_start_application()
• arm_start_transaction()
• arm_block_transaction()

MYARM_ERROR_NO_OUTPUT_CORR (-4)

The pointer to the output correlator was null in the arm_generate_correlator() API call.

MYARM_ERROR_NO_OUTPUT_VAR (-5)

The pointer to the output variable was null in one of the following API calls:

• arm_get_correlator_length()
• arm_get_arrival()
• arm_is_charset_supported()

MYARM_ERROR_NO_TRAN_DEF (-6)

A null pointer transaction id was passed to one of the following API calls:

• arm_generate_correlator()
• arm_report_transaction()
• arm_start_transaction()

MYARM_ERROR_INVALID_APP_HANDLE (-7)

One of the following API calls were called with an invalid application start handle:

• arm_stop_application()
• arm_report_transaction()
• arm_start_transaction()

This can be the case if an uninitialized handle is used (e.g. application was not started) or the appropriate application was stopped before (passing a handle a second time to arm_stop_application() is an error).

MYARM_ERROR_INVALID_TRAN_HANDLE (-8)

One of the following API calls was called with an invalid transaction start handle:

• arm_stop_transaction()
• arm_update_transaction()
• arm_discard_transaction()
• arm_bind_thread()
• arm_unbind_thread()
• arm_block_transaction()
• arm_unblock_transaction()

This can be the case if an uninitialized handle is used (e.g. transaction was not started) or the appropriate transaction was stopped before (passing a handle a second time to arm_stop_transaction() is an error).

MYARM_ERROR_NO_CORR (-9)

The arm_get_correlator_flags() was called with a null pointer for the correlator.

MYARM_ERROR_INVALID_ENCODING (-10)

The arm_register_application() was called with a charset that is not supported by MyARM.

MYARM_ERROR_NO_APP_DEF (-11)

The arm_start_application() was called with null pointer for the application id.

MYARM_ERROR_NOT_IMPLEMENTED (-12)

This error code is returned by any ARM 4.0 C API call when MyARM could not be initialized correctly. This is an indication of a misconfiguration of MyARM. Be sure all needed environment variables are correctly set.

MYARM_ERROR_NO_NAME (-13)

The mandatory name was not provided (null pointer) to one of the following API calls:

• arm_register_application()
• arm_register_transaction()
• arm_register_metric()

MYARM_ERROR_INVALID_METRIC_FORMAT (-14)

Either the arm_register_metric() was called with an invalid metric format or the metric format of a metric passed within the arm_subbuffer_metric_values_t on the following functions does not match its metric binding:

• arm_report_transaction()
• arm_start_transaction()
• arm_stop_transaction()
• arm_update_transaction()

MYARM_ERROR_INVALID_METRIC_USAGE (-15)

The arm_register_metric() was called with an invalid metric usage.

MYARM_ERROR_INVALID_APP_ID (-16)

An invalid application id was passed to one of the following API calls:

• arm_register_transaction()
• arm_register_metric()
• arm_start_application()

This is often the case if arm_register_application() failed for some reason.

MYARM_ERROR_INVALID_TRAN_ID (-17)

An invalid transaction id was passed to one of the following ARM 4.0 API calls:

• arm_report_transaction()
• arm_start_transaction()
• arm_generate_correlator()

This is often the case if arm_register_transaction() failed for some reason. Or when using the ARM 2.0 API and an invalid transaction id was passed to arm_start().

MYARM_ERROR_INVALID_INDEX (-21)

Context values and metrics are managed as arrays within the MyARM agent. An index passed to MyARM was out of bounds.

MYARM_ERROR_LIMIT_REACHED (-23)

MyARM tried to get a resource but the limit for the resource (transaction instance or metric instance) was reached.

MYARM_ERROR_INVALID_START_HANDLE (-24)

One of the following ARM 2.0 API calls was called with an invalid start handle:

• arm_update()
• arm_stop()

This can be the case if an uninitialized handle is used (e.g. transaction was not started) or the appropriate transaction was stopped before (passing a handle a second time to arm_stop() is an error).

MYARM_ERROR_INVALID_DATA_BUFFER_FORMAT (-25)

One of the following ARM 2.0 API calls was called with an invalid data buffer format:

• arm_getid()
• arm_update()
• arm_stop()

This can be the case if an uninitialized data buffer is used.

MYARM_ERROR_INVALID_API_CALL (-26)

An ARM 4.0 API function was called before any application definition was registered (arm_register_application()) or after the last application definition was destroyed (arm_destroy_application()).

MYARM_ERROR_INVALID_CURRENT_CORRELATOR (-28)

arm_report_transaction() was called with an invalid current correlator. The transaction was dropped.

MYARM_ERROR_INVALID_BLOCK_HANDLE (-29)

The arm_unblock_transaction() method was called with an invalid block handle. It seems that there is a arm_block_transaction() call missing or the block handle is invalid.

Warning return codes

MYARM_WARNING_UNKNOWN_SUBBUFFER (1)

An unknown sub-buffer was passed to one of the ARM 4.0 C-API calls.

MYARM_WARNING_DIAG_DETAIL_WITH_GOOD_STATUS (2)

A diagnostic detail sub-buffer was passed to arm_stop_transaction() call, although the transaction status was good. This is not supported as specified by the standard.

MYARM_WARNING_NOT_STARTED (3)

arm_stop_transaction() was called but the transaction was not started by MyARM. This can be the case if something failed within arm_start_transaction. For example in low memory situations transactions are not started.

MYARM_WARNING_PROPERTY_COUNT_TOO_LARGE (6)

An arm_subbuffer_tran_context_t sub-buffer was passed to the following ARM API functions and the property count field was too large:

• arm_report_transaction()
• arm_start_transaction()
• arm_stop_transaction() (MyARM extension)

MYARM_WARNING_INVALID_PARENT_CORRELATOR (10)

arm_report_transaction() or arm_start_transaction() was called with an invalid parent correlator.

Java Language Binding

Error return codes

The following error codes apply only to the MyARM Java agent. Additionally error codes from the MyARM C agent can be returned from the Java agent since MyARM Java agent is JNI based. This is indicated by an JNI error: prefix.

MYARM_ERROR_NONE (0)

This is not really an error code; it indicates that the operation succeeded successfully.

MYARM_ERROR_NO_MEMORY (-1)

MyARM tried to allocate some memory but this failed.

MYARM_ERROR_NO_TRAN_DEF (-6)

An ArmTransaction, ArmTranReport or an ArmTransactionWithMetrics was created with a null ArmTransactionDefinition instance.

MYARM_ERROR_NO_APP_DEF (-11)

An ArmTransactionDefinition or an ArmMetricDefinition was created with a null ArmApplicationDefinition instance.

MYARM_ERROR_NO_NAME (-13)

Either creating an ArmApplicationDefinition, ArmTransactionDefinition or an ArmMetricDefinition the mandatory name was not provided (null pointer).

MYARM_ERROR_INVALID_METRIC_FORMAT (-14)

The ArmMetric and ArmMetricDefinition does not match or is unknown.

MYARM_ERROR_NO_ARRAY (-18)

A null byte array was passed to the constructor of ArmID or to the setBytes() of ArmToken.

MYARM_ERROR_NO_APP (-19)

A null application instance was passed to the constructor of ArmTranReport, ArmTransaction or ArmTransactionWithMetrics.

MYARM_ERROR_INVALID_LENGTH (-20)

A null application instance was passed to the constructor of ArmTranReport, ArmTransaction or ArmTransactionWithMetrics.

MYARM_ERROR_INVALID_INDEX (-21)

Context values and metrics are managed as arrays within the MyARM agent. An index passed to MyARM was out of bounds.

MYARM_ERROR_ALIEN_OBJECT (-22)

Attempt to use an object from a different ARM implementation. This mostly fails because this implementation relies on opaque characteristics of its own implementation objects. Object-level interoperability with other ARM implementations is not provided here.

MYARM_ERROR_LIMIT_REACHED (-23)

MyARM tried to get a resource but the limit for the resource (transaction instance or metric instance) was reached.

MYARM_ERROR_JNI_INVALID_ARG (-30)

Within the Java JNI code an invaid argument was detected. Please report this error code to the MyARM support.

MYARM_ERROR_JNI_CLASS_NOT_FOUND (-31)

Within the Java JNI code a required MyARM java class could not be found. Please make sure you provided the current myarm.jar to the JVM. If the myarm.jar and MyARM C agent are from the same version please report this error code to the MyARM support.

Creating ARM 4.0 objects

The Java language binding standard defines a vendor independent way for creating ARM objects. Within ARM 4.0 there are three factory classes a ARM implementation has to provide. The class names of these factory classes are provided by the Java property concept. To use MyARM ARM 4.0 java agent please use the following factory class names:

Arm40.ArmTransactionFactory

com.myarm.arm40.ArmTransactionFactoryImpl

Arm40.ArmTranReportFactory

com.myarm.arm40.ArmTranReportFactoryImpl

Arm40.ArmMetricFactory

com.myarm.arm40.ArmMetricFactoryImpl

MyARM ARM 4.0 jar file

Once you configured the MyARM specific factory names you need to provide the MyARM implementation classes to the java virtual machine. This is done by appending the MyARM JAR (myarm.jar) archive to the CLASSPATH environment variable.

export CLASSPATH=$CLASSPATH:$MYARM_ROOT/lib/jar/myarm.jar

C# Language Binding

Error return codes

MYARM_ERROR_NONE (0)

This is not really an error code; it indicates that the operation succeeded successfully.

MYARM_ERROR_NO_MEMORY (-1)

MyARM tried to allocate some memory but this failed.

MYARM_ERROR_NO_TRAN_DEF (-6)

An ArmTransaction, ArmTranReport or an ArmTransactionWithMetrics was created with a null ArmTransactionDefinition instance.

MYARM_ERROR_NO_APP_DEF (-11)

An ArmTransactionDefinition or an ArmMetricDefinition was created with a null ArmApplicationDefinition instance.

MYARM_ERROR_NOT_IMPLEMENTED (-12)

Called an unimplemented method. Currently this is bindThread() and unbindThread() of ArmTransaction.

MYARM_ERROR_NO_NAME (-13)

Either creating an ArmApplicationDefinition, ArmTransactionDefinition or an ArmMetricDefinition the mandatory name was not provided (null pointer).

MYARM_ERROR_INVALID_METRIC_FORMAT (-14)

The ArmMetric and ArmMetricDefinition does not match or is unknown.

MYARM_ERROR_INVALID_APP_ID (-16)

An application definition with an invalid id was used to create an IArmApplication instance.

MYARM_ERROR_INVALID_TRAN_ID (-17)

An transaction definition with an invalid id was used to create an IArmTransaction or an IArmTranReport instance.

MYARM_ERROR_NO_ARRAY (-18)

A null byte array was passed to the constructor of ArmID or to the setBytes() of ArmToken.

MYARM_ERROR_NO_APP (-19)

A null application instance was passed to the constructor of ArmTranReport, ArmTransaction or ArmTransactionWithMetrics.

MYARM_ERROR_INVALID_LENGTH (-20)

A null application instance was passed to the constructor of ArmTranReport, ArmTransaction or ArmTransactionWithMetrics.

MYARM_ERROR_INVALID_INDEX (-21)

Context values and metrics are managed as arrays within the MyARM agent. An index passed to MyARM was out of bounds.

MYARM_ERROR_ALIEN_OBJECT (-22)

Attempt to use an object from a different ARM implementation. This mostly fails because this implementation relies on opaque characteristics of its own implementation objects. Object-level interoperability with other ARM implementations is not provided here.

MYARM_ERROR_LIMIT_REACHED (-23)

MyARM tried to get a resource but the limit for the resource (transaction instance or metric instance) was reached.

MYARM_ERROR_INVALID_METRIC_ID (-27)

A metric definition with an invalid id was used to create an IArmMetric instance.

Warning return codes

MYARM_WARNING_DIAG_DETAIL_WITH_GOOD_STATUS (2)

A diagnostic detail string was provided although the transaction status was good. This is not supported as specified by the standard.

MYARM_WARNING_NOT_STARTED (3)

The stop() method of an ArmTransaction instance was called with out being started. The call is ignored.

MYARM_WARNING_NOT_STOPPED (4)

The start() method of an ArmTransaction instance was called with out being stopped. The call is ignored.

MYARM_WARNING_MISSING_UNBLOCKED (5)

The stop() method of an ArmTransaction instance was called during an open blocked(). It seems that there is an unblocked() call missing.

MYARM_WARNING_INVALID_STATUS (7)

An invalid status was passed either to IArmTransaction.stop() or IArmTranReport.report(). Only the following status values are valid:

• ArmConstants.STATUS_GOOD
• ArmConstants.STATUS_FAILED
• ArmConstants.STATUS_ABORT.
• ArmConstants.STATUS_UNKNOWN.

MYARM_WARNING_NOT_BLOCKED (8)

The unblocked() method of an IArmTransaction instance was called but the provided blocked handle does not reference a previous blocked() call. It seems that there is a blocked() call missing or the block handle is invalid.

MYARM_WARNING_ALREADY_STOPPED (9)

The stop() method of an ArmTransaction instance was called but the measurement was already stopped. The call is ignored.

Creating ARM 4.0 objects

The C# ARM 4.0 language binding is derived directly from the Java binding thus the creation of the ARM factory objects are similar. The names of the factory classes are configured within some kind of environment. C# does not support a concept of system properties (as Java do) but uses a slightly different approach for configuration called application configuration based on XML files. Also C# has the possibility to read the contents of system environment variables. Therefore MyARM proposes the following steps to get the names of the factory classes:

1. Check the application configuration file (app.config) for the class names. ARM class names should be placed in the section ARM/Environment.

   <?xml version="1.0" encoding="utf-8" ?>
   <configuration>
     <configSections>
       <sectionGroup name="ARM"
           type="System.Configuration.ConfigurationSectionGroup">
         <section name="Environment" 
             type="System.Configuration.NameValueSectionHandler" />
       </sectionGroup>
     </configSections>
   
     <ARM>
       <Environment>
         <add key="Arm40.ArmTransactionFactory" 
              value="MyARM.arm40.ArmTransactionFactory" />
         <add key="Arm40.ArmMetricFactory"
              value="MyARM.arm40.ArmMetricFactory" />
         <add key="Arm40.ArmTranReportFactory"
              value="MyARM.arm40.ArmTranReportFactory" />
       </Environment>
     </ARM>
   </configuration>
   

   Configuration: C# ARM factory app.config example
2. Check the system environment variables. The eclipse project already uses the environment variable approach and uses the following keys as variable names which contains the appropriate class name:

   Arm40.ArmTransactionFactory

   contains the class name for the ArmTransactionFactory class: MyARM.arm40.ArmTransactionFactory

   Arm40.ArmTranReportFactory

   contains the class name for the ArmTranReportFactory class: MyARM.arm40.ArmTranReportFactory

   Arm40.ArmMetricFactory

   contains the class name for the ArmMetricFactory class MyARM.arm40.ArmMetricFactory

3. Check the registry under the Software/ARM path.
   • Software/ARM/Arm40.ArmTransactionFactory -- contains the class name for the ArmTransactionFactory class: MyARM.arm40.ArmTransactionFactory
   • Software/ARM/Arm40.ArmTranReportFactory -- contains the class name for the ArmTranReportFactory class: MyARM.arm40.ArmTranReportFactory
   • Software/ARM/Arm40.ArmMetricFactory -- contains the class name for the ArmMetricFactory class MyARM.arm40.ArmMetricFactory