|
•
|
The System Description File (mandatory), which describes how the input source files are organized on the migration platform file system, and also gives additional parameters necessary for their parsing;
|
|
•
|
The Cataloger option file (optional), which gives parameters for the analysis phase of the Cataloger (see Detailed Processing).
|
|
•
|
The JCL-Launcher Specification Files are used to describe the launchers used in a given asset, so that the cataloguer and the JCL translator can extract relevant information such as the name of the real program to launch.
|
|
•
|
DBCS (USAGE DISPLAY-1) and Unicode ( USAGE NATIONAL) constructs.
|
In certain conditions, the same sub-file can be used both as a PROC file and as an INCLUDE file. However, the translation to target files is different in each case, so it is necessary to duplicate the file(s) in question, so that one copy is used and translated as a PROC and the other as an
INCLUDE file. To achieve this, the two copies must, of course, be placed in separate directories, and the search paths must be set up so that the JCL which use these files as PROCs find the PROC version first and those which use them as INCLUDEs find the INCLUDE version first (it is not possible that the same JCL uses the same file as both a PROC and an INCLUDE).
|
•
|
Chapter BMS macros in appendix Detailed reference information for the CICS API commands of the IBM book CICS Application Programming Reference (document number SC34-6434-05 for CICS V3R1);
|
|
•
|
Chapter Creating the map in Part 6, Basic Mapping Support (BMS) of the IBM book CICS Application Programming Guide (document number SC34-6433-04 for CICS V3R1).
|
Sys-desc-file ::= “system” system-name “root”
system-root-path
global-options special-options
( “options” | “global-options” ) opt-name-1 “=”
opt-value-1 “,”
opt-name-2 “=”
opt-value-2 “,” ... “.”
|
|
|
|
|
|
|
|
|
Path of the Cataloger options file (see below). This path can be given in absolute form or in relative form; in the latter case, the path is relative to the directory containing the system description file itself. Note that this clause is optional: if it is not given, then the Cataloger will not attempt to read an option file and will use default values for all options.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Path of the JCL-launcher specification file to use for this system or directory; see JCL-Launcher Specification Files for more information on the contents and use of such files. This path can be given in absolute form or in relative form; in the latter case, the path is relative to the directory containing the system description file itself.
|
opt-name “=”
opt-value “.”
|
|
|
|
|
|
|
The fraction of physical memory which should remain free and available to other processes during execution of the Cataloger and all of the various Oracle Tuxedo Application Rehosting Workbench tools. In general, these tools consume more and more memory, depending on the number of components they process. When this limit is reached, the tool stops and restarts execution; incremental execution ensures that the components already processed are not re-processed, so that eventually, all the required work is achieved.
|
|
|
List of pairs var-name = var-value, separated by commas
|
Var-name is a symbol (or string interpreted as a symbol) and var-value is a string. When parsing a JCL script, the parser simulates the JCL-variable substitution process performed by JES2. The name-value pairs given here are used to substitute global variables (as opposed to parameters, etc.). The parser reports an error when it cannot find a suitable value for some variable.
|
|
|
|
|
|
|
|
|
“directory” directory-path
“files” file-specs “,” ...
The file-specs are strings designating one or more files in a directory. The string identifies the inclusive members of the asset and excludes the others. The simplest form of
file-spec is a complete file name such as
toto.cbl. No indication of directory should be given, the designated files must be located directly in the directory in question. To avoid the task of explicitly listing all components in the directory, you can also use shell-like regular expressions such as
*.cbl or
[A-F][D-Z]*.jcl.
“options” opt-name-1 “=”
opt-value-1 “,”
opt-name-2 “=”
opt-value-2 “,” ...
Syntactically, the directory-specific options clause is similar to the system-wide
Global Options clause, except for the trailing period. Semantically, the listed options and values have the same effect as the global options, but only locally on the files contained in the directory (they override global options with the same name). The same options as the ones marked
yes in the
local? column of the global-option table apply to directories, provided that they are relevant for the type of source files in the directory. For instance, the option
cobol-right-margin is relevant for directories of type COBOL-Batch, COBOL-TPR or COBOL-Sub, but not for type JCL or SQL-Script.
The libraries clause specifies an ordered search path of (other) directories in the asset. Whenever the Cataloger finds in a source file a reference to another component it searches, from first to last, the list of directories given in this clause, until it finds a component (source file) whose name and type matches those of the reference (see more details in section Sub-file search operation below). It is used both for compile and parse-time references, such as a COBOL program referencing a copy file or a JCL file referencing a PROC, and for run-time references, such as a COBOL program calling a COBOL subprogram or a JCL job invoking a COBOL program. This way, it is possible to simulate the effects of various source-platform library-search operations, such as SYSLIB or COPYLIB for COBOL compilation, JOBLIB and STEPLIB for JCL preparation and execution, etc.
“sql-libraries” directory-path “,” ...
|
•
|
The no-end-xxx-warnings option enables the lenient mode of parsing implicitly-closed COBOL constructs.
|
|
•
|
The cobol-left-margin and cobol-right-margin values are set for untransformed, IBM-like fixed-format programs with left-side numbering column and right-side comment column (area C). Note that, while this format causes no trouble for the COBOL parser, the correct operation of the COBOL converter cannot be guaranteed.
|
The local jclz-launcher-spec-file option attached to a directory, when present, overrides the global one, as usual. When no launcher specification file is specified either for a given directory or the whole system, then the default value is as if we used the following file:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
See Field Definitions. It is at least as high as the maximum anomaly level in all the contained jobs, and may be higher in case of syntax errors.
|
|
|
|
|
|
|
|
|
|
|
|
See Field Definitions. This is the path of the (main) file defining the job.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
See Field Definitions. This is the anomaly level of the job itself, and generally does not take into account syntax errors (because the latter prevent the analysis of the job).
|
|
|
|
|
|
|
|
|
|
|
|
See Field Definitions. This is the path of the file defining the screen.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
See Field Definitions. In fact, this is the anomaly level of the complete source file; see the anomaly report to see whether the anomalies really apply to this screen definition.
|
|
|
|
|
|
|
|
See Field Definitions. This is the path of the main file defining the component in which the anomaly occurs.
|
|
|
|
See Field Definitions. If the real location of the error (statement or other construct) is inside some sub-file (COBOL copy file, JCL PROC file, etc.), this is the path of this sub-file, otherwise this field is empty.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
During the parsing phase (see The Cataloger Process), for each parsable-component source file
A/B/C/file.ext in the system, the Cataloger produces a POB file named
A/B/C/pob/file.ext.pob (the
pob directory is created on demand by the Cataloger). This file contains the result of the parsing, namely the
Abstract Syntax Tree (AST) of the component. It is re-read by the analysis phase of the Cataloger and by other Oracle Tuxedo Application Rehosting Workbench tools such as the COBOL converter or JCL translator.
|
•
|
$SYSROOT/symtab-$SYSNAME.pob: this file houses the symbol table created by the Cataloger (during the analysis phase) and contains summary information for all the various components in the asset. This information is used to compute cross-reference information between these components.
|
|
•
|
$SYSROOT/sql-system-$SYSNAME.pob, $SYSROOT/sql-system-$SYSNAME-State-ments.pob: contains various internal forms of the complete SQL schema of the asset, derived from the union of all DDL files (SQL-Script files). These files are required for parsing (and linking) COBOL programs.
|
As described in The Cataloger Process, the operation is logically divided into four phases: parsing, analysis, post-analysis and report generation (see below for more details). Depending on the needs of the project and the migration-platform configuration, these phases can be executed sequentially or concurrently (parsing phase only), in a single run or incrementally.
|
•
|
preparse and its variant preparse-files: runs the parsing phase only.
|
|
•
|
analyze: runs the analysis phase: for each component, the pob-file is re-read and the most significant constructs in the component are translated into a smaller summary information stored in the cataloger symbol table (symtab).
|
|
•
|
fast-final: runs both the post-analysis and report generation phases.
|
|
•
|
catalog: runs in sequence the analysis phase (and hence the parsing phase, on demand), the post-analysis phase and the report generation phase.
|
The Cataloger is designed to be run through the refine command. The
refine command is the generic Oracle Tuxedo Application Rehosting Workbench launcher that is used to launch the major Oracle Tuxedo Application Rehosting Workbench tools. The launcher handles various aspects of the operation of these tools, such as execution log management and the incremental and repetitive operations described below (
Repetitive and Incremental Operation). The Oracle Tuxedo Application Rehosting Workbench launcher also handles a couple of generic command-line options.
$REFINEDIR/refine command [
launcher-options… ] \
[ command-specific-options-and-arguments… ]
As explained in Processing Phases, system-wide commands are preparse, analyze, fast-final and catalog. They operate globally on the whole asset. The generic command-line syntax for all these commands is:
JCL sub-files referenced from a JCL job, such as PROC files,
INCLUDE files and some
SYSIN files are also included because whereas on the MVS platform these sub-files are searched when the JCL job is run, hence it is a run-time reference; on the migration platform, the Cataloger has to resolve these references at parse-time, to make them available to the JCL translator, and hence they qualify as compile-time references. Even
SYSIN files are in this case, since they contain information which is needed at parse time, such as the program invoked by some DB2 launcher. In the Cataloger, "compile-time" is equivalent to parsing, and "run-time" is equivalent to post-analysis.
The search starts with a component identified as SRCFIL of a certain type
SRCTYP, that is located in some directory
SRCDIR and which references a component named
TGTFIL of a certain type
TGTTYP. The following table describes the various possible combinations:
|
1.
|
For each directory SUBDIR listed in the libraries (or sql-libraries, if applicable) clause associated with the definition of SRCDIR in the system description file, in order, locate the definition of SUBDIR in the same file, then:
|
|
•
|
If the type of SUBDIR is not the TGTTYP appropriate to the reference at hand, skip to the next element of the list.
|
This behavior implies that the libraries clause is ignored on directories of type JCL, at least when it comes to searching JCL-Sysin files (it is still valid to search JCL-Select files). On the other hand, as described above, if the
strict-jcl-libraries special option is not set, the
logical-name clauses on JCL=Sysin directories are ignored.
|
1.
|
For each directory SUBDIR listed in the libraries clause associated with the definition of SRCDIR in the system description file, in order, locate the definition of SUBDIR in the same file, then:
|
|
•
|
If the type of SUBDIR is not the TGTTYP appropriate to the reference at hand, skip to the next element of the list.
|
For a given TGTTYP of components to search, and for each appropriate
SRCTYP, it is possible to use directed search for some
SRCTYP directory, and unrestricted search for another directory of the same type. Indeed, duplicate component names cause trouble (anomalies) only when they are actually referenced. However, we advise against such practices, which only makes things confusing. For a given
SRCTYP/
TGTTYP combination, either use unrestricted search on all source directories, or use directed search on all of them.
