• 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.
• Hint files (optional), which give information that the Cataloger cannot find out by itself, for instance on dynamic program calls.
• Other system-wide pob files, such as the Symtab (see The Cataloger Symtab and other miscellaneous files), for use by the Cataloger and other Oracle Tuxedo Application Rehosting Workbench tools;Depending on the needs of the project and the migration-platform configuration, these phases can be executed sequentially or concurrently, in a single run or incrementally. See Repetitive and incremental operation and the Oracle Tuxedo Application Runtime Process Guide for further information.The parser processes various forms of sub-files and file inclusion directives (EXEC [PROC], INCLUDE, SYSIN, …) and searches the asset for sub-files as directed in the system description file. Since the cataloger and other tools such as the JCL translator need to have a complete understanding of all of the steps in all of the JCL scripts that they handle, it is very important that all the referenced sub-files be present in the asset and that file types and search paths be set so that the correct sub-file is found for every reference. The cataloger will report missing sub-files as severe anomalies, since they prevent the correct analysis and translation of the whole affected JCL(s). Translation should not be attempted until all such anomalies have disappeared.All JCL, JES2 and JES3 statements are parsed. The JCL must be directly executable by JES2. The parser performs JES variable substitution. Variables which are not defined locally in the JCL may be set using the JCL-globals option of the system description file, see Special options.
•
•
•
•
•
•
•
•
•
•
•
•
•
•
• Listing 2‑1 System Description file structureListing 2‑2 System Description file Global Options( “options” | “global-options” ) opt-name-1 “=” opt-value-1 “,”
opt-name-2 “=” opt-value-2 “,” ... “.”
Table 2‑1 Global Options 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. The “end-of-line” column for SQL-Script files (only—this does not apply to SQL code embedded in Cobol programs). Set it to 66 for fixed-format files with columns 1-6 and 72-80 removed (à la Cobol). Default value is “infinite”, which is suitable for free-format files. Note that left margin is always 1, so you must physically remove columns 1-6 of fixed format files if they are to be ignored. 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.Listing 2‑3 System Description file Special Optionsopt-name “=” opt-value “.”
Table 2‑2 Special Options 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. 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. The presence of this option influences how SYSIN files referenced by a JCL are searched in the whole system. See chapter Sub-file search operation below. Listing 2‑4 System Description file Directories“directory” directory-pathThis is a string giving the path (location) of the directory relative to the root directory of the system (see system-root-path). Although it is not an absolute requirement, it is strongly advised that all the directories of the same system are physical descendants of the system root directory. (A simple and readable way to achieve this is that no directory path contains the “../” upward-going name). Different directories must have different paths.“type” directory-type
Table 2‑3 Valid Directory Type clauses SYSIN files used by utility programs or program launchers in JCL scripts. Not all SYSIN files are required by the parser/Cataloger, see more details in the the Rehosting Workbench JCL Translator Reference Manual. CICS system definition files (CSD) as used by RDO to configure CICS, see IBM’s CICS Resource Definition Guide.“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.
Note: It is important that all files designated by the system description file, that is all source files in the asset, have a file extension rather than just a bare file name. The extension can be chosen freely — although we advise the use of “standard” extensions such as cbl for Cobol programs, cpy for Cobol copy files and jcl for main JCL files—but must be present.Listing 2‑5 options-clauseSyntactically, 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 “,” ...Listing 2‑6 Example System Description fileThis system-description file is for an asset named BNL, for example the name of a customer or a standalone application in a larger system. The location and name of this file are not constrained, but conventionally, the complete path should be something like: /.../BNL/param/system.desc. Given this assumption, and since the path for the system root directory given in this file is relative (../source), the absolute path for the root directory is /.../BNL/source. Similarly, the path for the Cataloger options file is given as ./options-catalog, so its absolute path is /.../BNL/param/options-catalog. The global options call for the following comments:
• 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, we do not guarantee the correct operation of the Cobol converter on it.The naming and organization of the various directories is quite standard, with source files in the asset being identified only with their file extensions. The only unusual feature here is the special cobol-right-margin value for directory “Batch”.Listing 2‑7 JCL-launcher syntaxThe 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:Listing 2‑8 Default launcher valueThey are generated in the $SYSROOT/Reports-${SYSNAME} directory, where $SYSROOT is the root directory for the current asset and $SYSNAME is the asset name, both as defined in the system description file.
Table 2‑4 Cobol report fields See Field Definitions. This is the path of the (main) source file defining the program.
•
•
•
Table 2‑5 Cobol copy report fields
•
•
Table 2‑6 JCL source file report fields 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.
Table 2‑7 JCL sub-file report fields
•
•
Table 2‑8 JCL Jobs report fields 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).
Table 2‑9 SQL Table report fields
•
•
•
•
Table 2‑10 SQL Views report fields
Note: A view is never MISSING, because references to views are indistinguishable from references to tables. So, when a reference to a table-or-view links to no definition of any kind, the Cataloger creates a missing table, not a missing view.
Table 2‑11 CICS Transaction report fields
Table 2‑12 Anomaly report fields 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. enum: FATAL, ERROR, WARNING, NOTICE enum: SYNTAX, LINKAGE, ANALYSIS, MISC
• ANALYSIS is for anomalies related to constructs which do not allow the Cataloger to perform an accurate analysis of the component, such as dynamic calls; 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.CDM (Common Data Model) files contain additional information about Cobol variables (so-called data description entries). For each Cobol program A/B/C/prog.cbl in the system, the Cataloger produces a CDM file named A/B/C/pob/prog.cbl.cdm to store information about variables defined in the main source file. In addition, for each Cobol copy file D/E/file.cpy which defines variables (as opposed to copy files containing Procedure Division code, for instance), the Cataloger produces a CDM file named D/E/pob/file.cpy.cdm to store information about those variables; this CDM file is shared by all programs which include this copy file.
• $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/Cobol-dump-map.pob: contains information (so-called dump descriptors) necessary to read and write Abstract Syntax Tree (AST) pobs for Cobol programs. Do not delete this file or you will not be able to re-read your existing Cobol pobs.
• $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.This is the only phase which can be run concurrently, at least after the SQL-System files have been generated. This is also the only phase for which you can request the processing of one or more specific components; otherwise, the Cataloger determines itself which components it must process (see Changes in the asset: incremental operation). In this phase, the Cataloger reads the component source files, any included sub-files and the SQL-System files, and produces (only) the POB-files for the processed components.
• 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.
Note: For all these commands, the whole configuration information comes from the system description file and the Cataloger option file. Except for preparse-files, the only command-line arguments are the path to the system description file and standard Oracle Tuxedo Application Rehosting Workbench tool arguments.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.( -s | -system-desc-file ) system-desc-path \[ command-specific-options-and-arguments… ]Print out a short description (usage) of the command, and then exits.Prints out a description of which work (phase) needs to be performed on which components but do not actually undertake the work see Changes in the asset: incremental operation.Specifies the location of the system description file. As usual for Unix/Linux commands, the given path can be absolute or relative to the current working directory.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:
• Otherwise, the component is parsed normally (and verbosely, unless the -quiet option is given in the launcher-options) and its POB file is produced.
Table 2‑13 Compile-time references Source type (SRCTYP) Target type (TGTTYP) COPY TGTFILCOPY TGTFIL REPLACING … EXEC SQL INCLUDE TGTFIL END-EXEC. sql-libraries, or libraries if not specified EXEC TGTFIL, … INCLUDE TGTFIL… SYSIN DD A.B.TGTFIL…SYSIN DD A.B.C(TGTFIL)…
• If there is no such definition, complain (this is done once and for all when the Cataloger starts and reads the system description file) and skip to the next element of the list.
•