TETware Java API Overview
7. Error Handling and Reporting
When an exception occurs in an API method in the TET package, the method throws a TetException object. This object contains fields and methods that provide information about the condition that caused the error to occur. Items that only apply to a particular method are described in the section that describes the method. Items that apply to all methods are described in the subsections that follow.
It is recommended that API exceptions are caught by test purposes and appropriate messages written to the journal. If an unhandled exception occurs in a test purpose function, the API catches the exception, prints a message to the journal and registers an UNRESOLVED result. If an unhandled exception occurs in a test case's startup method, the API cancels all the test purpose functions.
Classes in the TET package indicate fatal errors by throwing instances of subclasses of java.lang.Error. A test purpose either should not catch these objects or, if it does, the catching function should re-throw the error so that the API can catch it and perform the correct actions before terminating with the appropriate exit status.
In addition to the following fields and methods, the toString() method of TetException may be used in the usual way for Throwable objects; that is: to retrieve the message that describes the reason for the exception.
Contents: tet_errno tet_errlist()
The value of the tet_errno field in a TetException object indicates the reason why the exception was thrown. Distributed TETware uses a client/server architecture and calls to several of the API functions cause the API to send requests to server processes. A server sends a reply code in response to each request that it receives. When the reply code indicates that a request has failed, the value stored in tet_errno is derived from the server reply code. A list of the server reply codes and their meanings is presented in the appendix entitled "Server reply codes" in the TETware User Guide.
The possible error codes values are defined in the TestSession class as public static final fields, whose names and meanings are as follows:
Whenever an unsuccessful API call throws a TetException with tet_errno set to TET_ER_ERR (the general error code), a diagnostic message is generated somewhere which contains more precise details of the cause of the error. If an error of this type occurs in the API library, the diagnostic is printed to the execution results file as a TCM/API message if possible; if this is not possible, the diagnostic is printed on the test case's standard error stream.
However, in Distributed TETware, an error of this type can also occur in a server process. In this case the more detailed error message is printed on the server's standard error stream. The result of this is that when an API call is unsuccessful in Distributed TETware and tet_errno is set to TET_ER_ERR, the more detailed error message often appears in a TCCD log file on the local system or on one of the remote systems that is participating in the test run.
The array returned by tet_errlist() contains short strings which describe each of the values defined for tet_errno. The value of tet_errno in a TetException object may be used to index the array returned by tet_errlist(). The value of tet_errno should be checked against the length of the array to guard against the possibility that a new error code is added to the API before the corresponding message is added to the array.
This method returns an array of String objects, each of which contains a description of a tet_errno value.