The syntax for processing a TSF file is as follows:
[d:][path]TRCUST [d:][path]tsf [[d:][path]tdf] [/M=mapfile] [/Wn] [/D]
[/L=loadmod] [/NODE] [/NOLN] [/RMn] [/RSnnn] [/I] [/P]
[/PREINV] [/RAS]
where:
TRCUST
is the name of the Trace Customizer program. A drive and path may optionally be specified to explicitly define the location of the Trace Customizer program, otherwise the program is searched for in the current directory, followed by looking along the path defined by the PATH environment variable.
is the name of the trace source file. If no file extension is provided then an extension of TSF is assumed. If no path is provided the trace source file is searched for in the current directory, followed by using the current value of DPATH.
is the name of the trace definition file to store the dynamic tracepoint definitions. If not specified, the TSF filename is used with an extension of TDF. If no file extension is provided then an extension of TDF is assumed.
allows duplicate minor codes to be used. This is useful where there is no need to distinguish different tracepoints which create records of the same format. For exmaple, multiple return points from a subroutine.
allows case-insensitive references to MAP file symbols to be used in TSF TRACE statements.
specifies the load module path and file name to be read by TRCUST. If not specified TRCUST uses the specification in the MODNAME statement of the TSF. If no path information is given in the MODNAME statement TRCUST assumes uses current directory and DPATH to locate the load module.
MODNAME is required by the TRACE command to allow it to load and determine the traced module's handle. /L is useful in cases where the load module is built using a name that differs from the installed name or where path information is required on the MODNAME statement for the TRACE command which differs from the directory used when the TDF is built. See also the /P switch for TRCUST.
defines mapfile as the MAP file for this module. The name may be qualified by a drive/directory, otherwise it will be searched for in the current directory followed by the path specified by the DPATH environment variable. If specified as an option, the MAP file must exist and the filename extension must be MAP or TRCUST will abort processing. The mapfile will only be used if a symbol is not found in the symbolic debug information stored in the executable module.
forces TRCUST to ignore debugging information even if present. This is provided for cases where
a) the user wishes to use MAP symbols in preference to debugging information.
b) the level of debugging information in not supported by TRCUST and errors are produces if it is used.
Debugging information is not a public standard. Some compilers may appear to emulate supported styles of symbolic debugging information while not actually doing so.
TRCUST supports the following debugging information styles:
IBM C and C6 CodeView NB00 and NB02 styles.
IBM CSet/2 HLL version NB03 style.
IBM CSet/2++ and IBM VisualAge V1 to V3 HLL version NB04 styles.
IBM ALP assembler Debugging Informaion (HLL version NB04).
Any compiler or assembler that conforms to the HLL NB00 - NB04 debugging information styles.
forces TRCUST to ignore module line number records but honor any other debugging informantion present. This option is provided for cases where line number information does not conform to supported specifications and causes unpredictable results. Currenty TRCUST is limited to supporting no more then 64K of line number information. For exceedingly large source files this limit could be exceeded.
Note:
/NODE implies /NOLN
allows the path information specified with MODNAME to be retained in the TDF. The default is to strip path information from the module name. With no path information the TRACE command will rely on PATH, LIBPATH or the command line specification to the TRACE command to locate the traced module.
allows a tracepoint to be placed after the MOV (E)BP,(E)SP instruction on entry to a routine where local variable references will be valid. This is intended for use where local data refences are made from the TSF, but the tracepoint is definied by reference to the routine's MAP file symbol name. In general it is better to use number references since /PREINV relies on the style of code generated by the compiler used. See name specification of the TP statement for information on difference between MAP file symbol references and symbolic debugging information references.
Note: PREINV does not search for the equivalent ENTER instruction.
allows major code 0 trace definitions to be generated.
Note: Major code 0 is reserved by the system for system trace internal processing. The /RAS option should not be used except for the express purpose for which it is intended.
specifies the mode by which the RETEP keyword of the TSF TRACE statement will operate. Eight modes of RETEP operation are defined as follows:
This is the default RETEP processing mode.
Note: Version 2.0 of TRCUST only uses this search mode but is less reliable than mode 2 alone.
Warning:
Use of RETEP can run the risk of having a tracepoint not generated on an
insruction boundary. The result of which would be unpredictable and probably
cause the traced program to trap. This risk is grealty reduced by allowing
the RETEP mode to default to /RM2. If the user chooses to widen the
RETEP criteria then appropriate validation of the resulting tracepoints
must be made.
Note:
Successful location of return tracepoints can only be guaranteed with unoptimised IBM C and C6 CodeView information where the return point is given explicitely. More advanced compilers do not necessarily generate a single return point. They may even generate common epilog code for multiple routines hence the following limitations should be noted:
Only the last return from a routine is located.
Only mode 1 can accurately determine the last return, however this is only available to code-view version 0 modules.
Searching for instruction sequences may result in a tracepoint erroneously being placed within an instruction.
It may not be possible to use RETEP to define the return tracepoint for modules that use private (particularly optimised) calling conventions.
The default mode is 2. This reasonably safe. Higher modes are less safe.
Use mode 5 for compatible behaviour with earlier versions of TRCUST. However, note that earlier versions of TRCUST erroneously permit certain tracepoints which are not permitted using mode 5.
To avoid possible errors, JMP instructions with opcode 0xff are not selected in modes 6 and 7.
modifies RETEP processing to allow Pascal Return instructions (RET n) to be included in the search criteria for return tracepoint location. Use this with 16-bit code where you know that pascal returns are generated.
specifies how far RETEP will search from the end of a routine to find the return instruction sequence. This defaults to 18 bytes however RETEP will not search before the start of the routine.
is the level of error messages to be displayed, where n can be 0, 1, or 2. The possible message levels are shown below along with the messages that each displays:
A message level of 2 is the default.