Oracle Tuxedo Application Rehosting Workbench File-to-Oracle Converter

Overview

Purpose

This chapter describes how to install, implement, and configure the Rehosting Workbench File-to-Oracle converter in order to migrate VSAM files from the source z/OS environment to the target environment.

Skills

When migrating files, a good knowledge of COBOL, JCL, z/OS utilities and UNIX/Linux Korn Shell is required.

See also

For a comprehensive view of the migration process, see the Oracle Tuxedo Application Rehosting Workbench Reference Guide for the chapters Data Conversion and Cobol Conversion as well as the the Rehosting Workbench Cobol Converter chapter of this guide.

Organization

Migrating data files is described in the following sections:

•	The File-to-Oracle migration process

•	Initializing the process

•	Reengineering rules to implement

•	Preparing the environment

•	Generating the components

•	Performing the migration

•	Troubleshooting

The File-to-Oracle migration process

File organizations processed

When migrating VSAM files from a source platform to an Oracle UNIX target platform, the first question to ask, when VSAM is concerned, is whether to keep a file or migrate the data to an Oracle table.

The following file organizations handled by z/OS can be migrated using the Rehosting Workbench to Oracle databases: VSAM RRDS, ESDS and KSDS.

The Oracle Tuxedo Application Rehosting Workbench File-to-Oracle converter is used for those files that are to be converted to Oracle tables. For files that remain in file format, see Oracle Tuxedo Application Rehosting Workbench File-to-File Converter.

Migration Process Steps

The principle steps in the File-to-Oracle migration process, explained in detail in the rest of this chapter, are:

1.	Create an overall list of the files to be migrated.

2.	List those files that will be converted to Oracle tables.

3.	For each of these files, when necessary, create a list of discrimination rules.

4.	Prepare the environment to be used to generate the components.

5.	Using the Rehosting Workbench generate the components used in the following steps.

6.	Unload the data from the source platform.

7.	Transfer the data to the target platform.

8.	Transcode and reload the data.

9.	Check the results.

10.	Compile the access routines and the generated utilities.

11.	Create the Oracle database.

Interaction with other Oracle Tuxedo Application Rehosting Workbench tools

The migration of data in VSAM files to Oracle tables is dependant on the results of the Oracle Tuxedo Application Rehosting Workbench Cataloger. The File-to-Oracle migration impacts the COBOL and JCL conversion and should be completed before beginning the COBOL program conversion work.

Initializing the process

This section describes the steps to be performed before starting the migration of VSAM files to Oracle tables.

Listing the files to be migrated

The first task is to list all of the VSAM files to be migrated (in conjunction with the use of the File -to-File converter), and then identify those files that should be converted to Oracle tables. For example, permanent files to be later used via Oracle or files that need locking at the record level.

File descriptions and managing files with the same structure

For each candidate file for migration, its structure should be described in Cobol format. This description is used in a Cobol copy by the Rehosting Workbench Cobol converter, subject to the limitations described in COBOL description.

Once built, the list of files to migrate can be purged of files with the same structure in order to save work when migrating the files by limiting the number of programs required to transcode and reload data.

From the purged list of files, a last task consists of building the files:

•	Datamap-<datamap name>.re

•	mapper-<mapper name>.re

COBOL description

A COBOL description is related to each file and considered as the representative COBOL description used within the application programs. This description can be a complex COBOL structure using all COBOL data types, including the OCCURS and REDEFINES notions.

This COBOL description will often be more developed than the COBOL file description (FD). For example, an FD field can be described as a PIC X(364) but really contain a three times defined area including, in one case a COMP-3 based numerals table, and in another case a complex description of several characters/digits fields etc.

It is this developed COBOL description which describes the application reality and therefore is used as a base to migrate a specific physical file.

The quality of the file processing execution depends on the quality of this COBOL description. From this point, the COBOL description is not separable from the file and when referring to the file concerned, we mean both the file and its representative COBOL description. The description must be provided in COBOL format, in a file with the following name:

<COPY name>.cpy

Note:

If a copy book on the source platform provides a detailed description of the file, the file can be directly used and declared in the Rehosting Workbench.

COBOL description format

The format of the COBOL description must conform to the following rules:

•	Only one level 01.

•	The word FILLER is not allowed.

•	Fields names must be unique.

•	Some words are reserved, a list is supplied in the Appendix of the Oracle Tuxedo Application Rehosting Workbench Reference Guide.

•	The description should begin in column 1 without any preceding sequence numbers.

