Table of Contents Previous Next PDF


JCL Translator

JCL Translator
Overview
Oracle Tuxedo Rehosting platform is a packaged and comprehensive solution composed of tools (Oracle Tuxedo Application Rehosting Workbench) and runtime components (Oracle Tuxedo Application Runtime for CICS and Batch) which allow its users:
Oracle Tuxedo Application Rehosting Workbench is used only during the replatforming project itself, whereas the Runtime components are used throughout the whole life of the migrated system. Oracle Tuxedo Application Rehosting Workbench is composed of several tools, among which is the JCL Translator.
As its name suggests, the role of this tool is to translate JCLs running on the source platform (z/OS, IBM Job Control Language) into Korn-shell (KSH) shell scripts running on the target platform (Unix or Linux, Korn shell (KSH) dialect with invocations of Oracle Tuxedo Application Runtime for Batch functions) with the same behavior, in the context of other components translated or generated by the other Oracle Tuxedo Application Rehosting Workbench tools. The purpose of this chapter is to describe precisely all the features of the JCL translator.
This chapter contains the following topics:
JCL Translator Definitions
The following terms are used when describing the JCL Translator.
JCL: Job Control Language
A command language for the IBM operating system family. The components written in this language are called JCL jobs or simply JCLs. A source asset to be migrated with Oracle Tuxedo Application Runtime generally contains components of this type.
KSH or Korn Shell
A particular variant in the family of Unix Shell command languages. It is also the name of the shell interpreter itself. A shell script compatible with this language/interpreter is a KSH script. KSH scripts are the components in the target asset which correspond to source JCLs.
JES2
Job Entry Subsystem 2
SYMBOLS
Variables in JCLs, allowing them to be parameterized according to the environment. These variables are handled (substituted) by the JES2 reader.
Card Continuation
JCL cards (commands) of more than 72 characters need to be split over several lines. Lines after the first one are called continuation lines (or cards). The previous line must end before column 72 with an optional separator character (generally the comma character) and the continuation line starts with "//" followed by enough spaces to reach the option area. Comments may be embedded on continuation lines after the option area and must be separated from the latter by at least one space. Example:
//SYSIN DD DSN=LIB454R.COMMUN.SER, this is a comment
// DISP=SHR
See also the Concepts described in the Introduction.
General Description and Operation
General Information
Oracle Tuxedo Application Rehosting Workbench JCL Translator handles every required translation in a single pass to:
With the aid of the Oracle Tuxedo Application Runtime for Batch components, the resulting shell scripts can be compiled and run on the target platform with the same behavior as on the source platform, except in some cases detailed in the section Behavior Coverage.
The JCL translator takes as input:
(mandatory) the System Description File, which describes where to locate the JCL files and sub-files on the migration platform file system.
It produces as output:
The JCL translation process acts individually and separately on each JCL. However, it is not suitable to run the JCL Translator concurrently on multiple JCLs at the same time because, if several of these JCL contain the same sub-file, then their translator instances may want to write the translation of this sub-file at the same time, with the risk of corrupting it. In practice, JCL translation is fast and incremental, so there is no real need to accelerate it using multiple processors.
Behavior Coverage
For a detailed description of which JCL cards, parameters, options and utility programs are supported by the JCL translator and the underlying Oracle Tuxedo Application Runtime for Batch components, please refer to the chapter Z/OS JCL in the Oracle Tuxedo Application Runtime Batch Environment in the book Oracle Tuxedo Application Runtime for Batch Reference Guide.
Description of Input Components
The input components are all the JCL scripts (main files) in the asset, after they have been parsed by the cataloger. In fact, the JCL translator loads the POB files for the scripts, not their source files. In addition to the restrictions imposed by the cataloger (no multiple jobs per JCL, etc.; see the Cataloger), the following rules must be respected before attempting the JCL translation:
Description of the Configuration Files
The JCL translator is driven by two parameter files, the system description file and the JCL-translation configuration file.
The System Description File
The System Description File describes the location, type and possible dependencies of all the source files in the asset to process. As such, it is the key by which the cataloger, but also all of the Rehosting Workbench tools, including the JCL translator, can access these source files and the corresponding components.
The following component types are relevant to the JCL translator:
 
