.\"Copyright 1990 Open Software Foundation (OSF
.\"Copyright 1990 Unix International (UI)
.\"Copyright 1990 X/Open Company Limited (X/Open)
.TH tcc "1"
.SH NAME
tcc \- Test Case Controller commands for building, executing and
cleaning up test scenarios.
.SH SYNOPSIS
.in +5n
.ti -5n
\fBtcc\fR
[\ \fB\-b\fR\ ]
[\ \fB\-c\fR\ ]
[\ \fB\-e\fR\ ]
[\ \fB\-a\ \fIAlt_exec_dir\fR\ ]
[\ \fB\-f\ \fIClean_cfg_file\fR\ ]
[\ \fB\-g\ \fIBuild_cfg_file\fR\ ]
[\ \fB\-i\ \fIInt_results_dir\fR\ ]
[\ \fB\-j\ \fIJournal_file\fR\ ]
[\ \fB\-l\ \fIScenario_line\fR\ ]
[\ \fB\-p\fR\ ]
[\ \fB\-n\ \fISearch_string\fR\ ]
[\ \fB\-s\ \fIScenario_file\fR\ ]
[\ \fB\-t\ \fITimeout\fR\ ]
[\ \fB\-v\ \fIVariable=value\fR\ ]
[\ \fB\-x\ \fIExec_config_file\fR\ ]
[\ \fB\-y\ \fISearch_string\fR\ ]
[\ \fITest_suite\fR\ [\ \fIScenario\fR\ ]\ ]
.sp
.ti -5n
\fBtcc \-m\ \fICode_list\fR [ \fIoptions\fR ] \fIOld_journal_file\fR
[\ \fITest_suite\fR\ [\ \fIScenario\fR\ ]\ ]
.sp
.ti -5n
\fBtcc \-r\ \fICode_list\fR [ \fIoptions\fR ] \fIOld_journal_file\fR
[\ \fITest_suite\fR\ [\ \fIScenario\fR\ ]\ ]
.in -5n
.SH DESCRIPTION
The Test Case Controller (TCC) has three mode selection options,
which may be used singly or in any combination.  All of the other options
modify the behaviour of the TCC in one or more modes.
Each mode (with optionally modified behaviour) is applied to the test
cases and invocable components selected for processing.
.PP
Unless otherwise specified, journal information and saved intermediate
result files are placed below a sequentially numbered directory under the 
.B results
directory of the test suite selected. The TCC writes the name of the 
.B journal\fR
to standard output on startup.
.SH OPTIONS
.TP 5
\fBMode Selection\fR
.TP 5
\fB-b\fR
Enable build mode.
.TP 5
\fB-c\fR
Enable clean mode.
.TP 5
\fB-e\fR
Enable execute mode.
.PP
\fBMajor Options\fR
.PP
These two options cannot be used together.
.TP 5
\fB-m \fICode_list\fR
Resume from a specified point in a previous run.  The argument
.I Code_list
specifies a comma-separated list of result code names and the letters
\fBb\fR, \fBe\fR and \fBc\fR.  Upon encountering an execution result
corresponding to one of the specified result code names, or where
\fBb\fR, \fBe\fR or \fBc\fR is specified, any build, execute or clean
failure respectively, in the
.I Old_journal_file ,
the associated invocable component and all subsequent invocable
components in the scenario are built, executed and/or cleaned up, as
appropriate.  E.g.:
.TP 25
.in +5
tcc -b -m b
# resume building from IC which
.br
# failed to build.
.TP 25
.in +5
tcc -e -m FAIL,UNRESOLVED
# resume execution from IC which
.br
# gave FAIL or UNRESOLVED result
.br
# on execution.
.TP 25
.in +5
tcc -bec -m b,e
# resume building, executing and
.br
# cleaning from IC which failed
.br
# to build or execute, or did not
.br
# give a PASS result on execution.
.TP 5
\fB-r \fICode_list\fR
Re-run specified invocable components from a previous run.  The argument
.I Code_list
specifies a comma-separated list of result code names and the letters
\fBb\fR, \fBe\fR and \fBc\fR.  Upon encountering an execution result
corresponding to one of the specified result code names, or where
\fBb\fR, \fBe\fR or \fBc\fR is specified, any build, execute or clean
failure respectively, in the
.I Old_journal_file ,
the associated invocable component is built, executed and/or cleaned
up, as appropriate.  E.g.:
.TP 25
.in +5
tcc -b -r b
# re-build all ICs which failed
.br
# to build.
.TP 25
.in +5
tcc -e -r FAIL,UNRESOLVED
# re-execute all ICs which gave
.br
# FAIL or UNRESOLVED result on
.br
# execution.
.TP 25
.in +5
tcc -bec -r b,e
# re-build, execute and clean 
.br
# all ICs which failed to build
.br
# or execute, or did not give a
.br
# PASS result on execution.
.TP 5
\fBOther Options\fR
.TP 5
\fB-a \fIAlt_exec_dir\fR
The argument
.I Alt_exec_dir
specifies the pathname of the root of a directory hierarchy in which
executable test cases should be placed (by the build tool 
in build mode), executed 
from
(in execute mode), and cleaned from (by the clean tool
in clean mode). If unspecified, the alternate execution directory
is taken from the environment variable
.BR TET_EXECUTE ,
if set, otherwise the default behaviour is to execute test cases from the
test suite hierarchy.
.TP 5
\fB-f \fIClean_cfg_file\fR
The argument
.I Clean_cfg_file
specifies the pathname of the file of configuration variables to use
in clean mode. If unspecified this value defaults to
.B tetclean.cfg
in the alternate execution directory, or failing that,
.B tetclean.cfg
in the root directory of the test suite selected.
.TP 5
\fB-g \fIBuild_cfg_file\fR
The argument
.I Build_cfg_file
specifies the pathname of the file of configuration variables to use
in build mode. If unspecified this value defaults to
.B tetbuild.cfg
in the alternate execution directory, or failing that,
.B tetbuild.cfg
in the root directory of the test suite selected.
.TP 5
\fB-i \fIInt_results_dir\fR
The argument
.I Int_results_dir
specifies the pathname of the root of a directory hierarchy to store
intermediate result files (matching the configuration variable
TET_SAVE_FILES). If unspecified the intermediate results directory
defaults to a sequentially numbered directory under the
.B results
directory of the test suite.
.TP 5
\fB-j \fIJournal_file\fR
The argument
.I Journal_file
specifies the pathname of the file in which to record journal information.
If unspecified, the journal file is named
.B journal
in the root of the intermediate results hierarchy (see \fB-i\fR option).
.TP 5
\fB-l \fIScenario_line\fR
The argument
.I Scenario_line
specifies a single line that is be treated as though it appeared in a 
scenario file. Multiple lines may be specified by repeating this option.
Any scenario line, other than an invocable component execution line,
should be quoted to the shell.  If a scenario file is also specified (via
the \fB-s\fR option) the lines specified with \fB-l\fR options are
processed before the scenario file.  If no \fB-s\fR option is used, then
no scenario file is processed.
.TP 5
\fB-p\fR
Enable progress reporting.  As each build, execute or clean is started
a line is printed to standard output giving the time, the mode, and the 
scenario line.
.TP 5
\fB-n \fISearch_string\fR
The argument
.I Search_string
specifies a portion of text to search for in any scenario invocable component
execution line.  Multiple strings may be specified by repeating this option.
If a string is found then that line is not executed.
This option has a higher precedence than the \fB-y\fR option.  I.e. lines
which match a \fB-y\fR search string and a \fB-n\fR search string are
not processed.
.TP 5
\fB-s \fIScenario_file\fR
The argument
.I Scenario_file
specifies the pathname of a scenario file.  If no
.B -s
or
.B -l
options are specified, the default is to use a scenario file called
.B tet_scen
in the root directory of the test suite selected.
.TP 5
\fB-t \fITimeout\fR
The argument
.I Timeout
specifies the number of seconds to allow a single build, execute, or
clean of a test case to continue. If unspecified the TCC imposes no time
limit.
.TP 5
\fB-v \fIVariable\fR=\fIvalue\fR
The argument
\fIVariable\fR=\fIvalue\fR
is used to set the configuration variable
.I Variable
to
.IR value .
Multiple variables may be manipulated by repeating this option with
different settings.  If
.IR value
contains white space or other characters special to the shell, it must
be quoted.
.TP 5
\fB-x \fIExec_config_file\fR
The argument
.I Exec_config_file
specifies the pathname of the file of configuration variables to use
in execute mode. If unspecified this value defaults to
.B tetexec.cfg
in the alternate execution directory, or failing that,
.B tetexec.cfg
in the root directory of the test suite selected.
.TP 5
\fB-y \fISearch_string\fR
The argument
.I Search_string
specifies a portion of text to search for in any scenario invocable component
execution line.   Multiple strings may be specified by repeating this option.
A string must be found in order for the line to be processed.
This option has a lower precedence than the \fB-n\fR option.
I.e. lines which match a \fB-y\fR search string and a \fB-n\fR
search string are not processed.
.SH OPERANDS
.TP 5
.I Old_journal_file
This operand is only used with the resume and re-run options.  It
indicates the pathname of the journal file that is to be searched for
test failures meeting the criteria specified by the user.
.TP 5
.I Test_suite
This operand indicates the suite to which the scenario must be
applied. The suite name is used by the TCC to determine the
test suite root directory name.
If none is given on the command line, a default test suite may be deduced
by the TCC according to the following rules:

