Oracle Tuxedo Application Rehosting Workbench COBOL Converter

Overview

Purpose

Oracle Tuxedo Application Rehosting Workbench COBOL Converter aims to generate for each COBOL program on the z/OS source platform the same COBOL program for the target UNIX platform by applying accommodated transformations and modernization and restructuring rules.

The COBOL converter uses a set of configuration files to state which transformation rules to apply and provide specific hints to obtain the desired results.

This chapter describes how to convert COBOL programs from z/OS COBOL to Micro Focus COBOL or COBOL-IT.

Skills

This guide is intended for anyone using the Rehosting Workbench to convert programs from z/OS COBOL to Micro Focus COBOL or COBOL-IT.

When converting COBOL, a good knowledge of COBOL, JCL, MVS utilities and UNIX Korn Shell is required.

Organization

Migrating data files is described in the following sections:

•	Requirements & Prerequisites

•	Overview of the COBOL Converter in the Replatforming Process

•	Conversion Steps

•	Using a make File

•	Troubleshooting the COBOL Converter

Requirements & Prerequisites

Cataloguing Requirements

Cataloguing is mandatory before running the COBOL converter in order to check the consistency of the assets to be migrated and fix any errors related either to syntax or to the coherency (missing or unused components) of the asset.

Data Conversion

The data migration process must have been performed before the COBOL conversion is started. This dependency is because the data migration tools generate some of the configuration files read by the COBOL converter. The configuration files from data conversion are documented in the Oracle Tuxedo Application Rehosting Workbench Reference Guide.

Overview of the COBOL Converter in the Replatforming Process

The inputs to the Rehosting Workbench COBOL converter process are:

•	The abstract syntax trees of the COBOL programs stored in the pob files produced by the Rehosting Workbench Cataloger.

•	A set of configuration files, some of them are produced by the data conversion tools that specifies information about file-to-RDBMS conversion and relational DBMS conversion (from DB2to Oracle).

Conversion Steps

Building and Setting the Configuration Files

The main configuration file for translation is config-COBOL. It references other additional configuration files including:

•	keywords-file

•	tr-hexa.map

•	rename-call-map-file

Samples of all the needed configuration files are given in the Simple Application. You only need to check and adapt the values if necessary.

All of the configuration files that the COBOL Converter uses are described in the COBOL Converter chapter of the Oracle Tuxedo Application Rehosting Workbench Reference Guide.

Configuring config-COBOL

After preparing the prerequisites for the COBOL conversion, prepare the main configuration file using the following example as a model.

Note:

The following files can be used:

•	post-translation-file used when there is a need to perform some specific transformations. This file is to write manually.

•	rdbms-conversion-file used when migrating DB2 to an Oracle database. This file is generated by the Oracle Tuxedo Application Rehosting Workbench DB2 to Oracle Converter.

•	conv-ctrl-list-file used when there are files to be converted to Oracle tables. This file should be generated by the Oracle Tuxedo Application Rehosting Workbench File-To-Oracle Converter.

Listing 7‑1 config-cobol File

Config:

"Config version 1.0"

# sql-rules : none.

/* GENERAL */

target-dir: "../trf/".

keywords-file: "../param/keywords-file".

rename-call-map-file: "../param/rename-call-map-file".

accept-date : MW-DATE.

accept-day : MW-DAY.

# post-translation-file: "../param/renov.desc".

hexa-map-file: "../param/tr-hexa.map".

# rdbms-conversion-file : "dynamic-config/rdbms-conv.txt".

conv-ctrl-list-file : "dynamic-config/Conv-ctrl.txt".

on-size-error-call : "ABORT".

 

dcrp. /* Without reconcilation of copies files */

end

 

 

keywords-file

The keywords-file is a hint file for the COBOL Converter to help rename specific variables including reserved keywords probably not renamed systematically by the Rehosting Workbench COBOL Converter.

This is a reengineering mechanism offered by the WorkBench to perform a (mass-change) renaming operation for the customer’s own purposes, even when the variables are not MicroFocus or COBOL-IT reserved keywords.

Place the following entry in the main configuration file config-cobol:

keywords-file: "../param/keywords-file"

Listing 7‑2 Sample Keywords File

( TAB . MW-TAB )

( DOUBLE . MW-DOUBLE )

( POS . MW-POS )

)

 

In this example each occurrence of the item TAB will be replaced by MW-TAB.