•	Comments may be inserted by placing an * in column 1.

•	Field level numbers can start from column 2.

Example

Column
1	2	3	4	5	6	7	8	9	10	11	12	13	14	15	16	17	18	19	20	21	22	23	24	25	.
*	D	E	S	C	R	I	P	T	I	O	N		O	F		F	I	L	E		X	X	X	X
	0	1		F	V	1	4	.
			0	5		F	V	1	4	x	1		P	I	C		X	.

COBOL description and related discrimination rules

Within a COBOL description there are several different ways to describe the same memory field, which means to store objects with different structures and descriptions at the same place.

As the same memory field can contain objects with different descriptions, to be able to read the file, we need a mechanism to determine the description to use in order to interpret correctly this data area.

We need a rule which, according to some criteria, generally the content of one or more fields of the record, will enable us to determine (discriminate) the description to use for reading the re-defined area.

In the Rehosting Workbench this rule is called a discrimination rule.

Any redefinition inside a COBOL description lacking discrimination rules presents a major risk during the file transcoding. Therefore, any non-equivalent redefined field requests a discrimination rule. On the other hand, any equivalent redefinition (called technical redefinition) must be subject to a cleansing within the COBOL description (see the example below).

The discrimination rules must be presented per file and highlight the differences and discriminated areas. Regarding the files, it is impossible to reference a field external to the file description.

The following description is a sample of a COPY as expected by the Rehosting Workbench:

Listing 5‑1 Cobol COPY sample

01 FV14.

05 FV14-X1 PIC X.

05 FV14-X2 PIC XXX.

05 FV14-X3.

10 FV14-MTMGFA PIC 9(2).

10 FV14-NMASMG PIC X(2).

10 FV14-FILLER PIC X(12).

10 FV14-COINFA PIC 9(6)V99.

05 FV14-X4 REDEFINES FV14-X3.

10 FV14-MTMGFA PIC 9(6)V99.

10 FV14-FILLER PIC X(4).

10 FV14-IRETCA PIC X(01).

10 FV14-FILLER PIC X(2).

10 FV14-ZNCERT.

15 FV14-ZNALEA COMP-2.

15 FV14-NOSCP1 COMP-2.

15 FV14-NOSEC2 COMP-2.

15 FV14-NOCERT PIC 9(4) COMP-3.

15 FV14-FILLER PIC X(16).

05 FV14-X5 REDEFINES FV14-X3.

10 FV14-FIL1 PIC X(16).

10 FV14-MNT1 PIC S9(6)V99.

05 FV14-X6 REDEFINES FV14-X3.

10 FV14-FIL3 PIC X(16).

10 FV14-MNT3 PIC S9(6).

10 FV14-FIL4 PIC X(2).

 

The discrimination rules are written in the following format:

Listing 5‑2 Cobol COPY discrimination rules

Field FV14-X3

Rule if FV14-X1 = “A” then FV14-X3

elseif FV14-X1 = “B” then FV14-X4

elseif FV14-X1 = “C” then FV14-X5

else FV14-X6

 

Note:

In the COBOL description, the field FV14-X3 must be the first field to be redefined. The order of subsequent fields: FV14-X4, FV14-X5 and FV14-X6 is not important.

The copy name of the COBOL description is: <COPY name>.cpy

Redefinition examples

Non-equivalent redefinition

Listing 5‑3 Non-equivalent redefinition example

01 FV15.

05 FV15-MTMGFA PIC 9(2).

05 FV15-ZNPCP3.

10 FV15-NMASMG PIC X(2).

10 FV15-FILLER PIC X(12).

10 FV15-COINFA PIC 9(6)V99.

05 FV15-ZNB2T REDEFINES FV1 5-ZNPCP3.

10 FV15-MTMGFA PIC 9(4)V99.

10 FV15-FILLER PIC X(4).

10 FV15-IRETCA PIC X(01).

10 FV15-FILLER PIC X(2).

10 FV15-ZNCERT

15 FV15-ZNALEA COMP-2.

15 FV15-NOSCP1 COMP-2.

15 FV15-NOSEC2 COMP-2.

15 FV15-NOCERT PIC 9(4) COMP-3.

15 FV15-FILLER PIC X(16).

 

In the above example, two fields (FV15-ZNPCP3 and FV15-ZNB2T) have different structures: an EBCDIC alphanumeric field in one case and a field composed of EBCDIC data and COMP2, COMP3 data in a second case.

The implementation of a discrimination rule will be necessary to migrate the data to a UNIX platform.

