home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / ddkx86v1.zip / DDKX86 / BOOK / TRCUST.INF (.txt) < prev    next >
OS/2 Help File  |  1993-11-30  |  57KB  |  2,046 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. Dynamic Trace Customizer(TRCUST) ΓòÉΓòÉΓòÉ
  3.  
  4.  
  5. ΓòÉΓòÉΓòÉ 1.1. Description ΓòÉΓòÉΓòÉ
  6.  
  7. OS/2 provides a mechanism by which developers may dynamically apply tracepoints 
  8. in their module at run time.  This method eliminates all overhead of tracing 
  9. when tracing is disabled. It also allows the developer to add tracepoints 
  10. without modifying source code.  This reduces the possibility that adding a 
  11. tracepoint will induce errors into one's code.  OS/2 needs a binary file, for 
  12. each module being dynamically traced, which defines the tracepoints for the 
  13. module. 
  14.  
  15. The Trace Customizer(TRCUST) converts tracepoint definitions from a trace 
  16. source file(TSF) into dynamic tracepoints for the trace definition file(TDF), 
  17. and into formatting rules in the trace format file(TFF).  Definitions 
  18.  
  19. .TSF  An ASCII file created by a developer which defines all dynamic 
  20.       tracepoints for a given module. TRCUST currently allows at most only one 
  21.       major code per TSF. 
  22. .TDF  A binary file, created by TRCUST, using the .TSF file as input.  This 
  23.       file defines all tracepoints in the module in a manner acceptable to 
  24.       OS/2. This is used by the Trace Utility, TRACE. 
  25. .TFF  A binary file also created by TRCUST using the .TSF file.  This file 
  26.       defines how all tracepoints will be formatted.  This is used by the Trace 
  27.       Formatter, TRACEFMT. 
  28. major code A byte value used to identify the module being traced. TRCUST allows 
  29.       at most only one major code per TSF. 
  30. minor code A word value used to uniquely identify each tracepoint. 
  31. GROUP A value used to identify this tracepoint with tracepoints of the same 
  32.       category.  Examples are MEM for memory management and PM for Presentation 
  33.       Manager. For an example of uses of groups, see the online help for the 
  34.       TRACE command. 
  35. TYPE  A value used to associate a subset of dynamic trace events within a 
  36.       module. Examples are PRE for pre-invocation, POST for post-invocation and 
  37.       API for API calls within a module. For an explanation and examples of 
  38.       uses of types, see the online help for the trace command. 
  39.  
  40.  
  41. ΓòÉΓòÉΓòÉ 1.2. Overview ΓòÉΓòÉΓòÉ
  42.  
  43.  
  44. ΓòÉΓòÉΓòÉ 1.2.1. File Naming and Location ΓòÉΓòÉΓòÉ
  45.  
  46. The TDF file name is the same as the module to be traced, but has a file 
  47. extension of "TDF". The TFF has a name of the form "TRC00xx.TFF" where xx is 
  48. the major code, e.g. a module with major code 0xC2 will generate a TFF with the 
  49. name "TRC00C2.TFF". This naming convention is used to allow TRACEFMT to 
  50. dynamically generate the TFF name given only the major code. 
  51.  
  52. TRCUST can be invoked to process a TSF or to combine several TFF files into a 
  53. single TFF. For processing a TSF, TRCUST is given the name of a TSF, and 
  54. optionally: 
  55.  
  56. o the desired name of the resulting TDF 
  57.  
  58. o the MAP file name 
  59.  
  60. o the error message level 
  61.  
  62. TRCUST will store the TSF tracepoint formatting specifications in the TFF file 
  63. and if the tracepoint specified was not for a static tracepoint, the TSF 
  64. tracepoint definition will be converted into the format required by the Trace 
  65. Utility and stored in the TDF file. On errors, TRCUST will display appropriate 
  66. messages, skip any tracepoint with errors in its definition, and continue 
  67. processing the next tracepoint definition. 
  68.  
  69. For combining TFF files that use the same major code, TRCUST is given the name 
  70. of the file containing the TFF filenames to combine and the name of the file to 
  71. contain the combined trace format statements. 
  72.  
  73. TRCUST will issue an error message and abort processing under the following 
  74. conditions: 
  75.  
  76. o the TSF cannot be opened 
  77.  
  78. o when combining TFF files, if any TFF input files cannot be read or if all TFF 
  79.   input files do not use the same major code 
  80.  
  81. o when defining dynamic tracepoints, if the executable module to contain the 
  82.   tracepoints cannot be read 
  83.  
  84. o the TDF, or TFF files cannot be written to 
  85.  
  86. o an error in the header definition in the TSF 
  87.  
  88. o a missing ending quote in the TSF 
  89.  
  90. Note:  TRCUST always returns 0 so that, when invoking it from a makefile, 
  91. processing of the rest of the makefile can continue if TRCUST aborts. 
  92.  
  93. Combine TFF files when several modules that use dynamic tracing use the same 
  94. major code.  The Trace Formatter can only use one TFF file per major code to 
  95. get formatting information from. After the TSF file for each module is run 
  96. through TRCUST to produce a TDF and TFF file, TRCUST can be invoked again, this 
  97. time using the combine TFF files option and a file that only contains the paths 
  98. to all the TFF files using the same major code. TRCUST will read all the TFF 
  99. files.  If all TFF files don't use the same major code, TRCUST will issue an 
  100. error message and abort. TRCUST will read each trace format record from the TFF 
  101. files and write them(in ascending order according to minor code) to the 
  102. destination TFF file given. 
  103.  
  104.  
  105. ΓòÉΓòÉΓòÉ 1.2.2. Invoking the Trace Customizer ΓòÉΓòÉΓòÉ
  106.  
  107. The Trace Customizer is a protect mode only program and must therefore be run 
  108. under OS/2. TRCUST may be invoked to combine TFF files or to process a TSF. The 
  109. syntax for combining TFF files is as follows: 
  110.  
  111.  
  112.     [d:][path]TRCUST [d:][path]tffsource /C=[d:][path]tffdest [/Wn]
  113.  
  114. where: 
  115.  
  116. TRCUST 
  117.  
  118.     is the name of the Trace Customizer program. A drive and path may 
  119.     optionally be specified to explicitly define the location of the Trace 
  120.     Customizer program, otherwise the program is searched for in the current 
  121.     directory, followed by looking along the path defined by the PATH 
  122.     environment variable. 
  123. [d:][path]tffsource 
  124.  
  125.     is the name of a file containing fully qualified(including extensions) 
  126.     pathnames of TFF files to combine. Each TFF file must use the same major 
  127.     code and each filename in the tffsource file is separated by white space. 
  128.     This will combine all TFF files for the same major code into a single TFF 
  129.     file.  If duplicate minor code format definitions are found, the first 
  130.     format definition for the minor code remains valid, the duplicates are 
  131.     discarded and a warning message is issued. If no path is provided the 
  132.     tffsource file is searched for in the current directory, followed by using 
  133.     the current value of DPATH. 
  134. [d:][path]tffdest 
  135.  
  136.     is the name of the trace format destination file to store the combined 
  137.     trace format definitions. 
  138. /Wn (optional) 
  139.  
  140.     is the level of error messages to be displayed, where n can be 0, 1, or 2. 
  141.     The possible message levels are shown below along with the messages that 
  142.     each displays: 
  143.  
  144.     0 fatal and severe messages 
  145.     1 fatal, severe, and error messages 
  146.     2 all (fatal, severe, error, and warning) messages 
  147.  
  148.     A message level of 2 is the default. 
  149.  
  150. An example of a tffsource file for using the combine TFF files option of TRCUST 
  151. is: 
  152.  
  153.  
  154. \DRV6\SRC\PM\TRC00C2.TFF \DRV6\SRC\DM2\TRC00C2.TFF
  155. \DRV6\SRC\DOSCALLS\TRC00C2.TFF \DRV6\SRC\KB\TRC00C2.TFF
  156.  
  157. To invoke TRCUST to combine TFF files using the above file as input(assume 
  158. filename is \DRV6\SRC\TR\TFF00C2) and output the combined format statements 
  159. into file \DRV6\SRC\TR\TRC00C2.TFF is: 
  160.  
  161. TRCUST \DRV6\SRC\TR\TFF00C2 /C=\DRV6\SRC\TR\TRC00C2.TFF
  162. The syntax for processing a TSF file is as follows: 
  163.  
  164.  
  165.    [d:][path]TRCUST [d:][path]tsf [[d:][path]tdf] [/M=mapfile] [/Wn]
  166.  
  167. where: 
  168.  
  169. TRCUST 
  170.  
  171.     is the name of the Trace Customizer program. A drive and path may 
  172.     optionally be specified to explicitly define the location of the Trace 
  173.     Customizer program, otherwise the program is searched for in the current 
  174.     directory, followed by looking along the path defined by the PATH 
  175.     environment variable. 
  176. [d:][path]tsf 
  177.  
  178.     is the name of the trace source file. If no file extension is provided then 
  179.     an extension of TSF is assumed. If no path is provided the trace source 
  180.     file is searched for in the current directory, followed by using the 
  181.     current value of DPATH. 
  182. [d:][path]tdf (optional)
  183.  
  184.      is the name of the trace definition file to store the dynamic tracepoint 
  185.     definitions. If not specified, the TSF filename is used with an extension 
  186.     of TDF. If no file extension is provided then an extension of TDF is 
  187.     assumed. 
  188. /M=mapfile (optional)
  189.  
  190.      defines mapfile as the MAP file for this module. The name may be qualified 
  191.     by a drive/directory, otherwise it will be searched for in the current 
  192.     directory followed by the path specified by the DPATH environment variable. 
  193.     If specified as an option, the MAP file must exist and the filename 
  194.     extension must be MAP or TRCUST will abort processing. The mapfile will 
  195.     only be used if a symbol is not found in the symbolic debug information 
  196.     stored in the executable module. 
  197. /Wn (optional) 
  198.  
  199.     is the level of error messages to be displayed, where n can be 0, 1, or 2. 
  200.     The possible message levels are shown below along with the messages that 
  201.     each displays: 
  202.  
  203.     0 fatal and severe messages 
  204.     1 fatal, severe, and error messages 
  205.     2 all (fatal, severe, error, and warning) messages 
  206.  
  207.     A message level of 2 is the default. 
  208.  
  209.  
  210. ΓòÉΓòÉΓòÉ 1.2.3. Symbolic Debug Support ΓòÉΓòÉΓòÉ
  211.  
  212.  
  213. ΓòÉΓòÉΓòÉ 1.2.3.1. Source Level Symbolic Support ΓòÉΓòÉΓòÉ
  214.  
  215. If the module has been compiled and linked with the debug options: 
  216.  
  217.  1. /Ti on the C/Set2 language compiler for C source files 
  218.  2. /CO on the link command 
  219. then the Trace Customizer can look into the module to extract symbolic 
  220. information. In this case addresses may be specified symbolically. 
  221.  
  222. Note that not all source files must be C language,  although only public labels 
  223. from assembler routines will be found in the symbolic information.  You may 
  224. specify filename and line number, a local variable name or a global variable 
  225. name when using C routines. All symbolic names are case sensitive when the 
  226. source was compiled with debug options, but if linking in a C language program 
  227. that was not compiled with debug options, all symbolic names are case sensitive 
  228. and begin with an underscore "_" character unless the name is declared with the 
  229. Pascal calling conventions, in which case the underscore is omitted but the 
  230. symbolic name is capitalized. 
  231.  
  232.  
  233. ΓòÉΓòÉΓòÉ 1.2.3.2. MAP File Support ΓòÉΓòÉΓòÉ
  234.  
  235. The Trace Customizer can also use the symbolic information in the MAP file 
  236. produced by the linker. All public symbols will be listed with their offsets in 
  237. the module being traced. This is not as complete a support as offered by the 
  238. debug compile option for C language source files, but it does allow entry 
  239. points, public labels and global data to be referenced symbolically within the 
  240. TSF. Note that the use of a MAP file is NOT language dependent. 
  241.  
  242. Note:  When using a MAP file, if the symbolic name is a C language entry point, 
  243. it will be case sensitive and begin with an underscore "_" character unless it 
  244. is declared with the Pascal naming convention, in which case the underscore is 
  245. omitted and the name is capitalized. If the name is not from C language source 
  246. file, the name is case sensitive. 
  247.  
  248.  
  249. ΓòÉΓòÉΓòÉ 1.2.3.3. Building a Module ΓòÉΓòÉΓòÉ
  250.  
  251. To trace only public procedures, you only need your MAP file that was generated 
  252. by linking your module. 
  253.  
  254. To trace local variables in C language routines, compile the C programs with 
  255. the debug option and assemble the ASM routines with public symbols.  Link all 
  256. the OBJs together with the debug option(/CO) and run TRCUST on the executable 
  257. module. You can now strip the debug information from the executable file by 
  258. either relinking the OBJs without the debug option or by using a tool to delete 
  259. the debug information from the executable module file. 
  260.  
  261.  
  262. ΓòÉΓòÉΓòÉ 1.2.4. TDF and TFF File Usage ΓòÉΓòÉΓòÉ
  263.  
  264. The TDF, and TFF files produced by TRCUST are used in the following way: 
  265.  
  266.                                 ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  267.                                 Γöé  .TSF   Γöé
  268.                                 ΓööΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÿ
  269.                                      V
  270.                               ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  271.                               Γöé TRCUST Util Γöé
  272.                               ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  273.         ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  274.         V                            Γöé
  275.    ΓöîΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÉ                  ΓöîΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÉ
  276.    Γöé  .TDF   Γöé                  Γöé  .TFF   Γöé
  277.    ΓööΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÿ                  ΓööΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÿ
  278.         Γöé                            Γöé
  279.  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ                     Γöé
  280.  Γöé  TRACE util Γöé                     Γöé
  281.  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ                     Γöé
  282.         Γöé                            Γöé
  283. ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ                    V
  284. Γöétracepoints setΓöé                    Γöé
  285. ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ                    Γöé
  286. ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ                    Γöé
  287. Γöé tracepoint hitΓöé                    Γöé
  288. ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ                    Γöé
  289.         Γöé                            Γöé
  290. ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ                    Γöé
  291. Γöé  OS/2 kernel  Γöé                    Γöé
  292. ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ                    Γöé
  293.         Γöé                            Γöé
  294.         Γöé                            Γöé
  295.         Γöé                            Γöé
  296.         Γöé                            Γöé
  297.         Γöé                            Γöé
  298.         Γöé                            Γöé
  299.         Γöé                            Γöé
  300.         Γöé                            Γöé
  301.         Γöé                            Γöé
  302. ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ             ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  303. Γöé  trace buffer ΓöéΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ>ΓöéTRACEFMT utilΓöé
  304. ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ             ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  305.                                      Γöé
  306.                               ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  307.                               Γöé  formatted  Γöé
  308.                               Γöétrace recordsΓöé
  309.                               ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  310.  
  311.  How TRCUST fits into the system 
  312.  
  313.  Totraceamoduledothefollowing :
  314.  
  315.  1. Define the tracepoints and data to be traced in the TSF. 
  316.  
  317.  2. Invoke the Trace Customizer using the TSF as input. 
  318.  
  319.    This produces two files, a TDF and a TFF. 
  320.  
  321.  3. Put the TDF file in the same directory the module to trace resides, put the 
  322.     TFF file in a directory accessible by TRACEFMT.  It is suggested that all 
  323.     TFF files reside in the same subdirectory, an example directory could be 
  324.     \OS2\SYSTEM\TRACE. 
  325.  
  326.  4. Invoke the OS/2 TRACE command using the name of the TDF instead of the 
  327.     major code value. 
  328.  
  329.    This activates the tracepoints, causing the trace data to be saved in the 
  330.    system trace buffer. 
  331.  
  332.  5. The OS/2 TRACE command can be used to turn tracing off at any time. 
  333.  
  334.  6. To display the contents of the trace buffer, invoke the OS/2 TRACEFMT 
  335.     command. 
  336.  
  337.    TRACEFMT uses the major code to determine the TFF file and uses the 
  338.    formatting string corresponding to the minor code value to format the data 
  339.    in the RAS trace buffer and output it to the screen, file or printer. 
  340.  
  341.  
  342. ΓòÉΓòÉΓòÉ 1.2.5. Symbols and Abbreviations Used in the Document ΓòÉΓòÉΓòÉ
  343.  
  344. [...]     denotes optional items. 
  345. [... | ... | ...] denotes a list of optional items, zero or more of which may 
  346.           be chosen. 
  347. {... | ... | ...} denotes a list of items of which ONE must be chosen. 
  348. item...   denotes that item is repeated zero or more times. 
  349. statement,..... denotes this example is incomplete. 
  350. nnn       is a number in the range 0-255 inclusive. 
  351. nnnnn     is a number in the range 0-65535 inclusive. 
  352.  
  353. All numbers and values can be entered in decimal form or in C hexadecimal form 
  354. (0x....). 
  355.  
  356.  
  357. ΓòÉΓòÉΓòÉ 1.3. Trace Source File ΓòÉΓòÉΓòÉ
  358.  
  359. This section details the statements that can appear within a trace source file. 
  360.  
  361. Examples are given of TRACE statements. 
  362.  
  363.  
  364. ΓòÉΓòÉΓòÉ 1.3.1. TSF Format ΓòÉΓòÉΓòÉ
  365.  
  366. The layout of a trace source file is: 
  367.  
  368.  
  369.                 ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  370.                 Γöé        Header          Γöé
  371.                 Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  372.                 Γöé  Type List Definition  Γöé
  373.                 Γöé       (optional)       Γöé
  374.                 Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  375.                 Γöé  Group List Definition Γöé
  376.                 Γöé       (optional)       Γöé
  377.                 Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  378.                 Γöé                        Γöé
  379.                 Γöé                        Γöé
  380.                 Γöé Tracepoint Definitions Γöé
  381.                 Γöé                        Γöé
  382.                 Γöé                        Γöé
  383.                 ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  384.  
  385. Layout of a trace source file 
  386.  
  387. Notes :
  388.  
  389. o Comments may be freely inserted anywhere in the trace source file. A comment 
  390.   is identified by a ; or by using C syntax comments anywhere in the file.  A C 
  391.   comment has start and end delimiters, namely /* and */. C type comments may 
  392.   span lines, and may be nested. 
  393.  
  394. o Below are sample TSF files.  See Sample Trace Source Files for more examples. 
  395.  
  396. ;  Sample trace source file depicting dynamic tracing for OS calls compiled ; 
  397. with 32-bit addressing 
  398.  
  399.  
  400.    MODNAME = doscall1.dll
  401.    MAJOR  = 100  /* this is decimal, would be 0x64 if specified hex */
  402.    MAXDATALENGTH = 200 /* max bytes logged per tracepoint is 200 */
  403.  
  404.    TYPELIST NAME=PRE,ID=1,
  405.         NAME=SYS,ID=0x40,
  406.         NAME=API,ID=128,   /* decimal, if hex would be 0x80 */
  407.         NAME=POST,ID=0x8000
  408.  
  409.    GROUPLIST NAME=MEM,ID=2,
  410.         NAME=FS,ID=0x5,
  411.         NAME=MOU,ID=13,
  412.         NAME=DOS,ID=0x2B   /* would be 43 if decimal */
  413.  
  414.    TRACE  MINOR=0x0001,
  415.        TP=.DosOpen,      /* Pre-invocation tracing on DosOpen */
  416.        TYPE=(PRE,API),
  417.        GROUP=DOS,
  418.        DESC="(OS) DosOpen   Pre-Invocation",
  419.        FMT="Major = %X  Minor = %Y",
  420.        FMT="       EAX = %D",
  421.        FMT="       FileName = %P%S",
  422.        REGS=(EAX),
  423.        ASCIIZ32=(.FileName,DIRECT,128)
  424.  
  425.    TRACE  MINOR=0x7001,     /* Puts tracept on code at line 28 */
  426.                   /*  of file dosopen1.c.  Debug   */
  427.        TP=@dosopen1.c,28,   /*  info is needed to use this.  */
  428.        TYPE=(API),
  429.        GROUP=DOS,
  430.        DESC="(OS) CheckParm  After Createhandle",
  431.        FMT="         New handle = %P%W",
  432.        MEM32=(.handle,DIRECT,2)
  433.  
  434.    TRACE  MINOR=0x8001,     /* Post-invocation tracing at     */
  435.        TP=.DosOpenC,RETEP,  /*  procedure DosOpenC return point. */
  436.        TYPE=(API,POST),    /*  Debug   info is needed to use  */
  437.        GROUP=DOS,       /*  this type of tracepoint.     */
  438.        DESC="(OS) DosOpenC  Post-Invocation",
  439.        FMT="         Return Code = %P%W",
  440.        FMT="         Variable Rec= %P%U",
  441.        MEM32=(.retcode,DIRECT,2),
  442.        /* The following will log a variable length structure.  The */
  443.        /*  second field in the structure is the length of the   */
  444.        /*  record(position var_struct+2).  This LEN parameter must*/
  445.        /*  immediately precede the memory specification defining  */
  446.        /*  the variable length record.               */
  447.        LEN=(var_struct+2,DIRECT),
  448.        MEM32=(.var_struct,DIRECT,LEN)
  449.  
  450.  
  451. ΓòÉΓòÉΓòÉ 1.3.2. TSF Header ΓòÉΓòÉΓòÉ
  452.  
  453. This defines common information for the module to be traced. The format is: 
  454.  
  455.  
  456.         MODNAME = [d:][path]Name
  457.         MAJOR   = nnn
  458.       [ MAXDATALENGTH = nnnn ]
  459.  
  460. where: 
  461.  
  462. d: 
  463.  
  464.     is the drive containing the module. If not specified the current drive is 
  465.     used. 
  466. path 
  467.  
  468.     is the path to the module. If not specified the current path is used. 
  469. Name 
  470.  
  471.     is the name of the executable module to be traced. If an extension is not 
  472.     specified and the Name is not OS2KRNL, an extension of DLL is appended to 
  473.     Name. 
  474. MAJOR=nnn 
  475.  
  476.     defines the major trace ID allocated to this module. It may be in the range 
  477.     1 to 255 decimal or specified 0x1 to 0xFF hex. The default value is 1. The 
  478.     major trace ID is part of the data placed in the trace buffer when a 
  479.     tracepoint is executed. 
  480.  
  481.     Only one major code is permitted per module. 
  482.  
  483.     Note:  OS/2 currently only supports major codes 0x1 - 0x00FF. 
  484. MAXDATALENGTH=nnnn (optional) 
  485.  
  486.     defines the maximum amount of data that a single tracepoint call will 
  487.     insert into the trace buffer. 
  488.  
  489.     The length may be in the range 20 to 512 decimal or specified 0x14 to 0x200 
  490.     hex.  The default value is 512. This limit on the amount of data to trace 
  491.     is to avoid yielding the processor when doing dynamic tracing. 
  492.  
  493.  
  494. ΓòÉΓòÉΓòÉ 1.3.3. Typelist Definition ΓòÉΓòÉΓòÉ
  495.  
  496. This defines the optional typelist event IDs. For more description and examples 
  497. of event types see the online help for the trace command. 
  498.  
  499. The format is: 
  500.  
  501.  
  502.         TYPELIST NAME=TypeName,ID=TypeValue,
  503.                 [NAME=TypeName,ID=TypeValue,]...
  504.  
  505. where: 
  506.  
  507. NAME=Typename 
  508.  
  509.     defines a 1-8 byte character string used to reference the TypeValue in the 
  510.     tracepoint definitions.  All TypeNames and GroupNames within a TSF must be 
  511.     unique. 
  512. ID=TypeValue 
  513.  
  514.     defines a bit value of the form 2**y where y in range 0 to 15, permitting a 
  515.     maximum of 16 types to be defined in a single TSF. This can be decimal or 
  516.     specified  0xnnnn for hex. 
  517.  
  518. An example TYPELIST definition follows: 
  519.  
  520.       TYPELIST NAME=PRE,ID=1,
  521.                NAME=SYS,ID=0x40,
  522.                NAME=API,ID=128,
  523.                NAME=POST,ID=0x8000,.....
  524.  
  525.  
  526. ΓòÉΓòÉΓòÉ 1.3.4. Grouplist Definition ΓòÉΓòÉΓòÉ
  527.  
  528. This defines the optional grouplist IDs. For more description and examples of 
  529. groups see the online help for the trace command. 
  530.  
  531. The format is: 
  532.  
  533.  
  534.         GROUPLIST NAME=GroupName,ID=GroupValue,
  535.                  [NAME=GroupName,ID=GroupValue,]...
  536.  
  537. where: 
  538.  
  539. NAME=GroupName 
  540.  
  541.     defines a 1-8 byte character string used to reference the GroupValue in the 
  542.     tracepoint definitions.  There are a maximum of 48 GroupNames allowed in a 
  543.     TSF file.  All TypeNames and GroupNames within a TSF must be unique. 
  544. ID=GroupValue 
  545.  
  546.     defines a word value in the range 1 to 65535 decimal or 0x1 to 0xFFFF hex. 
  547.  
  548. An example GROUPLIST definition follows: 
  549.  
  550.       GROUPLIST NAME=MEM,ID=2,
  551.                 NAME=FS,ID=0x5,
  552.                 NAME=MOU,ID=13,.....
  553.  
  554.  
  555. ΓòÉΓòÉΓòÉ 1.3.5. Tracepoint Definitions ΓòÉΓòÉΓòÉ
  556.  
  557. The tracepoint address and the data to be traced are specified by the TRACE 
  558. statement. There are a maximum of 65535 tracepoints permitted in a trace source 
  559. file. 
  560.  
  561. The format of the TRACE statement is: 
  562.  
  563.  
  564.         TRACE   [MINOR=minorcode,]
  565.                 TP={@STATIC,|@filename,linenum,|.name[{+|-}offs][,RETEP]},
  566.                 [OPCODE=0xnn,]
  567.                 [TYPE=(typename[,typename...]),]
  568.                 [GROUP=groupnam,]
  569.                 [DESC="Tracepoint description",]
  570.                 [FMT="Formatting string",]...
  571.                 [LEN=(length_spec,flag),]
  572.                 [DATA_STMT,]...
  573.  
  574. The TRACE keyword delimits a tracepoint definition statement. The definition is 
  575. considered complete when the next TRACE keyword is encountered or the end of 
  576. file is reached. There is one TRACE statement for each tracepoint. 
  577.  
  578. LEN is used to log variable length records. A DATA_STMT must immediately follow 
  579. the LEN statement.  LEN will give the location of a one word field containing 
  580. the number of bytes to log for the following DATA_STMT. 
  581.  
  582.  
  583. ΓòÉΓòÉΓòÉ 1.3.5.1. MINOR Keyword ΓòÉΓòÉΓòÉ
  584.  
  585. The MINOR parameter is an optional keyword parameter.  If it is specified in 
  586. the first tracepoint definition, it must be specified in every tracepoint 
  587. definition.  If it is not specified in the first tracepoint definition, it 
  588. cannot be specified in any of the subsequent tracepoint definitions. It should 
  589. be coded as: 
  590.  
  591.  
  592.         MINOR=nnnnn,
  593.  
  594. where: 
  595.  
  596. nnnnn 
  597.  
  598.     is a decimal number from 1 to 65535 or a hex number from 0x1 to 0xFFFF. 
  599.     This represents the minor code for the tracepoint, which must be unique for 
  600.     the major code specified for this module. When tracepoints with duplicate 
  601.     minor codes are encountered, the first is saved and the rest are discarded, 
  602.     and an error message is issued. 
  603.  
  604. If minor codes are not specified in the TSF, TRCUST sequentially provides them, 
  605. starting with 1, for each tracepoint definition it encounters. 
  606.  
  607.  
  608.  
  609. ΓòÉΓòÉΓòÉ 1.3.5.2. TP Keyword ΓòÉΓòÉΓòÉ
  610.  
  611. The TP parameter is a required keyword parameter. If TP is specified more than 
  612. once for a single tracepoint definition, the tracepoint is discarded. TP has 
  613. three mutually exclusive definitions which can be coded as: 
  614.  
  615.  
  616.         TP=@STATIC,
  617.  
  618. where: 
  619.  
  620. STATIC 
  621.  
  622.     defines this tracepoint entry to be used only for creating a trace format 
  623.     statement for the TFF file.  No tracepoint definition is created for the 
  624.     TDF, and the only other TRACE parameters that will be used are DESC, MINOR 
  625.     and FMT. This is used to create trace formatting information for static 
  626.     tracepoints. If the TSF contains only @STATIC directives, no TDF files are 
  627.     created. 
  628.  
  629.  
  630.  
  631.         TP=@filename,linenum,
  632.  
  633. where: 
  634.  
  635. filename 
  636.  
  637.     is an ASCII string specifying the name(including extension) of a source 
  638.     filename used in creating the module.  The source filename is stored in the 
  639.     debug information contained in the executable module, so debug information 
  640.     must exist to use this parameter. The filename is not case sensitive. 
  641. linenum 
  642.  
  643.     is a decimal number specifying the line number in the given source file 
  644.     name to place the tracepoint. 
  645.  
  646.  
  647. Note:  Debug information must exist to use this option. The statement at the 
  648. given source linenum may have been rearranged during compiler optimization, so 
  649. the developer must use this with caution.  If the linenum is not found in the 
  650. debug information, the tracepoint is applied at the next linenum defined in the 
  651. debug information and a warning message is issued to the user. 
  652.  
  653. An example to apply a tracepoint to line 35 of file stubfile.c is: 
  654.  
  655.     TRACE   MINOR=0x700A,              /* puts tracepoint on code at line */
  656.             TP=@stubfile.c,35,.....    /*  35 of source file stubfile.c   */
  657.  
  658.  
  659.         TP=.name[{+|-}offs][,RETEP],
  660.  
  661. where: 
  662.  
  663. name 
  664.  
  665.     is a public label or an entry point name of a procedure to be traced. The 
  666.     "." preceding name is required. Name must be found in the debug information 
  667.     in the module or name must be a public symbol as found in the MAP file. If 
  668.     debug information is used, the address of this tracepoint will be 
  669.     immediately following the prologue of the procedure. If MAP information is 
  670.     used, this address points to the opcode at the given label. 
  671.  
  672.     If the procedure was compiled with debug support, Name is case sensitive. 
  673.     If not, C language functions will be case sensitive and begin with an 
  674.     underscore "_" character unless the function is declared with the Pascal 
  675.     calling convention, in which case the underscore is omitted and the name is 
  676.     capitalized. 
  677. offs (optional) 
  678.  
  679.     is a decimal(specified as nnnnnnnn)  or hex(specified as 0xnnnnnnnn) offset 
  680.     from the entry point address. 
  681. RETEP (optional) 
  682.  
  683.     specifies that the tracepoint will be inserted at the return address 
  684.     corresponding to this entry point. This is just before the procedure 
  685.     epilogue is executed and at this point the procedure's automatic data is 
  686.     still addressable from register (E)BP and the return code (if any) is set 
  687.     up in (E)AX. 
  688.  
  689.     The module must include information supplied by the debug compile option 
  690.     (see Symbolic Debug Support),  meaning that the source language must have 
  691.     been C, otherwise an error message will be generated and this tracepoint 
  692.     discarded. 
  693.  
  694.     When the RETEP is used, the name must be a valid entry point to a 
  695.     procedure. 
  696.  
  697. Note:  For ASM functions to accomplish tracing, a label must be made public to 
  698. have a tracepoint applied.  Therefore, to accomplish "POST" tracing, a label 
  699. must be made public at the return statement. 
  700.  
  701. Partial examples of Pre/Post tracing of DosOpen follows: 
  702.  
  703.       TRACE   MINOR=0x0001,
  704.               TP=.DosOpen,.....            /* Pre-invocation tracing */
  705.  
  706.       TRACE   MINOR=0x8001,
  707.               TP=.DosOpen,RETEP,.....      /* Post-invocation tracing */
  708.  
  709. Note:  It is not possible to set dynamic tracepoints on the following machine 
  710. instructions: 
  711.  
  712. 0x9C  PUSHF 
  713. 0xCC  INT 3 
  714. 0xCD  INT n 
  715. 0xCE  INTO 
  716. 0x62  BOUND 
  717. 0x69  IMUL 
  718. 0x6B  IMUL 
  719. 0xF6  DIV, IDIV, MUL, IMUL, NEG, NOT, TEST (immediate) 
  720. 0xF7  DIV, IDIV, MUL, IMUL, NEG, NOT, TEST (immediate) 
  721.  
  722.  
  723.  
  724. TRCUST gives an error for these opcodes and the tracepoint is rejected. 
  725.  
  726. Note:  In all cases, two tracepoints cannot be applied at the same address. 
  727.  
  728.  
  729. ΓòÉΓòÉΓòÉ 1.3.5.3. OPCODE Keyword ΓòÉΓòÉΓòÉ
  730.  
  731. The OPCODE parameter is an optional keyword parameter. 
  732.  
  733.  
  734.         OPCODE=0xnn,
  735.  
  736. where: 
  737.  
  738. nn 
  739.  
  740.     is the expected one byte hex opcode to be found at the tracepoint address 
  741.     and TRCUST verifies the value with that in the module. The opcode of the 
  742.     instruction being traced must be the same as this value or an error message 
  743.     is issued and the tracepoint is rejected. This may be used to verify the 
  744.     opcode expected at the address specified by the TP parameter. This may be 
  745.     useful when using TP = @filename,linenum to ensure the requested 
  746.     instruction is traced. 
  747.  
  748.  
  749. ΓòÉΓòÉΓòÉ 1.3.5.4. TYPE Keyword ΓòÉΓòÉΓòÉ
  750.  
  751. The TYPE parameter is an optional keyword parameter that defines the event 
  752. types of this tracepoint. For more description and examples of event types see 
  753. the online help for the trace command. 
  754.  
  755.  
  756.         TYPE=(typename[,typename...]),
  757.  
  758. where: 
  759.  
  760. typename 
  761.  
  762.     is an ASCII string specifying the type of this tracepoint. The typename 
  763.     symbol must have been previously defined by the TYPELIST statement. If an 
  764.     invalid typename is given, the tracepoint will be discarded and a message 
  765.     issued. 
  766.  
  767.     The final type value is obtained by logically combining each type name 
  768.     value using the OR operator.  If TYPE is omitted, the trace statement will 
  769.     have a typevalue of 0. 
  770.  
  771.  
  772. ΓòÉΓòÉΓòÉ 1.3.5.5. GROUP Keyword ΓòÉΓòÉΓòÉ
  773.  
  774. The GROUP parameter is an optional keyword parameter that defines the group 
  775. this tracepoint belongs to. For more description and examples of groups see the 
  776. online help for the trace command. 
  777.  
  778.  
  779.         GROUP=groupnam,
  780.  
  781. where: 
  782.  
  783. groupnam 
  784.  
  785.     is an ASCII string specifying which group this tracepoint belongs. The 
  786.     groupname symbol must have been previously defined by the GROUPLIST 
  787.     statement. If an invalid groupname is given, the tracepoint will be 
  788.     discarded and a message issued. 
  789.  
  790.     If GROUP is omitted, the trace statement will have a groupvalue of 0. 
  791.  
  792.  
  793. ΓòÉΓòÉΓòÉ 1.3.5.6. DESC Keyword ΓòÉΓòÉΓòÉ
  794.  
  795. The DESC parameter is used to produce a description for the tracepoint that is 
  796. output as the first line of formatted data. It should include the entry point 
  797. name of the procedure being traced and whether this is an entry or return 
  798. point. The descriptive string is enclosed in double quotes as for a C language 
  799. string. The DESC parameter is required if any FMT specifications are present. 
  800.  
  801. The recommended formats for such strings are as follows: 
  802.  
  803.         DESC="name Pre-Invocation",
  804.  
  805.         DESC="name Post-Invocation",
  806.  
  807. where: 
  808.  
  809. name 
  810.  
  811.     is the system component(in parentheses) followed by the entry point name of 
  812.     the procedure. 
  813. Pre-Invocation 
  814.  
  815.     identifies this tracepoint as an entry point, i.e. before the function has 
  816.     been executed. 
  817. Post-Invocation 
  818.  
  819.     identifies this tracepoint as a return point from the function. 
  820.  
  821. The words Pre-Invocation and Post-Invocation are not mandatory, merely 
  822. recommendations to be compatible with the base OS/2 tracepoints, when 
  823. formatted. If a tracepoint is inserted in the middle of a procedure it will be 
  824. appropriate to use different wording. The Trace Customizer does not check the 
  825. wording. 
  826.  
  827. An example of pre-invocation and post-invocation tracepoints follow: 
  828.  
  829.       TRACE  MINOR=0x0001,
  830.              TP=.DosOpen,
  831.              DESC="(OS) DosOpen    Pre-Invocation",.....
  832.  
  833.       TRACE  MINOR=0x8001,
  834.              TP=.DosOpen,RETEP,
  835.              DESC="(OS) DosOpen    Post-Invocation",.....
  836.  
  837.  
  838. ΓòÉΓòÉΓòÉ 1.3.5.7. FMT Keyword ΓòÉΓòÉΓòÉ
  839.  
  840. The optional FMT parameter is used to produce the formatting string for the 
  841. trace data. The developer should use these to control formatting the output 
  842. produced by the Trace Formatter.  Each FMT keyword causes CR/LF to be appended 
  843. to the format string. The formatting string is similar to a C library printf 
  844. string specification. It consists of ASCII characters and formatting controls 
  845. enclosed in double quotes as for a C language string. Each formatting primitive 
  846. describes the format of the data in the trace buffer at the formatting position 
  847. and must match the data stored in the trace buffer by the data statements 
  848. described later. See Formatting Trace Data for a description of how the data is 
  849. stored in the trace buffer and subsequently formatted. 
  850.  
  851. The formatting controls are as follows: 
  852.  
  853. %Innn Ignore nnn number of bytes in the trace buffer. 
  854.  
  855.     This tells the Trace Formatter to skip over the next nnn bytes in the 
  856.     current trace record. This could be used for example to skip over 
  857.     unimportant data, traced as a block, and only output the data of interest. 
  858.  
  859.     When using this control, nnn represents an ASCII decimal number and must be 
  860.     followed by a space. 
  861.  
  862.  
  863.                 statement: FMT = "ignore ten bytes %I10 here",
  864.                            FMT = "       and two more %I2 here",
  865.  
  866.                 generates: ignore ten bytes here
  867.                                   and two more here
  868.  
  869.  
  870.  
  871. %P  Process the data prefix bytes associated with the trace data. 
  872.  
  873.     This tells the Trace Formatter that the next bytes in the trace record are 
  874.     the prefix or header bytes for data logged by the dynamic tracing 
  875.     mechanism. This is required to precede any format control describing data 
  876.     logged from memory.  Do not use this before data that was logged from a 
  877.     register and never use with static tracepoints. See Formatting Trace Data 
  878.     for a description of how the data is stored in the trace buffer and the use 
  879.     of this control. 
  880.  
  881.  
  882.                 statements: FMT="memory byte = %P%B",
  883.  
  884.                 generates:  memory byte = C2
  885.  
  886.  
  887. %B  Output a byte of data. 
  888.  
  889.  
  890.                 statement: FMT = "memory byte = %P%B"
  891.  
  892.                 generates: memory byte = 01
  893.  
  894.  
  895.  
  896. %W  Output a word of data. 
  897.  
  898.  
  899.                 statement: FMT = "register word = %W"
  900.  
  901.                 generates: register word = 0001
  902.  
  903.  
  904.                 statement: FMT = "memory word = %P%W"
  905.  
  906.                 generates: memory word = 0001
  907.  
  908.  
  909.  
  910. %D  Output a double word of data. 
  911.  
  912.  
  913.                 statement: FMT = "double word EAX = %D"
  914.  
  915.                 generates: double word EAX = 0000 4B2C
  916.  
  917.  
  918.                 statement: FMT = "double memory word = %P%D"
  919.  
  920.                 generates: double memory word = 0000 4B2C
  921.  
  922.  
  923.  
  924. %F  Output a Flat (0:32 bit) address. 
  925.  
  926.  
  927.                 statement: FMT = "flat address EAX = %F"
  928.  
  929.                 generates: flat address EAX = 00004B2C
  930.  
  931.  
  932.  
  933. %Q  Output a quad word of data. 
  934.  
  935.  
  936.                 statement: FMT = "quad word from regs EAX and EBX = %Q"
  937.  
  938.                 generates: quad word from regs EAX and EBX = 00004B2C 00000001
  939.  
  940.  
  941.  
  942. %A  Output a segmented(16:16 bit) address. 
  943.  
  944.  
  945.                 statement: FMT = "segmented address in SS:SP = %A"
  946.  
  947.                 generates: segmented address in SS:SP = 00B7:0001
  948.  
  949.  
  950.                 statement: FMT = "segmented address in memory = %P%A"
  951.  
  952.                 generates: segmented address in memory = 00B7:0001
  953.  
  954.  
  955.  
  956. %R  Repeat the following format control for the rest of the memory that was 
  957.     logged. 
  958.  
  959.     This is used for formatting variable length records.  Use this in place of 
  960.     the prefix parameter %P to log the rest of the record in the format 
  961.     specified following the repeat code. 
  962.  
  963.  
  964.            statement: FMT = "log a variable number of words from memory = %R%W"
  965.  
  966.            generates: log a variable number of words from memory = 0001 0004
  967.  
  968.  
  969.  
  970. %S  Output an ASCIIZ string. 
  971.  
  972.     The prefix formatting control should always precede this for dynamic 
  973.     tracepoints because the data was logged from memory. 
  974.  
  975.     Note:  If the tracepoint is static, then %P should not be used because the 
  976.     string is terminated with a null byte. 
  977.  
  978.  
  979.                 statement: FMT = "string = %P%S"
  980.  
  981.                 generates: string = c:\os2\os2.ini
  982.  
  983.  
  984.  
  985. %U  Format the remainder of the trace record as a sequence of bytes. 
  986.  
  987.     This will output the remaining of the traced data, including any prefix 
  988.     bytes. 
  989.  
  990.  
  991.                 statement: FMT = "garbage = %U"
  992.  
  993.                 generates: garbage = 00 00 00 03 c2 c1 c4 ff 04 00 09 c0 18
  994.  
  995.  
  996.  
  997. %X  Output the major event code. 
  998.  
  999.  
  1000.                 statement: FMT = "major code = %X"
  1001.  
  1002.                 generates: major code = 00C2
  1003.  
  1004.  
  1005.  
  1006. %Y  Output the minor event code. 
  1007.  
  1008.  
  1009.                 statement: FMT = "minor code = %Y"
  1010.  
  1011.                 generates: minor code = 0081
  1012.  
  1013.  
  1014. Note:  To avoid conflicts with source file control information, all formatting 
  1015. specifications can be in upper or lower case. Also, prefix format 
  1016. specifications may be combined with data format specifications. For example, 
  1017. the following create the same format controls in the TFF: 
  1018.  
  1019.  
  1020.         FMT = "%P%W here"
  1021.         FMT = "%p%w here"
  1022.         FMT = " %P %W here"
  1023.  
  1024.  
  1025. ΓòÉΓòÉΓòÉ 1.3.5.8. LEN Keyword ΓòÉΓòÉΓòÉ
  1026.  
  1027. The LEN parameter is an optional keyword parameter that defines the length of 
  1028. the variable length record that will follow in the next MEM or MEM32 statement. 
  1029.  
  1030.  
  1031.         LEN=(length_spec,flag),
  1032.  
  1033. where: 
  1034.  
  1035. length_spec 
  1036.  
  1037.     is an address specification that points to the one word length field of the 
  1038.     next memory specification. This format can be symbolic_name+nnnnnnnn where 
  1039.     symbolic_name is a symbolic memory location and nnnnnnnn is the offset from 
  1040.     that symbolic address. The length_spec can also be Flat Register Form or 
  1041.     Segment Register Form. 
  1042. flag 
  1043.  
  1044.     is a mandatory parameter that identifies the level of indirection to be 
  1045.     used on the length_spec. It is one of: 
  1046.  
  1047.    D[IRECT] 
  1048.    I[NDIRECT][*[{+|-}iiiiiiii]]... 
  1049.  
  1050. DIRECT implies that the length_spec specifies a memory location that contains 
  1051. the length of the variable length record. INDIRECT means that the length_spec 
  1052. contains an address and is dereferenced to obtain the memory location.  The 
  1053. optional asterisks denote the level of indirection, one for each level.  The 
  1054. indirect offsets iiiiiiii are added to or subtracted from the value found at 
  1055. the given level of indirection. 
  1056.  
  1057. The following are example LEN statements followed by the memory statement whose 
  1058. length they describe. 
  1059.  
  1060.  
  1061.     TRACE MINOR=.....,
  1062.           /* Symbol vrecord is a record whose first field is a one */
  1063.           /* word value that is the total length of the entire     */
  1064.           /* variable length record.                               */
  1065.           LEN=(vrecord,DIRECT),
  1066.           MEM=(.vrecord,DIRECT,LEN),
  1067.  
  1068.           /* Symbol vrec_ptr is a pointer to a variable length record */
  1069.           /* and vend_ptr is a pointer to the end of the same record. */
  1070.           /* The second field(10 bytes from end of record) is  total  */
  1071.           /* length of the variable length record.                    */
  1072.           LEN=(vend_ptr,INDIRECT*-10),
  1073.           MEM=(.vrec_ptr,INDIRECT,LEN),
  1074.  
  1075.           /* Symbol vrec_ptr is a pointer to a variable length record.*/
  1076.           /* The second field(2 bytes from beginning of record) is    */
  1077.           /* total length of the variable length record.              */
  1078.           LEN=(vrec_ptr,INDIRECT*+2),
  1079.           MEM=(.vrec_ptr,INDIRECT,LEN),
  1080.  
  1081.           /* Symbol ind_ptr is a pointer to a structure.  The third   */
  1082.           /* field in the structure(6 bytes from beginning) is a      */
  1083.           /* pointer to a variable record.  The fourth field in the   */
  1084.           /* variable length record(8 bytes from beginning) is the    */
  1085.           /* total length of this variable length record.             */
  1086.           LEN=(ind_ptr,INDIRECT*+6*+8),
  1087.           MEM=(.ind_ptr,INDIRECT*+6*,LEN),
  1088.  
  1089.           /* If DS:DI contains the address of ind_ptr, to perform */
  1090.           /* the above logging, the statements would be:              */
  1091.           LEN=(RDS+DI,INDIRECT*+6*+8),
  1092.           MEM=(RDS+DI,INDIRECT*+6*,LEN)
  1093.  
  1094.  
  1095. ΓòÉΓòÉΓòÉ 1.3.5.9. DATA_STMT ΓòÉΓòÉΓòÉ
  1096.  
  1097. There are three types of data that may be traced as part of the optional 
  1098. DATA_STMT section of the TRACE statement. 
  1099.  
  1100. Registers 
  1101. Memory 
  1102. ASCIIZ strings 
  1103.  
  1104. More than one keyword is permitted in a tracepoint definition. The order of the 
  1105. statements defines the order in which the data is inserted into the trace 
  1106. buffer. 
  1107.  
  1108. The combined amount of data to be traced for a single tracepoint cannot exceed 
  1109. MAXDATALENGTH.  If TRCUST determines that the maximum data size might be 
  1110. exceeded, a warning message is issued but the tracepoint definition will remain 
  1111. valid. 
  1112.  
  1113. The keywords for tracing the three types of data are REGS, MEM32, MEM, 
  1114. ASCIIZ32, and ASCIIZ. 
  1115.  
  1116. The REGS keyword identifies which registers are to be recorded in the trace 
  1117. buffer. 
  1118.  
  1119. The MEM32 keyword is used to record sections of memory in the trace buffer. 
  1120. Access to this memory location is through 32-bit flat addresses from functions 
  1121. compiled using 32-bit addressing. Several MEM32 parameters may be coded at any 
  1122. one tracepoint if several different memory areas are to be traced. 
  1123.  
  1124. The MEM keyword is also used to record sections of memory in the trace buffer, 
  1125. but access to this memory is through a segment:offset pair.  This is used for 
  1126. functions compiled using 16-bit addressing with segment registers. Several MEM 
  1127. parameters may be coded at any one tracepoint if several different memory areas 
  1128. are to be traced. 
  1129.  
  1130. The ASCIIZ32 keyword is used to record an ASCIIZ string in the trace buffer. 
  1131. This is a special form of the MEM32 keyword and there may be more than one 
  1132. ASCIIZ32 parameter coded for a single tracepoint. 
  1133.  
  1134. The ASCIIZ keyword is used to record an ASCIIZ string in the trace buffer. This 
  1135. is a special form of the MEM keyword and there may be more than one ASCIIZ 
  1136. parameter coded for a single tracepoint. 
  1137.  
  1138.  
  1139. ΓòÉΓòÉΓòÉ 1.3.5.10. REGS Keyword ΓòÉΓòÉΓòÉ
  1140.  
  1141. This is coded as: 
  1142.  
  1143.  
  1144.         REGS=(register[,register]...),
  1145.  
  1146. where: 
  1147.  
  1148. register 
  1149.  
  1150.     is one of the following to support OS/2 versions 1.1 and 1.2: 
  1151.  
  1152.       CS,DS,SS,ES,AX,BX,CX,DX,SP,BP,SI,DI,IP,FLAGS 
  1153.  
  1154.     with the addition of the following to support OS/2 version 2.0: 
  1155.  
  1156.       EAX,EBX,ECX,EDX,ESP,EBP,ESI,EDI,EFLAGS,EIP,FS,GS 
  1157.  
  1158.     or the symbolic name of a C language variable declared with the register 
  1159.     storage-class specifier as: 
  1160.  
  1161.       .symbolic_name 
  1162.  
  1163.     The same register may appear multiple times in the register list. It will 
  1164.     be traced as many times as it appears. Extended registers(E) are 32 bits 
  1165.     and logged as two words. All other registers are 16 bits and logged as one 
  1166.     word. 
  1167.  
  1168. Note:  To log a C language variable declared with the register storage class, 
  1169. debug information must exist and the variable name is case sensitive.  When 
  1170. formatting the data logged from a register variable, remember that there are no 
  1171. memory prefix bytes put into the log buffer. 
  1172.  
  1173. Example of the REGS statement follows: 
  1174.  
  1175.      /* Given the following declaration in a C language source file: */
  1176.      register int ret_code;
  1177.  
  1178.      /* To log registers AX, CX and the register variable ret_code: */
  1179.      TRACE MINOR=.....
  1180.            REGS=(AX,CX,.ret_code),
  1181.            FMT="AX=%W  CX=%W  ret_code=%W"
  1182.  
  1183.  
  1184. ΓòÉΓòÉΓòÉ 1.3.5.11. MEM32 Keyword ΓòÉΓòÉΓòÉ
  1185.  
  1186. This is used to log memory in a function compiled using 32-bit flat addressing 
  1187. and is coded as: 
  1188.  
  1189.  
  1190.         MEM32=(address_spec,flag,{length|LEN}),
  1191.  
  1192. where: 
  1193.  
  1194. address_spec 
  1195.  
  1196.     is a flat memory address specification as described in Address 
  1197.     Specification. 
  1198. flag 
  1199.  
  1200.     is a mandatory parameter that identifies the level of indirection to be 
  1201.     used on the address. It is one of: 
  1202.  
  1203.    D[IRECT] 
  1204.    I[NDIRECT][*[{+|-}iiiiiiii]]... 
  1205.    IS 
  1206.  
  1207. DIRECT implies that the address specifies a memory location to be saved in the 
  1208. trace buffer. 
  1209.  
  1210. INDIRECT means that the address contains a flat address and is dereferenced to 
  1211. obtain the memory location. The optional asterisks denote the level of 
  1212. indirection, one for each level.  The indirect offsets iiiiiiii are added to or 
  1213. subtracted from the value found at the given level of indirection. 
  1214.  
  1215. IS(Indirect Segmented) means that the address contains a segmented address that 
  1216. is dereferenced to obtain the memory location. 
  1217. length 
  1218.  
  1219.     is the number of bytes at the memory location to be saved in the trace 
  1220.     buffer. If length is too big, a warning message will be given, and length 
  1221.     will be set to MAXDATALENGTH. If length is 0 an error message will be 
  1222.     given, and this tracepoint will be ignored. 
  1223. LEN 
  1224.  
  1225.     specifies that this is a variable length record to log and the length was 
  1226.     specified by the preceding LEN statement.  If there was no preceding LEN 
  1227.     statement, this tracepoint is rejected. Either length or LEN must be 
  1228.     specified, but not both. 
  1229.  
  1230. Example of the MEM32 statement follows: 
  1231.  
  1232.      TRACE MINOR=.....
  1233.            /* To log retcode enter the following: */
  1234.            MEM32=(.retcode,DIRECT,2),
  1235.  
  1236.            /* s_ptr is a pointer to a structure, log it for 4 bytes. */
  1237.            MEM32=(.s_ptr,INDIRECT,4),
  1238.  
  1239.            /* Field 6 bytes into structure pointed at by s_ptr is a     */
  1240.            /*  pointer to a structure, log 8 bytes past begin of struct.*/
  1241.            MEM32=(.s_ptr,INDIRECT*+6*+8,10),  /* logs ten bytes */
  1242.  
  1243.            /* s_ptr points to a variable length record, second field */
  1244.            /*  is the record length(offset 4 from record beginning). */
  1245.            LEN=(s_ptr,INDIRECT*+4),
  1246.            MEM32=(.s_ptr,INDIRECT,LEN)
  1247.  
  1248.            /* s_end points to the end of same variable length record,*/
  1249.            /*  second field is the record length(offset -6 from      */
  1250.            /*  record beginning).                                    */
  1251.            LEN=(s_end,INDIRECT*-6),
  1252.            MEM32=(.s_ptr,INDIRECT,LEN)
  1253.  
  1254.  
  1255.  
  1256. ΓòÉΓòÉΓòÉ 1.3.5.12. MEM Keyword ΓòÉΓòÉΓòÉ
  1257.  
  1258. This is used to log memory in a function compiled using 16-bit segment:offset 
  1259. addressing and is coded as: 
  1260.  
  1261.  
  1262.  
  1263.         MEM=(address_spec,flag,{length|LEN}),
  1264.  
  1265. where: 
  1266.  
  1267. address_spec 
  1268.  
  1269.     is a segmented memory address specification as described in Address 
  1270.     Specification. 
  1271. flag 
  1272.  
  1273.     is a mandatory parameter that identifies the level of indirection to be 
  1274.     used on the address. It is one of: 
  1275.  
  1276.    D[IRECT] 
  1277.    I[NDIRECT][*[{+|-}iiiiiiii]]... 
  1278.    IF 
  1279.  
  1280. DIRECT implies that the address specifies a memory location to be saved in the 
  1281. trace buffer. 
  1282.  
  1283. INDIRECT means that the address contains a segmented address and is 
  1284. dereferenced to obtain the memory location. The optional asterisks denote the 
  1285. level of indirection, one for each level.  The indirect offsets iiiiiiii are 
  1286. added to or subtracted from the value found at the given level of indirection. 
  1287.  
  1288. IF(Indirect Flat) means that the address contains a flat address that is 
  1289. dereferenced to obtain the memory location. 
  1290.  
  1291. Only far pointers may be dereferenced when using segmented addressing. 
  1292. length 
  1293.  
  1294.     is the number of bytes at the memory location to be saved in the trace 
  1295.     buffer. If length is too big, a warning message will be given, and length 
  1296.     will be set to MAXDATALENGTH. If length is 0 an error message will be 
  1297.     given, and this tracepoint will be ignored. 
  1298. LEN 
  1299.  
  1300.     specifies that this is a variable length record to log and the length was 
  1301.     specified by the preceding LEN statement.  If there was no preceding LEN 
  1302.     statement, this tracepoint is rejected. Either length or LEN must be 
  1303.     specified, but not both. 
  1304.  
  1305.  
  1306. ΓòÉΓòÉΓòÉ 1.3.5.13. ASCIIZ32 Keyword ΓòÉΓòÉΓòÉ
  1307.  
  1308. This is used to log a string in a function compiled using 32-bit flat 
  1309. addressing and is coded as: 
  1310.  
  1311.  
  1312.         ASCIIZ32=(address_spec,flag,maxlength),
  1313.  
  1314. where: 
  1315.  
  1316. address_spec 
  1317.  
  1318.     is a 0:32 bit flat memory address specification as described in Address 
  1319.     Specification. 
  1320. flag 
  1321.  
  1322.     is a mandatory parameter that identifies the level of indirection to be 
  1323.     used on the address. It is one of: 
  1324.  
  1325.    D[IRECT] 
  1326.    I[NDIRECT][*[{+|-}iiiiiiii]]... 
  1327.    IS 
  1328.  
  1329. DIRECT implies that the address points to a memory location, the contents of 
  1330. which are to be saved in the trace buffer. 
  1331.  
  1332. INDIRECT means that the address points to a flat address pointer which is 
  1333. dereferenced to obtain the target location to save in the trace buffer. The 
  1334. optional asterisks denote the level of indirection, one for each level.  The 
  1335. indirect offsets iiiiiiii are added to or subtracted from the value found at 
  1336. the given level of indirection. 
  1337.  
  1338. IS(Indirect Segmented) means that the address points to a segmented address 
  1339. pointer which is dereferenced to obtain the target location to save in the 
  1340. trace buffer. 
  1341. maxlength 
  1342.  
  1343.     is the maximum length of the string that will be saved in the trace buffer. 
  1344.     It should be no greater than MAXDATALENGTH. The actual length to be traced 
  1345.     will depend on where the zero terminating byte is found. 
  1346.  
  1347.     If maxlength is 0 an error message will be given, and this tracepoint will 
  1348.     be ignored. 
  1349.  
  1350.     Note:  When using dynamic tracing, the OS/2 kernel does not place the 
  1351.     terminating null byte into the trace buffer; therefore the prefix byte must 
  1352.     be used by the Trace Formatter to obtain the length of the string. 
  1353.  
  1354.  
  1355. ΓòÉΓòÉΓòÉ 1.3.5.14. ASCIIZ Keyword ΓòÉΓòÉΓòÉ
  1356.  
  1357. This is used to log a string in a function compiled using 16-bit segment:offset 
  1358. addressing and is coded as: 
  1359.  
  1360.  
  1361.         ASCIIZ=(address_spec,flag,maxlength),
  1362.  
  1363. where: 
  1364.  
  1365. address_spec 
  1366.  
  1367.     is a segmented memory address specification as described in Address 
  1368.     Specification. 
  1369. flag 
  1370.  
  1371.     is a mandatory parameter that identifies the level of indirection to be 
  1372.     used on the address. It is one of: 
  1373.  
  1374.    D[IRECT] 
  1375.    I[NDIRECT][*[{+|-}iiiiiiii]]... 
  1376.    IF 
  1377.  
  1378. DIRECT implies that the address points to a memory location, the contents of 
  1379. which are to be saved in the trace buffer. 
  1380.  
  1381. INDIRECT means that the address points to a far pointer which is a segmented 
  1382. address that is dereferenced to obtain the target location to save in the trace 
  1383. buffer. The optional asterisks denote the level of indirection, one for each 
  1384. level.  The indirect offsets iiiiiiii are added to or subtracted from the value 
  1385. found at the given level of indirection. 
  1386.  
  1387. IF(Indirect Flat) means that the address points to a far pointer which is is a 
  1388. flat address that is dereferenced to obtain the target location to save in the 
  1389. trace buffer. Only far pointers may be dereferenced using segmented addresses. 
  1390. maxlength 
  1391.  
  1392.     is the maximum length of the string that will be saved in the trace buffer. 
  1393.     It should be no greater than MAXDATALENGTH. The actual length to be traced 
  1394.     will depend on where the zero terminating byte is found. 
  1395.  
  1396.     If maxlength is 0 an error message will be given, and this tracepoint will 
  1397.     be ignored. 
  1398.  
  1399.     Note:  When using dynamic tracing, the OS/2 kernel does not place the 
  1400.     terminating null byte into the trace buffer; therefore the prefix byte must 
  1401.     be used by the Trace Formatter to obtain the length of the string. 
  1402.  
  1403.  
  1404.  
  1405. ΓòÉΓòÉΓòÉ 1.3.5.15. Address Specification ΓòÉΓòÉΓòÉ
  1406.  
  1407. The syntax for specifying a memory address given here applies to the MEM32, 
  1408. MEM, ASCIIZ32 and ASCIIZ keywords above. 
  1409.  
  1410. An address is specified in one of the following forms: 
  1411.  
  1412.  1. Symbolic name form(can be used for MEM32, MEM, ASCIIZ32, and ASCIIZ). 
  1413.  2. Flat register form(can be used only for MEM32 and ASCIIZ32). 
  1414.  3. Segment register form(can be used only for MEM and ASCIIZ). 
  1415.  
  1416.  
  1417. ΓòÉΓòÉΓòÉ 1.3.5.15.1. Symbolic Name Form ΓòÉΓòÉΓòÉ
  1418.  
  1419. This is coded as: 
  1420.  
  1421.  
  1422.         .name[{+|-}nnnnnnnn]...[{+|-}(iiiiiiii)],
  1423.  
  1424. where: 
  1425.  
  1426. name 
  1427.  
  1428.     is a symbolic name of a memory location.  The "." is required before the 
  1429.     name. The debug information in the module is checked for the name and if 
  1430.     not found and a MAP was given, the MAP is checked. An error message is 
  1431.     output by the Trace Customizer if the symbol is not found and the trace 
  1432.     definition is ignored. 
  1433.  
  1434.     The name is case sensitive except under the conditions that follow. 
  1435.  
  1436.     If the procedure containing name was not compiled with debug option then if 
  1437.     name is a C language symbolic name it will be case sensitive and begin with 
  1438.     an underscore "_" character unless it was declared with the Pascal naming 
  1439.     convention, in which case the underscore is omitted and name is 
  1440.     capitalized. 
  1441.  
  1442.  
  1443. nnnnnnnn (optional) 
  1444.  
  1445.     is a displacement from the symbolic address. If hex the syntax is 
  1446.     0xnnnnnnnn. 
  1447. iiiiiiii (optional) 
  1448.  
  1449.     is a displacement from the indirect address. If hex the syntax is 
  1450.     0xiiiiiiii. This specifies a displacement from the final address when using 
  1451.     INDIRECT, IF(Indirect Flat) or IS(Indirect Segmented) addressing. 
  1452.  
  1453.  
  1454. ΓòÉΓòÉΓòÉ 1.3.5.15.2. Flat Register Form ΓòÉΓòÉΓòÉ
  1455.  
  1456. This is coded as: 
  1457.  
  1458.  
  1459.         Fbreg[{+|-}ireg]...[{+|-}nnnnnnnn]...[{+|-}(iiiiiiii)],
  1460.  
  1461. where: 
  1462.  
  1463. breg 
  1464.  
  1465.     is a flat model(0:32 bit) base register and is one of: 
  1466.  
  1467.     EAX,EBX,ECX,EDX,ESP,EBP,ESI,EDI 
  1468. ireg (optional) 
  1469.  
  1470.     is an extended data, base or index register. More than one ireg may be used 
  1471.     to define a displacement from the flat register value to the memory 
  1472.     location. It may be one of: 
  1473.  
  1474.     EAX,EBX,ECX,EDX,EBP,ESI,EDI 
  1475. nnnnnnnn (optional) 
  1476.  
  1477.     is an optional fixed displacement to be added to the address calculated in 
  1478.     the registers.  If hex the format is 0xnnnnnnnn. 
  1479. iiiiiiii (optional) 
  1480.  
  1481.     is a displacement from the indirect address. If hex the syntax is 
  1482.     0xiiiiiiii. This specifies a displacement from the final address when using 
  1483.     INDIRECT or IS(Indirect Segmented) addressing. 
  1484.  
  1485. This form of address is calculated at run time. 
  1486.  
  1487.  
  1488. ΓòÉΓòÉΓòÉ 1.3.5.15.3. Segment Register Form ΓòÉΓòÉΓòÉ
  1489.  
  1490. This is coded as: 
  1491.  
  1492.  
  1493.         Rsreg[{+|-}dreg]...[{+|-}nnnnn]...[{+|-}(iiiii)],
  1494.  
  1495. where: 
  1496.  
  1497. sreg 
  1498.  
  1499.     is a segment register and is one of: 
  1500.  
  1501.     CS,DS,SS,ES,FS,GS 
  1502. dreg (optional) 
  1503.  
  1504.     is a data, base or index register. More than one dreg may be used to define 
  1505.     a displacement from the segment register value to the memory location. It 
  1506.     is one of: 
  1507.  
  1508.     BP,SP,SI,DI,AX,BX,CX,DX 
  1509. nnnnn (optional) 
  1510.  
  1511.     is an optional fixed displacement to be added to the address calculated in 
  1512.     the registers.  If hex the syntax is 0xnnnn. 
  1513. iiiii (optional) 
  1514.  
  1515.     is a displacement from the indirect address. If hex the syntax is 0xiiii. 
  1516.     This specifies a displacement from the final address when using INDIRECT or 
  1517.     IF(Indirect Flat) addressing. 
  1518.  
  1519. This form of address is calculated at run time. 
  1520.  
  1521.  
  1522. ΓòÉΓòÉΓòÉ 1.4. Formatting Trace Data ΓòÉΓòÉΓòÉ
  1523.  
  1524. This section gives a brief description of the formatting process as an aid to 
  1525. generating correct formatting strings. 
  1526.  
  1527. Each trace record stored in the RAS buffer consists of a header followed by a 
  1528. number of variable length trace data records. The header identifies the major 
  1529. and minor code, time stamp, process ID, etc., and the total length of the trace 
  1530. data for that trace record. 
  1531.  
  1532. Each MEM32, MEM, ASCIIZ32, or ASCIIZ data statement, coded in the trace source 
  1533. file for a tracepoint, produces an associated data record to be stored in the 
  1534. trace buffer. The data records consist of a 3-byte prefix followed by the trace 
  1535. data. This prefix consists of a status byte followed by the length of the data 
  1536. for that statement. The status byte indicates whether valid data has been 
  1537. traced. 
  1538.  
  1539. Dynamic trace can only trace data that is resident in memory at the time that 
  1540. the tracepoint is executed. Data may not be able to be traced for two reasons: 
  1541. it resides in a page that is currently paged out or the address specified is 
  1542. invalid. This latter case usually occurs due to tracing indirectly via invalid 
  1543. pointer variables. In either of these two cases dynamic trace sets the status 
  1544. byte accordingly and stores the pointer in the place of the wanted data. No 
  1545. more data is attempted to be traced for this invocation of the tracepoint, but 
  1546. tracing will resume the next time this tracepoint is encountered. 
  1547.  
  1548. Since the position of these prefix bytes, within a trace record, is dependent 
  1549. on the data being traced and the number of MEM32, MEM, ASCIIZ32, or ASCIIZ 
  1550. statements, the Trace Formatter must be told when to expect the prefix in the 
  1551. trace record. This is the purpose of the %P formatting control. It must be 
  1552. coded in the formatting string at every place a data record is expected. 
  1553.  
  1554. Note:  With ASCIIZ and ASCIIZ32 commands, the prefix must be used to obtain the 
  1555. length of the string since the string is not null terminated. 
  1556.  
  1557.  
  1558. ΓòÉΓòÉΓòÉ 1.5. Sample Trace Source Files ΓòÉΓòÉΓòÉ
  1559.  
  1560. This section gives four sample TSF files. The first is for a module written in 
  1561. a mix of C and MASM and compiled with 16:16 segmented addressing.  The second 
  1562. was compiled with 0:32 flat addressing.  The third module consists of routines, 
  1563. some which were compiled using 16-bit segmented addressing and some that were 
  1564. compiled using 32-bit flat addressing. The fourth is for monitoring function 
  1565. references in a module. 
  1566.  
  1567.  
  1568. ΓòÉΓòÉΓòÉ 1.5.1. TSF Using 16-bit Segmented Addressing ΓòÉΓòÉΓòÉ
  1569.  
  1570.  
  1571. ;  Trace source file for the xxx dynalink.  Compiled with 16-bit offsets. 
  1572.  
  1573.  
  1574.    MODNAME=\c\src\xxx.dll
  1575.    MAJOR=0xC5
  1576.    MAXDATALEN=200
  1577. ;  We will want to trace up to 200 bytes in any one trace call. 
  1578.  
  1579.  
  1580.    TYPELIST NAME=API,ID=08,
  1581.        NAME=SYS,ID=04,
  1582.        NAME=PRE,ID=02,
  1583.        NAME=POST,ID=64
  1584.  
  1585.    GROUPLIST NAME=MEM,ID=1,
  1586.         NAME=FS,ID=3
  1587.  
  1588.        /* The following tracepoint does not need debug info,
  1589.          only a MAP file is necessary with label xxalloc
  1590.          public in it.  The program must be compiled in 16-bit
  1591.          mode because segmented addressing is used(ASCIIZ
  1592.          instead of ASCIIZ32).
  1593.          This logs the word registers AX and BX and the string
  1594.          pointed at by DS:DI for a max of 20 bytes. */
  1595.  
  1596.    TRACE   MINOR=25, TP=.xxalloc,
  1597.        OPCODE=0x8B,   /* the opcode is optional */
  1598.        TYPE=(API,PRE),
  1599.        GROUP=MEM,
  1600.        DESC="(OS) xxalloc Pre-Invocation",
  1601.        FMT ="               AX = %W ",
  1602.        FMT ="               upper BX = %B",
  1603.        FMT ="               lower BX = %B",
  1604.        FMT ="               param = %P%S",
  1605.        REGS=(AX,BX),
  1606.        ASCIIZ=(RDS+DI,DIRECT,20)
  1607.  
  1608.  
  1609.        /* This defines a tracepoint at Foo label.  The ten words
  1610.          to log are found indirectly through SS:SP.  Note that
  1611.          each word needs a format control but since only one
  1612.          memory access was done,  one prefix control is needed. */
  1613.  
  1614.    TRACE  MINOR=0xB0, TP=.Foo,
  1615.        TYPE=(SYS),
  1616.        GROUP=FS,
  1617.        DESC="(OS) Foo Pre-Invocation",
  1618.        FMT="           First Five words = %P%W%W%W%W%W",
  1619.        FMT="           Three words ignored %I6",
  1620.        FMT="           Last Two Words = %W%W",
  1621.        MEM=(RSS+SP,INDIRECT,20)
  1622.  
  1623.  
  1624.        /* This defines a tracepoint at Goo label.  DS:DI points
  1625.          to a structure whose second field is a pointer to an
  1626.          ASCIIZ string.  The offset from the first field in the
  1627.          structure is 4 bytes. Max string size to log is 40 bytes. */
  1628.  
  1629.    TRACE  MINOR=0xB1, TP=.Goo,
  1630.        TYPE=(SYS),
  1631.        GROUP=FS,
  1632.        DESC="(OS) Goo Pre-Invocation",
  1633.        FMT="      Second field in struct points to %P%S",
  1634.        ASCIIZ=(RDS+DI+4,INDIRECT,40)
  1635.  
  1636.  
  1637.        /* This defines a tracepoint at Hoo label.  DS:DI points to
  1638.          memory that contains a pointer to a structure. We want to
  1639.          log the third field in the structure(offset 6 from begin
  1640.          of structure). */
  1641.  
  1642.    TRACE  MINOR=0xB2, TP=.Hoo,
  1643.        TYPE=(SYS),
  1644.        GROUP=FS,
  1645.        DESC="(OS) Hoo Pre-Invocation",
  1646.        FMT="      Third field in struct is doubleword = %P%D",
  1647.        MEM=(RDS+DI,INDIRECT*+6,4)
  1648.  
  1649.  
  1650.        /* This defines a tracepoint at Zoo label.  DS:DI points to
  1651.          memory that contains a pointer to end of a structure. We
  1652.          want to log the last field in the structure(offset -2 from
  1653.          end of structure). */
  1654.  
  1655.    TRACE  MINOR=0xB3, TP=.Zoo,
  1656.        TYPE=(SYS),
  1657.        GROUP=FS,
  1658.        DESC="(OS) Zoo Pre-Invocation",
  1659.        FMT="      Last field in struct is word = %P%W",
  1660.        MEM=(RDS+DI,INDIRECT*-2,2)
  1661.  
  1662.  
  1663.        /* This defines a tracepoint at procedure CheckIT.  This
  1664.          is a C routine compiled with debug information.  The
  1665.          data to log is an ASCIIZ string called NameIt.  */
  1666.  
  1667.    TRACE  MINOR=0xB3, TP=.CheckIt,
  1668.        TYPE=(PRE),
  1669.        GROUP=FS,
  1670.        DESC="(OS) CheckIt Pre-Invocation",
  1671.        FMT="        NameIt = %P%S",
  1672.        ASCIIZ=(.NameIt,DIRECT,64)
  1673.  
  1674.  
  1675.        /* This defines a tracepoint at the return point of the
  1676.          procedure CheckIt, a C routine compiled with debug.
  1677.          Status_Rec is a record variable. We want to log the
  1678.          age field(four bytes from the begin of Status_Rec),
  1679.          the name(six bytes from Status_Rec that points to
  1680.          an ASCIIZ string), the age of the next Status_Rec
  1681.          (a pointer to the next Status_Rec is ten bytes from
  1682.          the begin of Status_Rec, the age is four bytes from
  1683.          the begin of the next Status_Rec). */
  1684.  
  1685.    TRACE  MINOR=0x80B3, TP=.CheckIt,RETEP,
  1686.        TYPE=(POST),
  1687.        GROUP=FS,
  1688.        DESC="(OS) CheckIt Post-Invocation",
  1689.        FMT="        Status_Rec.age = %P%W",
  1690.        FMT="        Status_Rec.name = %P%S",
  1691.        FMT="        Status_Rec.next->age = %P%W",
  1692.        MEM=(.Status_Rec+4,DIRECT,2),
  1693.        ASCIIZ=(.Status_Rec+6,INDIRECT,64),
  1694.        MEM=(.Status_Rec+10,INDIRECT*+4,2)
  1695.  
  1696.  
  1697.        /* This defines a tracepoint at line 58 in the source
  1698.          file check.c  Debug info is needed to use this
  1699.          type of tracepoint. v_ptr is a pointer to a variable
  1700.          sized record.  The length is 4 bytes past the
  1701.          beginning of the record.  Log that record. */
  1702.  
  1703.    TRACE  MINOR=0x71B4, TP=@check.c,58,
  1704.        TYPE=(SYS),
  1705.        GROUP=FS,
  1706.        DESC="(OS) CheckIt  before allocation",
  1707.        FMT="        Variant Record = %P%W%D%U",
  1708.        LEN=(v_ptr,INDIRECT*+4),
  1709.        MEM=(.v_ptr,INDIRECT,LEN)
  1710.  
  1711.  
  1712.        /* This does not define a tracepoint, it only defines a
  1713.          trace formatting string for minor code 181(B5 hex). */
  1714.  
  1715.    TRACE  MINOR=0xB5, TP=@STATIC,
  1716.        DESC="(OS) StaticProcedure Pre-Invocation",
  1717.        FMT="         DI = %W FLAGS = %W"
  1718.  
  1719.  
  1720.        /* This defines a tracepoint at routine LookUp, but no
  1721.          data is to be logged, only the DESC will show up
  1722.          in the Trace log when the tracepoint is formatted. */
  1723.  
  1724.    TRACE  MINOR=0xB6, TP=.LookUp,
  1725.        TYPE=(SYS),
  1726.        GROUP=FS,
  1727.        DESC="(APP) LookUp  Pre-Invocation",
  1728.  
  1729.  
  1730. ΓòÉΓòÉΓòÉ 1.5.2. TSF Using 32-bit Addressing ΓòÉΓòÉΓòÉ
  1731.  
  1732.  
  1733. ;  Trace source file for the NEW dynalink.  Compiled with 32-bit offsets. 
  1734.  
  1735.  
  1736.    MODNAME=NEWCALLS.DLL
  1737.    MAJOR=241
  1738.    MAXDATALEN=200
  1739. ;  We will want to trace up to 200 bytes in any one trace call. 
  1740.  
  1741.  
  1742.    TYPELIST NAME=API,ID=08,
  1743.        NAME=SYS,ID=04,
  1744.        NAME=PRE,ID=02,
  1745.        NAME=POST,ID=64
  1746.  
  1747.    GROUPLIST NAME=MEM,ID=1,
  1748.         NAME=FS,ID=3
  1749.  
  1750.        /* The following tracepoint does not need debug info,
  1751.          only a MAP file is necessary with label NewAllocSeg
  1752.          public in it.  The program must be compiled in 32-bit
  1753.          mode because flat addressing is used(ASCIIZ32 instead
  1754.          of ASCIIZ).
  1755.          This logs lower word of EAX, the double word of EBX
  1756.          and the string at the address specified by ESP with
  1757.          offset ESI. */
  1758.  
  1759.    TRACE   MINOR=45, TP=.NewAllocSeg,
  1760.        TYPE=(API,PRE),
  1761.        GROUP=MEM,
  1762.        DESC="(NEW) NewAllocSeg Pre-Invocation",
  1763.        FMT ="               AX = %W ",
  1764.        FMT ="               EBX = %F",
  1765.        FMT ="               param = %P%S",
  1766.        REGS=(AX,EBX),
  1767.        ASCIIZ32=(FESP+ESI,DIRECT,20)
  1768.  
  1769.        /* This defines a tracepoint at Foo label.  The ten words
  1770.          to log are found indirectly by using EBP with offset
  1771.          EDI. Note that each value logged needs a format control. */
  1772.  
  1773.    TRACE  MINOR=0xD0, TP=.Foo,
  1774.        TYPE=(SYS),
  1775.        GROUP=FS,
  1776.        DESC="(NEW) Foo Pre-Invocation",
  1777.        FMT="           First Five words = %P%W%W%W%W%W",
  1778.        FMT="           Three words ignored %I6",
  1779.        FMT="           Last Two Words = %W%W",
  1780.        MEM32=(FEBP+EDI,INDIRECT,20)
  1781.  
  1782.  
  1783.        /* This defines a tracepoint at Goo label. EAX + EDI points
  1784.          to a structure whose second field is a pointer to an
  1785.          ASCIIZ string.  The offset from the first field in the
  1786.          structure is 4 bytes. Max string size to log is 40 bytes.*/
  1787.  
  1788.    TRACE  MINOR=0xD1, TP=.Goo,
  1789.        TYPE=(SYS),
  1790.        GROUP=FS,
  1791.        DESC="(NEW) Goo Pre-Invocation",
  1792.        FMT="      Second field in struct points to %P%S",
  1793.        ASCIIZ32=(FEAX+EDI+4,INDIRECT,40)
  1794.  
  1795.  
  1796.        /* This defines a tracepoint at Hoo label.  EBP + EDI points
  1797.          to memory that contains a pointer to a structure. We want
  1798.          to log the third field in the structure(offset 6 from
  1799.          begin of structure). */
  1800.  
  1801.    TRACE  MINOR=0xD2, TP=.Hoo,
  1802.        TYPE=(SYS),
  1803.        GROUP=FS,
  1804.        DESC="(NEW) Hoo Pre-Invocation",
  1805.        FMT="      Third field in struct is doubleword = %P%D",
  1806.        MEM32=(FEBP+EDI,INDIRECT*+6,4)
  1807.  
  1808.  
  1809.        /* This defines a tracepoint at Zoo label.  EAX + EDI points
  1810.          to memory that contains a pointer to end of a structure. We
  1811.          want to log the last field in the structure(offset -2 from
  1812.          end of structure). */
  1813.  
  1814.    TRACE  MINOR=0xD3, TP=.Zoo,
  1815.        TYPE=(SYS),
  1816.        GROUP=FS,
  1817.        DESC="(OS) Zoo Pre-Invocation",
  1818.        FMT="      Last field in struct is word = %P%W",
  1819.        MEM=(FEAX+EDI,INDIRECT*-2,2)
  1820.  
  1821.  
  1822.        /* This defines a tracepoint at procedure CheckIT.  This is
  1823.          a C routine compiled with debug information.  The
  1824.          data to log is an ASCIIZ string called NameIt. */
  1825.  
  1826.    TRACE  MINOR=0xD3, TP=.CheckIt,
  1827.        TYPE=(PRE),
  1828.        GROUP=FS,
  1829.        DESC="(NEW) CheckIt Pre-Invocation",
  1830.        FMT="        NameIt = %P%S",
  1831.        ASCIIZ32=(.NameIt,DIRECT,64)
  1832.  
  1833.  
  1834.        /* This defines a tracepoint at the return point of the
  1835.          procedure CheckIt, a C routine compiled with debug.
  1836.          Status_Rec is a record variable. We want to log the
  1837.          age field(four bytes from the begin of Status_Rec)
  1838.          the name(six bytes from Status_Rec that points to
  1839.          an ASCIIZ string) and the age of the next Status_Rec
  1840.          (a pointer to the next Status_Rec is ten bytes from
  1841.          the begin of Status_Rec, the age is four bytes from
  1842.          the begin of the next Status_Rec). */
  1843.  
  1844.    TRACE  MINOR=0x80D3, TP=.CheckIt,RETEP,
  1845.        TYPE=(POST),
  1846.        GROUP=FS,
  1847.        DESC="(NEW) CheckIt Post-Invocation",
  1848.        FMT="        Status_Rec.age = %P%W",
  1849.        FMT="        Status_Rec.name = %P%S",
  1850.        FMT="        Status_Rec.next->age = %P%W",
  1851.        MEM32=(.Status_Rec+4,DIRECT,2),
  1852.        ASCIIZ32=(.Status_Rec+6,INDIRECT,64),
  1853.        MEM32=(.Status_Rec+10,INDIRECT*+4,2)
  1854.  
  1855.  
  1856.        /* This does not define a tracepoint, it only defines a
  1857.          trace formatting string for minor code 223(DF hex). */
  1858.  
  1859.    TRACE  MINOR=0xDF, TP=@STATIC,
  1860.        DESC="(NEW) StaticProcedure Pre-Invocation",
  1861.        FMT="         DI = %W FLAGS = %W"
  1862.  
  1863.  
  1864.        /* This defines a tracepoint at routine LookUp, but no
  1865.          data is to be logged, only the DESC will show up
  1866.          in the Trace log when the tracepoint is formatted.
  1867.          LookUp is a C language routine not compiled with
  1868.          debug and not declared with Pascal
  1869.          calling conventions; the underscore is needed for
  1870.          this label. */
  1871.  
  1872.    TRACE  MINOR=0xE0, TP=._LookUp,
  1873.        TYPE=(SYS),
  1874.        GROUP=FS,
  1875.        DESC="(NEW) LookUp  Pre-Invocation"
  1876.  
  1877.  
  1878.  
  1879. ΓòÉΓòÉΓòÉ 1.5.3. TSF Using Mix of 16-bit and 32-bit Addressing ΓòÉΓòÉΓòÉ
  1880.  
  1881.  
  1882. ;  Trace source file for the MIXED dynalink. ;   Parts were compiled with 
  1883. 16-bit compiler, some with 32-bit compiler. ;   The developer must know how the 
  1884. parameters being sent in are ;   to be addressed, whether they are segmented or 
  1885. flat addresses. 
  1886.  
  1887.  
  1888.    MODNAME=MIXCALLS.DLL
  1889.    MAJOR=250
  1890.    MAXDATALEN=200
  1891. ;  We will want to trace up to 200 bytes in any one trace call. 
  1892.  
  1893.  
  1894.    TYPELIST NAME=API,ID=08,
  1895.        NAME=SYS,ID=04,
  1896.        NAME=PRE,ID=02,
  1897.        NAME=POST,ID=64
  1898.  
  1899.    GROUPLIST NAME=MEM,ID=1,
  1900.         NAME=FS,ID=3
  1901.  
  1902.        /* The following tracepoint is for the routine MixStub.
  1903.          This was compiled using segmented addressing and
  1904.          one of the parameters to it is a pointer to a control
  1905.          block called mix_ctrl.  This pointer, found at SS:SP,
  1906.          is a flat address because the routine that sent it was
  1907.          compiled with the flat addressing specification.
  1908.          This logs the mix_ctrl block for 6 bytes. */
  1909.  
  1910.    TRACE   MINOR=95, TP=.MixStub,
  1911.        TYPE=(API,PRE),
  1912.        GROUP=MEM,
  1913.        DESC="(OS) MixStub   Pre-Invocation",
  1914.        FMT ="               mix_ctrl = %P%W %W %W",
  1915.        MEM=(RSS+SP,IF,6)   /* is an indirect flat address */
  1916.  
  1917.  
  1918.        /* The following is for the routine FlatStub.  This was
  1919.          compiled using 32-bit flat addresses.  A parameter to
  1920.          flatstub is a pointer called p_seg_info.  This
  1921.          pointer is a segmented address because the routine
  1922.          calling flatstub was compiled using 16-bit segmented
  1923.          addressing.  Log where p_seg_info points for 2 bytes. */
  1924.  
  1925.    TRACE  MINOR=0xf0, TP=.FlatStub,
  1926.        TYPE=(SYS),
  1927.        GROUP=FS,
  1928.        DESC="(OS) FlatStub Pre-Invocation",
  1929.        FMT="           seg_info = %P%W",
  1930.        MEM32=(.p_seg_info,IS,2)  /* value p_seg_info is a 16-bit */
  1931.                      /*  segmented address      */
  1932.  
  1933.  
  1934.  
  1935. ΓòÉΓòÉΓòÉ 1.6. Trace Customizer Messages ΓòÉΓòÉΓòÉ
  1936.  
  1937. The messages generated by the Trace Customizer are given below. In addition to 
  1938. the message itself, the source line in error is displayed. 
  1939.  
  1940. Errors in the FATAL and SEVERE category will cause the compiler to abort 
  1941. immediately. 
  1942.  
  1943. ERROR messages will normally cause a tracepoint definition to be discarded and 
  1944. processing continues with the next definition. 
  1945.  
  1946. WARNING messages will allow a valid tracepoint definition to be produced, and 
  1947. the results will normally be as expected. 
  1948.  
  1949.  
  1950. ΓòÉΓòÉΓòÉ 1.6.1. Fatal Messages ΓòÉΓòÉΓòÉ
  1951.  
  1952.       Value               Message
  1953.   TRCERR_NO_TSF      TSF file not specified
  1954.   TRCERR_NO_FILE      file not found or access denied : %s
  1955.   TRCERR_FILE_OPEN     cannot open file : %s
  1956.   TRCERR_FILE_ACCESS    error accessing file : %s
  1957.   TRCERR_FILE_WRITE    error writing to file : %s
  1958.   TRCERR_NO_MEM      unable to allocate more memory
  1959.   TRCERR_TOOMANYRECS    too many tracepoints in file
  1960.   TRCERR_FILE_READ     error reading file: %s, Rc = %s
  1961.   TRCERR_FILE_MOVE     changing file pointer for: %s, Rc = %s
  1962.   TRCERR_BAD_EXEH     unknown EXE header type for: %s
  1963.   TRCERR_COMBINE_PATH   invalid path specified in combine file
  1964.   TRCERR_TOOMANYTFF    max TFF files to combine is 50
  1965.   TRCERR_DIF_MAJOR     all TFFs not have same major code, file: %s
  1966.   TRCERR_MAP_EXTN     invalid MAP file extension given in: %s
  1967.   TRCERR_NO_TCF      TCF file not specified
  1968.   TRCERR_FILENAME     filename to long: %s
  1969.   TRCERR_TOKENLENGTH    token in TSF file exceeds %s bytes
  1970.  
  1971.  
  1972. ΓòÉΓòÉΓòÉ 1.6.2. Severe Messages ΓòÉΓòÉΓòÉ
  1973.  
  1974.       Value               Message
  1975.   TRCERR_NOMODNAME     module name not specified
  1976.   TRCERR_UNEXPECTEDEOF   premature end of file encountered
  1977.   TRCERR_SYNTAX_ABORT   syntax error : missing '%s' before '%s'
  1978.   TRCERR_NLINLITERAL    new line in literal
  1979.   TRCERR_NULLINLITERAL   NULL in literal
  1980.   TRCERR_KEYWORD      keyword '%s' expected, '%s' found
  1981.   TRCERR_NO_SYMBOLIC    symbolic info not given for %s
  1982.   TRCERR_MULTIPLEMAJOR   MAJOR redefinition
  1983.   TRCERR_MULTIPLEMAXDL   MAXDATALENGTH redefinition
  1984.   TRCERR_LINE_SIZE     line too long in input file: %s
  1985.  
  1986.  
  1987. ΓòÉΓòÉΓòÉ 1.6.3. Error Messages ΓòÉΓòÉΓòÉ
  1988.  
  1989.       Value               Message
  1990.   TRCERR_NOTANUMBER    number expected, '%s' found
  1991.   TRCERR_SPURIOUS     unexpected: %s, ignored
  1992.   TRCERR_NOMINOR      minor code not specified
  1993.   TRCERR_MINORRANGE    minor code out of range
  1994.   TRCERR_MULTIPLETYPL   TYPELIST redefinition, ignored
  1995.   TRCERR_MULTIPLEGROUPL  GROUPLIST redefinition, ignored
  1996.   TRCERR_MULTIPLETP    TP redefinition, tracepoint ignored
  1997.   TRCERR_MULTIPLEMINOR   MINOR redefinition, tracepoint ignored
  1998.   TRCERR_MULTIPLEOPCD   OPCODE redefinition, tracepoint ignored
  1999.   TRCERR_SYNTAX_SKIP    syntax error: missing '%s' before '%s'
  2000.   TRCERR_OPCODETOOBIG   opcode: %s out of range
  2001.   TRCERR_BADOPCODE     opcode at TP address cannot be traced
  2002.   TRCERR_OPCODEMISMTCH   opcode mismatch at address to apply TP
  2003.   TRCERR_NOTAREG      register expected, '%s' found
  2004.   TRCERR_BADSYMBOL     symbol not found: %s
  2005.   TRCERR_BADADDRESS    address not found
  2006.   TRCERR_NOTASEGREG    segment register expected, '%s' found
  2007.   TRCERR_INCOMPLETE    trace record incomplete, '%s' required
  2008.   TRCERR_TPRTOOBIG     RPN command record exceeds 255 bytes
  2009.   TRCERR_BADPARM      invalid parameter: '%s', ignored
  2010.   TRCERR_BADID       invalid ID: %s, ignored
  2011.   TRCERR_MULTIPLEVENTNM  group/type redefinition: %s, ignored
  2012.   TRCERR_MULTIPLETYPEID  typeid redefinition: %s, ignored
  2013.   TRCERR_MULTIPLEGRPID   groupid redefinition: %s, ignored
  2014.   TRCERR_INVALIDADDRESS  invalid address specified: %s
  2015.   TRCERR_BADLINENUM    line number past end of code for file %s
  2016.   TRCERR_NO_CV       Debug info does not exist for: %s
  2017.   TRCERR_INVALIDLINENUM  line number missing or invalid: %s
  2018.   TRCERR_BADFILENAME    filename %s not found in Debug info
  2019.   TRCERR_DUP_MINOR     duplicate minor code = %s, ignored
  2020.   TRCERR_DUP_TFFMINOR   duplicate minor code = %s in file %s, ignored
  2021.   TRCERR_VAR_LEN      variable LEN parameter not preceding
  2022.   TRCERR_RPN_OVER     RPN stack limit of 16 exceeded
  2023.   TRCERR_INVALIDREG    invalid flat register specified: %s
  2024.   TRCERR_FMT_LONG     total FMT format specs above 4096 bytes
  2025.   TRCERR_ZEROLENGTH    zero length specified, tracepoint ignored
  2026.   TRCERR_DUP_SEGOFF    duplicate TP address, ignored
  2027.  
  2028.  
  2029. ΓòÉΓòÉΓòÉ 1.6.4. Warning Messages ΓòÉΓòÉΓòÉ
  2030.  
  2031.       Value               Message
  2032.   TRCERR_INVALIDLENGTH   MAXDATALENGTH out of range, 512 used
  2033.   TRCERR_NOTATYPE     typename unknown: %s, ignored
  2034.   TRCERR_NOTAGROUP     groupname unknown: %s, ignored
  2035.   TRCERR_BAD_EXTN     file: %s, extension invalid, using: %s
  2036.   TRCERR_EXPECTED     '%s' expected before '%s', one assumed
  2037.   TRCERR_TOOMANYNAMES   too many %s, first 16 types, 48 groups used
  2038.   TRCERR_NAMETOOBIG    name too long: %s, first 8 characters used
  2039.   TRCERR_NEXTLINENUM    linenum in file: %s not found, using #%s
  2040.   TRCERR_BAD_OBJ      bad object number: %s used for file %s
  2041.   TRCERR_BAD_OFFSET    offset %s is invalid for object number %s
  2042.   TRCERR_BAD_PAGE     page tracepoint to be applied at not valid
  2043.   TRCERR_MAXLEN_EXCEED   MAXDATALENGTH to log could be exceeded
  2044.   TRCERR_INVALIDMAJOR   MAJOR out of range, 1 used
  2045.   TRCERR_INDEXTRUNC    index too large, high word ignored
  2046.