The following (global and/or local) options are relevant to the JCL translator:
 
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 a variable.
Listing 9‑1 JCL Translator global and local options examples
options jcl-globals = VAR01 = "T23RT", PARM = "USERT".
directory "Sysin/BPRO.PARMIMS" logical-name "BPRO.BXZ.PARMFIX" type JCL-SYSIN files "*.sysin".
directory "JCL/BPRO" type JCL files "*.jcl" libraries "Sysin/BPRO.PARMIMS".
 
The JCL-Translation Configuration File
The contents of the JCL-translation configuration file is a list of "assignments" of the form parameter-name = parameter-value. Some of these assignments, those in which the parameter-value is a sequence of strings, must be terminated by a period; the strings are separated by commas. The following parameters are available:
 
Target sort utility to use either mf-sort or sync-sort, or cit-sort. Default is mf-sort.
set-delete-fsn and set-no-delete-fsn
For the last two parameter names, set-delete-fsn and set-no-delete-fsn, the syntax of the parameter value is as follows:
ddname ( program-name, program-name, … ) , ddname (program-name … ) , … .
Note:
The semantics of this parameter value is as follows: when a DD name is associated with an explicit list of program names, it stands for exactly these logical files (a logical file is some FD or SD in some pro-gram); when a DD-name is associated with no program name, it stands for all the logical files (FD or SD) which have these names in all programs in the asset. After expansion, we get two lists of logical files, the "to-keep" and the "to-remove". The "to-keep" list is subtracted from the "to-remove" list; then any file assignment (DD card) pertaining to some "to-remove" logical file is not translated into the target KSH script. This allows to "clean up" the target scripts from file assignments which are not directly useful to the invoked programs, such as temporary sort files, physical database files, etc.
Description of Output Files
Translated KSH Scripts and Sub-Files
KSH Version
The generated scripts are certified to be compatible only with ksh88 or pdksh (public-domain KSH). Note that the Oracle Tuxedo Application Runtime for Batch components invoked by the script may have more stringent requirements regarding the underlying KSH engine.
File Structure, Naming Scheme and Sub-File Handling
For each (main) JCL file (job), the JCL translator produces one (main) KSH file (script) with the same base name and extension as specified with the suffix-skeleton configuration parameter (see JCL-translation Configuration File Contents). This file is placed under the hierarchy rooted at the directory specified with the root-skeleton configuration parameter, in the same relative sub-directory as was the source file under the system root. If the target file existed before the translation, it is overwritten.
If a sub-file referenced by some main file is absent from the source asset when the main file is processed by the cataloger, the latter will complain in the log (with a message of the form "*Warning*: ZZZ file XXXXXX not found in JCL file YYYYYY", where ZZZ is PROC or INCL or SYSIN) and an anomaly will be reported. In this case, the JCL translator will refuse to process the (incomplete) main file or produce a non-working, incomplete KSH script.
Procedures are invoked using the m_ProcInclude Oracle Tuxedo Application Runtime for Batch function. The target sub-file is not "executable" outside of this function and, more generally, an Oracle Tuxedo Application Runtime for Batch-generated KSH script. The procedure contents are inserted into the script structure in the "conversion" phase of job processing, see the Oracle Tuxedo Application Runtime for Batch User Guide.
Similarly, include files are invoked using the m_ShellInclude Oracle Tuxedo Application Runtime for Batch function and cannot be used outside this context. Most include files are translated into separate sub-files; however, in some cases, when the include file contains an EXEC card but does not define a (sequence of) complete steps(s), the extraction cannot be performed and the contents of the original sub-file is translated as if it came from the main file.
SYSIN files and their contents are either directly translated into KSH statements (function invocations) or handled as standard file assignments (see below for more details).
In-stream procedures and SYSIN files are handled as their out-of-stream sisters, as far as translation is concerned, but of course they remain inside the main target file. In-stream procedures are moved to the end of the main file; in-stream SYSINs remain within the corresponding step.
Handling of JCL and KSH Variables
The z/OS variables used in the original JCL are translated into special symbols of the form $[PARM], which are "statically" substituted in the manner of JES2 in the conversion phase, just before the execution phase. See the Oracle Tuxedo Application Runtime for Batch User Guide for more details.
Besides this, the generated KSH script and the components of the Oracle Tuxedo Application Runtime for Batch use a small number of KSH and environment variables, for instance:
These variables are substituted at run-time, in the execution phase.
Script Structure
The target KSH script is organized around an execution loop which allows to implement any kind of control flow, including "backward" jumps; it also makes it possible to (re)start the script at any step. The different steps in the original JCL are implemented in the same order in the loop body, and delimited by their label (the same as in the source JCL) and the case-element terminator. Technical support and bookkeeping operations are inserted at the beginning and end of each step, as well as at the beginning and end of the whole script. They allow for instance to handle the control flow (condition codes, jumps, etc.).
Script Layout
The following JCL cards or constructs are translated into invocations of appropriate Oracle Tuxedo Application Runtime for Batch functions: JOB, JCLLIB, SET, DD, proc-overriding DD, EXEC (program), EXEC (procedure), INCLUDE, IF/THEN/ ELSE/ENDIF from the original JCL, IF from IDCAMS command files and the COND option.
Comments in the source JCL are translated into KSH comments, which the translator tries to place as close as possible to "the right place". However, comments in the continuation area (i.e., after the first space after the parameters) are ignored and not reproduced in the result script.
The // card which terminates the job is translated as a jump to the end of the script.
As mentioned above, an EXEC procedure card is translated into an invocation of the m_ProcInclude Oracle Tuxedo Application Runtime for Batch function, and an INCLUDE card is translated into an invocation of the m_ShellInclude function. SYSIN files and references (DD cards) are handled in two different ways:
In-stream data files (DD * cards and associated contents), which are generally text-like files, are also implemented inside the target script. The EBCDIC-to-ASCII conversion of their contents is performed at the same time as the source JCL file is converted, during the transfer to the migration platform.
Execution Logs
The execution log reports about the progress of the translation process. Its structure is as follows:
Listing 9‑2 Example Log file:
CMD : /refine/launch.bash jclz-unix -archi64 -s ../param/sys.desc -c ../param/config.desc
MetaWorld starter
(funcall MAKE-TRANSLATE)
*interactive-mode-string* *UNDEFINED*
Parsing system file : ../param/system.desc
MY_DIR = /refine
Current OS is IBM-MF
Parsing config file : ../param/config-trad-JCL.desc
File list in table : /workspace/FTJCL01/source/../param/file-list-in-table.txt
Creating target file /workspace/FTJCL01/trf-jcl/JCL/BBSAJ001.ksh ...
At 12:02:08, Loading /workspace/FTJCL01/source/JCL/pob/BBSAJ001.jcl.pob...
Printing /workspace/FTJCL01/trf-jcl/JCL/BBSAJ001.ksh
done
Creating target file /workspace/FTJCL01/trf-jcl/JCL/BDBAJ001.ksh ...
At 12:02:08, Loading /workspace/FTJCL01/source/JCL/pob/BDBAJ001.jcl.pob...
Patching because current version ("9.9.1") and POB version ("0.8.6") are not the same
Printing /workspace/FTJCL01/trf-jcl/JCL/BDBAJ001.ksh
done
Rest in peace, ART...
 