Listing 5‑4 Related discrimination rules

Field FV15-ZNPCP3

Rule if FV15-MTMGFA = 12 then FV15-ZNPCP3

elseif FV15-MTMGFA = 08 and FV15-NMASMG = "KC " then FV15-ZNB2T

 

Equivalent redefinition called technical redefinition

Listing 5‑5 Technical redefinition initial situation

01 FV1.

05 FV1-ZNPCP3.

10 FV1-MTMGFA PIC 9(6)V99.

10 FV1-NMASMG PIC X(25).

10 FV1-FILLER PIC X(12).

10 FV1-COINFA PIC 9(10).

10 FV2-COINFA REDEFINES FV1-COINFA.

15 FV2-ZNALEA PIC 9(2).

15 FV2-NOSCP1 PIC 9(4).

15 FV2- FILLER PIC 9(4).

10 FV15-MTMGFA PIC 9(6)V99.

10 FV15-FILLER PIC X(4).

10 FV15-IRETCA PIC X(01).

10 FV15-FILLER PIC X(2).

 

Listing 5‑6 Technical redefinition potential expected results

01 FV1. 05 FV1-ZNPCP3. 10 FV1-MTMGFA PIC 9(6)V99. 10 FV1-NMASMG PIC X(25). 10 FV1-FILLER PIC X(12). 10 FV1-COINFA PIC 9(10). 10 FV15-MTMGFA PIC 9(6)V99. 10 FV15-FILLER PIC X(4). 10 FV15-IRETCA PIC X(01). 10 FV15-FILLER PIC X(2).

01 FV1. 05 FV1-ZNPCP3. 10 FV1-MTMGFA PIC 9(6)V99. 10 FV1-NMASMG PIC X(25). 10 FV1-FILLER PIC X(12). 10 FV2-COINFA. 15 FV2-ZNALEA PIC 9(2). 15 FV2-NOSCP1 PIC 9(4). 15 FV2- FILLER PIC X(4). 10 FV15-MTMGFA PIC 9(6)V99. 10 FV15-FILLER PIC X(4). 10 FV15-IRETCA PIC X(01). 10 FV15-FILLER PIC X(2).

 

In the above example, the two descriptions correspond to a simple EBCDIC alphanumeric character string (without binary, packed or signed numeric fields). this type of structure does not require the implementation of a discrimination rule.

Reengineering rules to implement

This section describes the reengineering rules applied by the Rehosting Workbench when migrating data from VSAM files to an Oracle database.

Migration rules applied

•	Each VSAM file becomes an Oracle table.

•	Each table name is stipulated in the mapper-<configuration name>.re file using the table name clause.

•	Each elementary field name contained in the copy description of the file becomes a column name in an Oracle table. Hyphens (-) are replaced by underscore (_) characters.

•	For sequential VSAM files (VSAM ESDS):

the Rehosting Workbench adds a technical column: *_SEQ_NUM NUMBER(8).

This column is incremented each time a new line is added to the table; the column becomes the primary key of the table.

•	For relative VSAM files (VSAM RRDS):

the Rehosting Workbench adds a technical column *_RELATIVE_NUM.

The size of the column is deduced from the information supplied in the Datamap parameter file; the column becomes the primary key of the table.

The column:

•	is incremented when a sequential write is made to the table, and the relative key is zero.

•	contains the relative key when the relative key is not zero.

•	For indexed VSAM files (VSAM KSDS):

the Rehosting Workbench does not add a technical column unless duplicate keys are accepted; the primary key of the VSAM file becomes the primary key of the table.

Rules applied to Picture clauses

The following rules are applied to COBOL Picture clauses when migrating data from VSAM files to Oracle tables:

Table 5‑1 Picture clause reengineering

COBOL Picture	Oracle format
PIC 9(…)	NUMBER(…)
COMP-1 or COMP-2	NUMBER(…)
PIC X(…)	Becomes CHAR if length <= 2000 Becomes VARCHAR2 if length > 2000 Note: If the parameter: file:char_limit_until_varchar is set in the db-param.cfg file, it takes precedence over the above rule.

Rules applied to Occurs and Redefines clauses

For OCCURS and REDEFINES clauses with discrimination rules, three reengineering possibilities are proposed:

•	Creation of a sub-table:

•	Redefinitions: each description is associated with a sub-table (one sub-table for each description).

•	Occurs: one sub-table is created containing a technical column that references the element of the array to which the data corresponds.

•	Creation of an opaque field:

