DriverTrace

Controls the listing of driver control blocks (DCBs) between the I/O server and drivers. It can be useful in debugging a driver, for example, it can help determine why a driver is unable to fully initialize.

This command supports the same functionality as the Citect.ini parameter [Debug]DriverTrace, though the traces can be applied dynamically during a session. The Kernel command also provides an additional DUMP option when running on an I/O server (see below).

Note: Running syslog traces can draw heavily on a CPU usage. monitor the impact on CPU performance when implementing a large number of traces.

Syntax

DriverTrace [OFF|CMDS|VER[BOSE]|ERR[OR]|PORT=<name>|MASK=<xxxxxxxx>|DUMP]

Where:

• blank

  Returns the current DriverTrace settings. This can be useful to determine the current mask or port settings before implementing a new trace. Just key DriverTrace into the Kernel and hit the return key to view the current settings.

• OFF

  Turns the DriverTrace off.

• CMDS

  Turns the DriverTrace on, but does not display the contents of the data buffer.

  Note: Specific driver commands need to be enabled with the Kernel command DriverTrace[Mask], or the DriverTraceMask INI parameter.

• VER[BOSE]

  Turns the DriverTrace on, and displays the contents of the data buffer.

  Note: Specific driver commands need to be enabled with the Kernel command DriverTrace[Mask], or the DriverTraceMask INI parameter.

• ERR[OR]

  Turns the DriverTrace on, but only traces DCBs with errors (DCBs are the internal data structures used for communication between the I/O server and a driver).

• PORT

  Allows traces to be limited to a particular driver port, by defining a port name. The default setting, PORT=*, will trace all ports.

• MASK

  A 4-byte hexadecimal number that represents a bit mask used to either include or exclude driver commands from the DriverTrace. The driver commands and their values are as follows:

For example, the value you would use to include only the CTDRV_OPEN, CTDRV_INIT_UNIT and CTDRV_READ commands would be: 0000001A.

Most users will want to exclude the CPU function call, as this happens often. Do this by setting a mask of 7ffffeff.

The default <mask> is 7FFFFFFF.

• DUMP

  Sends a list to the I/O server's syslog.dat file that provides a snapshot of the driver control blocks (DCBs) in the various I/O server queues.

Examples

-> 07f96fdc Cmd: 03 CTDRV_INIT_UNIT ,MOCKOPC, Port: PORT1, Unit: IODev1
(UR0,N1)
| 07f96fdc UnitType: 0 (0x0), UnitAddr: 0 (0x0), BitWidth: 1, UnitCount: 16
<-07f96fdc Cmd: 03 CTDRV_INIT_UNIT ErrDriver 23 (0x17) and took 0ms
-> 07ff1584 Cmd: 04 CTDRV_READ ,DISKDRV, Port: DISKDRV, Unit: IODevDisk
(UR1,N2)
| 07ff1584 UnitType: 1 (0x1), UnitAddr: 1 (0x1), BitWidth: 16, UnitCount: 5,
RawType: INTEGER
<+07ff1584 Cmd: 04 CTDRV_READ ErrDriver 0 (0x0) and took 0ms
<+07ff1584 UnitType: 1 (0x1), UnitAddr: 1 (0x1), BitWidth: 16, UnitCount: 5,
RawType: INTEGER
<+07ff1584 000: 1 0 0 0 5
~> 00000000 Cmd: 25 CTDRV_SUBSCRIBE ,MOCKOPC, Port: PORT1, Unit: IODev1
(UR0,N1)
>-00000000 SUBSCRIBE Tag=Tag4 UpdateRate=500ms
~< 000003e9 Cmd: 26 CTDRV_EVENTUPDATES,MOCKOPC, Port: PORT1, Unit: IODev1
(UR0,N1)
<-000003e9 DS Event UPDATE_MODE=ALL Tag=Tag4 RawValue=0x00
Timestamp=<time_not_set> RawQual=0x0000 DSError=0 (0x0)

Explanation of arrows used above

-> Flags information going down to the driver

|

<- Flags information back from the driver straight away

<+ Flags information back from the driver asynchronously (i.e. after some small time delay)

~> Flags subscription based calls into the driver

>-

~< Flags subscription based updated from the driver

<-

(URx,Ny) addition to UNIT and Data driver traces

UR stands for Unit Record number and is 0 based, so a value of 3 would be the 4th device in the IODevice settings. N stands for the (Network) Number in the IODevice settings. The use of this is to distinguish between redundant units which may use the same unit name. Thus the trace will positively confirm which unit is in use.

See Also

Kernel Commands

Display the Kernel Window