Using the MAPTSF Utility

The MAPTSF utility will generate a TSF from a MAP file. One tracepoint is generated for each public code symbol. Optionally a return tracepoint may be generated for each public code symbol.

The syntax for MAPTSF is as follows:

         MAPTSF map_file [/MAJOR=major_code]
                         [/MODNAME=name]
                         [/MAXDATALENGTH=max_data_length]
                         [/MINORSTART=minor_code]
                         [/TEMPLATE=template_file]
                         [/LOGSTACK=stack_bytes]
                         [/EXCLUDE=string[*][,....]]
                         [/INCLUDE=string[*][,....]]
                         [/REGISTERS=reg[,reg]...]
                         [/LOGRETURN]
                         [/RETEP]
                         [/CASESENSITIVE]
                         [/TYPES]
                         [/GROUPS=string[,.....]]

There is only one required parameter: map_file, which specifies the input MAP file. The remaining parameters are optional and have the following meaning:

• MAJOR
  specifies the major code to be used in the MAJOR= statement of the TSF . If omitted, TRCUST will select the default major code of 1 when compiling the TSF.
  /MODNAME
  specifies the module name to be used in the MODNAME= statement of the TSF. If omitted, MAPTSF will use the module name that appears in the second line of the MAP file. Note, the MAP file excludes the module extension. TRCUST will assume an extension of .DLL if not specified.
  /MAXDATALENGTH
  specifies the MAXDATALENGTH= statement of the TSF. If omitted, TRCUST will assume the default of 512 when compiling the TSF.
  /MINORSTART
  specifies the first minor code. Subsequent tracepoints have incremental minor codes. If omitted, the MINOR= statement is not generated. TRCUST will assume an initial minor code of 1 and increment for each tracepoint.
  /INCLUDE
  specifies a comma delimited list of case insensitive strings used as inclusion criteria for public symbols. An optional trailing * signifies a generic match. If both /INCLUDE and /EXCLUDE are specified then the logical OR of their criteria is used for selection. For example:

  • I=dos*,strupr inludes all public symbols beginning 'dos' or equal to 'strupr'.

  • E=s* /I=strupr excludes all public symbols beginning 's' except for 'strupr' and includes everything else.
  /EXCLUDE
  specifies a comma delimited list of case insensitive strings used as exclusion criteria for public symbols. An optional trailing * signifies a generic match. If both /INCLUDE and /EXCLUDE are specified then the logical OR of their criteria is used for selection. For example:

  • E=_*,dos* excludes all public symbols beginning '_' or 'dos'.

  • E=s* /I=strupr excludes all public symbols beginning 's' except for 'strupr' and includes everything else.
  /CASESENSITIVE
  switch applies to /INCLUDE and /EXCLUDE. If specified then the inculde and exclude strings will be match on a case-sensitve basis.
  /LOGSTACK=n
  specifies the number of bytes of stack to log for entry tracepoints. This causes the following TSF statements to be generated for each entry tracepoint:

  for 16-bit code -

  
          REGS=(SP,SS),
          FMT="Stack pointer SS:SP=%A->",
          MEM=(RSS+SP,D,n),
          FMT="%R%W"
  
  

  for 32-bit code -

          REGS=(ESP),
          FMT="Stack pointer ESP=%F->",
          MEM32=(FESP,D,n)
          FMT="%R%F"
  
  

  If /LOGSTACK is specified without a value then 16 bytes is assumed.
  /LOGRETURN
  specifies that for each return tracepoint, the return value in AX/EAX should be logged. This causes the following TSF statements to be generated:

  for 16-bit code:

          REGS=(AX)
          FMT="Returns (ax) %W"
  
  

  for 32-bit code:

          REGS=(EAX)
          FMT="Returns (eax) %F"
  
  

  /REGISTERS
  specifies one or more processor registers to be logged, each separated by a comma. The following register mnemonics are supported:

  
          AX,BX,CX,DX,CS,DS,ES,FS,GS,IP,SI,DI,SP,BP,FLAGS,
          EAX,EBX,ECX,EDX,EIP,ESI,EDI,ESP,EBP,EFLAGS
  
  

  /REGS may be used as a synonym for /REGISTERS.

  /RETEP
  specifies that for each public entry-point in the MAP file, a return tracepoint should be generated using the RETEP parameter of the TRACE statement in the TSF.
  /TYPES
  specifies that generated tracepoints are to be assigned one or more of the following pre-defined types:

  PUB

  Public routines - names the begin upper case (ignoring leading underscores)
  PRIV
  Private routines - names the begin lower case (ignoring leading underscores)
  PRE
  Entry tracepoint.
  POST
  Exit tracepoint.
  /GROUPS
  Requests that each of the strings listed be used to define a group. Tracepoints are assigned to a group according to whether a group name matches the beginning of the tracepoint name, ignoring case and leading underscore characters
  /TEMPLATE
  specifies a file where up to four template tracepoint definitions may be specified, one for each of the following categories:

  16-bit entry points

  16-bit return points

  32-bit entry points

  32-bit return points

  The definitions are in a shortened form of the TRCUST TRACE statement syntax. They are appended to each tracepoint of the category to which they apply. All parameters other than MINOR and DESC are permissible. TP and RETEP are specified as follows:

  TP=@16

  signifies a 16-bit entry-point
  TP=@16,RETEP
  signifies a 16-bit return-point
  TP=@32
  signifies a 32-bit entry-point
  TP=@32,RETEP
  signifies a 32-bit return-point
  Only TP and RETEP may appear on the same line as the TRACE keyword.

  For example:

  
          TRACE TP=@16
                MEM=(SS:BP+8,I,0x10)
                FMT="16-bytes of parameter 1: %R%W"
  
  

  will append

  
                MEM=(SS:BP+8,I,0x10)
                FMT="16-bytes of parameter 1: %R%W"
  
  

  to every 16-bit entry tracepoint definition.

  ---

  [Back: Using the DEBDEL Utility]
  [Next: System Tracepoints Reference]