•	Redefinitions: all the descriptions are stored in an opaque field type CHAR or VARCHAR2.

•	Occurs: all the occurrences are stored in an opaque field type CHAR or VARCHAR2.

•	Extended description

•	Redefinitions: all the fields described in the copy file are created as columns in the Oracle table.

•	Occurs: each occurrence of a field in a redefined area is created as a column in the Oracle table, one column for each occurrence in the OCCURS clause.

Example VSAM file migration to Oracle table

In the following example, the indexed VSAM file described in ODCSFOB uses as a primary key the VS-CUSTIDENT field.

Listing 5‑7 Example VSAM copy description

* ------------------------------------------------------------

* Customer record description

* -Record length : 266

* ------------------------------------------------------------

01 VS-ODCSF0-RECORD.

05 VS-CUSTIDENT PIC 9(006).

05 VS-CUSTLNAME PIC X(030).

05 VS-CUSTFNAME PIC X(020).

05 VS-CUSTADDRS PIC X(030).

05 VS-CUSTCITY PIC X(020).

05 VS-CUSTSTATE PIC X(002).

05 VS-CUSTBDATE PIC 9(008).

05 VS-CUSTBDATE-G REDEFINES VS-CUSTBDATE.

10 VS-CUSTBDATE-CC PIC 9(002).

10 VS-CUSTBDATE-YY PIC 9(002).

10 VS-CUSTBDATE-MM PIC 9(002).

10 VS-CUSTBDATE-DD PIC 9(002).

05 VS-CUSTEMAIL PIC X(040).

05 VS-CUSTPHONE PIC 9(010).

05 VS-FILLER PIC X(100).

* ------------------------------------------------------------

 

Listing 5‑8 Oracle table generated from VSAM file

WHENEVER SQLERROR CONTINUE;

DROP TABLE CUSTOMER CASCADE CONSTRAINTS;

WHENEVER SQLERROR EXIT 3;

CREATE TABLE CUSTOMER (

VS_CUSTIDENT NUMBER(6) NOT NULL,

VS_CUSTLNAME VARCHAR2(30),

VS_CUSTFNAME CHAR (20),

VS_CUSTADDRS VARCHAR2(30),

VS_CUSTCITY CHAR (20),

VS_CUSTSTATE CHAR (2),

VS_CUSTBDATE NUMBER(8),

VS_CUSTEMAIL VARCHAR2(40),

VS_CUSTPHONE NUMBER(10),

VS_FILLER VARCHAR2(100),

CONSTRAINT PK_CUSTOMER PRIMARY KEY (

VS_CUSTIDENT)

);

 

Note:

The copy book ODCSFOB contains a field redefinition: VS-CUSTBDATE-G PIC 9(008), as this is a technical field, no discrimination rule is implemented. In this case, only the redefined field is created in the generated table VS_CUSTBDATE NUMBER(8).

Preparing the environment

This section describes the tasks to perform before generating the components to be used to migrate data from VSAM files to Oracle tables.

Initializing environment variables

Before executing the Rehosting Workbench set the following environment variables:

•	export TMPPROJECT=$Home/tmp

— the location for storing temporary objects generated by the process.

•	export $PARAM=$HOME/param

— the location of the configuration files.

Implementing the configuration files

Three files need to be placed in the Rehosting Workbench file structure as described by:

•	$PARAM for:

•	db-param.cfg,

•	$PARAM/file for:

•	Datamap-<configuration name>.re,

•	mapper-<configuration name>.re.

For a File-to-Oracle conversion you must create the Datamap-<configuration name>.re and mapper-<configuration name>.re files yourself.

Two other configuration files:

•	file-templates.txt

•	file-move-assignation.pgm

are automatically generated in the file structure during the installation of the Rehosting Workbench. If specific versions of these files are required for particular z/OS files they will be placed in the $PARAM/file file structure.

Configuring the files

Database Parameter File (db-param.cfg)

For the db-param.cfg file, only the target and file parameters need to be adapted.

Listing 5‑9 db-param.cfg example

# This configuration file is used by FILE & RDBMS converter

# Lines beginning with "#" are ignored

# write information in lower case

# common parameters for FILE and RDBMS

# source information is written into system descriptor file (OS, DBMS=,

# DBMS-VERSION=)

target_rdbms_name:oracle

target_rdbms_version:11

target_os:unix

#

# specific parameters for FILE to RDBMS conversion

file:char_limit_until_varchar:29

# specific parameters for RDBMS conversion

rdbms:date_format:YYYY/MM/DD

