9 Tracing

With help of various command line switches, processing in the DM can automatically be debugged and tested.

9.1 Description of Tracing

With help of the tracing facility, the DM application can be debugged. The tracefile contains all executed rules, all called application functions and all called DM functions with their current parameters (please refer also to manual “C Interface - Basics”).

The following is also traced:

• built-in functions with side-effects (e.g. create),
• setvalues (always - not only when a changed event was created),
• call to format and canvas functions,
• DM-calls in network applications on the server part.

The general layout of the file is as follows:

[<Abbreviation>]<Action>

The explanation of what has currently be done is given in the <Action>.

The <Abbreviation> stands for the DM action. The following codes are possible:

9.2 Configuration of Tracing

If enormous dialogs are being processed the tracefiles increase accordingly. This is why the tracing can be configured. In addition the possibility to switch on and off the tracing (setup.tracing := true/false) is available.

The configuration of tracing enables you to switch off the tracing for special trace events. This is helpful for e.g. loops or other trace-intensive rules or program codes. You may switch off trace events at the Setup object. The attribute .tracing is indexed with a string:

setup.tracing["<abbreviation>"] := false;

Example

setup.tracing["RR"] := false;

This definition switches off all return values of named rules.

By switching off certain trace events – e.g. ["RC"] (call of a named rule) – you may also obtain a grouping effect: in the above example the calls of named rules are oppressed as well as the return values of named rules (see table below, column Grouping).

Note

Please note that the following trace events cannot be switched off:

• important trace events (see table below, column Can be toggled by user.)
• trace events via DM_TraceMessage

Warning

If you need IDM support, do not switch off too many trace messages, as we might not be able to help you efficiently. If important trace messages are missing it is not possible to get a satisfactory analysis.

Please not the following programming hints.

Right

variable boolean I_NEED_HELP_FROM_ISA_SUPPORT := true;
...
rule MyCode()
{
  TraceEvent("RC", false);
  ...
}

rule TraceEvent(string TraceTag, boolean Value)
{
  !! Check the global variable for support.
  if ( not I_NEED_HELP_FROM_ISA_SUPPORT ) then
    setup.tracing[TraceTag] := Value;
  endif
}

Wrong

rule MyCode()
{
  !! Do not look for help in your rules without a trace.
  !! Nobody knows which rule was called!
  setup.tracing["RC"] := false;
  ...
}

The following table summarizes how trace events are grouped and indented in the trace file. It also indicates whether the trace messages can be turned off by the user. In the table mean:

• Abbreviation of relevant trace event: Please refer to chapter “Description of Tracing”.
• Grouping: Trace event which also switches trace event in the first column.

• Indention:

  =	no indention
  >	to the right
  <	to the left

9.3 Time Marks during Tracing

The option ‑IDMtracetime <No.> is used to protocol the absolute or relative time needed for functions and rules during program run. It is thus possible to identify very time-consuming functions or rules for which tuning measures could then be taken .

There are three types of time measurement, which can be set using the <No.> parameter:

0

No times are logged in the trace file.

1

This value indicates start time mode. In this mode all start and end times are logged. The time needed for a single structure may then be calculated with the difference. In this mode only the system and user time will be considered.

The times are given in format [hh:mm:ss:uuu] at the beginning of line:

• hh = hours
• mm = minutes
• ss = seconds
• uuu = milliseconds

2

This value indicates the trace time mode. In this mode the time difference to the last logged call is given. It is thus possible to easily recognize how much time is needed for individual actions.

In this mode the time difference to the last trace output is given in the format [sss:uuu] at the beginning of line:

• ss = seconds
• uuu = milliseconds

3

This value specifies the real-time mode. In this case the real time is indicated for each action to be logged in the trace file.

In this mode the real time is given in format [hh:mm:ss] at the beginning of line:

• hh = hours
• mm = minutes
• ss = seconds

9.4 Safety Tracing

Availability

The safety mode of tracing is available in the IDM versions A.05.01.g3 and A.05.01.h as well as from A.05.02.e.

Safety tracing is a special trace file mode. In order to keep the trace file running during long application sessions without experiencing a slower running system and the use of too many resources, safety tracing uses a limited ring buffer that is held in the memory. For this use the option ‑IDMstracefile <filepath> instead of ‑IDMtracefile <filepath> or when using ‑IDMtracefile <filepath> switch on safety mode with the option ‑IDMstrace.

With respect to the ring buffer, limited means that the number of lines and the number of characters per line (without indents) is restricted. In addition, the length of the string values (typically displayed in "…") is shortened and the string length is attached in brackets [ ]. The limitations can be influenced via the option ‑IDMstraceopts. For the hierarchical indentation in the trace file two blank spaces are used. This cannot be influenced by the option ‑IDMindent. If the issued lines are discontiguous this is marked by a line and a colon. If the maximum length of the line is exceeded, this is marked with a tilde (~).

The content of the ring buffer is written to the trace file only after the application has been ended. It is necessary to have an active exception catcher in order to guarantee that files are saved in case of system crashes (see chapter “Exception Catcher”).

Switching off the tracing or the output of certain trace codes is not possible in the safety tracing.

The following limitations apply within the safety tracing: