This chapter discusses how to set up your execution environment in order to use, or modify the behavior of, ATAC. Section 4.1 provides general information and describes the environment variables which are common to UNIX and Windows platforms. Section 4.2 describes variables specific to the UNIX environment. Section 4.3 documents variables specific to Windows users.
4.1 Common Environment Variables
ATAC components make use of a number of environment variables. The role played by
each of these variables and the specific ATAC components that make use of their values
are discussed below.
4.1.1 ATAC_BLOCKONLY
When a test is run, ATAC records data for a number of types of coverage (see Section 3.3,
What Does ATAC Do?). For very large programs it may be necessary to restrict run-time
recording to reduce the execution time and disk space (see Section 3.5, What Will Using
ATAC Cost You?). If ATAC_BLOCKONLY is set to yes at run-time, ATAC will only record
data for block coverage and weaker coverage types. Zero is displayed for other coverage
types. Tests run with this option set can be identified in the atactm -L listing by the B flag
(see. Section 7.1, Listing Test Cases).
4.1.2 ATAC_COMPRESS
In order to save disk space, atac instruments the program under test to compress the
trace file after each test execution. The ATAC_COMPRESS variable may be used to
suppress compression completely or to compress periodically. If ATAC_COMPRESS is set
to no when the program is executed, trace file compression is suppressed. If
ATAC_COMPRESS is set to an integer n, the trace file will be compressed after
approximately every n test executions. A trace file can be explicitly compressed using
atactm, regardless of whether or not ATAC_COMPRESS is set.
4.1.3 ATAC_COST
If ATAC_COST has a numeric value it will be assigned as the execution cost of the test case.
Test case costs are used by ATAC to compute a minimal test set (atac -M) or a cost
effective ordering (atac -S). The default value of ATAC_COST is 100.
4.1.4 ATAC_DIR
By default, trace data is written to a file in the current directory. If ATAC_DIR is set it is
the path name of the directory in which trace data is written. However, if ATAC_TRACE
(see Section 4.1.7, ATAC_TRACE) is set to a fully qualified path name, ATAC_DIR is not
used.
4.1.5 ATAC_TEST
Each program execution results in named test information being appended to the trace file.
The default test name is the base name of the trace file. A numeric suffix is appended to
each test name in order to make it unique (e.g., wordcount.1, wordcount.2, wordcount.3).
If ATAC_TEST is set, its value is used as the test name. The test name must be less than
1024 characters long, composed of alpha-numeric characters, comma, period, at-sign, and
underscore, and must not begin with a digit. Other characters in the test name are replaced
by question mark, except that slash is replaced by colon and hyphen is replaced by the
pound sign.
4.1.6 ATAC_TMP
While a test is running, ATAC stores coverage data in a temporary file. The default
directory on UNIX is the /usr/tmp directory. On Windows, the default is
%SystemRoot%\TEMP for Windows 95, and %SystemDrive%\TEMP for Windows NT.
When ATAC_TMP is set, it is the path of the directory in which the temporary files will be
written. The temporary file is written in append mode. On some systems, appending to a
file on a networked file system is very slow. For this reason, it is recommended that
temporary files be written to a directory on a local disk. Normally, temporary files are
removed when test execution completes. (See Section 4.1.2, ATAC_COMPRESS and
Chapter 7, ATAC: Managing Your Test Cases.)
4.1.7 ATAC_TRACE
By default, trace data is written to a file named prog.trace where prog is the name of the
program executable. If ATAC_TRACE is set, it is the name of the file to which the trace data
will be written. If the name does not end with the .trace suffix, the suffix is appended.
4.2 UNIX Only Environment Information
ATAC components make use of the following additional environment variables on UNIX:
ATAC_NOTRACE, ATAC_SIGNAL, ATAC_TEST_FILE, PATH and TERM. Of these,
only the PATH variable must be set.
4.2.1 ATAC_NOTRACE
If ATAC_NOTRACE is set, no trace file is created. This option may be useful when it is
necessary to run an instrumented program without creating a trace file.
4.2.2 ATAC_SIGNAL
Normally, a test case consists of a complete execution of a program. In some situations, a
single program execution may represent multiple test cases. The program can indicate the
start of a new test case by calling atac_restart(). This requires that the code be modified to
include this call, and that the call be removed when ATAC is not used. ATAC_SIGNAL
provides an alternate way of indicating the start of a test case. If ATAC_SIGNAL is set to
a UNIX signal name or number, ATAC will start a new test case each time the specified
signal is received by the program under test. The signal name must be a standard UNIX
signal name (e.g. SIGINT). The SIG prefix is not required and upper and lower case are
not distinguished. The signal number may be any valid signal number for your system.
4.2.3 ATAC_TEST_FILE
If ATAC_TEST is not set and ATAC_TEST_FILE is the name of a readable file, the
contents of the first line of that file is used as the test name. This facility is useful when it
is not possible to vary the value of the ATAC_TEST variable at run-time. In this case the
ATAC_TEST_FILE variable may be set at link-time to the name of a file that may be
modified at run-time to contain the test name.
4.2.4 PATH
When running ATAC component tools or programs compiled with atac, the PATH variable
should include the bin directory containing ATAC component tools (refer to your shell's
manual entry for more details). The component tools require that ataclib be found in the
PATH search. This permits ATAC user-layer components to locate ATAC library
components, and also permits you to execute each component from the command-line
without having to enter its absolute path name. Programs compiled with atac require that
atactm be found in the PATH search at run-time in order to compress the trace file (see
Section 7.8, Concerning Trace File Compression).
4.2.5 TERM
The atac (character-based) component requires the termcap (or terminfo) entry for the
terminal on which it is to display and highlight source code. This means that, when atac
executes, TERM should be set appropriately for the terminal on which its output is to be
displayed.
4.2.6 ATACLIB
ataclib is the location of the directory containing the Toolsuite library file.
4.2.7 ATAC_UMASK
When a trace file is created, it is given the same read/write
permissions as the directory in which it is created. This is important when multiple
processes run by different owners will be writing to the same trace file, so that the write
permissions on the trace file are not restricted to processes with the same owner as the
process that first created the trace file. If it is necessary to further restrict access to the trace
file, the ATAC_UMASK variable may be set.
4.3 Windows Only Environment Information
The following registry variables can be set from xconfig (see Section B.12, xconfig
(Windows only)). Although there are other variables defined in the Toolsuite registry, these are
installation options and should not be changed by the user.
4.3.1 ATAC_CL
ATAC_CL is the root of the Microsoft Visual C++ directory subtree. ATAC_CL is set
automatically by xconfig at installation or through the ``Find Compiler'' control on the
xconfig dialog.
4.3.2 ATAC_ICC
ATAC_ICC is the root of the IBM VisualAge directory subtree. ATAC_ICC is set
automatically by xconfig at installation or through the ``Find Compiler'' control on the
xconfig dialog.
4.3.3 ATAC_LIB
ATAC_LIB is the location of the directory
containing the Toolsuite library files.
4.3.4 ATAC_BIN
ATAC_BIN is the location of the directory containing the Toolsuite executables.
4.3.5 ROOT
ROOT is the base directory of the Toolsuite installation.
4.3.6 DEFINE
DEFINE specifies extra default definitions not provided by the cl.exe or icc.exe command
processor for C code. The DEFINE variable contains a semicolon-separated list of
preprocessor definitions. For example, DEFINE=-DWIN32=1;-DX86=TRUE;-
DFPUBUG=FALSE is a legal format. Default empty.
4.3.7 DEFINEPP
DEFINEPP functions the same as DEFINE only for C++. Default empty.
4.3.8 VERSION
VERSION provides information about the current release of the Toolsuite software, in terms of its underlying Suds release number.