Oracle Tuxedo Application Rehosting Workbench Cataloger

Overview

Purpose

This chapter aims to:

•	Provide information and instructions about how to use the the Rehosting Workbench Cataloger.

•	Help you to configure and run the Rehosting Workbench Cataloger tools.

•	Show how to verify the results by interpreting messages and status information.

This guide includes information about the following:

•	How to use the Rehosting Workbench Cataloger within the whole migration process.

•	Best practices on how to prepare assets to be migrated, organize work spaces and effectively use the Rehosting Workbench tools.

Note:

These practices and methodologies are not part of thethe Rehosting Workbench product but are presented in this guide to help new users. You can proceed otherwise, customize the Rehosting Workbench in your own way and develop your own methods.

Skills

Migration process and concepts

You should understand the processes, concepts and terminology used by the Rehosting Workbench Cataloger; know the inputs, outputs and configuration expected by the Cataloger and how it analyzes all the components separately and together to determine whether the asset is consistent and can be migrated.

The Oracle Tuxedo Application Rehosting Workbench Reference Guide describes precisely all features of the Cataloger. Read at least the three first sections of the Cataloger chapter for an introduction to the concepts, terminology, inputs and outputs, and configuration.

UNIX/Linux skills

UNIX/Linux skills are required to work correctly on the migration platform environment and perform certain actions accompanying the cataloguing process. You need to know:

•	The standard Unix/Linux commands to create, modify, display and delete configuration files and output files.

•	The standard Unix/Linux commands and specialized scripts (shells, makefile, cvs) to store and manage the original z/OS asset before and after cataloging.

•	A set of commands (shell, makefile) to start, monitor and terminate the execution of the Rehosting Workbench Cataloger.

z/OS skills

You should be able to identify and understand z/OS components and programming languages. General skills in z/OS environment (COBOL, files, DB2, CICS, JCL, utilities) are sufficient.

See also

For more information, see:

•	Oracle Tuxedo Application Rehosting Workbench Reference manual

•	Oracle Tuxedo Application Runtime Process Guide.

Organization

The Oracle Tuxedo Application Rehosting Workbench Cataloger is described in the following sections:

•	Requirements & Prerequisites

•	Overview of the Cataloger in the replatforming process

•	Cataloging steps

•	Using the make utility

Requirements & Prerequisites

Preparing the migration platform

The migration platform is the platform on which the migration tools (the Rehosting Workbench) execute, including the Cataloger. This platform is based on Linux running on an Intel-compatible hardware platform.

Before performing any action, the Rehosting Workbench should be installed and configured according to specifications and requirements detailed in the Oracle Tuxedo Application Rehosting Workbench Installation Guide.

Overview of the Cataloger in the replatforming process

This section describes the inputs and outputs of the Cataloging step and dependencies with other migration steps in the replatforming process.

Simple Sample Application

In order to illustrate all of the migration activities performed and how to use the the Rehosting Workbench Cataloger to determine whether the asset is consistent and can be migrated to the target platform, the Simple Application STFILEORA will be used. STFILEORA is provided with the Rehosting Workbench set of tools.

Cataloging migration steps

Description of the cataloging operations shown in the graphic:

1.	Read the configuration files and the description of the source files prepared for cataloging

2.	Parse each of the components in the source asset and create an internal representation called packed object base (with extension .pob). Identify internal inconsistencies in these components (e.g. syntax error or reference to an undeclared variable);

3.	Compute cross-reference relationships between these components, such as a CALL statement from a Cobol program to a Cobol sub-program;

4.	Identify mutual inconsistencies in these relationships, such as a CALL statement referencing a sub-program missing from the asset, or an SQL table referenced by none of the Cobol programs in the asset (unused component);

5.	Create CSV-format reports listing all the components in the asset, together with their status (missing, unused or correct) and all the anomalies (inconsistencies) detected above.

The operations described above are explained in more detail in the next sections.

Cataloging steps

Building-up an asset

This step is a pre-requisite for the Cataloger and, as mentioned in the Oracle Tuxedo Application Process Guide that gives an overview of the whole migration process, it is up to the user of the Rehosting Workbench to gather these source files on the source platform, transfer them to the migration platform, install them in an appropriate file structure and prepare them for migration.

Building up the asset consists of several steps from getting sources to organizing them to be available as a valid input to the Cataloger tool:

1.	Gathering sources to be migrated from z/OS

2.	Transfer the sources to the Rehosting Workbench platform:

