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.