The following definitions are common to the QTRC Trace APIs:
A
Active Trace Level
The Trace Level that is currently active for a given application Component. The active trace level is specified when a Trace Collection is started, using the Start Trace (STRTRC) CL command. The user indicates which component and at what trace level they want that component to trace. The terms used to describe the active trace level for a given component include: ERROR Trace, INFO Trace, and VERBOSE Trace. Since the active trace level is specific to a component, different components can have different active trace levels. The QtrcGetActiveLevel() function will indicate an active trace level of NONE if a trace collection is not active, or if the component is not part of an active trace collection.
C
Coded Trace Level
The Trace Level that is specified in the application code, for each Trace Point. The application developer chooses the appropriate trace level based on the type of data to be collected. This could also be called the desired trace level, since it becomes the indicator, based on the Trace Conditions, as to whether a trace point will actually be written as a Trace Record. The coded trace level is also shown in the trace output for each trace record that is written. The terms used to describe a coded trace level, as seen in the application code, include: ERROR-level Trace Point, INFO-level Trace Point, and VERBOSE-level Trace Point.
Component
A 10-byte character string which names the application component. Each Trace Point has an associated component that is specified on the QTRC Trace APIs. The component name is also shown in the trace output for each Trace Record that is written. A component is defined to the QTRC Trace environment when specified on the Start Trace (STRTRC) CL command. Component names should only contain characters in the invariant character set. Avoid using lowercase a through z. Application component names should contain an abbreviated company name along with the application name. Component names starting with an asterisk (*) are reserved for the operating system. Component names starting with Q are reserved for IBM® licensed programs.
E
ERROR-level Trace Point
A Trace Point which has a Coded Trace Level of ERROR. The trace data will be written as a Trace Record when the Trace Conditions are met and the component's Active Trace Level is set to either ERROR, INFO, or VERBOSE. For more information, see QTRC Trace Levels.
ERROR Trace
A Trace Collection that is started, using the Start Trace (STRTRC) CL command, where the trace data collected for a given Component should only include error conditions. It indicates the type and amount of trace data that will be collected. For more information, see QTRC Trace Levels. An ERROR Trace means the Active Trace Level for a given component is set to ERROR, hence only ERROR-level Trace Points will be written as a Trace Record to the trace collection, if the Trace Conditions are met.
F
Function
An optional character string, up to 512 bytes, which can be specified on a Trace Point. The function can be used to identify a function, program, procedure, class, or method name, among other things, and is shown in the trace output for each Trace Record that is written. If no function is defined, *NONE will be shown. Function should only contain characters in the invariant character set. For example, the function could be "MYLIB/MYPGM," "MyFunction()," or "MyClass::MyMethod(int,void *)."
I
INFO-level Trace Point
A Trace Point which has a Coded Trace Level of INFO. The trace data will be written as a Trace Record when the Trace Conditions are met and the component's Active Trace Level is set to either INFO or VERBOSE. For more information, see QTRC Trace Levels.
INFO Trace
A Trace Collection that is started, using the Start Trace (STRTRC) CL command, where the trace data collected for a given Component should include informational data and error conditions. It indicates the type and amount of trace data that will be collected. For more information, see QTRC Trace Levels. An INFO Trace means the Active Trace Level for a given component is set to INFO, hence both INFO-level Trace Points and ERROR-level Trace Points will be written as Trace Records to the trace collection if the Trace Conditions are met.
L
Label
An optional character string, up to 128 bytes, which can be specified on certain Trace Points. The label can be used to identify or describe the trace data. The label should only contain characters in the invariant character set. For example, if a structure named myStruct is being written by the QtrcWriteHexDumpF() function, the label could be something like "Contents of myStruct after initialization."
S
Subcomponent
An optional 10-byte character string which can be specified on a Trace Point. The subcomponent further classifies the trace data, and is shown in the trace output for each Trace Record that is written. If no subcomponent is defined, *NONE will be shown. The subcomponent can be used to identify related sections within a Component. Each trace point can have a subcomponent associated with it. Subcomponent should only contain characters in the invariant character set. Avoid using lowercase a through z. For example, the component could be XYZ_LOANS and the subcomponents could be HOME, AUTO, and RV.
T
Trace Collection
A trace that has been started and is now collecting trace data to a common storage area. This is accomplished through the Start Trace (STRTRC) CL command, which also uses the term trace session to describe this process.
Trace Conditions
The conditions that must be met in order for a Trace Point to be written out as a Trace Record. The conditions include: 1) A Trace Collection must be started and active for the current thread, 2) The Component is part of the trace collection (namely, an Active Trace Level is set for that component), 3) The trace point must have a Coded Trace Level that allows trace data to be written based on the active trace level.
Trace Level
There are 3 trace levels: ERROR, INFO, and VERBOSE. Trace levels are used to describe both an Active Trace Level as well as a Coded Trace Level. For more information, see QTRC Trace Levels.
Trace Point
The location within a program where an application developer has coded a call to a QTRC Trace API to write trace data. Trace data can include a string of text, a hexadecimal dump, or a call stack.
Trace Record
A Trace Point that was actually written out, and is now part of a Trace Collection.
V
VERBOSE-level Trace Point
A Trace Point which has a Coded Trace Level of VERBOSE. The trace data will be written as a Trace Record when the Trace Conditions are met and the component's Active Trace Level is set to VERBOSE. For more information, see QTRC Trace Levels.
VERBOSE Trace
A Trace Collection that is started, using the Start Trace (STRTRC) CL command, where the trace data collected for a given Component should include detailed data, informational data, as well as error conditions. It indicates the type and amount of trace data that will be collected. For more information, see QTRC Trace Levels. A VERBOSE Trace means the Active Trace Level for a given component is set to VERBOSE, hence all VERBOSE-level Trace Points, INFO-level Trace Points, and ERROR-level Trace Points will be written as Trace Records to the trace collection if the Trace Conditions are met.