a.	The source files must be converted to the ASCII code-set in order to be understood on the migration platform. This conversion can be made either by using the file transfer utility or by applying a separate EBCDIC/ASCII conversion step.

b.	You have to be sure that source content is not corrupted due to transfer procedures.

3.	Dispatch and prepare sources by types as they are expected by the Cataloguer

a.	Put all components in UNIX format (using dos2unix command for example)

b.	Put the Cobol components in free format as it will be requested in that format by the Cobol Converter. The Cataloger itself accepts both formats, you have only to configure the cobol-left-margin and cobol-right-margin options.

c.	Organize components by type: put all CICS programs in one directory that could contain sub-directories, the same applies for Cobol includes, Batch programs, Jobs, etc.

d.	Add file extensions to each type: .cbl for Cobol programs, .cpy for Cobol includes and.jcl for Jobs

4.	Some other actions may be required: such as clean components from certain characters or lines added after the extraction from z/OS or during the transfer.

Initialization and configuring the working environment

As the the Rehosting Workbench Cataloger is the first tool of the Oracle Tuxedo Application Workbench suite used in the migration process, a general configuration step for the whole project to be performed is explained here.

Configuration objectives

•	Reduce the time needed to prepare the working environment and avoid further possible errors due to configuration.

•	Initialize the configuration for other WorkBench tools not only for the Cataloger.

•	Recommend a standard organization to facilitate team work.

Recommended file structure

The more organized and standardized the working space, the more migration tasks will be easier and automated.

In the following sample we illustrate a typical organization and we recommend working with the same structure.

Listing 2‑1 The hierarchy of Sample Application

SampleApp

|-- CVS_DELIVRY

|-- Logs

|-- param

| `-- system.desc

|-- source

| `-- makefile

|-- tools

 

The contents of each directory are:

•

Source

Contains all sources to be migrated and prepared as input for the Rehosting Workbench tools.

Workspace where all the Rehosting Workbench processes can find the source code.

•

param

Contains all configuration files (parameters and hints for use by the Rehosting Workbench tools).

•

Logs

Working directory where all the Rehosting Workbench tools are launched, all log files are generated

•

tools

Directory to place specific tools developed by the user during the migration process

Setting environment and working variables

It is recommended that each time you work on a project using the Rehosting Workbench to set certain environment variables that will be useful later. The only environment variable that is mandatory is REFINEDISTRIB; others can be used for simplification reasons.

The following table explains the usage of proposed variables.

Table 2‑1  

Variable	Value	Usage
REFINEDISTRIB	Linux64, or Linux32	Specifies the architecture of the the Rehosting Workbench binary files.
PROJECT	${HOME}	Project root within the workspace. HOME is used for training. But value should be something like /project/SampleApp
CVSROOT	${PROJECT}/CVS_DELIVRY	CVS repository to use containing the source and configuration files.
LOGS	${PROJECT}/Logs	Structure where tthe Rehosting Workbench logs are stored
PARAM	${PROJECT}/param	Directory where the parameter files are stored
SOURCE	${PROJECT}/source	Structure where the source files to translate are stored
REFINEDIR	/<InstallDir>/refine	Root of the Rehosting Workbench binaries and utilities
PHOENIX	${REFINEDIR}	Variable used by the Rehosting Workbench
TMPPROJECT	${PROJECT}/tmp	Temporary structure for R4Z the Rehosting Workbench
PATH	${PATH}:/platform/Tools	PATH complement

In the Simple Application example project, we use a setting file named $PROJECT/.project that contains all initializations using an export Linux command. This file is to be executed each time a new Linux session is opened to work in the project

Listing 2‑2 Extract from Simple Application .project file:

echo "Wellcome to SampleApp"

export GROUP=refine

export PROJECT=${HOME}/SampleApp

export CVS_LIV=${PROJECT}/CVS_DELIVRY

export CVSROOT=${PROJECT}/CVS_DELIVRY

export LOGS=${PROJECT}/Logs

export SOURCE=${PROJECT}/source

export PARAM=${PROJECT}/param

export REFINEDIR=/product/art_wb11gR1/refine

export PHOENIX=${REFINEDIR}

export TMPPROJECT=${PROJECT}/tmp

export REFINEDISTRIB=Linux64

 

Project initialization summary

To initialize a new project, proceed as follow:

1.	Create a file structure as described above.

2.	Copy a sample of the configuration (system.desc, version.mk, options-catalog, etc) files from Simple Application to $PROJECT/param directory to make any necessary modifications.

