TET
Class TestSession

java.lang.Object
  extended byTET.TestSession

public final class TestSession
extends java.lang.Object

The TestSession class provides TETware API services to Java test cases.


Field Summary
static int TET_ER_2BIG
          tet_errno value for argument list too long.
static int TET_ER_ABORT
          tet_errno value for abort TCM on TP end.
static int TET_ER_CONTEXT
          tet_errno value for request out of context.
static int TET_ER_DONE
          tet_errno value for event finished or already happened.
static int TET_ER_DUPS
          tet_errno value for request contained duplicate IDs.
static int TET_ER_ERR
          tet_errno value for general error code.
static int TET_ER_FID
          tet_errno value for a bad file id.
static int TET_ER_FORK
          tet_errno value for can't fork.
static int TET_ER_INPROGRESS
          tet_errno value for event in progress.
static int TET_ER_INTERN
          tet_errno value for a server internal error.
static int TET_ER_INVAL
          tet_errno value for invalid request parameter.
static int TET_ER_LOGON
          tet_errno value for not logged on.
static int TET_ER_MAGIC
          tet_errno value for a bad magic number.
static int TET_ER_NOENT
          tet_errno value for no such file or directory.
static int TET_ER_OK
          tet_errno value for ok, success.
static int TET_ER_PERM
          tet_errno value for priv request/kill error.
static int TET_ER_PID
          tet_errno value for no such process.
static int TET_ER_RCVERR
          tet_errno value for a receive message error.
static int TET_ER_REQ
          tet_errno value for an unknown request code.
static int TET_ER_SIGNUM
          tet_errno value for a bad signal number.
static int TET_ER_SNID
          tet_errno value for bad snid in syncd request.
static int TET_ER_SYNCERR
          tet_errno value for sync completed unsuccessfully.
static int TET_ER_SYSID
          tet_errno value for sysid not in system name list.
static int TET_ER_TIMEDOUT
          tet_errno value for request timed out.
static int TET_ER_TRACE
          tet_errno value for tracing not configured.
static int TET_ER_WAIT
          tet_errno value for process not terminated.
static int TET_ER_XRID
          tet_errno value for bad xrid in xresd request.
static int TET_FAIL
          Result code for FAIL result.
static int TET_NORESULT
          Result code for NORESULT result.
static int TET_NOTINUSE
          Result code for NOTINUSE result.
static int TET_PASS
          Result code for PASS result.
static int TET_SV_NO
          Synchronisation "no" vote.
static int TET_SV_YES
          Synchronisation "yes" vote.
static int TET_UNINITIATED
          Result code for UNINITIATED result.
static int TET_UNRESOLVED
          Result code for UNRESOLVED result.
static int TET_UNSUPPORTED
          Result code for UNSUPPORTED result.
static int TET_UNTESTED
          Result code for UNTESTED result.
 
Method Summary
 void tet_delete(int testno, java.lang.String reason)
          Mark the test purpose specified by testno as cancelled.
 java.lang.String[] tet_errlist()
          Retrieves the list of error strings which describe each value of tet_errno.
 void tet_exit(int status)
          Exit function for child process.
 int tet_getblock()
          Deprecated. Not part of the published API.
 SystemEntry tet_getsysbyid(int sysid)
          Retrieves information about a system participating in the test.
 java.lang.String tet_getvar(java.lang.String name)
          Gets the value of a configuration variable.
 void tet_infoline(java.lang.String line)
          Prints a line to the execution results file.
 long tet_jspawn(java.lang.String classname, java.lang.String[] args, java.lang.String[] envp)
          Creates a new subprogram using a Java class.
 void tet_kill(long pid, int sig)
          Sends a signal to a process.
 void tet_logoff()
          Log off TETware.
 void tet_minfoline(java.lang.String[] lines)
          Prints a group of lines to the execution results file.
 java.lang.String tet_pname()
          Retrieves the test case name.
 java.lang.String tet_reason(int testno)
          Retrieves the reason for test purpose cancellation.
 int[] tet_remgetlist()
          Gets a list of the other systems participating in the test case.
 int tet_remgetsys()
          Gets the system ID of the system on which the calling process is executing.
 void tet_remsync(long syncptno, int[] sysnames, int waittime, int vote, SyncMessage msg)
          Synchronises with one or more of the other systems in a distributed test case.
 java.util.Date tet_remtime(int sysid)
          Obtains the system time on another system.
 void tet_result(int result)
          Informs the API of the result of the current test purpose.
 void tet_setblock()
          Increments the current block ID.
 void tet_setcontext()
          Sets the current context to the value of the current process ID, and resets the block and sequence numbers to 1.
 long tet_spawn(java.lang.String file, java.lang.String[] argv, java.lang.String[] envp)
          Creates a new subprogram.
 int tet_thistest()
          Retrieves the absolute test number for the currently executing test purpose.
 int tet_wait(long pid)
          Waits for a process to terminate.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