rdbms:timestamp_format:YYYY/MM/DD HH24 MI SS

rdbms:time_format:HH24 MI SS

# rename object files

# the file param/rdbms/rename-objects-<schema>.txt is automatically loaded # by the tool if it exists.

 

•	target_rdbms_name: oracle

name of the target RDBMS.

•	target_rdbms_version:11

version of the target RDBMS.

•	target_os:unix

Name of the target operating system.

•	file:char_limit_until_varchar:29

Indicates the maximum field length of a COBOL alphanumeric (PIC X) field before the field will be transformed into an ORACLE VARCHAR data type.

In this example, fields longer than 29 characters will become VARCHAR, fields shorter than 30 characters will become CHAR fields.

Datamap parameter file (Datamap-<configuration name>.re)

Each VSAM file to be migrated must be listed.

The following parameters must be set:

Table 5‑2 Datamap parameters

Parameter	Value in example	Set by
configuration name	STFILEORA (data map STFILEORA-map)	Freely chosen by user.
system name	STFILEORA (system cat::STFILEORA)	Determined during cataloging in the System description file.
file name	PJ01AAA.SS.VSAM.CUSTOMER	z/OS physical file name.
Organization	Indexed	Source organization

Note:

The description of the different parameters used is provided in the Oracle Tuxedo Application Rehosting Workbench Reference Guide - File To File Convertor.

The PJ01AAA.SS.VSAM.CUSTOMER file is a VSAM KSDS file and the organization is therefore indexed. The parameters, keys offset 1 bytes length 6 bytes primary, describe the key. In this example, the key is six bytes long starting in position1.

Listing 5‑10 Example datamap file: Datamap-STFILEORA.re

%% Lines beginning with "%%" are ignored

data map STFILEORA-map system cat::STFILEORA

%%

%% Datamap File PJ01AAA.SS.VSAM.CUSTOMER

%%

file PJ01AAA.SS.VSAM.CUSTOMER

organization Indexed

keys offset 1 bytes length 6 bytes primary

 

Mapping parameter file (mapper-<configuration name>.re)

Each z/OS file to be migrated, that is included in the Datamap configuration file, must be listed.

A file parameter and its options must be included for every VSAM file to convert to an Oracle table. The following parameters must be set:

Table 5‑3 Mapping parameters

Parameter	Value in example	Set by
configuration name	STFILEORA (ufas mapper STFILEORA)	Coherent with the name used in the datamap configuration file.
file name	PJ01AAA.SS.VSAM.CUSTOMER	Name used in the Datamap file.
include	include "COPY/ODCSF0B.cpy"	The name and path of the copy file BCOAC01E.cpy is freely chosen by the user when creating the file.
table name	table name CUSTOMER	Provide a name for the Oracle table to be created.
map record	map record VS-ODCSF0-RECORD defined in "COPY/ODCSF0B.cpy"	VS-ODCSF0-RECORD corresponds to the level 01 field name in the copy file.
logical name	logical name ODCSF0B	Chosen by the user, maximum eight characters. This name is used for naming the objects (Cobol, JCL) created by the different tools in the Rehosting Workbench.
converter name	converter name ODCSF0B	Same name and use as logical name.

Note:

The description of the different parameters used is provided in the Oracle Tuxedo Application Rehosting Workbench Reference Guide - File To File Convertor.

Listing 5‑11 Example mapper file: mapper-STFILEORA.re

%% Lines beginning with "%%" are ignored

ufas mapper STFILEORA

%%

%% Desc file PJ01AAA.SS.VSAM.CUSTOMER

%%

file PJ01AAA.SS.VSAM.CUSTOMER transferred converted

table name CUSTOMER

include "COPY/ODCSF0B.cpy"

map record VS-ODCSF0-RECORD defined in "COPY/ODCSF0B.cpy"

source record VS-ODCSF0-RECORD in "COPY/ODCSF0B.cpy"

logical name ODCSF0B

converter name ODCSF0B

attributes LOGICAL_MODULE_IN_ADDITION

 

 

Installing the copy files

Once the COBOL description files have been prepared, the copy files described in the mapper-<configuration name>.re file should be placed in the $PARAM/file/recs-source directory.

If you use a COBOL copy book from the source platform to describe a file (see note in COBOL description), then it is the location of the copy book that is directly used in the mapping parameter file as in the "COPY/ODCSF0B.cpy" example above.

Generating the components

To generate the components used to migrate data from VSAM file to Oracle tables the Rehosting Workbench uses the file.sh command. This section describes the command.

