Click or drag to resize

Tracing the Execution of an IVI-COM Driver

All IVI-COM drivers produced with Nimbus are instrumented with special code that can trace the execution of the driver when used in an application. Tracing is controlled via special Nimbus-defined tracing parameters passed to the driver in the DriverSetup parameter of the Initialize method. Because tracing is controlled via the Initialize method, this feature is available to end users working with a deployed driver as well as driver developers authoring a driver.

When tracing is enabled, the following information is recorded by the Nimbus-generated code and stored in a trace log file:

  • The method or property name.

  • The value of each [in] and [in, out] parameter passed from the application to the driver.

  • The value of each [out] and [in, out] parameter returned from the driver to the application.

  • The local system date and time at which the driver method or property began executing.

  • The total execution time for the method or property.

Important note Important

Enabling tracing adds overhead to driver execution. Typically, tracing should only be enabled for diagnostic purposes.

Controlling Tracing with the Initialize Method

By default tracing is not enabled in an IVI-COM driver. The end user must explicitly enable tracing by passing Trace=True as part of the DriverSetup parameter in the driver's Initialize method. This is demonstrated in the following C# code:

C#
driver.Initialize("GPIB::15", true, true, "DriverSetup= Trace=True");

Several other DriverSetup parameters are available for controlling the tracing features of Nimbus IVI-COM drivers. These options are presented in the table below:

DriverSetup Option

Description

Values

Trace

Enable or disable tracing.

true,false

TraceName

If specified, an XML trace file of the specified name is created each time the driver is initialized with tracing enabled.

If not specified, tracing generates a unique XML trace file name based on the date and time. A new file is created each time the driver is initialized with tracing enabled.

If TraceName is a fully qualified path, then the trace log is written to the specified path. If TraceName includes no path information then the file is stored in the current working directory of the calling application. See the section below on The Trace Log File for details.

String name

TraceArray

Specifies if array parameters should be traced.

true,false

TraceArraySizeMax

Specifies the maximum number of elements to trace for array parameters. The default value is 10.

Numeric value in elements

TraceSizeMax

Specifies the maximum size of the trace log file in bytes. Once the file reaches this size, tracing will be turned off automatically by the driver. The default value is 1000000.

Numeric value in bytes

TraceSaveInterval

Specifies how often the driver should save trace data to the trace log file. The value is specified in minutes. The default value is 1.

Numeric value in minutes

The Trace Log File

The trace data collected by the driver during execution is periodically saved to an XML log file. When the driver is closed, the trace log file is closed. If the TraceName option is not specified, Nimbus creates a new trace log file each time the driver is initialized. The trace log file has a name of the following form:

<driverIdentifier>_<timeStamp>.xml

where <timeStamp> is of the form:

yyyy-mm-dd_hr-min-sec

It is important to understand where the trace log file is stored when tracing is enabled. The folder can be controlled by including a fully qualified path in the TraceName option passed to the Intialize method. If the TraceName option does not include path information, then the trace log is written to the current working directory. This folder is determined by the calling application. The trace log file is written to the same folder where the calling application executable (.exe) resides.

Important note Important

When running the IVI-COM driver unit test, the calling "application" is the Nimbus unit test execution engine (MindWorks.IviDriverUnitTestHost.exe). This file is located in the Nimbus installation folder (typically a folder such as C:\Program Files\Pacific MindWorks\Nimbus 2.1). Thus, Nimbus will attempt to write the trace log file to that folder. If User Account Control (UAC) is enabled, then the Program Files folder under which Nimbus is installed may not accessible, in which case the trace log file may not be written. For this reason, it is typically best to specify a full path with the TraceName option when tracing IVI-COM driver unit tests.

Download a complete CHM version of this documentation here.