TET_PASS

public static final int TET_PASS
Result code for PASS result.

See Also:
Constant Field Values

TET_FAIL

public static final int TET_FAIL
Result code for FAIL result.

See Also:
Constant Field Values

TET_UNRESOLVED

public static final int TET_UNRESOLVED
Result code for UNRESOLVED result.

See Also:
Constant Field Values

TET_NOTINUSE

public static final int TET_NOTINUSE
Result code for NOTINUSE result.

See Also:
Constant Field Values

TET_UNSUPPORTED

public static final int TET_UNSUPPORTED
Result code for UNSUPPORTED result.

See Also:
Constant Field Values

TET_UNTESTED

public static final int TET_UNTESTED
Result code for UNTESTED result.

See Also:
Constant Field Values

TET_UNINITIATED

public static final int TET_UNINITIATED
Result code for UNINITIATED result.

See Also:
Constant Field Values

TET_NORESULT

public static final int TET_NORESULT
Result code for NORESULT result.

See Also:
Constant Field Values

TET_SV_YES

public static final int TET_SV_YES
Synchronisation "yes" vote.

See Also:
Constant Field Values

TET_SV_NO

public static final int TET_SV_NO
Synchronisation "no" vote.

See Also:
Constant Field Values

TET_ER_OK

public static final int TET_ER_OK
tet_errno value for ok, success.

See Also:
Constant Field Values

TET_ER_ERR

public static final int TET_ER_ERR
tet_errno value for general error code.

See Also:
Constant Field Values

TET_ER_MAGIC

public static final int TET_ER_MAGIC
tet_errno value for a bad magic number.

See Also:
Constant Field Values

TET_ER_LOGON

public static final int TET_ER_LOGON
tet_errno value for not logged on.

See Also:
Constant Field Values

TET_ER_RCVERR

public static final int TET_ER_RCVERR
tet_errno value for a receive message error.

See Also:
Constant Field Values

TET_ER_REQ

public static final int TET_ER_REQ
tet_errno value for an unknown request code.

See Also:
Constant Field Values

TET_ER_TIMEDOUT

public static final int TET_ER_TIMEDOUT
tet_errno value for request timed out.

See Also:
Constant Field Values

TET_ER_DUPS

public static final int TET_ER_DUPS
tet_errno value for request contained duplicate IDs.

See Also:
Constant Field Values

TET_ER_SYNCERR

public static final int TET_ER_SYNCERR
tet_errno value for sync completed unsuccessfully.

See Also:
Constant Field Values

TET_ER_INVAL

public static final int TET_ER_INVAL
tet_errno value for invalid request parameter.

See Also:
Constant Field Values

TET_ER_TRACE

public static final int TET_ER_TRACE
tet_errno value for tracing not configured.

See Also:
Constant Field Values

TET_ER_WAIT

public static final int TET_ER_WAIT
tet_errno value for process not terminated.

See Also:
Constant Field Values

TET_ER_XRID

public static final int TET_ER_XRID
tet_errno value for bad xrid in xresd request.

See Also:
Constant Field Values

TET_ER_SNID

public static final int TET_ER_SNID
tet_errno value for bad snid in syncd request.

See Also:
Constant Field Values

TET_ER_SYSID

