Extension Functionality

XYZ manages a set of tags. A tag consists of a tag name, a tag value, and a trace level. The tag name is a character string used to name a specific tag. The tag value is a signed integer counter. The trace level is used to determine if a tag should be output if tracing is enabled.

Figure: Example of use of XYZ macro.
\begin{figure}\begin{center} {\tt \begin{tabular}{\vert l\vert} \hline \\ int \... ...urn (BadRequest); \\ \} \\ \\ \hline \end{tabular}} \end{center} \end{figure}

Tags are used by scattering XYZ macros through server code intended to be instrumented or traced. The XYZ macro takes a tag name as its single argument. Figure [*] shows an example code fragment which uses the XYZ macro. When the macro is encountered during code execution, the macro either:
  1. increments the tag value by one for the named tag, i.e. instrumentation;
  2. outputs the tag name and corresponding tag value if the trace level for the tag is less than or equal to the current trace level, i.e. tracing;
  3. does both; or
  4. does nothing.
The XYZ instrumentation and XYZ tracing booleans determine whether the instrumentation and tracing functions are enabled or not.

The outcome also depends on the XYZ status which can be either XYZ_NO_ERROR (the normal state) or XYZ_ERROR. If the XYZ status is XYZ_ERROR, the incrementing of the tag value is not performed. When the XYZ status is reset to XYZ_NO_ERROR, the instrumentation function will resume.

Because the instrumentation function can cause memory to be dynamically allocated (an operation which can fail), the XYZ_ERROR status is used to signal failure. The stopping of instrumentation results in predictable semantics in the face of memory allocation failure.

In the tracing case, whether the tag name and tag value are actually output or not depends on the trace level for that tag. By default, all tag trace levels are 255. XYZ maintains a current trace level. If the trace level of the specified tag is less than or equal to the current trace level, the tag is output. Individual trace levels of tags can be changed using XYZ requests.

A version of the XYZ macro called XYZdelta is also available which takes a second signed integer argument which is the amount to change the tag value by for the named tag.


Subsections