file.sh

Name

file.sh — Generate z/OS migration components.

Synopsis

file.sh [ [-g] [-m] [-i <installation directory>] <configuration name> | -s <installation directory> (<configuration name>,...) ]

Description

file.sh generates the components used to migrate VSAM files by the Rehosting Workbench.

Options

-g <configuration name>

Generation option. The unloading and loading components are generated in $TMPPROJECT using the information provided by the configuration files.

-m <configuration name>

Modification option. Makes the generated shell scripts executable. The COBOL programs are adapted to Micro Focus COBOL fixed format. When present, the shell script that modifies the generated source files is executed.

-i <installation directory> <configuration name>

Installation option. Places the components in the installation directory. This operation uses the information located in the file-move-assignation.pgm file.

-s <installation directory> <schema name>,...)

Enables the generation of the configuration files used by the Cobol converter. All these files are created in $PARAM/dynamic-config.

Example

file.sh -gmi $HOME/trf FTFIL001

Using the make utility

Make is a UNIX utility intended to automate and optimize the construction of targets (files or actions).

You should have a descriptor file named makefile in the source directory in which all operations are implemented (a makefile is prepared in the source directory during the initialization of a project).

The next two sections describe configuring a make file and how to use the Rehosting Workbench File-To-Oracle Converter functions with a make file.

Configuring a make file

Version.mk

The version.mk configuration file in $PARAM is used to set the variables and parameters required by the make utility.

In version.mk specify where each type of component is installed and their extensions, as well as the versions of the different tools to be used. This file also describes how the log files are organized.

The following general variables should be set at the beginning of migration process in the version.mk file:

•	ROOT_PROJECT

•	DIR_TRADDATA

•	TOOLS_DATA

•

LOGDIR

In addition, the FILE_SCHEMAS variable is specific to file migration, it indicates the different configurations to process.

This configuration should be complete before using the make file.

make file contents

The contents of the makefile summarize the tasks to be performed:

•	Including vesion.mk

•	Controlling if the main variables are set

•	Collecting the value of variables and building the required lists to process.

•	Implementing the targets.

A makefile and a version.mk file are provided with the Rehosting Workbench Simple Application.

Using a makefile with the Rehosting Workbench File-To-Oracle Converter

The make FileConvert command can be used to launch the Rehosting Workbench File-To-Oracle Converter. It enables the generation of the components required to migrate z/OS files to a UNIX/Linux target platform.

The make file launches the file.sh tool with the -g, -m and -i options, for all configurations contained in the FILE_SCHEMAS variable.

Locations of generated files

The unloading and loading components generated with the -i $HOME/trf option are placed in the following locations:

Table 5‑4 Location of components

Location	Contents
$HOME/trf/unload/file/<configuration name>	The programs and JCL used for each unloading are generated for each <configuration name>.
$HOME/trf/reload/file/<configuration name>	The programs and KSH used for each loading are generated for each <configuration name>. Example: loadfile-ODCSF0.ksh RELFILE-ODCSF0.cbl
$TMPPROJECT/outputs	The generation log files Mapper-log-<configuration name> can be used to resolve problems.
$HOME/trf/SQL/file/<schema name>	Location of the SQL scripts for creating tables and the Korn shell scripts used to perform various technical operations for the Oracle tables generated.
$HOME/trf/DML	Location of the COBOL and PRO*COBOL access routines. These routines are executed by the COBOL programs instead of the access verbs used for the VSAM file migrated to Oracle tables.

Examples of generated components

For the example used in this chapter, the following scripts are generated.

The SQL script used to create the CUSTOMER table is named:

•	ODCSF0B.sql

The scripts used for the different technical operations are named:

•	cleantable-ODCSF0B.ksh

•	createtable-ODCSF0B.ksh

•	droptable-ODCSF0B.ksh

•	ifemptytable-ODCSF0B.ksh

•	ifexisttable-ODCSF0B.ksh

Nine COBOL programs are generated, their usage is described in the Oracle Tuxedo Application Rehosting Workbench Reference Guide.

•	ASG_ODCSF0B.cbl

•	close_all_files_STFILEORA.cbl

•	dml_locking.cbl

•	init_all_files.cbl

•	UL_ODCSF0B.cbl

•	close_all_files.cbl

•	DL_ODCSF0B.cbl

•	getfileinfo.cbl

•	init_all_files_STFILEORA.cbl

One PRO*COBOL program for accessing the ORACLE CUSTOMER table is generated:

