The Tcl programming interface provides a special command to load an event base into memory and to instantiate extra commands that allow the event base and its associated contexts to be manipulated directly from the command line. This procedure is written in C++ and uses the WindView C++ API to access the event base. The event-base library initializes a Tcl interpreter and then adds its own commands to the interpreter.

The syntax for wvEventBaseLoad is as follows:

wvEventBaseLoad "filename" eventBaseRootName 

It returns a special handle which represents the event base. It also creates a number of new commands which work directly on the loaded event base and its task contexts; these commands start with the string specified by eventBaseRootName. The returned handle must be saved so it can be used with the command wvCoordsCreate to instantiate a coordinates object for navigating around the event base.

To load the event base logfile.wvr with the root name eb and save the handle to the constant ebHandle, enter the following:

set ebHandle [wvEventBaseLoad "logfile.wvr" eb]

If the event-base root name is eb then a command eb is created, plus one extra command for each task-context identified by the context name. For example, if there is a context called tFtpdTask, it is accessible through the command eb.tFtpdTask.

The event-base commands accept the following extra command arguments:

returns a list of all context names.

returns a 2-element list containing the start and end timestamps.

removes all the context commands and frees all memory allocated for the event base.

The context commands accept the following arguments:

returns the task VxWorks ID.

returns the task priority.

returns the index of the nearest event to the given time.

returns M, the number of events in the context, numbered 0...M-1.

returns a list representing the Nth event in the context where N is an integer between 0 and M-1. Optional formatting of the output of this command is available via the -format option.

The default string format of an event returned by the N context command is:

eventName timeStamp argList state

where argList is a Tcl list with each item in the list being a name:value pair and state is a hexadecimal value representing the wind state bits defined in installDir/host/include/wvapi.h.

The output of an event record can be reformatted if the default style is inadequate for your needs. For example, the event parameters can be omitted or the timestamp can be printed first. In the context N command described above, an optional -format formatString can be appended. The formatString argument is a string containing literal characters and %-escaped field specifiers. The field specifiers can take the following values:

event name

time stamp

task state after the occurrence of the event

event parameters 1 to 7. Event parameters are always printed as a name:value pair.

For example, to print only event type and timestamp information, use the following option:

-format %n %t

The default format string (including backslashes escaping the open- and close-braces) is equivalent to the following:

-format %n %t \{ %1 %2 %3 %4 %5 %6 %7 \} %s 

To create a coordinates object, given an established event base, the command wvCoordsCreate is invoked with the following format:

wvCoordsCreate coordsName ebHandle timeStamp [contextName] [eventType]

The ebHandle argument is be the result of a previous wvEventBaseLoad command. The coordsName argument is user specified; it is used for subsequent commands on the coordinates object. The time stamp must be a real number between the limits indicated by the result of an ebHandle interval operation. Optionally, the name of a context (one of the values returned by ebHandle names) can be supplied, and also an event type (the numeric value).

The command creates a new Tcl command, named after the coordsName given in the invocation, which represents the WVCoords object. It responds to the following commands, assuming coordsName is cc:

cc ++ 

move forward one event.

cc -- 

move backward one event.

cc * 

return a description of the event currently referenced by the coordinates object.

cc contextLock 0|[1 contextName] 

If the second argument is 0, this command unlocks the coordinates object from any particular context. If it is 1, the third argument must be supplied and the command locks the coordinates object to the specified context.

cc eventTypeLock 0|[1 eventType] 

If the second argument is 0, this command unlocks the coordinates object from any particular event type. If it is 1, the third argument must be supplied and the command locks the coordinates object to the specified event type (by full, upper-case name, as given in the event definition file). This would be, for example, EVENT_SEMTAKE rather than semTake.

cc print 

print out the internal indexing information or status of the coordinates object.

cc timeSet time 

set the internal time of the coordinates object to the given value, then move it to the next valid event after that time.

cc destroy 

remove the cc command and destroy the associated WVCoords object.

This section shows a typical session. User input is shown in bold.

The first command loads an event base, creating the command eb and its associated context commands. The second command prints the names of all contexts. The third command uses the command form eb.contextName with the taskId argument to find the task ID for tLogTask.

% wvEventBaseLoad "eventlog.wvr" eb 
<<informational stuff during loading>> 
% eb names 
INT3 INT6 tLogTask tWdbTask tTask1 idle 
% eb.tLogTask taskId 
3567312

The fourth command uses the names command again, but assigns its result to the variable cnames. The fifth command shows the number of events in tLogTask.

% set cnames [eb names] 
INT3 INT6 tLogTask tWdbTask tTask1 idle 
% eb.tLogTask events 
514

The sixth command iterates over all context names (using $cnames) and builds a command to print the number of events for each context, using eval.

% foreach ctx $cnames { set cmd "eb.$ctx" ; eval $cmd events } 
12 
23 
514 
211 
67 
478

The sixth command displays the interval that the event log covers. The seventh command illustrates the Nth index command for a context, printing the third event in the INT6 context.

% eb interval 
0.000000 1.804050 
% eb.INT6 3 
intEnt-6 0.0100023 {} 

Upon startup, the API library sources the Tcl script:

installDir/host/resource/tcl/app-config/WindView/database.tcl 

It reads the first event in the event log (which must be EVENT_CONFIG) to determine which kernel is running on the target. It loads the appropriate event-description files for that kernel. The file defines all the events the parser can handle. It defines the event name and its binary format (the number and type of its arguments) and it also includes human-readable information regarding the nominal meaning of each argument.

The file format is free-form plain text; each entry is separated by at least one blank line. Comment lines begin with #. An entry defines a single event format and has the style:

wvEvent EVENT_NAME value {[-notimestamp] [-nosearch] [-name=altName]}{ 
    argType argName 
    argType argName [*] 
}

There can be between zero and seven arguments for a single event. The value is the 16-bit unsigned value (expressed in decimal) of the event-type. The argType field can be either UINT32 for an unsigned 32-bit integer or STRING for a textual or binary block, whose length is always defined by the previous field, which must be of type UINT32. The argName field is the name with which the argument is displayed in the WindView GUI; it must start with a lower-case character. The optional asterisk indicates the object ID argument (the argument that contains the unique object ID).

The -notimestamp option indicates that the event has no time stamp when emitted by the target, requiring that one be added by synthesis at the host. The -name argument allows a more user-friendly name to be added, if required. The -nosearch option indicates that events of this type are not reported by searches in the GUI.

Two sample event, taken from the vxworks.e file, are the following:

wvEvent EVENT_BEGIN 0 { -notimestamp -nosearch }| 
    UINT32 CPU 
    UINT32 bspSize 
    STRING bspName 
    UINT32 taskIdCurrent 
    UINT32 collectionMode 
    UINT32 revision 
}

 
wvEvent EVENT_SEMTAKE 10015 ( -name=semTake }{ 
    UINT32 recurse 
    UINT32 semOwner  
    UINT32 semId *  
}

This format allows user events to be given sophisticated descriptions. For information on instrumenting your own libraries with your own events, see Wind Technical Note #49: Instrumenting Libraries for Use with WindView.