Tracer – step 0022 – December 2009

1 Purpose of SrrTracer

SrrTrains provides the possibility to develop your own 3^rd party SRR objects. In this case you will need some means to debug the 3^rd party SRR object while using it in a test scene.

Additionally the tracer can help when you develop your own modules and models.

Last but not least the tracer can be used to debug the software that is provided by the SrrTrains Core Team.

The tracer provides an interface that enables you to output debug information on different trace levels to the Web3D browser's console. The software contains trace points. When a trace point is reached and when the active trace level is greater or equal the trace level of the trace point, then the debug output is actually done.

The tracer uses the functions Browser.print() (Blaxxun) or Browser.println() (Octaga) to output the debug information.

2 Trace Levels

Trace Level 1:

This trace level is reserved for errors. Errors are defined as malfunctions that can easily be corrected by the end user (model railroad player). Errors are predefined by the SRR Framework and described by an error number.

commParam.errorNo is set by the tracer, when a trace point with level=1 is reached. commParam.errorNo is never reset.

The user can output the current error status by commParam.errorStrings[commParam.errorNo] at any time.

For a general explanation of commParam see SrrControl.x3d.

Currently following error numbers are defined:

"[0] no error has occurred yet"

"[1] unsupported Browser detected -> please use supported Web3D browser"

"[2] unexpected software error -> please use better version of SRR"

"[3] frame requested multiuser-mode, but did not provide sessionId -> please use better version of frame"

"[4] layout module(s) could not be registered (central controller did not answer) -> please start collaboration server"

"[5] network sensor of an SRR object could not be initialized -> please start collaboration server"

"[6] vehicle(s) could not be registered (central train controller did not answer) -> please start collaboration server"

"[7] network sensor of an optional SRR Controller module could not be initialized -> please start collaboration server"

"[8] SRR Controller did not respond to a module announcement -> please start collaboration server"

"[9] module coordinator could not initialize network sensor -> please start collaboration server"

"[10] empty"

"[11] required SRR Controller module is not present -> use another frame for this layout module"

"[12] required ModCoord module for an SRR object missing -> dont use this SRR object in this layout module"

"[13] could not load vehicle model from registered URL -> register better URL"

Usually only errorNo = 5 or 12 should be triggered by an SRR object, the other errors are more or less reserved for use by the SRR Framework.

New error numbers can be introduced on request (you can reach the SRR Core Team at http://simulrr.wordpress.com/about).

Trace Level 2:

This trace level is reserved for informational output. This output can be used to

study the functionality of an SrrTrains layout generally
begin to localize an error, when debugging (set several tracer instances to trace level 2 and reproduce the error, to get hints, in which tracer instance the error could be located)

Trace Level 3:

This trace level is defined for debug output. This output can be used to

study the functionality of a specific tracer instance
generate output that can be sent to the author of the erroneous tracer instance for fixing a bug

Active Trace Level

The SRR Controller provides an interface to set active trace levels (see SrrControl.x3d).

This trace level can be set to different values for nearly every tracer instance.

“Classic” Trace Level:

If some custom software uses the “classic” tracer, the active trace level of all those users can be set globally.

Trace Levels for SrrControl:

The tracer instance SrrControl (SRR Controller client parts) has got two different trace levels. One is applied during initialization (from the moment, when the frame sends init=true via the uiControl interface, until the moment, when the SRR Controller answers with a reference to the common parameters commParam), the second is applied afterwards (initialization of modules, initialization of SRR objects, normal operation).

Trace Levels for CommControl:

The tracer instance CommControl (communication controller – server parts of SrrControl.x3d) has got two trace levels, too. The application of both is analogous to the trace levels of SrrControl.

Trace Levels for TrainControl:

The tracer instance TrainControl (train controller – server parts of SrrControlTm.x3d) has got only one trace level. This is applied the whole time, until it is changed via uiControl.

Trace Levels for Modules:

The trace levels for all modules are defined in a single SFString value. The SFString has the following syntax.

*=<TLoperation>,<TLinit>[;<modulePattern>=<TLoperation>,<TLinit>]...

That means, a general default value of TLoperation and TLinit is given, and new values of TLoperation and TLinit can be superimposed for one or more specified modules (the asterisk '*' can be used to address more than one module).

<TLinit> will be applied during the initialization of the module (from the moment, when the module sends the commParam to the module coordinator until the module coordinator answers with modParam), <TLoperation> will be applied afterwards (initialization of SRR objects, normal operation)

Trace Levels for Objects:

The trace levels for all SRR objects (and models, if they use the SrrTracer) are defined in a single SFString value. The SFString has the following syntax.

*-*=<TLoverall>[;<modulePattern>-<objectPattern>=<TLoverall>]...

That means, a general default value of TLoverall is given, and new values of TLoverall can be superimposed for one or more specified SRR objects/models (the asterisk '*' can be used to address more than one module and more than one object within each module).

3 The “Classic” Tracer (deprecated)

SrrTracer has been implemented in step 0021. A basic trace function was already available from the beginning by the tracer part of the common parameters (commParam).

The commParam contains a script node command, that provides the fields

ErrLog takes an errorNo, sets the parameter commParam.errorNo and outputs the error message to the console, if commParam.traceLevel ≥ 1.

Example Error Message:
SRR:traceLevel=1,timeStamp=2009/07/24/17:51:45.328,errorNo=1,ownSessionId=-1
SRR: unsupported Browser detected
SRR: need one of the following Browsers:
SRR: blaxxunCC3D, version >= 7.206
SRR: Octaga Player, version >= 2.307
SRR:END

The first line with the trace level, time stamp, errorNo and ownSessionId as well as the last line “SRR:END” are inserted by ErrLog. The prefix “SRR: “ of all lines is added by ErrLog.

InfoLog takes a set of lines as input and outputs them as a trace output with traceLevel 2, if commParam.traceLevel ≥ 2.

Example Info Message

SRR:traceLevel=2,timeStamp=2009/07/24/18:18:25.046,ownSessionId=-1
SRR: user requests initialization of SRR Controller
SRR:END

The first line with the trace level, time stamp and ownSessionId as well as the last line “SRR:END” are inserted by InfoLog. The prefix “SRR: “ of all lines is added by InfoLog.

Debug takes a set of lines as input and outputs them as a trace output with traceLevel 3, if commParam.traceLevel ≥ 3.

Example Debug Message

SRR:traceLevel=3,timeStamp=2009/07/24/18:24:16.765,ownSessionId=-1
SRR: SrrControl.handleServerRequest: wait until received comm state sequence is .GE. sent comm state sequence
SRR:END

The first line with the trace level, time stamp and ownSessionId as well as the last line “SRR:END” are inserted by Debug. The prefix “SRR: “ of all lines is added by Debug.

The “classic” tracer interface is still available, although it is recommended to use the new prototype SrrTracer (see next chapter).

4 User Interface of SrrTracer

SrrTracer is an external prototype, available at the directory srr/.

</ProtoInterface>

The fields of the user interface can be arranged according to the following categories:

x) Defining the Tracer Instance