•	RM_ODCSF0B.pco

Modifying generated components

The generated components may be modified using a project’s own scripts. these scripts (sed, awk, perl,…) should be placed in:

$PARAM/file/file-modif-source.sh

When present, this file will be automatically executed at the end of the generation process. It will be called using the <configuration name> as an argument.

Performing the migration

This section describes the tasks of unloading, transfer and reloading using the components generated using the Rehosting Workbench (see Generating the components).

Preparation

Configuring the environments and installing the components

Installing the unloading components under z/OS

The components used for the unloading (generated in $HOME/trf/unload/file) should be installed on the source z/OS platform. The generated JCL may need adapting to specific site constraints including JOB cards, library access paths and access paths to input and out put files (Data Set Name – DSN).

Installing the reloading components under UNIX

The components used for the reloading (generated in $HOME/trf/reload/file) should be installed on the target platform (runtime).

Installing the Oracle object creation components

The components used for creating the Oracle objects (generated in $HOME/SQL/rdbms/<schema name>) should be installed on the target platform (runtime).

Setting the target platform environment variables

The following environment variables should be set on the target platform:

Table 5‑5  

Variable	Value
DATA_SOURCE	The name of the directory containing the files transferred from z/OS to be reloaded.
DATA	The name of the directory containing the physical files converted to ASCII format and ready to be loaded to Oracle tables.
BIN	The location of the generic reload and control scripts ($HOME/trf/reload/bin)
TMPPROJECT	The temporary directory.
MT_LOG	Directory to contain execution logs.
NLS_LANG	Set according to the instructions in the Oracle documentation.
DDL	The location of the SQL scripts used to create Oracle objects ($HOME/trf/SQL/file/<schema name>).

The following variable should be set according to the information in the Oracle Tuxedo Application Rehosting Workbench Installation Guide:

•	MT_DB_LOGIN.

Unloading the JCL

An unloading JCL is generated for each z/OS file listed in the Datamap parameter file (Datamap-<configuration name>.re). These unloading JCLs are named <logical file name>.jclunload. These JCL use the REPRO function of the IDCAMS utility to unload the files.

Note:

The .jclunload extension should be deleted for execution under z/OS.

Transferring the files

Files should be transferred between the source z/OS platform and the target UNIX platform in binary format using the file transfer tools available at the site (CFT, FTP, …).

Compiling the transcoding programs

The generated COBOL programs used for transcoding and reloading are named:

RELTABLE-<logical file name>

Example:

RELTABLE-ODCSF0.cbl

These COBOL programs should be compiled with Micro Focus COBOL using the options described in the Cobol converter section of the Rehosting Workbench Reference Guide.

Each program produces an output file that is then read by the SQL*LOADER utility.

Executing the Oracle object creation scripts

The option -d of the loadtable-<…>.ksh scripts enables the creation of the Oracle objects.

Executing the transcoding and reloading scripts

The transcoding and reloading scripts have the follow parameters:

Synopsis

loadtable-<logical file name>.ksh [-d] [-t/-l] [-c <method>]

Options

-d

Create the Oracle objects.

-t

Transcode and reload the file.

-l

Transcode and reload the file (same action as -t).

-c ftp:<…>:<…>

Implement the verification of the transfer (see Checking the transfers).

Examples

For the example provided in Mapping parameter file (mapper-<configuration name>.re), the generated script is:

•	loadtable-ODCSF0B.ksh

Files

By default, the input file is located in the directory indicated by $DATA_SOURCE, and the output file is placed in the directory indicated by $DATA.

These files are named with the logical file name used in the Mapping parameter file (mapper-<configuration name>.re) configuration file.

An execution log is created in the directory indicated by $MT_LOG.

A return code different from zero is produced when a problem is encountered.

Checking the transfers

This check uses the following option of the loadtable-<logical file name>.ksh

-c ftp:<name of transfered physical file>:<name of FTP log under UNIX>

Note:

This option enables the verification after the reloading that the physical file transferred from z/OS and the file reloaded on the target platform contain the same number of records. This check is performed using the FTP log and execution report of the reloading program. If the number of records is different, an error message is produced.

Compiling the access routines and utilities

The COBOL and PRO*COBOL access routines should be compiled using the Microfocus compilation options described in the Oracle Tuxedo Application Rehosting Workbench Reference Guide.

Troubleshooting

This section describes problems resulting from usage errors that have been encountered when migrating files from the source to target platform.

Overview

