Trace logging from a user-defined C extension

Message processing nodes and parsers that are written to the C programming language API can write entries to trace.

You can use two types of trace:
  • Service Trace: entries usually describe what is happening within the code and are only useful to the owner of the code, such as the user-defined extension developer.
  • User Trace: entries usually describe what is happening at an external level and are useful to the user of the code. Users of the code include message flow designers, and integration node domain administrators.
For each trace type, there are three levels:
  • None
  • Normal
  • Debug
For C user-defined extensions, the following utility functions are available for each trace type:
  • cciServiceTrace and cciUserTrace: these functions write an entry to the respective trace type only when trace has been activated, that is, trace is at normal or debug level.
  • cciServiceDebugTrace and cciUserDebugTrace: these functions write an entry to the respective trace type only when trace is active at debug level.
To help avoid making function calls in the case where no trace is written, the cciIsTraceActive utility function is provided. cciIsTraceActive reports whether trace is active and the level at which trace is active.

The cci*Trace functions can be used by a user-defined extension regardless of the trace settings. The functions determine if trace is active and only write entries which are appropriate for the trace settings. When calling the cci*Trace functions, some additional processing can be required. The cciIsTraceActive function is provided to allow the user-defined extension to query the trace settings and avoid this extra processing when trace is inactive.

In many cases, it is sufficient to treat the value returned from the cciIsTraceActive function as a Boolean value. If the returned value is non zero, trace is active at some level and it is appropriate to call any of the cci*Trace functions. The returned value can also be inspected closely in the cases when details of the trace settings are required.

Trace settings can be changed at any time so it is advisable to query them regularly. For example, use cciIsTraceActive to query the trace settings when an implementation function is entered.

Trace entries can be associated with certain objects, which allows for further refinement of control for writing trace. A trace entry can be associated with a node or parser and trace is written according to the trace setting for that object. The object's trace setting is inherited from the message flow to which the node or parser belongs. If no object is specified, the trace is associated with the integration server.