sm_trace

Programming Guide

Create event trace and dump files
int sm_trace(char *commands);
commands
Commands to execute.

Returns

· 0: no errors found in commands.

· SM_EQUALS: No equal sign following a DUMPFILE; FRAMES or TRACEFILE command.

· SM_FORMAT: a non-alphabetic character was found in a command.

· SM_MALLOC: a call to the malloc C function has failed.

· SM_MISSARGS: commands is the null pointer; the null string or just whitespace.

· SM_NOFILE: unable to open the file in a DUMPFILE or TRACEFILE command.

· SM_NOT_LOADED: DUMP command when DUMPFILE is not specified.

· SM_NUMBER: DUMP command when FRAMES is zero or the FRAMES command value is not one or more digits.

· SM_QUOTE: DUMPFILE or TRACEFILE value starts with a quote character but a matching terminating quote was not found.

· SM_SYNTAX: character after the closing quote in a DUMPFILE or TRACEFILE is not a NUL or whitespace.

· SM_VERB_UNKNOWN: command is not valid.

Description

sm_trace can create trace and dump files containing information about Panther events. The events that are reported in these files can be selected. The commands parameter is series of command tokens that control operations. Most tokens can be prefixed with NO to reverse their effect. The case of tokens is ignored but they will be capitalized in this manual.
sm_trace was first released in Panther 5.30.
Trace files are written as events occur. The following commands control trace files:

TRACEFILE=

File to write event information to. The file name should be quoted if it contains spaces. Use the null string "" to stop tracing and to close the current TRACEFILE.

TRACE

Used to control whether event information is to be written to TRACEFILE. Default is TRACE. You can use NOTRACE to disable tracing to reduce the size of the trace file when nothing of interest is happening.

Dump files are written when the DUMP command is executed. The number of events to store for reporting is controlled by the FRAMES= command. The following commands control dump files:

DUMPFILE=

File to write information to. The file name should be quoted if it contains spaces.

DUMP

Used to cause information is to be written to DUMPFILE.

FRAMES=

Specifies how many events are to be stored for writing by the DUMP command. 500 is the default.

The following commands control how files are opened:

OVERWRITE

Specifies that existing files should be overwritten. It is the default.

APPEND

Specifies that existing files should be appended to.

The following commands control which events are to be logged:

CSTR

Control String events.

DBI

Database events.

FIELD

Field entry, exit and validation events.

FUNCTION

Installed function call and return events.

GRID

Grid and grid row entry, exit and validation events.

GROUP

Group entry, exit and validation events.

JAVA

Java events.

JPL

JPL execution events.

KEY

Key being taken off the key queue events.

LDB

Local Data Block events.

RW

Report Writer events.

SCREEN

Screen entry, exit and expose events.

TM

Transaction Manager events.

ALL

All of the above events. This is the default.

CORE

All of the above events except for DBI, RW and TM.

NONE

The same as NOALL.

The following command causes parameters to be displayed:

PARMS

Causes parameters to be displayed for calls to functions, including JPL functions. The default is NOPARMS.

To enable tracing to begin at startup, the SMTRACE application variable can be included in a SMVARS or SMSETUP setup file, for example:
SMTRACE=NOJAVA FRAMES=100 TRACEFILE="c:\temp\forex.trc"
SMINITJPL in a setup file can also be used to call sm_trace, for example:
SMINITJPL=call sm_trace('PARMS TRACEFILE="c:\temp\forex.trc"')
When debugging a program, sm_trace can be called from the debugger to produce a dump file. For example, one can call:
sm_trace("DUMPFILE='dump1.dmp' DUMP")
to create a dump file named "dump1.dmp" with the most recent trace information.

`TRACEFILE=`	File to write event information to. The file name should be quoted if it contains spaces. Use the null string "" to stop tracing and to close the current `TRACEFILE`.
`TRACE`	Used to control whether event information is to be written to `TRACEFILE`. Default is `TRACE`. You can use `NOTRACE` to disable tracing to reduce the size of the trace file when nothing of interest is happening.

`DUMPFILE=`	File to write information to. The file name should be quoted if it contains spaces.
`DUMP`	Used to cause information is to be written to `DUMPFILE`.
`FRAMES=`	Specifies how many events are to be stored for writing by the `DUMP` command. 500 is the default.

`OVERWRITE`	Specifies that existing files should be overwritten. It is the default.
`APPEND`	Specifies that existing files should be appended to.

`CSTR`	Control String events.
`DBI`	Database events.
`FIELD`	Field entry, exit and validation events.
`FUNCTION`	Installed function call and return events.
`GRID`	Grid and grid row entry, exit and validation events.
`GROUP`	Group entry, exit and validation events.
`JAVA`	Java events.
`JPL`	JPL execution events.
`KEY`	Key being taken off the key queue events.
`LDB`	Local Data Block events.
`RW`	Report Writer events.
`SCREEN`	Screen entry, exit and expose events.
`TM`	Transaction Manager events.
`ALL`	All of the above events. This is the default.
`CORE`	All of the above events except for `DBI`, `RW` and `TM`.
`NONE`	The same as `NOALL`.