When executing any of the Rehosting Workbench tool users should check:

•	If any error messages are displayed on the screen.

•	If the Mapper-log-<configuration name> file contains any errors (see Common problems and solutions).

Error messages and associated explanations are listed in the appendix of the Oracle Tuxedo Application Rehosting Workbench Reference Guide.

Common problems and solutions

Error: External Variable PARAM is not set

When executing file.sh -gmi $HOME/trf STFILEORA the following message appears:

*=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-==-=-=-=-=-=-=-=-=-=-=-=-=-

########################################################################

Control of configuration STFILEORA

External Variable PARAM is not set!

ERROR: Check directive files for configuration STFILEORA

 

Abort

Explanation

The variable $PARAM has not been set.

Error: Target directory does not exist

When executing file.sh -gmi $HOME/trf STFILEORA1 the following message appears:

*=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-==-=-=-=-=-=-=-=-=-=-=-

Target output directory /home2/wkb9/trf is missing

Check parameters: -i <output_directory> <schema>

ERROR : usage : file.sh [ [-g] [-m] [-i <output_directory>] <schema_name> | -s <output_directory> (<schema>,...) ]

abort

Error: Unknown file organization

When executing file.sh -gmi $HOME/trf STFILEORA2 the following message appears:

Refine error...

Log

The contents of the Mapper-log-STFILEORA2 log file include:

file PJ01AAA.SS.VSAM.CUSTOMER Oracle

file logical name ODCSF0B

*** Unknown file organization : INDEXD

mapping record VS-ODCSF0-RECORD

record VS-ODCSF0-RECORD: logical name VS

record VS-ODCSF0-RECORD: logical name VS

record VS-ODCSF0-RECORD REDEFINES:

field VS-CUSTBDATE as opaque (default strategy)

record VS-ODCSF0-RECORD REDEFINES:

field VS-CUSTBDATE as opaque (default strategy)

Explanation

The file is configured with a file organization of INDEXD instead of INDEXED.

Error: The illegal text is: "converted

When executing: file.sh -gmi $HOME/trf STFILEORA the following message appears:

*=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-==-=-=-=-=-=-=-=-=-=-=-

##########################################################################

Control of configuration STFILEORA

##############################

Control of templates

Project Templates list file is missing /home2/wkb9/param/file/file-templates.txt

OK: Use Default Templates list file

File name is /Qarefine/release/M2_L4_1/convert-data/default/file/file-templates.txt

##############################

Control of Mapper

##############################

COMPONENTS GENERATION

 

…

 

Parsing mapper file /home2/wkb9/tmp/mapper-STFILEORA.re.tmp ...

Parse error at character position 1346 in file:

/home2/wkb9/tmp/mapper-STFILEORA.re.tmp.

The illegal text is: "converrted

table name CUSTOMER

include \"COPY/ODCSF0B.cpy\"

map record VS-ODCSF0-RECORD defin"

While parsing in grammar UFAS-CONVERTER::MAPPER-INPUT-GRAMMAR,

CONVERRTED is a symbol, which is not a legal token

at this point in the input. The legal tokens at this point are:

 

:END "templates" "filler" "field" "file" "one-for-n" "multi-record" "table" "transferred" "mode-tp" ... [14 others]

*ERROR*: parse error is found in /home2/wkb9/tmp/mapper-STFILEORA.re.tmp.

Refine error...

/tmp/refine-exit-status.snICMmElNYF25625

ERROR: generation aborted

abort

Explanation

A typing error in the word ‘CONVERTED’ was made in the mapping file.

Error: Can't find file in file table named PJ01AAA.SS.VSAM.CUSTOMERS

When executing: file.sh -gmi $HOME/trf STFILEORA the following message appears:

*=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-==-=-=-=-=-=-=-==-=-=-=

##########################################################################

Control of configuration STFILEORA

##############################

Control of templates

Project Templates list file is missing /home2/wkb9/param/file/file-templates.txt

OK: Use Default Templates list file

File name is /Qarefine/release/M2_L4_1/convert-data/default/file/file-templates.txt

##############################

Control of Mapper

##############################

COMPONENTS GENERATION

 

…

 

Point 1 !!

Warning: Can't find file in file table named PJ01AAA.SS.VSAM.CUSTOMERS

Point 2 !!

 

…

 

Refine error...

/tmp/refine-exit-status.IvmFDYsYDdr31956

ERROR : generation aborted

 

Abort

Explanation

The name of the file to convert to an Oracle table does not correspond to the name present in the Datamap file.