1. If the current directory lies under the TET_ROOT directory hierarchy,
the test suite is the component of the current directory's pathname
which lies immediately below the TET_ROOT.  E.g. if the TET_ROOT is
/usr/TET and the current directory is /usr/TET/suite1/results, then
the default test suite is
.IR suite1 .

2. If the current directory lies outside of the TET_ROOT directory hierarchy,
then no default can be deduced.
.TP 5
.I Scenario
This operand indicates the Test Scenario that is to be processed
by the Test Case Controller. If none is given on the command line,
the default scenario is
.BR all .
If a scenario is specified but no scenario file is in use (see \fB-l\fR
and \fB-s\fR options), the TCC gives an error message and exits.
.SH "ENVIRONMENT VARIABLES"
.TP 5
TET_ROOT
The pathname of the TET root directory. When set, this variable
has precedence over the value compiled into the TCC.
.TP 5
TET_EXECUTE
The pathname of the root of the execution directory hierarchy.
If set this value is used as the alternate execution directory, unless
overridden by use of the \fB-a\fR option.
.TP 5
TET_TMP_DIR
The location for the temporary directories created by the TCC (see
\fBFILES\fR below). Performance problems due to networked file systems
may be helped by setting this variable to a directory on a local file system.
.SH FILES
By default the TCC creates a temporary directory in the TET root directory
called \fBtet_tmp_dir\fR. Each invocation of the TCC creates a unique 
sub-directory below it.
In the sub-directory are placed files that are needed during TCC
execution. After completion the sub-directory is removed. However should the
the TCC terminate abnormally there is a possibility that a sub-directory will
remain. Such sub-directories should be removed to avoid wasting space.
.SH RELEASE
1.9 (03/09/92)
