Interfaces
An interface describes how to call a program interface that is to be tested. It is based on the technical parameters which correspond to those used in a call instruction: the called program and the data areas passed to it. In Total Test, we speak of the target program and the argument structures, respectively.
In addition to this purely technical information, Total Test requires you to add some semantic information, that is, information about how the content of the data area is used by the interface. Structures and attributes may be used as input, output or other, like control purposes. This information is usually defined outside the program source as a convention between the target program and its callers. By adding this information to a Total Test interface, defining test cases based on it becomes a much easier and more efficient task. Because an interface is defined once, but usually used multiple times, the additional effort is well invested.
Creating a New Interface
In order to create a new interface, select the project folder in which you want to create the interface, right-click to open the context menu and select New > 
Unit Test Interface... . The Interface Wizard opens. On the first page, enter the following data (obligatory fields listed in bold):
Field | Description |
|---|---|
Name | File name for the interface |
Alias Name | More descriptive name |
Type | Select the interface type, either:
|
Description | Detailed description |
If you have not selected a Total Test project before invoking the wizard, a list of Total Test projects displays in the Project list at the bottom of the wizard pages. You must select a project to continue to the next wizard page.
Click Next > to proceed to the next page. For z/OS, this is usually the name of the load module.
Then select the Call Parameters by selecting the required structures from the list of Available (previously imported) structures on the left, and clicking on the middle arrow in order to copy them to the list of Selected structures on the right. A structure may be copied to the Selected structures multiple times, if necessary. The Selected structures must be in the exact order in which they are expected by the target when invoking this interface. This means, the structures must exactly match the data areas passed in a call. You can re-arrange the Selected structures by selecting a structure and clicking the Up or Down buttons on the right of the list. Click the Remove button to remove a structure from the Selected structures.
If you select a structure, additional information regarding this structure will be displayed in the lower area. Although displayed, an Alias is not used for structures.
Once you have provided all required information, click Finish. The interface will be created and opened in the Interface Editor where you can complete the interface description by providing the usage of the structures and attributes. Optionally, default values can be provided.
For details on how to use the Interface Editor, see Editing an Interface.
Editing an Interface
The Interface Editor has two tabs that can be selected in the top area of the editor view:
• Edit Parameters to edit the type and values of argument structures.
• Information to edit the alias name and the description, but also the target name, as well as the structures used in the interface.
Edit Parameters
The Edit Parameters tab of the Interface Editor is used to complete the interface description to provide a business view on the interface.
• The Structure column displays a list of the structures and attributes used in the interface.
• The Usage column allows you to change the usage of structures and attributes.
• The Default Value column allows you to enter default values for attributes.
Structure
The Structure column displays a list of the structures used in the interface, including their substructures and attributes. Please refer to General Editor Behavior for a detailed description of all options provided to navigate in this list.
You can change the names of structures and attributes in this list by simply overwriting them in the Structure column. The new names will be used in all test cases based on this interface. This can be very useful to change cryptic technical names into more descriptive names. Changing names like this will even affect test cases that have been created before.
When the structure includes keys, for example, VSAM KSDS or VSAM RRDS structures, the primary key field is identified with the 
key icon. To set a field as primary key, right-click the field in the structure and select Set as Primary key. This update will also be reflected in the associated stub(s) and test cases for this interface.
Usage
In the Usage column, you can select the type of usage for a structure or field from a drop-down list. The usage of a structure or attribute is information about how it is used in the interface. This information is required to later display only relevant attributes, hence enabling easy and efficient creation of tests. Because this information is not available from the source code, it must be added here.
If you change the usage type of a structure, all attributes and substructures contained therein will be changed to the same usage type. It is therefore best to proceed from top down, that is, first define the main usage of the argument structures, then go down and modify its substructures and attributes as required.
The meaning of the different types of usage is explained below.
Types | Description |
|---|---|
Usage "in" | Attributes for which data have to be entered when defining a test, must be defined as usage in (input data). This usage type allows data to be entered in a test case. |
Usage "out" | Attributes in which the interface target returns data, must be defined as usage out (output data). This usage type allows data to be used in check conditions in a test case, and to be passed on to subsequent test cases. |
Usage "inout" | Some interfaces may use the same attributes for input and output at the same time. (Although this is not a good interface design, these interfaces must also be tested.) Attributes for which data have to be entered when defining a test, but at the same time are filled with a return value, the usage type must be set to inout (input and output data). |
Usage "fix" | Attributes may provide input data to the interface target, but at the same time, this input need not be entered in a test because, for this interface, the data are always the same. In such cases, the usage type should be set to fix (fixed data). This usage type effectively hides such attributes in test cases, keeping them as simple as possible. |
Usage "none" | This usage type is required for overlapping structures as defined by a |
REDEFINES clause in COBOL. You specify which one of the overlapping fields to use when processing these fields for this interface, and which not to use. All overlapping structures that are not used for this interface target, must be set to usage none (not used at all). Usage type none not only hides such attributes, but effectively prevents them from being assigned any data.Default Value
The Default Value column allows you to change or add the default value of an attribute. The default value is used in all test cases based on these interfaces. If you change a default value in an interface, this will even change the default value for existing test cases.
Even a newly created interface can have default values. These default values are taken from the structures. Default values from structures are displayed in blue. If you change or enter new default values in the Interface Editor, these values are displayed in black.
Values for text attributes can alternatively be entered in hex format, for example as x'61a5'. The hex value must be given in the target platform encoding because for hex values, no character conversion is performed.
If you want to reset a default value entered in an interface to the default value from the structure, simply clear the input field. If you want to override a text default value taken from the structure to spaces, simply enter space.
Besides entering values for attributes, you may enter values for structures, too. However, as structures cannot really hold values, the value entered will be propagated to the attributes contained in the structure. Values entered for structures are always treated as character data. Please note that character data propagated to numeric data types may lead to unexpected values.
The values used in a test case are determined in the following order for input attributes (usage in and inout):
- Value entered in the test case, if existing
- Default value entered in the interface, if existing
- Default value stored in the structure, if existing
- Empty according to project settings (see Building/Parsing Settings for details)
Table Processing Order provides an overview of the processing order.
Processing Order
Usage | Test case | Interface | Structure | EmptyA |
in | 1 | 2 | 3 | 4 |
out | - | 1 | 2 | 3 |
in/out | 1 | 2 | 3 | 4 |
fixed | - | 1 | 2 | 3 |
none | - | - | - | - |
n/aB | - | - | 1 | 2 |
ADepending on the project settings – for more information, see Project-Properties.
BAttributes without a defined usage may occur due to new attributes in re-imported structures if the interface has not been updated.
If an input attribute is later changed to a non-input usage type, values previously entered in test cases based on this interface are not used anymore (but they are still present in the test case).
Information
The Information tab allows you to change the Alias Name and Description of the interface.
Additionally, you can change the Selected structures. Changes will affect all test cases based on this interface. You can add, remove or re-arrange the Selected structures. However, any modifications that lead to changed positions of the structures, will cause an Automatic Intelligent Migration to take place for the affected test cases. This will usually work as expected, but under some circumstances, the Automatic Intelligent Migration may not be able to migrate all values.