The resulting programs can be compiled and run on the target platform with the same behavior as on the source platform, except in some cases detailed in Scope.
•
• The individual conversion phase can run concurrently on several programs but, since the copy-reconciliation phase updates the global copy file base, it must run as a single process, possibly incrementally. This dictates the possible execution modes of the Cobol converter; see Command-line syntax for more details.By definition, the Rehosting Workbench Cobol Converter accepts only those programs accepted by the Rehosting Workbench Cobol Cataloger, but imposes no further restriction on entry.
• Listing 6‑1 Binary field manipulation exampleOn a big-endian machine such as the z/OS hardware, CHARVAR(1:1) contains the most significant (higher-order) byte of BINVAR. However, on a little-endian machine, with the same code, CHARVAR(1:1) will contain the least significant (lower-order) byte of BINVAR; this is definitely a change of behavior and will probably lead to different observable results. However, the Rehosting Workbench Cobol Converter is unable to detect and fix all occurrences of this situation (the example above is "obvious", but there exists many much more complex cases); these must be handled manually.As mentioned in the previous paragraph, the Rehosting Workbench Cobol converter translates portable binary integer types (BINARY, COMP, COMP-4) to the native binary type COMP-5. In addition to endianness problems, this may cause another kind of difference of behavior for applications which were compiled with the (default) TRUNC(STD) option on the source platform – this option corresponds to the TRUNC option of Micro Focus Cobol. Indeed, both on the source and on the target platforms, the portable binary types obey this option whereas the native type does not. In our opinion, the probability of observing a real difference of behavior is very low, because in general, binary-integer variables are used to hold "control" values (loop counters, array indices, etc.) rather than applicative values. In any case, if differences of behavior are observed, it is up to the Rehosting Workbench user to deal with them, either by accepting them or by manually correcting them, for instance by returning a few selected variables to their original binary type.As mentioned above, string or character literals in Cobol programs, including hexadecimal string literals, are subject to EBCDIC-to-ASCII conversion. This is legitimate when these literals denote texts or pieces of text. Sometimes however, such constant values denote (numeric) codes such as file status codes, condition codes, CICS-related values, etc. In this case, it is generally not appropriate to apply EBCDIC-to-ASCII conversion to these values. However, the Cobol converter, like any automatic tool, cannot reliably "guess" the semantic nature of a Cobol variable or literal, so it cannot handle itself these exceptions; this will have to be done manually using post-translation, see post-translation-file clause).Source floating-point variables (COMP-1 and COMP-2) types are "translated" to the same types on the target platform. Given this, the Micro Focus Cobol compiler and run-time system offer the possibility to use floating-point data (COMP-1 and COMP-2 variables) in either the IBM hexadecimal format or the native (IEEE 754) format. If the NONATIVEFLOATINGPOINT option is set at compile time (which is true by default), then the floating-point format is selected at run-time, depending on the MAINFRAME_FLOATING_POINT environment variable and/or the mainframe_floating_point tunable:
• MAINFRAME_FLOATING_POINT environment variable set, or mainframe_floating_point tunable set to true: the IBM format will be used.
• MAINFRAME_FLOATING_POINT environment variable unset, and mainframe_floating_point tunable unset or set to false: the native format will be used.In the first case, the Micro Focus run-time system will ensure that you will observe no difference of behavior. However, this is at the expense of run-time efficiency, because the handling of this format is done entirely in software, whereas the native format is directly supported by the processor. Furthermore, this format is not directly compatible with the Oracle floating-point data types (BINARY_FLOAT and BINARY_DOUBLE) and cannot be converted to other numeric types by the Oracle engine; in fact, the only thing you can do with it is store it in opaque columns (RAW(4) and RAW(8), respectively), which forbids using such values in SQL code.
• On the source platform, COMP-1 and COMP-2 types have the same representation range, from about 10-79 to 1076, whereas on the target platforms (which all natively support the IEEE 754 format), the range for COMP-1 is about from 10-45 to 1038 and the range for COMP-2 is about from 10-323 to 10308. So the tradeoff between range and precision is different on both platforms.When the same computations are performed on ranges available on both the source and target platforms, the relative error between the observed results (as printed by DISPLAY) is always less than 10-6 when using COMP-1 variables and less than 10-14 using COMP-2 variables. This is not a definitive proof that everything works fine, but it is at least an encouraging indication.Given these results, it seems that one can always reproduce the same behavior on the target as on the source, up to insignificant approximations, possibly by replacing some COMP-1 variables by COMP-2 ones.
Note: If you decide to go with the native IEEE 754 format, we recommend that you set the NATIVEFLOATINGPOINT compiler option, which forces the use of this format at compile-time, regardless of run-time options and tunables. Thus, you will save the run-time format tests.By default, data files which are SEQUENTIAL on the source platform are translated into LINE SEQUENTIAL files on the target platform, to be more "usable". In general, this is a good choice and such files are well supported by the Micro Focus Cobol system. However, there is a catch: since such files are inherently of variable record size, a REWRITE operation may cause unpredictable results and differences of behavior (see the Micro Focus documentation). If you are not sure that REWRITE operations on a given SEQUENTIAL file would always succeed if that file is turned into a LINE SEQUENTIAL one, we advise to keep it purely SEQUENTIAL; this can be done by inserting its description in the configuration sub-file referenced by the pure-seq-map-file clause below.To ease the handling of this problem, in a future version, the the Rehosting Workbench cataloger will produce the list of SEQUENTIAL logical files which incur a REWRITE operation.On the source platform, a variable of type POINTER occupies 4 bytes in memory (32 bits); on all the sup-ported target platforms, based on 64-bit Operating Systems, such a variable occupies 8 bytes. This may lead to various kinds of differences of behavior for which we take no responsibility:
• Technical redefinitions: if a POINTER variable is directly redefined by a PIC X(4) or PIC S9(9) COMP variable used to manipulate the representation of the pointer values, the redefining variable and the code dealing with it will have to be manually rewritten. However, we strongly discourage such machine-dependent "hacks".
• Structure alignments: if a POINTER variable is part of a structure containing variants (redefinitions), and if the different variants (sub-structures) are designed so that one particular field of one variant must be aligned with (have the same location as) some other field in some other variant, then this property must be maintained after the POINTER variable changes size: compensation fillers must be inserted, etc. Again, this must be handled manually. Note that such intended alignments must be maintained across redefinitions, but also across MOVEs to other structures.
• Structure size: if a POINTER variable is part of a structure which is moved to some unstructured PIC X(…) variable which was big enough to hold the structure before the POINTER variable changes size, then you must make sure that it is still the case after the change.On both the source and target platforms, a program parameter (defined in the Linkage Section and listed in the USING clause of the procedure division) which is not actually passed by the caller, either because of an explicit OMITTED item is passed instead or because the caller passes less arguments than the callee expects, appears to have a NULL address in the callee. So it is quite legal, and in fact recommended, to check whether the ADDRESS OF some parameter is NULL before accessing the value of this parameter.
• However, when the callee fails to check the parameter address and the actual address is NULL, the source and target platforms may behave differently. For instance:
• On z/OS and AIX, NULL is address 0 and this is considered as a legal address, so when the parameter is accessed, you get whatever is stored at that address (possibly with unpredictable results).
• On Linux however, although NULL is also address 0, this is not considered as a legal address, so when the parameter is accessed, the program crashes.
• There is one exception, though, which may alleviate the problem for a large majority of the offending cases: the Oracle Tuxedo Application Runtime for CICS will ensure that all programs called from it (first program in a transaction, EXEC CICS XCTL, EXEC CICS LINK, etc.) will receive a valid COMMAREA: either the one passed from the caller or a dummy-but-legal one.
• See also the discussion of the STICKY-LINKAGE compiler option below.The representation of the NULL pointer value may vary from one platform to another, in particular between the source and target platforms – if only because they don't have the same size, like every other pointer value. In consequence, every program which assumes a specific representation for this value, for instance by "casting" it to or from some binary integer value, may have a different behavior from one platform to another. The Cobol converter cannot handle this issue by itself, automatically, and it will have to be handled manually. Anyway, we strongly discourage such machine-dependent "hacks".The input components are all the Cobol programs in the asset, after they have been parsed by the cataloger. In fact, the Cobol Converter loads the POB files for the programs, not their source files. In addition to the restrictions imposed by the cataloger (no nested programs, etc.; see Cataloger), the following rules must be respected before attempting the Cobol conversion:
Note: Because of the need to have Cobol source files with the numbering area and comment area C removed, option Cobol-left-margin must be set to 1 (one) and option Cobol-right-margin must be set to 66; these are the default values.This file is given to the Cobol converter using the -c or -config mandatory command-line option. It defines various "scalar" parameters influencing the conversion and points to subordinate files containing "large" configuration data, such as renaming files.This clause specifies the location of the directory that will contain the complete hierarchy of target files, for both programs and copy files. If there is a source program A/B/name.ext in the root directory of the asset (as specified in the system description file), then the corresponding target program will be located as A/B/name.ext in this target directory (possibly with a different file extension, see below). The same mechanism is used for copy files, except that the target path will be Master-copy/A/B/name.ext (or possibly a different file extension). The Master-copy directory is related to the copy reconciliation process, see Command-line syntax.
• If the keep-same-file-names clause is given, the converted programs and copy files will have the same file extensions as the original files in the source asset (as cataloged). The other clauses, if given, will be ignored.
• If the target-program-extension clause is given, then the converted programs will have the given file extension,
• If the target-copy-extension clause is given, then the converted copy files will have the given file extension.
• By default, the converted programs will have the file extension cbl and the converted copy files will have file extension cpy.This clause specifies that the copy-reconciliation process crp is to be deferred until after the conversion is completed; this allows Cobol conversion to run in multiple concurrent processes. By default, in the absence of this clause, the copy-reconciliation process is executed incrementally immediately after each program is converted, which mandates single-process execution. See the copy-reconciliation process below for more details.This clause specifies the location of the subordinate configuration file containing information to rename copy files, see the copy-renaming configuration file below. The file path is given as a string. It 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.This clause specifies the location of the subordinate configuration file containing information to rename sub-programs and their calls, see the call-renaming configuration file. The file path is given as a string. It 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.This clause specifies the location of the subordinate configuration file containing the description of manual transformations to apply after the Rehosting Workbench Converter, see the post-translation configuration file. The file path is given as a string. It 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.This clause specifies the location of the subordinate configuration file containing the EBCDIC-to-ASCII transformation to apply to characters in hexadecimal form, see the hexadecimal conversion configuration file. The file path is given as a string. It 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.These clauses specify the location of the two subordinate configuration files containing information regarding file-to-Oracle conversion. These files are generated by the Rehosting Workbench File-to-Oracle conversion tool, as respectively the Conv-ctrl-file or the Conv-ctrl-list-file and the Alt-key file. See file-to-RDBMS configuration files.Only one of the first two clauses must be given: either the conv-ctrl-file clause or the conv-ctrl-list-file clause, but not both.This clause specifies the location of the top-level subordinate configuration file containing information about relational DBMS conversion (from DB2 to Oracle). See the RDBMS-conversion configuration files for more details. The file path is given as a string. It 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.This clause specifies the location of the subordinate configuration file containing information to rename Cobol identifiers which happen to be keywords or reserved words in the target Cobol dialect, see the keywords file for more details. The file path is given as a string. It 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.This clause specifies the location of the subordinate configuration file containing the list of DB2 stored procedures called directly from Cobol, see the stored-procedure file for more details. The file path is given as a string. It 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.This clause forces the Cobol converter to apply to any program processed in the current execution the rules which normalize the EXEC CICS statements and prepare the program for use with the Oracle Tuxedo Application Runtime for CICS environment, including the CICS preprocessor.
• There exists a command-line option of the same name (see cobol-convert command) which has the same effect as this clause, and which is more flexible to use. So we believe that the configuration-file clause will be seldom used, except perhaps in projects in which the TP and batch parts of the asset are well identified and strictly separated in the migration project.
• Whether this clause is given or not, the above rules will be applied anyway to every program which contains one or more EXEC CICS statement. So this clause (or the equivalent command-line argument) will be effective only for subprograms used in a CICS environment (implicit COMMAREA, etc). but do not perform CICS operations themselves.This clause specifies the location of the subordinate configuration file containing the list of SEQUENTIAL logical files which are to be kept (record) SEQUENTIAL rather than converted to LINE SEQUENTIAL. See purely-sequential configuration file for more details. The file-path is given as a string. It 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.When present, this clause specifies that the what-string containing conversion timestamp and converter version information, which the converter normally inserts at the beginning of every converted file, is not to be printed out in this execution. This will be seldom used, unless you really want to hide the fact that your application is migrated using the the Rehosting Workbench!This clause specifies the location of the subordinate configuration file containing additional pairs of equivalent DB2 & Oracle SQLCODE values. See the sql-return-codes configuration file for more details. The file-path is given as a string. It 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.This file is associated with the rename-copy-map-file clause. Its contents are in CSV format, with the semicolon character used as separator. Each line is in the form:When the rename-copy-map-file clause is not present, or when this file is empty, no copy renaming takes place. It is an error when the file cannot be found or read, or when the same original-copy-name;original-library-name combination is associated with different new-copy-names in different lines of the file. In this case, the converter stops with an error message and does not convert any programs. Note however that it does not check whether two different copy files in the same directory are renamed to the same target file. In principle, this would be handled gracefully by the copy reconciliation process, but without guarantee.This file is associated with the rename-call-map-file clause described above. Its contents are in CSV format, with the semicolon character as separator. Each line is in the form:When the rename-call-map-file clause clause is not present, or when this file is empty, no call renaming takes place. It is an error when the file cannot be found or read, or when the same original-call-name is associated with different new-call-names in different lines of the file. In this case, the converter stops with an error message and does not convert any programs. Note however that it does not check whether two different subprograms in the same directory are renamed to the same target file.This file is associated with the post-translation-file clause. Its contents are a sequence of rules with the following syntax:The semantics of such a rule are simple: if, in a program, the (base) name of which matches any of the "positive" program_name_regexp's but none of the "negative" ones, a block of lines matching source_lines_block1 is encountered, it is replaced by target_lines_block. rule_name is used in the comment associated with the application of the transformation. See appendix the post-translator below for more details.This file is associated with the hexa-map-file clause above. Its contents are an EBCDIC-to-ASCII conversion table to apply to characters in hexadecimal form (characters in textual form are supposed to be converted at the same time as the source file itself). The syntax is simply a CSV file with a semicolon as separator. Each line is in the form:These files are associated with the conv-ctrl-file clause and alt-key-file clause. They contain information about file-to-RDBMS conversion, e.g. to define which logical files (FDs) are converted into RDBMS tables (actually, because the physical files they are associated with are converted to these DB tables). Since these files are automatically generated by the the Rehosting Workbench File-to-Oracle conversion tool and should not be modified by hand, their contents are not further specified here.These files are associated with the RDBMS-conversion-file clause above. The information they contain is accessed in a two-level way:
• The top-level file is named in the RDBMS-conversion-file clause proper. Its contents is a CSV table, with each line in the form:This file is associated with the keywords-file clause. Its contents are a CSV table using the semicolon as separator, each line being in the form:This file is associated with the sql-stored-procedures-file clause. Its contents are a list of subprogram names, one per line. When one of these names appears in a Cobol CALL statement, the latter is replaced by an SQL CALL statement. In addition, declarations of the parameters of the CALL, if any, are adapted so that they can be used in SQL statements.This file is associated with the pure-seq-map-file clause. Its contents is a CSV table using the semi-colon as separator, each line being in the formwith both names being symbols. The effect of such a line is to prevent this particular logical file (the given FD in the given program), assumed to be (record) SEQUENTIAL on the source platform, to be converted to LINE SEQUENTIAL on the target platform; rather, it is kept unchanged as a record SEQUENTIAL file. This makes it much less amenable to manipulation using standard target-platform utilities, but on the other hand, it will support unrestricted REWRITE operations (see section REWRITE operations on LINE SEQUENTIAL files above). This might also be useful for files exchanged with a z/OS platform in binary form.This file is associated with the sql-return-codes-file clause. Its contents is a CSV table using the semicolon as separator, each line being in the form:Listing 6‑2 DB2 to Oracle SQL return code mappingAs mentioned above, the main purpose of the Rehosting Workbench Cobol Converter is to produce the converted Cobol components, in the form of their source files. There is a direct, one-to-one correspondence between the hierarchy of main program files inside the source root directory and the hierarchy of main program files inside the target root directory; the only possible differences, as far as file names are concerned, come from the CALL-renaming map and the choice of the target program-file extension, see rename-call-map-file clause and keep-same-file-names, target-program-extension and target-copy-extension clauses. The same comments apply for the target copy files, with the following observations:
• The hierarchy of target copy files is located in the Master-copy sub-directory of the target root directory.
• The names of the target copy files may differ from those of the source files because of the COPY-renaming map and the choice of the target copy-file extension.If file ORIGCOPY(.s-ext) is translated into multiple versions, these versions are named ORIGCOPY(.t-ext), ORIGCOPY_V1(.t-ext), ORIGCOPY_V2(.t-ext), etc.Listing 6‑3 Transformation comment example
• A header line giving the transformation-rule name and version; the header line starts with the prefix "*+{", in which the opening curly bracket symbolizes the start of the transformation and the plus sign indicates that this is an insertion rather than a transformation.
• Listing 6‑4 Validated Cobol compiler option list
4. The (text of the) resulting AST is then printed out in the target program file. When the beginning of a copy file is encountered, the COPY clause is written to the caller file and the sequel of the output is diverted to a new output file for this copy file, in a private directory; if a file with this name already exists in the directory, it probably is because the same copy file is included more than once in the program, and the new file carries a new version number (the existing version is not overwritten). If the copy file was invoked with a REPLACING clause, the effects of the replacements are undone before the file is printed out (see the caveat Miscellaneous issues regarding interferences between transformations and replacements). When the end of the copy file is reached, output is reverted to the caller file. This allows to correctly handle nested copy files.
6. Lastly, if the deferred-copy-reconcil clause is not given, either on the command-line or in the con-figuration file, the copy reconciliation process is applied to the target copy files in the private directory.The converter can be executed by several concurrent processes at the same time, provided that the deferred-copy-reconcil clause is given either on the command-line or in the configuration file; otherwise, the copy-reconciliation phase of these concurrent processes may run into access conflicts over the "data-base" of final, reconciled copy files, which could lead to corrupted results.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 of the Rehosting Workbench tools are then derived from the location of this file, including that of the main configuration file (see next option); this makes it easy to run the same command from different working directories.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.Has the same effect as the deferred-copy-reconcil clause of the configuration file, namely to not run the copy reconciliation process incrementally after converting each program. Only with this clause or flag can the Cobol converter run in multiple concurrent processes.-tce extension or -target-copy-extension extension-force or -force-translation
•