tr-hexa.map

The tr-hexa.map file is a mapping table between EBCDIC (z/OS code set) and ASCII (Linux/UNIX code set) hexadecimal values.

Place the following entry in the main configuration file config-cobol:

hexa-map-file: "../param/tr-hexa.map"

This file is used by some translation rules like Tr-Hexa-Map and may help the user to solve problems related to differences between EBCDIC and ASCII codes in values and strings that could lead to different behavior in sorting and in string comparisons.

Generated hexa-map-file with convert-hexa-copy-to-map.sh script

This script is located in REFINEDIR/scripts/convert-hexa-copy-to-map.sh.

Syntax

REFINEDIR/scripts/convert-hexa-copy-to-map.sh convertmw_copy_file

convertmw_copy_file: location of the CONVERTMW.cpy file

The script generates a tr-hexa.map file inside the current directory (it should be the PARAM directory).

Hexadecimal Code for Space Example

The hexadecimal code for space in z/OS is 40 and the hexadecimal code for space in UNIX is 20.

The statement in the source platform code is:

01 VarName pic X value X'40'.

This is translated as:

Listing 7‑3 Hexadecimal Code Translation

*{ Tr-Hexa-Map 1.4.2.1

*01 VarName pic X value X'40'.

*--

01 VarName pic X value X'20'.

*}

 

Listing 7‑4 Sample of tr-hexa.map

00;00

01;01

02;02

03;03

37;04

2d;05

2e;06

2f;07

...

40;20

...

 

rename-call-map-file

The rename-call-map-file is a mapping file between the old call name and the new one.

It is used by some translation rules like Tr-Rename-External-Call and allows the user to make specific changes if needed.

Place the following entry in the main configuration file config-cobol:

rename-call-map-file: "../param/rename-call-map-file"

Listing 7‑5 Example rename-call-map-file

(

("MQGET" . "MWMQGET")

("KIX-ABEND" . "KIX_ABEND")

("KIX-ASKTIME" . "KIX_ASKTIME")

)

 

In this example all calls to MQGET are changed to MWMQGET.

Conversion

There are many possibilities allowed by the conversion command options (see the Oracle Tuxedo Application Rehosting Workbench Reference Guide). In this section the following examples are described:

•	Translate Batch programs and CICS programs.

•	Translate a list of programs.

•	Translate one program.

The distinction between programs (Batch and CICS) and sub-programs is mandatory; the option -cobol-type takes the following values:

•	Batch programs: batch

•	CICS programs: tpr

•	Sub-programs: sub

In the following command lines, the following working variables are set:

 

Table 7‑1 Conversion Variables

Variable	Value
REFINEDIR	/product/art_wb11gR1/refine
PROJECT	$(HOME)/ simpleapp
PARAM	$PROJECT/param
SOURCE	$PROJECT/source
LOGS	$PROJECT/Logs

Translation of Batch, CICS Programs and Sub-Programs

The command lines are:

•	To translate all batch programs:

$REFINEDIR/refine cobol-convert -v version -loop -limit=50 -s $PARAM/system.desc -c $PARAM/config-cobol -cobol-type batch

The COBOL Converter knows which are the batch programs to be translated from the system description file which describes all components. Where version is the release version, for example M2_L5_7

•	To translate all CICS programs invoke the command:

$REFINEDIR/refine cobol-convert -v version -loop -limit=50 -s $PARAM/system.desc -c $PARAM/config-cobol -cobol-type tpr

•	To translate one program, for example the CICS program PGMM002.cbl, invoke the command:

$REFINEDIR/refine cobol-convert -v version -loop -limit=50 -s $PARAM/system.desc -c $PARAM/config-cobol -cobol-type tpr CICS/PGMM002.cbl

•	To translate all sub-programs files invoke the following command:

$REFINEDIR/refine cobol-convert -v version -loop -limit=50 -s $PARAM/system.desc -c $PARAM/config-cobol -cobol-type sub

•	To translate all CICS programs invoke the command:

$REFINEDIR/refine cobol-convert -v version -loop -limit=50 -s $PARAM/system.desc -c $PARAM/config-cobol -cobol-type tpr -cics

The log file is generated in the directory from where the command line is executed. If you want to have logs in a specific directory or file use -log-file-base followed by the path and name of the file to store the execution logs.