3.	Copy the makefile from the source (SimpleApp) into $PROJECT/source.

4.	Create a file .project under $PROJECT and initialize it with variables listed in Setting environment and working variables. Variables in the file are to be exported each time you work on the project.

5.	Copy the prepared source files to $PROJECT/source

6.	Optional: Manage the source and configuration files under CVS.

Configuration

You need to set at least two configuration files, additional configuration files are described in the advanced usage section.

The two configuration files needed by the Cataloger are:

•	System description file

•	General option file

System description file

The system description file is the main configuration file for the Rehosting Workbench tools.

For the Simple Application example:

•	The system-name is SampleApp

•	The path where sources to be migrated are stored is ../source

•	To inform the Cataloger of the location of the global options file you can use relative or absolute naming but it is recommended to use an absolute path when you have multiple source environments to migrate.

global-options catalog = "../param/options-catalog.desc".

•	Then add entries for each directory containing components to be catalogued.

Listing 2‑3 system description for Simple Application

system SampleApp root "../source"

global-options

catalog="../param/options-catalog.desc",

no-END-Xxx.

DBMS-VERSION="8".

% Copies

directory "COPY" type Cobol-Library files "*.cpy".

% DDL

directory "DDL" type SQL-SCRIPT files "*.ddl".

% Batch

directory "BATCH" type Cobol-Batch files "*.cbl" libraries "COPY". %, "INCLUDE".

% Cics Cobol Tp

%

directory "CICS" type Cobol-TPR files "*.cbl" libraries "COPY". %, "INCLUDE".

 

 

Global options

The purpose of the Cataloger options file is to give the Cataloger additional information that will influence its behavior.

In the Simple Application example we use only three options, of course other options can be used; see the Oracle Tuxedo Application Rehosting Workbench Reference Guide for a full list of options.

Listing 2‑4 Global Options file for the Simple Application

%% Options for cataloging the system

job-card-optional.

 

Executing the Cataloger

One operation

You can launch the Cataloging with one command; all operations are performed sequentially.

The example command line syntax is:

${REFINEDIR}/refine r4z-catalog -s $PARAM/system.desc

Where:

•	${REFINEDIR} is the directory where the Rehosting Workbench tools are installed.

•	$(CATALOG) is the version of the Cataloger to be used

•	$(SYSTEM) is the path of the system description file.

In our sample the command will be:

From directory $LOGS/catalog execute the command:

${REFINEDIR}/refine r4z-catalog -s $PARAM/system.desc

The execution log is printed on the screen and at the same is redirected in log file under the directory from which you lunched the command.

Step by step

Parsing

Running this step is useful when you want to check specific programs without waiting for the whole cataloging to see the results.

Listing 2‑5 Parsing examples

# parse only one program

${REFINEDIR}/refine r4z-preparse-files -s $PARAM/system.desc CICS/PGMM000.cbl

 

# parse a list of programs

# build a list that contains programs with path from source (CICS/PGMM000.cbl)

${REFINEDIR}/refine r4z-preparse-files -s $PARAM/system.desc -f list-of-file

 

Analysis

The result of this step is the binary file named symtab-SampleApp.pob that represents inter-component information.

Listing 2‑6 Analysis example

cd $LOGDIR/catalog

${REFINEDIR}/refine r4z-analyze -s $PARAM/system.desc

 

Print reports

In this step information stored in binary files is collected and printed in CSV format reports.

Listing 2‑7 Print Reports example

cd $LOGDIR/catalog

$REFINEDIR/refine r4z-fast-final -v M2_L3_3 -s $PARAM/system.desc

 

In the Simple Application reports are generated in $PROJECT/source/Reports-SampleApp:

•	report-SAMPLEAPP-Anomalies

•	report-SAMPLEAPP-Cobol-Copy

•	report-SAMPLEAPP-Cobol-Programs

•	report-SAMPLEAPP-JCL-Files

•	report-SAMPLEAPP-JCL-Jobs

•	report-SAMPLEAPP-JCL-Sub-Files

•	report-SAMPLEAPP-SQL-Tables

•	report-SAMPLEAPP-SQL-Views

•	report-SAMPLEAPP-Transactions

The different reports are described in the Oracle Tuxedo Application Rehosting Workbench Reference guide.

Result analysis and validation

Using the cataloging reports, you can perform different actions in order to create the exact asset set to be migrated and give launch the other the Rehosting Workbench steps: Cobol conversion, JCL translation and Data conversion.

Note:

