TRCUST
------

The base version of TRCUST shipped with the Warp 3.0 and 4.0 ToolKits is 2.0.

TRCUST 3.05 provides the following enhancements and fixes since version 2.0:

Regression for NE modules, which may result in a TRAP D but also
results in an invalid TDF being generated.

MODNAME is not required for Static Tracepoints.

Supports MAXDATALEN may be specified upto 4099. Note, MAXDATALEN above 512
is permissible only on Warp 3.0 Fix Pack 35 and higher.

MAXDATALEN defaults to 512

Allows formatting controls to be specified in lower case.

Supports Major codes up to 0xffff.  Note, MAJOR code above 255 are
permissible only on Warp 3.0 Fix Pack 35 and higher.

Fixed problems with keyword order on the TRACE statement.

Allows the %C formatting control to specify an ASCII character interpretation of
a byte of trace data.

Allows the /NODE switch to bypass module debug information processing.

RETEP has been extended to work with MAP files and HLL version 4
style debugging information.

Case insensitive references to MAP file symbols is allowed.

Line number support for HLL 4 (VisualAge C++)

All TSF keywords are case insensitive.

All TRCUST parameters are case insensitive.

TSF TRACE statement keywords are now order independent.

/L= parameter introduce to allow MODNAME to specify a different filespec
    to the load module read by TRCUST.

/P  allows the path information specified with MODNAME to be retained in
    the built TDF.

Fixes a TRAP caused by large line number tables with HLL3 (CSET++ 2.01)

Fixes a TRAP caused by using non-code DLLs.

Fixes a problem where TEST, NOT and NEG instructions with opcode byte 0XF6
or 0XF7 were disallowed as tracepoints.

Fixes a problem with RETEP compatibility processing with previous versions,
adds the /RP parameter and extends /RM options.


The syntax for TRCUST 3.05 is as follows:

Usage1:  Trcust filename1 filename2 /M=mapfile /W{0|1|2} /D +
                /L=loadmod /NODE /NOLN /RM{0-6} /RSnnn /I /P

        filename1  is Trace Source File
        filename2  is Trace Defintion File      (Optional)
        /M=mapfile is map filename to use       (Optional)
        /W{0|1|2}  is warning level to use      (Optional)
        /D         allows duplicate minors      (Optional)
        /L=loadmod is file name of load module  (Optional)
        /NODE      ignore debug information     (Optional)
        /NOLN      ignore line numbers          (Optional)
        /RM{0-7}   RETEP match criteria         (Optional)
        /RSnnn     RETEP search range           (Optional)
        /RP        RETEP Pascal returns allowed (Optional)
        /I         Case insensitive map symbols (Optional)
        /P         Retain MODNAME Path Info     (Optional)

Usage2:  Trcust filename1 /C=dest_tff /W{0|1|2}

        filename1  is Trace Combine File containing TFF filenames
        dest_tff   is destination TFF name for combined records
        /W{0|1|2}  is warning level to use      (Optional)


Usage 1 has introduced sever new parameters and some previouly
undocumented parameters, which are now described:

/L=loadmod allows TRCUST to use a different file specification to the
       name specified by the MODNAME TSF statement.

       TRCUST needs to exctract information from the load module to
       generate the TDF. The module name is also required by the
       TRACE command and so is recorded in the TDF from the MODNAME
       statemenmt. /L is useful in cases where a module is built
       using one name and subsequenlty renamed when installed,
       or where the load module is built in a target directory
       which differs from that of the TSF.


/NODE  forces TRCUST to ignore debugging information even if present.
       This is provide for cases where

       a)  the user wishes to use MAP symbols in preference to
           debugging info.
       b)  the level of debugging info in not supported by TRCUST and errors
           are produces if it is used.

 NB debugging information is not a public standard. Some compilers may
 appear to emulate Code View level 0, HLL 3 or HLL4, which not
 actually doing so.

/NOLN 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.

      N.B /NODE implies /NOLN

/I allows MAP file references to public symbols to be made case
insensitively.

/RM{0-7} specfifes the default Return Entry Point (RETEP) match
         criteria. By default, RETEP will use mode 2, however the
         following modes may be specified:

         0  - Disallow RETEP.

         1 - Take RETEP from Code View symbol records only. NB HLL does
             not provide return information.

         2 - Use mode 1 then search for a LEAVE+RET  or POP EBP 
             instruction sequence near the end of the routine.

         3 - Use mode 2 then search for an isolated LEAVE instruction
             near the end of the routine.

         4 - Use mode 2 then search for an isolated RET instruction
             near the end of the routine.

         5 - Use modes 2 and 3 combined. Version 2.0 of TRCUST uses this
             search mode. 

         6 - Use mode 4 then search for an isoloted JMP instruction
             near the end of the routine.

         7 - Use mode 6 but search for an isolated LEAVE instruction
             near the end of the routine, before searching for JMP.

        NB Determination of RETEP is subject to the following
           limitations:

         1 - Only the last return from a routine is located.

         2 - Only mode 1 can accurately determine the last return, however
             this is only available to code-view version 0 modules.

         3 - Searching for instruction sequences may result in a tracepoint
             erroneously being placed within an instruction.

         4 - It may not be possible to use RETEP to define the return
             tracepoint for modules that  use private (particularly optimised)
             calling conventions.

         5 - The default mode is 2. This reasonably safe. Higher modes are less
             safe.

         6 - Use mode 5 for compatible behaviour with earlier versions of TRCUST.
             However, note that earlier versions of TRCUST erroneously permitted 
             certain tracepoints which are not permitted using mode 5.

         7 - To avoid possible errors, JMP instructions with opcode 0xff are not 
             selected.

/RP modifies RETEP processing to allow Pascal Return instructions (RET n) to be 
    included in the search criteria with normal returns. Use this with 16-bit 
    code where you know pascal returns are generated.


/RSnnn 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.


The RETEP keyword of the TSF  TRACE statement has been extended to
allow specific RETEP search criteria to be specified per tracepoint.
The syntax for RETEP is:

 RETEP[=options]

where options may be a combination of the following keywords
separated by + signs:

CV    - use CV information

LRET  - search for a LEAVE+RET or POP EBP + RET sequence near
        the end of the routine.

RET   - search for RET instruction near the end of the routine.

JMP   - search for JMP instruction near the end of the routine.

LEAVE - search for a LEAVE instruction near the end of the routine.

If more than one option is specified the RETEP uses the
following order of precidence:

CV, LRET, RET, LEAVE, JMP