$REFINEDIR/refine cobol-convert -v version -loop -limit=50 -s $PARAM/system.desc -log-file-base $LOGS/trans-cbl/translate-cobol-datetime -c $PARAM/config-cobol -cobol-type sub

In this example, the logs file will be generated in $LOGS/trans-cbl/translate-cobol-datetime. The logs directory should be previously created.

Reconciling Copybooks

Reconciliation of copybooks can be executed implicitly by the COBOL Converter or can be performed separately (through usage of the dcrp option, see Configuring config-COBOL) after all

programs have been generated..

To apply reconciliation separately, you should execute the following script from the directory where converted programs are located, (in the case of the Simple Application, from the $PROJECT/trf directory:

Listing 7‑6 Copy Reconciliation

for file in `find * -name '*-copies'`

do

$REFINEDIR/scripts/reconcil-copy-opt-imbr $PROJECT/trf $file .cbl

done

 

Checking Results

To check conversion results, verify that:

•	All expected programs are generated.

•	There are no empty programs.

•	There are no truncated programs.

•	There are no multi-versions for copybooks (reconciliation completed properly).

For empty or truncated programs, the user can refer to execution logs generated in $Logs to analyze errors encountered during the conversion.

Compiling

Compilation is a validation step for conversion. A program cannot be considered fully converted if it has not compiled successfully.

Compilation Options and Settings

You need to check that the compilation environment is configured correctly for COBOL MicroFocus or COBOL-IT compilation according to the following variables:

 

Table 7‑2 Compilation Variables

Variable	Value	Usage
COBDIR	/Product/microfocus/cobol	COBOL product access
COBOLITDIR	/product/COBOL-IT	COBOL-IT product access
Other COBOL-IT environment variables	source $COBOLITDIR/bin/cobol-it-setup.sh	Initializes environment variables (PATH.LD_LIBRARY_PATH...)
PATH	$COBDIR/bin: ${PATH}	Add Cobdir to PATH variable
LD_LIBRARY_PATH	/usr/lib:$COBDIR/lib:${ORACLE_HOME}/lib:${JAVA_HOME}/lib	Defined LD_LIBRARY_PATH
COBCPY	../DML:../Master-copy/COPY:../fixed-copy:.	Indicates where programs can find includes
PCCINCLUDE	"include=../Master-copy/COPY, include=../../fixed-copies, include=.	Indicates where programs can find includes

A compilation options file must be prepared. The compilation options used for the Simple Application are:

Listing 7‑7 MF Compilation Options Example

SOURCEFORMAT"FREE"

DEFAULTBYTE"00"

ADDRSV"COMP-6"

COMP-6"2"

ALIGN"8"

NOTRUNCCALLNAME

NOTRUNCCOPY

NOCOPYLBR

COPYEXT"cpy,cbl"

RWHARDPAGE

PERFORM-TYPE"OSVS"

NOOUTDD

INDD

NOTRUNC

HOSTARITHMETIC

NOSPZERO

INTLEVEL"4"

SIGN"EBCDIC"

ASSIGN"EXTERNAL"

NOBOUND

SETTINGS

REPORT-LINE"256"

WARNING"2"

TRACE

LIST()

 

For more details on compilation options, see the Oracle Tuxedo Application Rehosting Workbench Reference Guide.

Compilation Command

The command to compile the programs BATCH/PGMMB00.cbl:

Listing 7‑8 MF Compilation Example

# From $PROJECT/trf/BATCH

cd $PROJECT/trf/BATCH

 

export COBCPY=../DML:../Master-copy/COPY:../fixed-copy:.

export PCCINCLUDE="include=../Master-copy/COPY, include=../fixed-copies, include=."

cob -ug PGMMB00.cbl -C "use(../../compil_tools/opt.dir)" -C "list(PGMMB00.lst)" -C XREF -C SETTINGS 2> PGMMB00.err

 

Where:

•	opt.dir is a file where the compilation options are specified.

•	Compilation errors are generated in PGMMB00.err.

•	Compilation is listed in PGMMB00.lst.

•	Compilation is successful if GMMB00.gnt is generated.

Note:

The best way to compile programs is to use a compilation makefile, you can set compilation options and a required configuration and perform compilation procedure using a make tool designed for these operations

For the Simple Application example, there is a compilation makefile that can be used for other projects. See Using a make File.

Using a make File

Configuration

The makefile delivered with the Simple Application example implements all conversion operations and can be used in any other project with the following adaptations:

•	Set the required working variables.

•	Update the version.mk configuration file according to your project properties and organization.

This configuration is supplementary to the preceding configuration started in the cataloging step.

Before using the make commands, the user should check the values in the version.mk supplied with the Simple Application:

Listing 7‑9 version.mk Example

#

# Defined extensions converted files

#

ext_trad = cbl

ext_trad_copy = cpy

ext_trad_ksh = ksh

ext_trad_map = bms

 

#

# Define Version variables

# Information

# with GLOBAL_VERSION=CURRENT all -v option in the makefile are ignored

#

GLOBAL_VERSION = M2_L3_5

CATALOG = $(GLOBAL_VERSION)

TRAD = $(GLOBAL_VERSION)

TRAD_JCLZ = $(GLOBAL_VERSION)

DATA_TOOLS = $(GLOBAL_VERSION)

RECONCIL_COPY = $(GLOBAL_VERSION)

TIMEOUT = 900

TIMEOUT_PARSE = 300

 

#

# Define Config and opt files

#

FILE_TRAD_JCL = "$(PARAM)/config-trad-JCL.desc"

FILE_TRAD_COBOL = "$(PARAM)/config-cobol"

COMM_TRADJCL = "-c $(FILE_TRAD_JCL)"

 

COMM_RECONCIL_COPY = "reconcil-copy-opt-imbr"

 

COBOL Conversion

To perform the COBOL conversion the following commands are run from $SOURCE:

•	To translate all programs in the source directory

make trad

•	To translate batch programs only:

make trad_batch

•	To translate CICS programs only:

make trad_cics

•	To translate sub-programs:

make trad_sub

Reconciling Copybooks

To reconcile copybooks invoke the following command from $SOURCE:

make reconcil_copy

Troubleshooting the COBOL Converter

During translation you may encounter error messages or the COBOL Converter may abort. Certain errors are shown below as examples of how to proceed when errors occur.

Configuration File Does Not Exist

Particularly at the beginning of the conversion process, some configuration files could be missing, the COBOL Converter then aborts showing the following error:

Message

Parsing config /home2/wkb7/simpleapp/param/config-cobol...

*FATAL*: Hexa-map-file: this file '/home2/wkb7/simpleapp/param/tr-hexa.map' does not exist

 

Error: Uncaught throw of :MESSAGE-ERROR to :MESSAGE-ERROR.

1 (abort) Quit process.

 

Type :b for backtrace, :c <option number> to proceed, or :? for other options

Solution

Add the missing configuration file or disable the line in the main configuration file if the file requested (in this example, tr-hexa.map) is unnecessary.

Missing POB file

Message

Parsing config /home2/wkb7/simpleapp/param/config-cobol...

Creating target file /home2/wkb7/simpleapp/trf/CICS/PGMM002.cbl ...

*FATAL INTERNAL ERROR*: Can't find POB file /home2/wkb7/simpleapp/source/CICS/pob/PGMM002.cbl.pob; please re-catalog the system.

FIN

Rest in peace, Refine...

Solution

Either the programs is not catalogued yet or the .pob file was wrongly deleted. Recatalog to generate the requested file.

POB File Too Old

Message

Creating target file /home2/wkb7/simpleapp/trf/CICS/PGMM002.cbl ...

*FATAL INTERNAL ERROR*: POB file /home2/wkb7/simpleapp/source/CICS/pob/PGMM002.cbl.pob is less recent than source file /home2/wkb7/simpleapp/source/CICS/PGMM002.cbl; please re-catalog the system.

Solution

This error occurs if the modification date of the source program is more recent than its corresponding POB file. Sometimes the POB file is generated but the source program is updated later, recatalog the program to ensure you have the latest changes.

Parsing error encountered

A program containing parsing errors is not translated, especially programs with fatal errors during cataloging. Generally, COBOL Converter can translate programs containing errors with severities less than FATAL.

Message

Program name is PGMM002

Warning:-- Parse-Error at line 163

*FATAL*: file CICS/PGMM002.cbl contains true parse errors, ABORTING!

 

FIN

Rest in peace, Refine...

Solution

Check the source code of the program and fix any errors, catalog the program and convert again.

More details about the parsing errors can be found in the cataloging reports and logs. In principle, you should not start conversion work before fixing errors identified during the cataloging step.

See Also

•	Oracle Tuxedo Application Rehosting Workbench Reference Guide