The fields subsystem, ssVersion, fileName, objId and instanceId will be output in each trace output written by this tracer instance, to define the origin of the trace output.

If SrrTracer is used outside of a model/SRR object (e.g. in a frame or in a module), objId must be explicitly set to the empty string “”.

x) Initializing the Tracer

One of the fields commParam and modParam has to be set to initialize the tracer instance. The SRR Controller will initialize its tracer with commParam, where the module coordinator and all SRR objects will initialize it with modParam (the module coordinator will set objId to the empty string).

If a frame uses SrrTracer, it is expected, that the tracer will be initialized with commParam.

If a module, a model or a 3^rd party SRR object uses SrrTracer, it is expected, that the tracer will be initialized with modParam.

x) Produce Diagnostic Output

An event at the field errLog will output an error (trace level 1).

An event at one of the fields freeTextInfo, messageReceived, sendMessage, eventReceived, sendEvent, newState, startTimer, stopTimer, timerExpired, instanceStarted and instanceStopped will output an info (trace level 2).

An event at the field freeTextDebug will output debug info (trace level 3).

x) Setting the Active Trace Level

Each instance of SrrTracer keeps its own active trace level.

If objId is empty, the user (frame, module) must set the trace level actively at the field localTraceLevel. A frame has to provide some own means to achieve that, a module can use the localTraceLevel output field of SrrModCoord to set the own trace level.

If objId is not empty (in models and 3^rd party SRR objects), SrrTracer will proactively set the own localTraceLevel. It will use the information broadcast by SrrControl in the common parameters (commParam).

5 A Hint

The fields of commParam.command should be triggered by “direct access” instead of using <ROUTE> commands. This is necessary to ensure the correct order of output of the trace statements to the console.

The same is valid for the fields of the SrrTracer prototype.

6 Some Examples:

A usage of SrrTracer in a frame could look like (the tracer is used as an SFNode field in a <Script> node):

</ProtoInstance>

</field>

A usage of SrrTracer in a module could look like (the tracer is used as an SFNode field in a <Script> node). The instanceId will be set with the concrete module name during initialization:

</ProtoInstance>

</field>

A usage of SrrTracer in a model could look like (the tracer is used as an SFNode field in a <Script> node). The instanceId is set with the concrete extended object id and the objId is set with the concrete objId of the vehicle during initialization:

</ProtoInstance>

</field>