Agent reference

Documentation / C# Edition / User Guide / Appendix / Agent reference
 

This chapter provides a quick reference to the MyARM agent bindings and describes possible error codes and log messages.

C# Language Binding

Error return codes

MYARM_ERROR_NONE (0)
This is not really an error code; it indicates that the operation succeeded successful.
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:
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 (due to clearance of the agent or from a call from the application). 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>
  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