public static final int TET_ER_SYSID
tet_errno value for sysid not in system name list.

See Also:
Constant Field Values

TET_ER_INPROGRESS

public static final int TET_ER_INPROGRESS
tet_errno value for event in progress.

See Also:
Constant Field Values

TET_ER_DONE

public static final int TET_ER_DONE
tet_errno value for event finished or already happened.

See Also:
Constant Field Values

TET_ER_CONTEXT

public static final int TET_ER_CONTEXT
tet_errno value for request out of context.

See Also:
Constant Field Values

TET_ER_PERM

public static final int TET_ER_PERM
tet_errno value for priv request/kill error.

See Also:
Constant Field Values

TET_ER_FORK

public static final int TET_ER_FORK
tet_errno value for can't fork.

See Also:
Constant Field Values

TET_ER_NOENT

public static final int TET_ER_NOENT
tet_errno value for no such file or directory.

See Also:
Constant Field Values

TET_ER_PID

public static final int TET_ER_PID
tet_errno value for no such process.

See Also:
Constant Field Values

TET_ER_SIGNUM

public static final int TET_ER_SIGNUM
tet_errno value for a bad signal number.

See Also:
Constant Field Values

TET_ER_FID

public static final int TET_ER_FID
tet_errno value for a bad file id.

See Also:
Constant Field Values

TET_ER_INTERN

public static final int TET_ER_INTERN
tet_errno value for a server internal error.

See Also:
Constant Field Values

TET_ER_ABORT

public static final int TET_ER_ABORT
tet_errno value for abort TCM on TP end.

See Also:
Constant Field Values

TET_ER_2BIG

public static final int TET_ER_2BIG
tet_errno value for argument list too long.

See Also:
Constant Field Values
Method Detail

tet_thistest

public int tet_thistest()
Retrieves the absolute test number for the currently executing test purpose. This is 0 when in the startup and cleanup routines.

Returns:
the current test number.

tet_pname

public java.lang.String tet_pname()
Retrieves the test case name.

Returns:
the test case name.

tet_errlist

public java.lang.String[] tet_errlist()
Retrieves the list of error strings which describe each value of tet_errno.

Returns:
the list of error strings.

tet_setcontext

public void tet_setcontext()
Sets the current context to the value of the current process ID, and resets the block and sequence numbers to 1.


tet_setblock

public void tet_setblock()
Increments the current block ID.


tet_getblock

public int tet_getblock()
Deprecated. Not part of the published API.

Retrieves the current TET block number.

Returns:
the current TET block number.

tet_infoline

public void tet_infoline(java.lang.String line)
Prints a line to the execution results file.

Parameters:
line - line to print to the results file.

tet_minfoline

public void tet_minfoline(java.lang.String[] lines)
                   throws TetException
Prints a group of lines to the execution results file. In Distributed TETware these lines are printed using a single operation which guarantees that lines from other test case parts do not appear in between lines printed by one call to this function.

Parameters:
lines - group of lines to print to the results file.
Throws:
TetException - if there was an error printing the lines.

tet_result

public void tet_result(int result)
Informs the API of the result of the current test purpose.

Parameters:
result - the result code.

tet_delete

public void tet_delete(int testno,
                       java.lang.String reason)
Mark the test purpose specified by testno as cancelled.

Parameters:
testno - absolute test number of the test purpose to be cancelled.
reason - text describing the reason why the test purpose is to be marked as cancelled. May be NULL, in which case the specified test purpose is reactivated if it has previously been marked as cancelled.

tet_reason

public java.lang.String tet_reason(int testno)
Retrieves the reason for test purpose cancellation.

Parameters:
testno - absolute test number of the test purpose.
Returns:
a string describing the reason for test purpose cancellation, or null if this test purpose is not marked as cancelled.

tet_getvar

public java.lang.String tet_getvar(java.lang.String name)
Gets the value of a configuration variable.

Parameters:
name - name of the configuration variable.
Returns:
the value of the specified configuration variable. If the variable specified is defined but has no setting, a String object of zero length is returned. If the variable is undefined, null is returned.

tet_spawn

