Mainframe use case: Branch wiring instructions, control REDEFINES

COBOL record layouts may include REDEFINES clauses that allow alternate layout information in the same memory field to be described by different data items within a single physical file. The distinct SQL mappings for the file create separate table definitions in the metadata catalog. The REDEFINES clause defines alternate values for the data.

The challenge with loading these datasets traditionally has been that the COBOL language does not define a type tag to identify which branch of the REDEFINES union is in effect (so that only valid branch values are preserved). The property cobol.branch.wiring.instructions allows users to declare how they want REDEFINES clauses to be treated so that elementary items under valid branches preserve their value; elementary items under invalid branches are set to null.

In contrast to filtering on one desired record type as with record filtering, COBOL branch wiring instructions allows multiple record types to be ingested and parsed on record values so that if a value is valid for a variable, the other values are automatically invalidated. COBOL layouts with REDEFINES require branch wiring instructions for data to load successfully. A buffer of predefined size reserves space for the record fields—this placeholder element name is arbitrary as it will never be represented in the data. In the example below, this 40-space buffer is called  'LOAN-DATA'.

REDEFINES elements store different field values for different record types in the same space. Level 02-Level 49 are equal though hierarchical in that the lower levels (higher numbers) typically hold subsets of elements described in the higher levels (lower numbers). The levels tell the COBOL compiler how to associate or group fields within the record. The copybook layout below illustrates three primary functions:

• This copybook defines 3 different Entities as shown by separate 01-levels. This record layout exists at a higher-level (01) from branch wiring but is worth noting for the copybook and data file in the example.

• The field name <LOAN-TYPE> holds a 4-character string.

  • Level number 88 is used for conditional names. The conditional name identifies the particular value associated for the dataload. 88 Value Clauses in the example provide possible values for the 3 distinct branches associated with the conditional names. (Note: conditional names do not use any storage.)

• The three rows that are underlined describe how a 40-character spaceholder <LOAN-DATA-AREA> will be populated for specific values based on which branch is in effect (<LOAN-TYPE> branch: 'AUTO', 'HOME', or 'EDUC')

Copybook example text:
       01 HEADER.
         20 RECORD-TYPE       PIC X(4).
           88 HEADER-RECORD-FLAG  VALUE 'HEAD'.
         20 PROCESSING-SYSTEM PIC X(4).
         20 PROCESSING-DATE   PIC X(8).
         20 FILLER            PIC X(48).

       01 TRAILER.
         20 RECORD-TYPE       PIC X(4).
           88 TRAILER-RECORD-FLAG  VALUE 'TRLR'.
         20 RECORD-COUNT      PIC 9(4).
         20 FILLER            PIC X(56).

       01 LOAN.                                     
         20 RECORD-TYPE       PIC X(4).
           88 LOAN-RECORD-FLAG    VALUE 'LOAN'.
         20 LOAN-TYPE         PIC X(4).                    
           88 AUTO-LOAN-FLAG VALUE 'AUTO'.           
           88 HOME-LOAN-FLAG VALUE 'HOME'.           
           88 EDUC-LOAN-FLAG VALUE 'EDUC'.           
         20 LOAN-NUMBER       PIC 9(4).
         20 CUSTOMER-ID       PIC X(4).
         20 LOAN-AMOUNT       PIC 9(6)V9(2).               
         20 LOAN-DETAIL-AREA  PIC X(40).

	 20 AUTO-LOAN REDEFINES LOAN-DETAIL-AREA.
	   30 AUTO-TYPE		PIC X(8).
	   30 AUTO-MODEL-YEAR	PIC 9(4).
	   30 FILLER		PIC X(28).

 	 20 HOME-LOAN REDEFINES LOAN-DETAIL-AREA.
	   30 CONSTRUCTION-YEAR	PIC X(8).
	   30 CONSTRUCTION-TYPE	PIC X(8).
	   30 FILLER		PIC X(28).

 	 20 EDUC-LOAN REDEFINES LOAN-DETAIL-AREA.
	   30 INSTITUTION	PIC X(8).
	   30 MAJOR		PIC X(8).
	   30 GRADUATION-YEAR	PIC X(4).
	   30 FILLER		PIC X(20).

