COBOL Scanner Guide

Follow these steps to configure a connection for the COBOL and JCL scanner.

Step 1: Configure the Connection

Create a new connection in Admin UI http://localhost:8281/manta-admin-gui/app/index.html?#/platform/connections/ to enable lineage analysis of COBOL jobs by IBM Automatic Data Lineage. A best practice is to create a separate connection for each system. The connection requirements and privileges are listed in COBOL Integration Requirements.

Properties that must be configured:

Identification of the COBOL connection: cobol.dictionary.id, cobol.script.format

Optional properties:

To control lineage analysis: jcl.script.enabled, cobol.script.processScriptsWithoutJCL

See COBOL Resource Configuration for the full list and a detailed explanation of the properties that can be configured for the scanner.

Step 2: Provide the COBOL and JCL Files

Automatic Data Lineage does not provide an extractor for COBOL, which means that the jobs must be exported and provided to Automatic Data Lineage by the Manta Administrator before or upon execution of the lineage analysis. There are three types of files that should be provided to the respective directories matching respective filename patterns as per COBOL Manual Inputs. See the chart below with details on COBOL script formats to chose the right extensions for the input files and determine your COBOL script format to configure it in the cobol.script.format connection property.

Source Code Formats

The COBOL source code format option determines which file format the analyzed COBOL programs use. The following formats are supported.

Format	cobol.script.format configuration value	Description	Tips for identifying the format	Example
Free	FREE	Position of the text in the line is usually insignificant	Program code usually starts at column 1 or 4 with no sequence numbers or empty columns	`IDENTIFICATION DIVISION. PROGRAM-ID. GET-CUST. >\*************************************************************** > Program: GET-CUST > Change history: > REV00002 1990-04-01 Changed program name >*************************************************************** AUTHOR. DEV1. ENVIRONMENT DIVISION. ... WORKING-STORAGE SECTION. 01 WS-COL-HEADER pic X(60) VALUE '123456789012345678901234567890123456789012345678901234567890'.`
Fixed (IBM COBOL)	FIXED	Columns 1–6: sequence area Column 7: indicator field Columns 8–12: area A Columns 13–72: area B Columns 73–80: comments	Program code starts at column 8 or 12 Columns 1–6 are usually either empty or contain a number sequence Column 7 is empty most of the time; program comments, however, start with a `*` in this column Lines are never more than 80 characters long Columns 73–80 sometimes contain comments or a number sequence	000010 IDENTIFICATION DIVISION. 000020 PROGRAM-ID. GET-CUST. REV00002 000030***************************************************************** 000040* Program: GET-CUST * 000050* Change history: * 000060* REV00002 1990-04-01 Changed program name * 000070***************************************************************** 000080 AUTHOR. DEV1. 000090 ENVIRONMENT DIVISION. ... 000200 WORKING-STORAGE SECTION. 000210 01 WS-COL-HEADER pic X(60) VALUE '123456789012345678901234567890' 000220-'123456789012345678901234567890'.
Variable	VARIABLE	Columns 1–6: sequence area Column 7: indicator field Columns 8–12: optional area A Columns 13 to the end of the line: optional area B	Similar to FIXED, but columns 73 and higher may contain program code and do not contain comments or number sequences	`000010 IDENTIFICATION DIVISION. 000020 PROGRAM-ID. GET-CUST. 000030***************************************************************** 000040* Program: GET-CUST * 000050* Change history: * 000060* REV00002 1990-04-01 Changed program name * 000070***************************************************************** 000080 AUTHOR. DEV1. 000090 ENVIRONMENT DIVISION. ... 000200 WORKING-STORAGE SECTION. 000210 01 WS-COL-HEADER pic X(60) VALUE '123456789012345678901234567890123456789012345678901234567890'.`
HP / Tandem	TANDEM	Column 1: indicator field Columns 2–5: optional area A Columns 6–132: optional area B	Program code starts at column 2 or 6 Column 1 is empty most of the time; program comments, however, start with a `*` in this column	`IDENTIFICATION DIVISION. PROGRAM-ID. GET-CUST. ***************************************************************** * Program: GET-CUST * * Change history: * * REV00002 1990-04-01 Changed program name * ***************************************************************** AUTHOR. DEV1. ENVIRONMENT DIVISION. ... WORKING-STORAGE SECTION. 01 WS-COL-HEADER pic X(60) VALUE '123456789012345678901234567890123456789012345678901234567890'.`

The JCL orchestrates execution of the COBOL program. The syntax appears as follows.

//COMPILE   JOB ,CLASS=6,MSGCLASS=X,NOTIFY=&SYSUID             
//*            
//STEP1     EXEC IGYCRCTL,PARM=RMODE,DYNAM,SSRANGE
//SYSIN     DD DSN=MYDATA.URMI.SOURCES(MYCOBB),DISP=SHR
//SYSLIB    DD DSN=MYDATA.URMI.COPYBOOK(MYCOPY),DISP=SHR
//SYSLMOD   DD DSN=MYDATA.URMI.LOAD(MYCOBB),DISP=SHR
//SYSPRINT  DD SYSOUT=*
//*

Step 3: Database Connection Definition Settings

If your COBOL scripts read from or write to a database, you need to provide additional details for successful lineage analysis such as the database and/or schema names. Definitions of database connections are not included in the COBOL scripts and need to be specified separately. Create the Automatic Data Lineage connectionsConfiguration.prm file as follows.

Create or open the file referenced by the cobol.connections.file property (e.g., <MANTA_DIR_HOME>/input/cobol/<cobol.dictionary.id>/connectionsConfiguration.prm).
Follow the instructions in Manually Define a Database Connection.
See a sample configuration for a COBOL connecion. The Server_Name, Database_Name and Schema_Name properties are optional.
```
[DEFAULT]
Type=DB2
Connection_String=identificationOfConnection
Server_Name=NameOfDb2Server 
Database_Name=DefaultDbName
Schema_Name=DefaultSchemaName
```
Once completed, you may also need to provide a connection alias as described in Alias (Manual) Connection Mappings Explained.

Step 4: Calls to Sub-Programs Specified via Variable

COBOL allows for dynamic calls to sub-programs by dynamically specifying the sub-program name as a value of a variable in the program. Automatic Data Lineage cannot evaluate these dynamic assignments for the lineage analysis. The user can statically specify what program should be called for lineage analysis.

These cases can be identified in COBOL Dataflow Analysis log files via messages similar to:

2022-05-06 00:27:55.335 [pool-2-thread-1] 0 ERROR io.proleap.cobol.metamodel.procedure.statement.program.CallStatementImpl [Context: c:\manta\mantaflow-latest-demo\cli\platform\bin\..\..\input\cobol\cobol\Copybookfolder\TX3TIER.cpy]
INPUT_STRUCTURE_ERRORS MISSING_CALL_PROGRAM_NAMES_CONFIG_ENTRY
User message: Missing configuration of sub-program names for CALL in program D3BINTP by variable W-VHJKJMAX.
Technical message: Missing configuration of sub-program names for CALL in program D3BINTP by variable W-VHJKJMAX: <496,12> callStatement.
Solution: Add at least one record into configuration in following form: D3BINTP;W-VHJKJMAX;SUB-PROGRAM-NAME
Impact: SINGLE_INPUT

The entry suggested in the solution message should be added to the file specified by the property cobol.call.targets.file, and replace SUB-PROGRAM-NAME with the name of the actual sub-program that should be used for lineage analysis. The first line of the file is always interpreted as a header.

For example:

"Calling program name";"Calling variable name";"Target program name"
D3BINTP;W-VHJKJMAX;D3SORTX