Work with copybook messages

The Tricentis Tosca API Engine supports messages in the formats CBL, COB, and CPY. This allows you to work with Common Business Oriented Language (COBOL) files that are often used in administration, business, and finance systems. Copybook files are included files that contain information on the data structure of COBOL files and allow programs to interpret them.

First you have to import your copybook messages as described in chapter "Import copybook messages". Then the API Engine enables you to define Module Attributes and to verify their values.

Read copybook messages

A copybook message contains data records that consist of multiple individual fields and field groups. There are three possible field types:

  • A: an alphabetic field (A-Z, a-z, space)

  • 9: a numeric field (0-9)

  • X: any character field (including binary)

For instance, X(20) represents a character field with twenty characters and 9(05) represent a numeric field with five digits. The field type can also contain COMP-3 which indicates that the field packs data in binary coded decimal format, i.e. two digits in every byte.

It is not possible to easily translate the payload of a copybook message into text. Therefore, the API Engine displays the payload in a table. The table consists of the following columns:

  • Level: defines which fields belong together as a group. Data records have a hierarchical structure with levels from 1 (highest) to 99 (lowest). Level 0 specifies the name of the data record.

  • Element ID: indicates the name of the element, i.e. field. Field names are unique with the exception of FILLER which acts as a placeholder.

  • Position: indicates the position of the field in the data record, e.g. 90 means the field starts with character 90.

  • Length: indicates the number of characters that the field comprises, e.g. 20 means the field contains 20 characters. If the value has fewer characters than the length indicates, the system adds white spaces or zeros in case of numeric fields.

  • Type: indicates the field type, e.g. 9(07) COMP-3.

  • Value: displays the value of the field, e.g. any information such as a name or account number.

Import copybook messages

To work with copybook messages using the API Engine, you have to import them and enable the table view. To do so, follow the steps below:

  1. Configure a CICS service port and record messages from your copybook files in OSV.

  2. Import the messages to Tosca Commander.

  3. To enable the table view, open the directory C:\Tosca_Projects and create a new folder with the name ServiceDefinitions.

  4. Create a sub-folder with the name Copybooks.

  5. Copy and paste the copybook files that you created messages from into the Copybooks folder. If required, you can create new sub-folders in the Copybooks folder.

Now you can work with your imported copybook messages using the table view.

To create API TestCases, convert your OSV Scenarios.

Create Module Attributes

You can create Module Attributes to steer the values of copybook message elements. To do so, follow the steps below:

  1. Select an API Module and access the API Testing menu.

  2. Click Add in the API Testing menu. This opens the Attribute Assistant window.

  3. To add a Module Attribute, select it in the Attribute Assistant window and click Add. You can select multiple Module Attributes by holding CTRL.

Alternatively, you can add Module Attributes manually. To do so, select one or multiple elements in the payload and click Add in the API Testing menu.

The created Module Attributes indicate the respective message elements and are organized hierarchically based on the message structure.

Copybook Module Attributes