Mainframe Wizard: Branch wiring instructions controlling for REDEFINES

Connect to the data source and provide the information required to establish the connection. Initiate the Add Data Wizard and select To existing source.

Name the entity to be created and the filepath location of sourced data. Upload the copybook.

Select the entity or entities to be created. To display the fields expand the caret to the left of the entity name. Click on Next.

Select Internal file format SAVE the entity.

Note that in single node environments, TEXT_TAB_DELIMITED is the only Stored Format Type.

Once the copybook has been uploaded and metadata definition steps are complete; navigate to the entities screen, locate the entity that was created (in this case 'LOAN'). Select the entity row and Load from the More dropdown.

The job status screen will display.—data will have loaded but all records validate as Bad. This is because the application has been given no direction regarding how this copybook's REDEFINES should be treated therefore the records are sequentially processed and no data is found in the space-holder (buffer). User instructions are required as to how the branches should be processed and which branch is in effect.

Property Definition: Branch Wiring

Open the properties panel of the entity to expand entity properties (Key/Values) by selecting Details or View/Edit Properties from the More dropdown. The cobol.branch.wiring.instructions property is already in place. Click on the (view) icon to the right of the property to access a wider field to enter the property value.

The following branch wiring instructions directs the application to validate and populate values <AUTO-LOAN-DATA>, <HOME-LOAN-DATA>, and <EDUCATION-LOAN-DATA> when <LOAN-TYPE> == <AUTO>, <HOME>, <EDUC>, respectively as those branches are in effect. The copybook and screenshot are provided here for reference.

Copybook example text:
        20 LOAN-TYPE PIC X(4)
	   88 AUTO-LOAN-FLAG VALUE 'AUTO'.           
           88 HOME-LOAN-FLAG VALUE 'HOME'.           
           88 EDUC-LOAN-FLAG VALUE 'EDUC'.
	 20 LOAN-NUMBER       PIC 9(4).
        20 CUSTOMER-ID       PIC X(4).
        20 LOAN-AMOUNT       PIC 9(6)V9(2).               
        20 LOAN-DETAIL-AREA  PIC X(40).

 	 20 AUTO-LOAN REDEFINES LOAN-DETAIL-AREA.
	   30 AUTO-TYPE		PIC X(8).
	   30 AUTO-MODEL-YEAR	PIC 9(4).
	   30 FILLER		PIC X(28).

 	 20 HOME-LOAN REDEFINES LOAN-DETAIL-AREA.
	   30 CONSTRUCTION-YEAR	PIC X(8).
	   30 CONSTRUCTION-TYPE	PIC X(8).
	   30 FILLER		PIC X(28).

 	 20 EDUC-LOAN REDEFINES LOAN-DETAIL-AREA.
	   30 INSTITUTION	PIC X(8).
	   30 MAJOR		PIC X(8).
	   30 GRADUATION-YEAR	PIC X(4).
	   30 FILLER		PIC X(20).

Enter guidelines for handling REDEFINES. See also Branch Wiring property detail and syntax

Once entered, Apply and Save the cobol.branch.wiring.instructions definition.

Reload data for the Entity ('LOAN'). The first job status row listed shows results for the successfully branched data.

Note that for this example, the EBCDIC file had a header and trailer that had to be accounted for with property values: [(header.byte.count, 64), (trailer.byte.count, 64)]; so the next dataload resulted with 2 Bad records . Once those properties were set the entity loaded with appropriate records branched by LOAN_TYPE.

Sample data shows how the 40-character space-buffer was replaced with data branched by LOAN-TYPE.

Sample data shows how the 40-character space-buffer was replaced with data branched by LOAN-TYPE.