UserTracing is an advanced feature for various tracking/timing/troubleshooting needs. When looking at the performance of libraries and middleware generally, it can be useful to trace calls to some of the middleware functions, such as those reading files or evaluating table lookups.

CabMasterPro has the capability to time cabinet placement and other events such as lookups and file reading functions to the nearest millisecond.

To turn tracing on/off, first make sure that the main window has the focus by clicking on the title bar to ensure that it is active. Next use the hotkey Ctrl+Shift+F11. The system will beep when you turn it on and in a different way when you turn it off so you can toggle it at will.

When tracing is first turned on, a file called !Trace!.txt will be created in the nominated ProgramFolder. This is a tab-separated file which can be imported into Microsoft Excel to filter, sort and examine.

Columns

The first column is a timestamp to the nearest millisecond. The format of this column is a string with a leading T. This is so when you right click on the file and "Open With" Excel, it does not mess up this column by trying to interpret it. It comes into Excel as a string field, but Excel will sort correctly on it using alpha sorting because it explicitly has leading zeros where necessary.

The second column is the "context" that the formula was evaluating in. This is usually the name of a cabinet or section or component. Sometimes the context will be empty.

The third column is the function being executed.

Following columns are optional. For lookup functions they will usually provide information about what is being looked up. But if it is a formula or type that needs conversion to a string or number, then it may only display the type (eg YesNo). Not all parameters are necessarily displayed, but where they are displayed, they will be the first of the available parameters.

The trace file (called !Trace!.txt) is opened for write but allows sharing so you can look at it during a test session.

Output is flushed every minute, and is also flushed whenever you toggle the tracing status with Ctrl+Shift+F11. And it is flushed when you finish running the program of course.

Mask bits

The registry options has a key UserTraceMask which controls which events are traced. By default, all events are traced.

• TableLookups and a few other functions: 0x01
• Cabinet placement timings: 0x02
• Formula Evaluations: 0x04
• Component reporting: 0x08
• Component name changes: 0x10
• HSection name changes: 0x20
• OpenGL tracing: 0x40 // USERTRACE MASK
• Turn off timestamps in release mode UserTrace output: 0x80 (for easier trace filediff comparisons)
• Flexi3D tracing messages to/from Flexi: 0x100
• HSection importing, changes to document, notifications tracing: 0x200

To control multiple features, simply add the numbers corresponding to the features you want. For example, if you want to trace cabinet placements and formula evaluations set UserTraceMask to 4 + 2 = 6.

User Tracing Supported

Feature	Parameters
RELOAD QLT	tablename
BEGINTRANS QLT	tablename
COMMITTRANS QLT	tablename
ROLLBACK QLT	tablename
UPDATE QLT	tablename
CALL	filename
ROWCOUNT	vv1
COLCOUNT	vv1
COLLABELS	vv1
ROWLABELS	vv1
READANDINCREMENT	filename
COLVALUES	vv1, vv2
ROWVALUES	vv1, vv2
COLVALUESBYINDEX	vv1, vv2
ROWVALUESBYINDEX	vv1, vv2
COLLABEL	vv1, vv2
ROWLABEL	vv1, vv2
READFILE	filename
READLINE	filename
WRITELINE	filename
APPENDLINE	filename
LOOKUP	vv1, vv2, vv3
LOOKUPEXACT	vv1, vv2, vv3
LOOKUPBYINDEX	vv1, vv2, vv3
COLLABELSFORROW	vv1, vv2, vv3
ROWLABELSFORCOL	vv1, vv2, vv3
COLLABELSFORVAL	vv1, vv2, vv3
ROWLABELSFORVAL	vv1, vv2, vv3
ROWVALUESFILTERBYROW2	vv1, vv2, vv3
COLVALUESFILTERBYCOL2	vv1, vv2, vv3
COLLABELSFORROW2	vv1, vv2, vv3
ROWLABELSFORCOL2	vv1, vv2, vv3