• Description of the Output Files including the Generated Objects.
• Detailed Processing including the Command-Line Syntax.
• For sequential VSAM files (VSAM ESDS): Tuxedo ART Workbench adds a technical column: *_SEQ_NUM NUMBER.
•
• For indexed VSAM files (VSAM KSDS): Tuxedo ART 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.
Table 7‑1 Picture Clause Re-engineering Sample: PIC S9(4) BINARY is migrated as NUMBER(5) Becomes CHAR if length <= 2000Becomes VARCHAR2 if length > 2000 and <= 4000If the parameter file:char_limit_until_varchar is set in the db-param.cfg file, it takes precedence over the above rule.This file should be created in the directory indicated by the $PARAM directory:Listing 7‑1 db-param.cfg Template
Table 7‑2 db-param.cfg Parameters Default value is “cobol_mf” for Micro Focus COBOL. Specifies a mapping table file between EBCDIC (z/OS code set) and ASCII (Linux/UNIX code set) hexadecimal values; if hexa-map-file is not specified, a warning will be logged.
• For a field size > 2000 it is migrated in VARCHAR2, except if the parameter file:char_limit_until_varchar is used.If the parameter contains: file:char_limit_until_varchar:29 When presented, this file will be automatically executed at the end of the generation process. It will be called using the <configuration name> as an argument.Listing 7‑2 file-template.txtWhen required, another version of the file-template.txt file can be placed in the $PARAM/file directory. The use of an alternative file is signaled during the execution of file.sh by the message:Listing 7‑3 Execution Log with Alternative Template FileThis file is placed during the installation of Tuxedo ART Workbench, it controls the transfer of components generated in the different installation directories. This file indicates the location of each component to copy during the installation phase of file.sh, when launched using file.sh -i.
Note: In the mapper file, the converted clause has to be used for RDBMS Table target.
Indicates file is to be converted to Oracle table (converted clause can be combined with transferred clause) Indicates that the file is to be loaded and reloaded (can be combined with converted clause).
• record name: corresponds to the level 01 field name of the copy description.
• path/COPY name: corresponds to the access path and name of the descriptive copy of the file to migrate.
Note: “map record” and “source record” parameters must use the same “record name” and “descriptive copy”. They are used for forward compatibility.
• record name: corresponds to the level 01 field name of the copy description of the file to migrate.
• path/COPY name: corresponds to the access path and name of the descriptive copy of the file to migrate.
Note: “map record” and “source record” parameters must use the same “record name” and “descriptive copy”. They are used for forward compatibility.
Table 7‑4 Mapper File Attributes Listing 7‑5 Mapper File ExampleIn this example the mapper file is named STFILEORA. The file processes only one file named PJ01AAA.SS.VSAM.CUSTOMER that is migrated to an Oracle table using the convert option. The ODCSF0B.cpy copy file used to describe the file is one of the source copy files.
•
•
Table 7‑5 Mapping Strategies When discarding subfields at the level NIV1, Tuxedo ART Workbench File-to-Oracle Converter only processes the field NIV1 PIC 9(5). When not discarding subfields, the NIV1 field is ignored and the two fields NIV2A and NIV2B are processed.Listing 7‑10 Mapper File for the File: PJ01AAA.SS.VSAM.CUSTOMERThe table is generated as follows (only the VS_CUSTBDATE field is kept).Listing 7‑13 Mapper File for the File: PJ01AAA.SS.VSAM.CUSTOMERThe tables are generated as follows (a parent table is generated using the fields not part of the REDEFINES, and two child tables are generated, one for each REDEFINES description).A discrimination rule must be set on the redefined field; it describes the code to determine which description of the REDEFINES to use and when.
Table 7‑6 Discrimination Rules In the following example the fields DPODP-DMDCHQ, DPONO-PRDTIV, DP5CP-VALZONNUM are redefined.Listing 7‑15 Discrimination Rule COBOL DescriptionListing 7‑16 Discrimination RulesThe first rule is to test the value of the numeric field DPODP-RDCRPHY.The second rule tests the first two characters of an alphanumeric field DPONO-NPDT. Only the values 01 and 02 are allowed.The third rule tests whether the field DPODP-RDCRPHY is numeric.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 COBOL Description), then it is the location of the copy book that is directly used.
Note:
• Log generated by the option -g:The unloading and loading components generated with the -i $HOME/trf option are placed in the following locations
Table 7‑7 Component Locations <file name>.jclunload Location by <configuration name> of the SQL scripts used to create the Oracle objects. List of components is depending on the optional attributes clause initialized in the mapper file.
Note: <target table name> is the file name on the target platform, this file name is furnished in the mapper file.The JCL used to unload the files are generated using the -g option of the file.sh command. They are then (using the -i option) installed in:Each JCL contains two steps and unloads one file using the z/OS IDCAMS REPRO utility. The JCL return code is equal to 0 or 4 for a normal termination.
The JCLs are named: <file name>.jclunload
Note: The .jclunload extension should be deleted for execution under z/OS.
•
• Listing 7‑17 Unload JCL ExampleThe COBOL transcoding programs are generated using the -g option of the file.sh command. They are then (using the -i option) installed in:The programs are named: RELTABLE-<logical file name>.pcoThe programs should be compiled using the target COBOL compilation options and Oracle Precompiler options documented in Compiler Options.The compilation of these programs requires the presence of a CONVERTMW.cpy copy file adapted to the project, documented in Codeset Conversion..Listing 7‑18 FILE CONTROL Section - for Rranscoding Programs
Note: The do_commit module is part of Oracle Tuxedo Application Runtime Batch.
Note: When migrating to a target platform using Intel hardware the message: “PROCESSOR UNIT IS INTEL” is output at the beginning of transcoding.The Reloading Korn shell scripts are generated using the -g option of the file.sh command. They are then (using the -i option) installed in:The scripts are named: loadtable-<logical file name>.kshThe execution of the scripts produces an execution log in $MT_LOG/<logical file name>.logListing 7‑19 Reloading Table Script VariablesVarious messages may be generated during the three execution phases of the scripts; explanations of these messages are listed in Oracle Tuxedo Application Rehosting Workbench Messages.Oracle objects are created under SQLPLUS using: ${DDL}/STFILEORA/ODCSF0B.sqlThe ORACLE DDL is generated using the -g option of the file.sh command. They are then (using the -i option) installed in:They are named: <target file name>.sqlOracle column name; the format is xx_SEQ_NUMConstraint name of primary key (PK_<Oracle table name>Constraint name of unique key (UK_<Oracle table name>)Constraint name of foreign key (FK_<Oracle table name>_<parent_table_name>)Listing 7‑20 DDL Generation sql ExampleVS_CUSTIDENT NUMBER(6) NOT NULL,VS_CUSTLNAME VARCHAR2(30),VS_CUSTFNAME CHAR (20),VS_CUSTADDRS VARCHAR2(30),VS_CUSTSTATE CHAR (2),VS_CUSTBDATE NUMBER(8),VS_CUSTEMAIL VARCHAR2(40),VS_CUSTPHONE NUMBER(10),These access functions are generated using the -g option of file.sh and installed in$HOME/trf/DML using the -i and -s options.
Table 7‑8 Access Functions Calls all init_all_files_<configuration name>.cbl (function used by Oracle Tuxedo Application Runtime Batch). Initializes a transaction. All variables used by relational module and ASG_<logical file name> module are initialized for the configuration name listed (function used by Oracle Tuxedo Application Runtime Batch). Closes a transaction. This program closes all cursors opened in tables for the configuration listed and unlocks all files opened with logical accessor ASG_<logical file name> (function used by Oracle Tuxedo Application Runtime Batch). Calls all close_all_files_<configuration name>.cbl (function used by Oracle Tuxedo Application Runtime Batch).The RM_<logical file name>.pco and ASG_<logical file name>.cbl access functions use the following variables:
Table 7‑9 Access Call Implemented Variables Indicates the type of operation to execute, for example OPEN, WRITE, etc. The code is passed using the FILE-CODE-F variable of the MWFITECH copy file. A file can be opened in different modes: INPUT, OUTPUT, I O, EXTEND. The mode is passed using the FILE-OPEN-MODE variable of the MWFITECH copy file. The name of the secondary key is passed using the FILE-ALT-KEY-NAME variable of the MWFITECH copy file. For a relative file, the value of the relative key is passed to or from the access module using the FILE-REL-KEY variable of the MWFITECH copy file.Listing 7‑21 LINKAGE SECTION StructureFor all OPEN operations, the FILE-CODE-F variable should contain the key-word OPEN.The FILE-OPEN-MODE variable should contain the type of OPEN to perform as follows:.
Table 7‑10 Call Argument File Open Modes For CLOSE operations, the FILE-CODE-F variable should contain the key-word CLOSE.For CLOSE LOCK operations, the FILE-CODE-F variable should contain the key-word CLOSE-LOCK.
Table 7‑11 Call Argument Delete Modes
Table 7‑12 Read Operation Values Depending on Arguments If DataName1 is a variable corresponding to the keyAltKey1
Note: If the INTO clause is found, a MOVE operation is added after the call in order to set the value of the indicated field.
Note: If the FROM clause is found, a MOVE operation is added before the call in order to set the value of the indicated field.
The following copy files are used by certain access functions. They should be placed in the directory: < installation platform>/fixed-copy/ during the installation of Tuxedo ART Workbench:These KSH scripts are generated using the -g option of file.sh and then installed in $HOME/trf/SQL/file/<configuration name> using the -i option. When necessary, they are used by Oracle Tuxedo Application Runtime Batch.
Table 7‑16 Korn Shell Utilities The desc.vsam and envfile_tux files are generated in the $HOME/trf/config/tux/ directory when VSAM files are migrated to Oracle tables. They are used by Oracle Tuxedo Application Runtime CICS.This file is used by Tuxedo ART Workbench COBOL Converter and JCL Converter to rename object names.
Table 7‑17 Conversion File Names These files are created when VSAM files are converted to Oracle tables. They are used by Oracle Tuxedo Application Runtime Batch to bridge the technical differences between the z/OS file on the source platform and the corresponding Oracle table on the target platform.The files are generated in: $HOME/trf/dataThey are named: <source platform physical file name>.rdb${DATA}/<source platform physical file name> <max> <org> <form> UL_<logical file name> <asgn_in> DL_<logical file name> <asgn_out> RM_<logical file name> <target table name> ${DDL}/<configuration name/cleantable-<target table name>.ksh ${DDL}/<configuration name>/droptable-<target table name>.ksh ${DDL}/<configuration name>/createtable-<target table name>.ksh ${DDL}/<configuration name>/ifemptytable-<target table name>.ksh ${DDL}/<configuration name>/ifexisttable-<target table name>.ksh
Table 7‑18 .rdb file Parameters <source platform physical file name> Uploading component name used by Oracle Tuxedo Application Runtime Batch.
• n: offset of the indexed key (in COBOL description).
• m: length of the indexed key (in COBOL description). m: length of the relative key (in COBOL description).The following example is generated when migrating an indexed VSAM file to an Oracle table. On the source platform, the VSAM file is named: PJ01AAA.SS.VSAM.CUSTOMERListing 7‑22 .rdb indexed VSAM Examplefile.sh creates different execution reports depending on the options chosen. In the following examples the following command is used:Copied <Templates>:../../Conv-ctrl-STFILEORA to /home2/wkb9/param/dynamic-config/Conv-ctrl-STFILEORAThis section describes the Command-Line Syntax used by the File-to-Oracle Converter, and the Process Steps summary.file.sh - generate file migration components.file.sh generates Tuxedo ART Workbench components used to migrate z/OS files to Oracle databases.Makes the generated SHELL scripts executable. COBOL programs are adapted to the target COBOL fixed format. When present, the shell script described in File Modifying Generated Components is executed.Places the components in the installation directory. This operation uses the information located in the file-move-assignation.pgm file.If the file.sh options are used one at a time, they should be used in the following order:
1.
2.
3. 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).The components used for the reloading (generated in $HOME/trf/reload/file) should be installed on the target platform.
Table 7‑19 Target Platform Environment Variables The location of the generic reload and control scripts ($HOME/trf/reload/bin). ($HOME/trf/SQL/file/<configuration name>). This UNIX/Linux variable has to contain the directory of the Oracle Tuxedo Application Runtime for Batch utilities. The directory where the *.rdb files are generated by workbench. When "use-file-catalog" is set in system description file, this variable is necessary.E.g., "$HOME/trf/data".Compiling these programs requires the presence of a copy of CONVERTMW.cpy adapted to the project.These unloading JCLs are named <logical filename>.jclunloadThe files transferred to the target UNIX/Linux platform should be stored in the $DATA_SOURCE directory.loadtable transcode and reload data to table.This check uses the following option of the loadtable-<logical file name>.ksh