public long tet_spawn(java.lang.String file,
                      java.lang.String[] argv,
                      java.lang.String[] envp)
               throws TetException
Creates a new subprogram. The subprogram launched must be built with the child process controller.

Parameters:
file - path of the subprogram to execute.
argv - argument array to pass to new process.
envp - environment data to pass to new process. If this is null or has length 0, the current environment is used.
Returns:
the process ID of the newly created process.
Throws:
TetException - if there is an error launching the child process.

tet_jspawn

public long tet_jspawn(java.lang.String classname,
                       java.lang.String[] args,
                       java.lang.String[] envp)
                throws TetException
Creates a new subprogram using a Java class. The class must be a subclass of ChildTestCase.

Parameters:
classname - name of the Java class to execute in a new process.
args - argument array to pass to main() method of the class N.B. args[0] is the first actual argument, not the name of the interpreter or the name of the class.
envp - environment data to pass to new process. If this is null or has length 0, the current environment is used.
Returns:
the process ID of the newly created process.
Throws:
TetException - if there is an error launching the child process.

tet_wait

public int tet_wait(long pid)
             throws TetException
Waits for a process to terminate.

Parameters:
pid - process ID of the process to wait for.
Returns:
the exit status of the process.
Throws:
TetException - if the wait is unsuccessful.

tet_kill

public void tet_kill(long pid,
                     int sig)
              throws TetException
Sends a signal to a process.

Parameters:
pid - process ID of the victim process.
sig - number of the signal to send. Note that this is ignored on a Windows NT system.
Throws:
TetException - the kill was unsuccessful.

tet_remsync

public void tet_remsync(long syncptno,
                        int[] sysnames,
                        int waittime,
                        int vote,
                        SyncMessage msg)
                 throws TetException
Synchronises with one or more of the other systems in a distributed test case.

Parameters:
syncptno - the sync point number to which the calling system wishes to synchronise. If syncptno is zero, a successful call to tet_remsync() returns as soon as all participating systems have synchronised to the next sync point.
sysnames - a list of IDs of the other systems with which to synchronise. The system ID of the calling system is ignored if it appears in the list.
waittime - the number of seconds that may elapse between synchronisation requests from other participating systems before the calling system times out.
vote - how the calling system wishes to vote in the synchronisation event. This should be TET_SV_YES or TET_SV_NO.
msg - used to exchange sync message data with other participating systems.
Throws:
TetException - if this is TETware-Lite, or if an error occurs during the sync.
See Also:
SyncMessage

tet_remgetlist

public int[] tet_remgetlist()
Gets a list of the other systems participating in the test case.

Returns:
list of IDs of the other systems participating in the test case. Returns null in TETware-Lite or for a test case in which no other systems are participating.

tet_remgetsys

public int tet_remgetsys()
Gets the system ID of the system on which the calling process is executing.

Returns:
the system ID of the current system.

tet_getsysbyid

public SystemEntry tet_getsysbyid(int sysid)
                           throws TetException
Retrieves information about a system participating in the test.

Parameters:
sysid - ID of the system of interest.
Returns:
the entry for the requested system.
Throws:
TetException - if this is TETware-Lite, or if an error occurs retrieving the entry for the specified system.
See Also:
SystemEntry

tet_remtime

public java.util.Date tet_remtime(int sysid)
                           throws TetException
Obtains the system time on another system.

Parameters:
sysid - ID of the system of interest.
Returns:
the system time on the system of interest.
Throws:
TetException - if this is TETware-Lite, or if an error occurs retrieving the system time of the specified system.

tet_exit

public void tet_exit(int status)
Exit function for child process. This should be used instead of java.lang.System.exit() by child processes created by tet_spawn(). In Distribute TETware this method logs off all TETware servers, then exits with the specified status.

Parameters:
status - exit status.

tet_logoff

public void tet_logoff()
Log off TETware. This may be called by a child process that is started by a call to tet_spawn() which does not need to make any further TETware API calls and is not able to call tet_exit() at process termination. This should only be called once from the child process. In Distributed TETware, the results are undefined if a process or any of its descendents makes any TETware API calls after tet_logoff() is called.