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