This does not mean that cataloging and conversion activities are strictly sequential, they may overlap.

Inventory

After cataloging each Program, Copy, Job, Include is given a status depending on its use.

Table 2‑2 Inventory status

Status	Description
CORRECT	Components are present in source and used: • Copybooks used at least by one program, • Programs used at least by one transaction, by at least one jcl or by at least one program • All jobs are considered as used. • JCL sub-file use at least by one Job. Action: Accept it
UNUSED	Component present is source but not used: • Copybooks that are not called by a program • Programs that are not called by a transaction, or by a Job and that are not called as a sub-program by a program, • JCL sub-files that are not used by a Job Action: Decide whether to keep the component or to delete it from asset
MISSING	Component is not present in the asset but at least one reference to it has been found: • Copybooks used at least by one program, • Programs used at least by one transaction, by at least one JCL or by at least one program. • JCL sub-files used by at least one Job Action: Decide whether to add missing components or delete calling components that could be unused or unnecessary.

Anomaly analysis

All the errors reported in the Anomalies Report must be analyzed:

•	FATAL and ERROR severity level anomalies make the component or asset unsuitable for conversion, they must be analyzed and fixed.

•	NOTICE and WARNING severity level anomalies should also be analyzed and they can be kept if there is no impact on the conversion.

The asset should be free from severe errors before proceeding to conversion.

Completion criteria

Cataloging can be considered complete once all expected outputs are generated (pob files and cataloging reports).

As a process, it depends on the context of the project, but generally cataloguing is considered as completed when:

•	All Unused and Missing components are either fixed or justified.

•	All errors are fixed or justified.

Using the make utility

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

We highly recommend using make to perform the different operations that compose the migration process because this enables you to:

•	Have all (executable) processes documented.

•	Effectively manage incremental operations and hence save time.

•	Control and check the results of processes.

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 following two sections describe the make configuration and how to use the Cataloger functions thru make.

Make configuration

Version.mk

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

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

Listing 2‑8 Extract from version.mj for Simple Application

Root = ${PROJECT}

#

# Define directory Projet

#

Find_Jcl = JCL

Find_Prg = BATCH

Find_Tpr = CICS

Find_Spg =

Find_Map = MAP

SCHEMAS = AV

…

#Logs organisation

#

LOGDIR := $(LOGS)

CATALDIR := $(LOGS)/catalog

PARSEDIR := $(LOGS)/parse

TRADJCLDIR := $(LOGS)/trans-jcl

TRADDIR := $(LOGS)/trans-cbl

DATADIR := $(LOGS)/data

…

 

Makefile

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.

The makefile provided with the Simple Application is auto-documented.

Parsing

Parsing all programs

From the $SOURCE directory execute the command:

> make pob

The log file is generated in $LOGS/parse

Check need to be parsed

> make pob VERIF=TRUE

Check : Parse of BATCH/PGMMB02.cbl Need Process .. To obtain BATCH/pob/PGMMB02.cbl.pob

Parsing of one program

Sample: parsing the program BATCH/PGMMB02.cbl

> make BATCH/pob/PGMMB02.cbl.pob

The log file is generated in $LOGS/parse

Cataloging

To launch cataloging use:

make catalog

The log file is generated in $LOGS/catalog

Advanced usage of make

To add or update a target

You can update the makefile to add some targets or to update existing ones.

For example, if you developed you own script (report.sh) to generate a customized report based on basic cataloguing reports, place your script in $TOOLS directory.

The makefile can be modified as follow:

•	To add a new target to execute the new script:

Reporting:

@${TOOLS}/report.sh

•	To update existing catalog target

catalog:

@$(REAL_CMD) ${REFINEDIR}/refine r4z-catalog -v $(CATALOG) -s $(SYSTEM) $(LOG_FILE_FLAGS_CAT)

@make reporting

Your customized report will be updated automatically after each catalog execution.

Debugging the make target

Sometimes a command thru make cannot work properly because of a lack of configuration.

Proceed as follow:

1.	Copy the used makefile to debug copy (makfile.debug), to not disturb current operations.

2.	Modify makefile.debug changing REAL_CMD to COMMENT

catalog:

@$(COMMENT) ${REFINEDIR}/refine r4z-catalog -v $(CATALOG) -s $(SYSTEM) $(LOG_FILE_FLAGS_CAT)

Using the command with option VERIF=TRUE

> make catalog VERIF=TRUE -f makefile.debug

The command to be executed is printed = after replacement of all variables.