Asset Variants

Overview

An Asset Variant is OpenLegacy’s handling of a COBOL REDEFINES statement. To understand Asset Variants and how they are used, let’s first review the COBOL REDEFINES statement.

COBOL REDEFINES

A COBOL REDEFINES statement is used to define a storage area with different data descriptions. If one or more data items are not used simultaneously, then the same storage area can be utilized for another data item. Then the same storage area can be referred to with different data items. The following example illustrates this:
01 WS-DESCRIPTION.
05 WS-DATE1 PIC X(8).
05 WS-DATE2 REDEFINES WS-DATE1.
10 WS-YEAR PIC X(4).
10 WS-MONTH PIC X(2).
10 WS-DATE PIC X(2).
In this example, WS-DESCRIPTION is an 8-byte storage area that can be utilized as:

• WS-DATE1 – an 8-byte character string (this is the default field)
  or
• WS-DATE2 – an 8-byte structure comprised of 3 sub-fields (this is the REDEFINES field)

Asset Variants

An OpenLegacy asset is a metadata representation of the set of input and output fields. If the fields can be defined with multiple data descriptions using COBOL REDEFINES statements, then we need a way to represent each data structure definition associated with the asset definition. This is accomplished by creating a separate data definition in the asset for each COBOL REDEFINES statement. The asset data definitions corresponding to the COBOL REDEFINES are called Asset Variants. The Default Variant corresponds to the original COBOL definition. In the above example, WS-DATE1 is represented by the Default Variant and WS-DATE2 is represented by an Asset Variant.

The main features of Asset Variants are:

• An Asset may have several variants.
• An Asset Variant can be selected when mapping the Input-Output flow. If no Variant is selected, the Asset used is the Default configuration corresponding to the original COBOL data definition.
• When a new version of asset is created, Asset Variants are migrated from the previous version, unless the new version has made changes to fields that were referenced in the variant.

Displaying Asset Variants

We will illustrate the use of Asset Variants with an example. Let’s say we have a module named "redefine", which contains one asset:

Clicking on the module displays the asset named "redf" in this module:

Clicking on the asset "redf" drills down further to show us the asset data, dfhcommarea:

If we drill down further by clicking on dfhcommarea, we see the structure of this data area:

The dfhcommarea data structure shown contains a sub-field called "customerData", which is highlighted in turquoise and has two arrow icons adjacent to it. This indicates that there is at least one REDEFINES for the "customerData" data field. Clicking on the "customerData" data field reveals the original data field, "customerData", as well as the REDEFINES field, "customerDataX":

The Backend Attributes displays the attributes of the original COBOL field, "CUSTOMER-DATA". To see the attributes of the REDEFINES field, "customerDataX", click on the arrow icon:

To see the structure of the REDEFINES field, "customerDataX", click on the arrow icon to the left of "customerDataX":

Note that "customerDataX" consists of three sub-fields: customerName, customerPhone and customerAddress. Note also that "customerAddress" is a REDEFINES field within the "customerDataX" REDEFINES field – a nested REDEFINES.

Adding an Asset Variant

To enable using the COBOL REDEFINES, you must create an Asset Variant for each COBOL REDEFINES you want to use in your API.
For example, we will create an Asset Variant that has the data structure as shown above.

1. Click on the Save Variant button on the right-hand side of the screen:

2. The Add New Variant window opens. Type a Variant name for the new variant and click on Save Variant.

3. The newly created Asset Variant appears in the Variant drop-down menu:

The Default variant corresponds to the original COBOL data structure. Additional variants can be created from additional REDEFINES, as needed.

Configuring Asset Variants

To use an Asset Variant:

1. Open the Project containing the Asset:

2. Create a Contract based on the modules in the Project, for example, using the Bottom Up option:

3. The Contract screen is displayed:

4. Click on the icon and select Add Method:

5. Enter a name for the Method and click on Done:

6. The screen for the newly created method is displayed:

7. Drag the Invoke block on the right-hand side of the screen to the method flow:

8. The Add Asset block is added to the map:

9. Click on the Add Asset block. Project Modules appears below:

10. Select the radio button next to the desired module and click the Next button:

11. The selected asset appears in the map:

12. Click on the selected asset block. The Asset Variant appears below (initially the Default variant):

13. Click on the icon on the right-hand side of the screen and select Set Asset Configuration:

14. To select the Asset Variant to use, click on the Variant dropdown menu and select the desired Asset Variant:

15. For example, selecting the variant "var-x" displays the "var-x" data structure:

16. After you have selected the desired Asset Variant, click the Save Changes button. A confirmation window opens:

17. Click Save to save the selected Asset Variant configuration or Cancel to change/cancel the selection.

Mapping the Asset Variant

After the Asset Variant has been configured, it can be used to map the Input to Output flow.

1. Click the mapping block:

2. The mapper displays the configured Asset Variant:

The configured Asset Variant can now be used to map the Input-Output flow.