Detailed Operation
General Information
When the JCL translator starts, it reads and checks the various configuration files, starting with the main one. If any inconsistency is detected at this stage, one or more error messages are printed and the translator exits. Otherwise, the translator uses both command-line options and configuration-file options to set its internal parameters, including the list of (source) JCLs to process. Then it proceeds to handle each of these JCLs in turn; for each JCL:
1.
2.
3.
4.
5.
The translator cannot be executed by several concurrent processes at the same time, because there is a risk that two different processes want to write the same sub-file at the same time.
Command-line Syntax
The Refine Launcher Interface
The JCL translator is designed to be run through the refine command, which is the generic Oracle Tuxedo Application Rehosting Workbench launcher. It handles various aspects of the operation of these tools, such as execution log management and incremental/repetitive operations. See Command-line Syntax in the Cataloger chapter.
The jclz-unix Command
Syntax
$REFINEDIR/refine jclz-unix [ launcher-options… ] \
( -s | -system-desc-file ) system-desc-path \
( -c | -config ) main-config-file-path \
( source-file-path | ( -f | -file | -file-list-file ) file-of-files )…
The launcher options are described in Command-line Syntax in the Cataloger chapter. The mandatory options are:
(-s | -system-desc-file ) system-desc-path
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. Note that many other paths used by many Oracle Tuxedo Application Rehosting Workbench tools are then derived from the location of this file, including that of the main configuration file (see next item); this makes it easy to run the same command from different working directories.
( -c | -config ) main-config-file-path
Specifies the location of the main conversion configuration file. The given path can be either an absolute path or a relative path; in the latter case, it is relative to the directory containing the system description file, as usual for the Rehosting Workbench tools.
The generic options which define which source JCLs to process are:
source-file-path
Adds to the work-list the JCL source file designated by this path. The path must be given as relative to the root directory of the system, $SYSROOT, even if the current working directory is different.
( -f | -file | -file-list-file ) file-of-files
Adds to the work-list the JCL source files listed in the file designated by this path. The file-of-files itself may be located anywhere, and its path is either absolute or relative to the current working directory. The JCL source files listed in this file though, must be given relative to the root directory of the system.
You can give as many individual JCLs and/or files-of-files as you wish. The work-list is built when the command line is analyzed by the JCL translator, see the detailed description above.
Repetitive and Incremental Operation
Even with the powerful computing platforms easily available nowadays, processing a complete asset using the Rehosting Workbench remains a computing-intensive, long-running, memory-consuming task. Oracle Tuxedo Application Rehosting Workbench tools are hence designed to be easily stoppable and restartable and, thanks to a make-like mechanism, not repeat any piece of work which has already been done. This allows efficient operation in all phases of a migration project.
Initial Processing: Repetitive Operation
In the initial phase, starting with a completely fresh asset up to the end of the first conversion / translation / generation, with a stable asset, the make-like mechanism is used to allow repetitive operation, as follows:
1.
2.
3.
4.
This mode is particularly well suited for tools or commands which operate globally on the whole asset, such as the cataloger, but it is also useful for component-specific tools such as the JCL translator. This is the normal mode of operation for the Rehosting Workbench tools and there is no specific action required to activate it.
Changes in the Asset: Incremental Operation
The JCL translator knows the dependencies between the various components (main JCL files and sub-files) and associated result files (POB files, target KSH files). Using this information, it is able to react incrementally when some change occurs in the asset, i.e. when a JCL source file is added, modified or removed: the cataloger reparses the affected JCLs, and then the JCL translator re-translates only the reparsed JCLs. Again, this is the normal mode of operation for the Rehosting Workbench tools and there is no specific action required to activate it.
Concurrent Operation
As mentioned above, it is not advised to run the JCL translator concurrently with several processes, because different processes might wish to write the same target sub-file at the same time. However, JCL translation is fast and there is generally no need to make it faster using concurrent processing.
Use through make
to be completed
Frequently Asked Questions
When do I translate anew some JCL?
How do I force the (re)translation of a JCL?
Either:
The former solution is recommended, because it is less "intrusive" on the source asset than the other.
I deleted a JCL. Why is the corresponding KSH still present?
You have to delete the latter by hand, together with its sub-files such as procedures and include files (if they are not used by any other KSH).
I run the translator but it produces no translation
The procedures are not included in the JCLs, and hence in the KSH
In the system description file, check the following:
Where do I find the translated procedures?
They are located in the directory defined by the target-proc (or possibly root-skeleton) option of the translator configuration file. To this path is appended the relative path of the procedures under the root directory of the source asset (as defined in the system description file). For instance, with the following directives:
target-proc=/Workspace/Master-Proc
directory "PROC" type JCL-LIB files "*.proc".
directory "INCLUDE" type JCL-LIB files "*.incl".
directory "JCL" type JCL files "*.jcl" libraries "SYSIN", "INCLUDE", "PROC".
The procedures will be located in the directory /Workspace/Master-Proc/PROC.
Why are some FSNs lost during translation?
Check that the FSNs you want to keep are not in the list of FSNs to delete (set-delete-fsn option in the translator configuration file). If so, remove them from this list or, if you still want to delete some of them but not all ("wild card" in the set-delete-fsn list), add those you want to keep into the set-keep-fsn list.
 

Copyright © 1994, 2017, Oracle and/or its affiliates. All rights reserved.