trcfmt File Format

Purpose

Stores trace templates.

Description

The trcrpt command, which formats trace reports, uses trace templates to determine how the data contained in trace entries should be formatted. All trace templates are stored in the master template file, /etc/trcfmt. Trace templates identify the trace hook ID, the version and release number, the indentation level, the event label, and data description fields. The data description fields contain formatting information for the trace entry data and can be repeated as many times as is necessary to format all of the trace data in the trace entry.

Modifying this File

The trcfmt file should only be modified using the trcupdate command. Trace hooks with values less than 010 are for internal use by the trace facilities. If these hooks are changed, the performance of trace, in particular trcrpt, is unpredictable.

Trace Entries

The data recorded for each traced event consist of a word containing the trace hook identifier and the hook type followed by a variable number of words of trace data optionally followed by a timestamp. The word containing the trace hook identifier and the hook type is call the hook word. The remaining two bytes of the hook word are called hook data and are available for recording event data.

Data Pointer

The DATA POINTER is a pointer to the current position in the trace entry. The DATA POINTER is changed by the trcrpt as it interprets the template and formats the trace entry. The initial position of the DATA POINTER is the third byte of the HookWord for HookTypes 1, 9, 2, A, 6, and E and the first byte after the HookWord for HookTypes 0 and 8.

Trace Data Formatting

Indentation Level

The formatted trace data is aligned in columns corresponding to the source of the trace event. This is identified in each template using the L=X descriptor. The possible values of the L=X command are as follows:

Continuation Character

A \ (backslash) at the end of a line must be used to continue a template on the next line.

Labels or Text Strings

Individual strings (or labels) can be separated by any number of spaces or tabs, but all excess spacing is compressed to one blank on the trace report unless other format structures are put into effect. Labels are enclosed in double quotes (" ").

Format Codes

DATA POINTER Position Format Codes

Output Format Codes

Interpreter Format Codes

Switch Statements

A SWITCH statement is a format code followed by a comma. Each CASE entry of the SWITCH statement consists of:

1. A 'MatchValue' with a type (usually numeric) corresponding to the format code.
2. A simple 'String' or a new 'Descriptor' bounded by braces. A descriptor is a sequence of format codes, strings, switches, and loops.
3. A comma delimiter.

The switch is terminated by a CASE entry without a comma delimiter. The CASE entry is selected as the first entry whose MatchValue is equal to the expansion of the format code. The special matchvalue '\*' is a wildcard and matches anything.

The DATA POINTER is advanced by the format code.

LOOP Statements

Loops are used to output binary buffers of data; therefore, the descriptor for a LOOP is usually X0 or X1. The syntax of a loop is LOOP format_code {descriptor}. The descriptor is executed N times, where N is the numeric value of the format code.

The DATA POINTER is advanced by the format code and by the operations of the descriptor.

Macros

Macros are temporary variables that work like shell variables. They are assigned a value with the syntax:

{{ $xxx = EXPR }}

where EXPR is a combination of format codes, macros, and constants. The operators + (addition), - (subtraction), / (division), and * (multiplication). are permissible within macros.

Predefined Macros

Built-in Macros

The built-in macros are:

Implementation Specifics

The trcfmt file is part of the operating system.

Files

Related Information

The trcupdate command.

The trcgen subroutine, trchook subroutine.

Trace Facility Overview in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.