FMT Keyword

The optional FMT parameter is used to produce the formatting string for the trace data. The developer should use these to control formatting the output produced by the Trace Formatter. Each FMT keyword causes CR/LF to be appended to the format string. The formatting string is similar to a C library printf string specification. It consists of ASCII characters and formatting controls enclosed in double quotes as for a C language string. Each formatting primitive describes the format of the data in the trace buffer at the formatting position and must match the data stored in the trace buffer by the data statements described later. See Formatting Trace Data for a description of how the data is stored in the trace buffer and subsequently formatted.

The formatting controls are as follows:

• Innn
  Ignore nnn number of bytes in the trace buffer.

  This tells the Trace Formatter to skip over the next nnn bytes in the current trace record. This could be used, for example, to skip over unimportant data, traced as a block, and only output the data of interest.

  When using this control, nnn represents an ASCII decimal number and must be followed by a space.

          statement: FMT = "ignore ten bytes %I10 here",
                     FMT = "       and two more %I2 here",
  
          generates: ignore ten bytes here
                            and two more here
  
  

  %P
  Process the data prefix bytes associated with the trace data.

  This tells the Trace Formatter that the next bytes in the trace record are the prefix or header bytes for data logged by the dynamic tracing mechanism. This is required to precede any format control describing data logged from memory. Do not use this before data that was logged from a register and never use with static tracepoints. See Formatting Trace Data for a description of how the data is stored in the trace buffer and the use of this control.

          statements: FMT="memory byte = /usr/cmvc/family/pubdoc/vc/0/1/2/2/s.69B",
  
          generates:  memory byte = C2
  
  

  %B
  Output a byte of data.

          statement: FMT = "memory byte = /usr/cmvc/family/pubdoc/vc/0/1/2/2/s.69B"
  
          generates: memory byte = 01
  
  

  %W
  Output a word of data.

          statement: FMT = "register word = %W"
  
          generates: register word = 0001
  
  
          statement: FMT = "memory word = /usr/cmvc/family/pubdoc/vc/0/1/2/2/s.69W"
  
          generates: memory word = 0001
  
  

  %D
  Output a double word of data.

          statement: FMT = "double word EAX = %D"
  
          generates: double word EAX = 0000 4B2C
  
  
          statement: FMT = "double memory word = /usr/cmvc/family/pubdoc/vc/0/1/2/2/s.69D"
  
          generates: double memory word = 0000 4B2C
  
  

  %F
  Output a Flat (0:32 bit) address.

          statement: FMT = "flat address EAX = %F"
  
          generates: flat address EAX = 00004B2C
  
  

  %Q
  Output a quad word of data.

          statement: FMT = "quad word from regs EAX and EBX = %Q"
  
          generates: quad word from regs EAX and EBX = 00004B2C 00000001
  
  

  %A
  Output a segmented (16:16 bit) address.

          statement: FMT = "segmented address in SS:SP = %A"
  
          generates: segmented address in SS:SP = 00B7:0001
  
  
          statement: FMT = "segmented address in memory = /usr/cmvc/family/pubdoc/vc/0/1/2/2/s.69A"
  
          generates: segmented address in memory = 00B7:0001
  
  

  %R
  Repeat the following format control for the rest of the memory that was logged.

  This is used for formatting variable length records. Use this in place of the prefix parameter %P to log the rest of the record in the format specified following the repeat code.

     statement: FMT = "log a variable number of words from memory = 1W"
  
     generates: log a variable number of words from memory = 0001 0004
  
  

  %S
  Output an ASCIIZ string.

  The prefix formatting control should always precede this for dynamic tracepoints because the data was logged from memory.

  Note: If the tracepoint is static, then %P should not be used because the string is terminated with a null byte.

          statement: FMT = "string = /usr/cmvc/family/pubdoc/vc/0/1/2/2/s.69S"
  
          generates: string = c:\os2\os2.ini
  
  

  %U
  Format the remainder of the trace record as a sequence of bytes.

  This will output the remaining of the traced data, including any prefix bytes.

          statement: FMT = "garbage = %U"
  
          generates: garbage = 00 00 00 03 c2 c1 c4 ff 04 00 09 c0 18
  
  

  %X
  Output the major event code.

          statement: FMT = "major code = %X"
  
          generates: major code = 00C2
  
  

  %Y
  Output the minor event code.

          statement: FMT = "minor code = %Y"
  
          generates: minor code = 0081
  
  

  To avoid conflicts with source file control information, all formatting specifications can be in upper or lower case. Also, prefix format specifications may be combined with data format specifications. For example, the following create the same format controls in the TFF:

          FMT = "/usr/cmvc/family/pubdoc/vc/0/1/2/2/s.69W here"        FMT = "%p%w here"
          FMT = " %P %W here"
  
  

  ---

  [Back: DESC Keyword]
  [Next: LEN Keyword]