SNAP-IX TN3270 Administrator's Guide - 5.2 Controlling Tracing

5.2 Controlling Tracing

This section describes how you can start and stop tracing, how you specify the names of trace files, and how you can control the size of trace files.

5.2.1 Controlling Tracing of the TN3270 Program

The SNAMSG environment variable controls tracing the TN3270 program. The syntax for SNAMSG is:

file1 [ : file2 ]

Specify the following parameters in the SNAMSG environment variable:

file1: Name of the trace file.
file2: Optionally included name of a second trace file. Use a colon to separate the two file names. If you specify two trace files, when one file has reached the maximum size (as specified by the SNATRACESIZE environment variable), trace data is written to the second file. When the second file has reached the maximum size, trace data is written again to the first file.

SNAMSG tracing is always active if the environment variable is set. Tracing cannot be turned on and off while the program is running.

Trace data must always be written to text files. Do not specify the name of a device (such as /dev/tty) or a print spooler as a trace filename. If you do not specify a full path for the trace file or files, SNAP-IX TN3270 uses the directory from which you start the application.

5.2.2 Controlling Tracing of HLLAPI Applications

The SNATRC environment variable and the HLLAPI Set Session Parameters function control HLLAPI application tracing. To use the Set Session Parameters function, always set the SNATRC environment variable before starting the application program.

Specifying Trace Files for a HLLAPI Application

The SNATRC environment variable specifies one or two files to hold trace data and indicates whether to activate tracing when the application starts. The syntax for the SNATRC environment variable is:

file1 [ : [ file2 ] [ : ] ]

Specify the following parameters in the SNATRC environment variable:

file1: Name of the trace file.
file2: Optionally included name of a second trace file. Use a colon to separate the two file names. If you specify two trace files, when one file has reached the maximum size (as specified by the SNATRACESIZE environment variable), trace data is written to the second file. When the second file has reached the maximum size, trace data is written again to the first file.
Final colon (:): The final colon indicates that tracing is active as soon as the HLLAPI application is started. If tracing is not active when the application is started, it can be activated from within the application using the HLLAPI function Set Session Parameters. (For more information, see Controlling Tracing from Within a HLLAPI Application.) If you specify only one file name, use two colons to make tracing active as soon as the application is started.

If you specify only one file name, the size of the trace file has no limit. If you specify two file names, the maximum size of each trace file is specified by the SNATRACESIZE environment variable. For more information, see Controlling the Amount of Trace Data. Using two files extends the trace period and limits the disk space usage to twice the value specified in SNATRACESIZE.

Trace data must always be written to text files. Do not specify the name of a device (such as /dev/tty) or a print spooler as a trace filename. If you do not specify a full path for the trace file or files, SNAP-IX TN3270 uses the directory from which you start the application.

The following examples illustrate the SNATRC environment variable:

file1.trc:file2.trc

Trace to file1 and file2. Tracing is inactive when the HLLAPI application is started.

filea.trc::

Trace to one file (filea.trc) of unlimited size. Tracing starts when the HLLAPI application is started.

file1.trc:file2.trc:

Trace to file1 and file2. Tracing starts when the HLLAPI application is started.

Controlling Tracing from Within a HLLAPI Application

The and options of the HLLAPI Set Session Parameters function enable you to trace the specific section of a HLLAPI program where a problem is being encountered (without having to trace the whole application). Tracing can be activated at the start of this section and deactivated at the end of it. Refer to the SNAP-IX HLLAPI Programmer's Guide for more information.

To use this facility, the SNATRC environment variable must be set before the application program is started. For more information, see Controlling Tracing of HLLAPI Applications. When setting this environment variable, set tracing to be active or inactive when the HLLAPI application is started and then activate it or deactivate it from within the application as required.

You can disable the and options by using the SNACTL environment variable.

Disabling the Application's Control of Tracing

The SNACTL environment variable overrides the and options of the HLLAPI Set Session Parameters function so that the application cannot control its own tracing. You can use SNACTL to force the tracing of an application program that normally turns tracing off for some functions, or to prevent tracing for an application program that normally uses it.

If the SNACTL variable is set before the application program is started, any and tracing control requests from within the application program are ignored, although the return code indicates a successful completion. If tracing is on, it remains on; if tracing is off, it remains off.

To use SNACTL, set it to any non-blank string. To cancel it, set SNACTL to a blank character.

5.2.3 Controlling the Amount of Trace Data

The following environment variables control the amount of data stored in trace files:

SNATRUNC

Specifies the maximum length in bytes of each entry in a trace file. This variable applies both to HLLAPI trace files (specified by the SNATRC environment variable) and to TN3270 emulation program tracing (specified by the SNAMSG environment variable).

Set this variable to a decimal number. If a message has more characters than this value, the excess characters are truncated. For example, setting SNATRUNC to 70 limits tracing to 70 bytes of data per entry. By default, the length of internal messages is limited to a maximum of 256 bytes.

SNATRACESIZE

Specifies the maximum size in bytes of each trace file when using two files. This value applies both to HLLAPI trace files (specified by the SNATRC environment variable) and to TN3270 emulation program tracing (specified by the SNAMSG environment variable), but only when tracing to two files. If you are tracing to one file, the size of the trace file has no limit.

Set this environment variable to a decimal number. When SNAP-IX TN3270 is writing a message to one of the trace files and the maximum file size is reached, SNAP-IX TN3270 clears the other trace file and continues tracing to that file. This ensures that the maximum amount of disk space taken up by a pair of user-space trace files is approximately twice the value of SNATRACESIZE.

If you do not set SNATRACESIZE, the default is 1 megabyte. To cancel the SNATRACESIZE setting and return to the default, set SNATRACESIZE to a blank character.

5.2.4 Resetting Trace Files

The SNATRCRESET environment variable controls whether a trace file is reset when an application first writes to it. Normally, the file is reset and its contents discarded when an application writes its first trace message to the file. If you are tracing two or more applications to the same file, or if you want to trace two or more runs of the same application to the same file, you can prevent the file from being reset by setting the SNATRCRESET environment variable to NO.

If you are tracing to two files, the files continue to be reset as normal when the maximum file size is reached, but they will not be reset when an application starts tracing for the first time. If you are tracing to one file, setting SNATRCRESET to NO means that the file will never be reset automatically. To avoid taking up too much disk space, delete it manually from time to time.

To cancel the setting of SNATRCRESET and return to the default setting so that the file is reset when an application first traces to it, set SNATRCRESET to YES.