MAKETSF 1.1
-----------

The purpose of MAKETSF is to extract dynamic trace definitions imbedded
in C or ASM source file to which they relate. MAKETSF will also
substitute line number information into those trace definions that are
specified by line number and source file reference.

For example:

  TRACE TP=@myprog.c,1234

This specifies a tracepoint at location corresponding to line 1234
in module whose source is "myprocg.c".

The problem with this type of specification is that line number
reference will need to be updated whenever the source is changed.

MAKETSF allows the trace definitions to be imbedded in the source as
comments but in extraction will generate the correct line number
information. It does this be detecting the string "TP=@," or "TP=@ "
and then inserting the line number specification. If the TP=
keyword explicitly specifies an address expression then the trace
definiton is extracted without modification.

To use line number references modules must be compiled and linked
with debugging information. For CSET2 the compile option is /TI, and
the LINK386 option is /DE.

Warning: Optimised code may not place tracepoints in the desired
location.


For example:
in C:

    +-------------------------------------------+
    |/***DT here is the header                  |
    | * MODNAME=my.exe                          |
    | * MAJOR=256                               |
    | */                                        |
    |                                           |
    |                                           |
    |                                           |
    |void myproc(char * parm1) {                |
    |int result;                                |
    |                                           |
    |.                                          |
    |.                                          |
    |.                                          |
    |                                           |
    |/***DT tracepoint definition               |
    | *   TRACE TP=@,                           |
    | *   DESC="a tracepoint",                  |
    | *   MEM32=(.parm1,I,4),                   |
    | *   MEM32=(.resut,D,4),                   |
    | *   FMT="parm1=%p%f result=%f"            |
    | */                                        |
    |                                           |
    |                                           |
    |                                           |
    +-------------------------------------------+



    in ASM:

    +-------------------------------------------+
    |;***DT here is the header                  |
    |;  MODNAME=my.exe                          |
    |;  MAJOR=256                               |
    |                                           |
    |                                           |
    |parm1 DD ?                                 |
    |                                           |
    |myproc proc                                |
    |       push ebp                            |
    |       move ebp,esp                        |
    |.                                          |
    |.                                          |
    |.                                          |
    |                                           |
    |;***DT tracepoint definition               |
    |;   TRACE TP=@,                            |
    |;   DESC="a tracepoint",                   |
    |;   MEM32=(.parm1,D,4),                    |
    |;   FMT="parm1=%p%f"                       |
    |                                           |
    |                                           |
    +-------------------------------------------+

Notes: The comment block must begin in column 1 with either
       ;***DT or /***DT.

       If the C form is used then an * must appear in column 2 of each
       line. A */ in column 2 ends the comment block.

       If the ASM form is used then a ; is required in every column.

       If TP=@ is coded then MAPTSF will insert the file name and line
       number corresponding to the trace definition.

MAKETSF  will respond to the $include <filename> directive if coded
in column 1. This is intended for use where multiple source modules
comprise a single load module. A list of component source files can
be coded in a single file using include statements then given to
MAKETSF for processing. For example:

    +-------------------------------------------+
    |;A sample include file for MAKETSF         |
    |                                           |
    |                                           |
    |$include myprog.c                          |
    |$include ..\asm\myproc.asm                 |
    |$include ..\sub\subr.c  This is a comment  |
    |                                           |
    +-------------------------------------------+


MAKETSF will ignore any line that is not part of a ;***DT or /***DT
comment block or a $include statement.

TSF output form MAKETSF is written to the output file if specified,
otherwise to STDOUT.

Messages are written to STDERR.

There are five switch options that MAKETSF supports:

-v verbose mode - this gives information about number of files read
   and blocks processed.

-n no includes - this forces MAKETSF to ignore $include directives.

-p include source file path info  - this forces MAKETSF to retain
   the full file specification from $include statements or the
   command line input file in the TP= keyword.
   The default is to strip path information.

-a append output to output file. Default - replace output file

-o<output> specifies the output file. The default is to direct output
   to STDOUT.

The syntax for MAKTSF is:

    MAKETSF <options> input