File Organization Support

PEngiEZT does not support DL1 and IDMS files. Programs accessing such files can be translated by tailoring your Easytrieve source to call a subprogram for I/O services.

EBCDIC Files Support

PEngiEZT supports EBCDIC files only. Easytrieve programs that read KANJI and DCBS files cannot be translated.

Fixed Length Records

Make sure that the record size of each file is fully defined. This can be done by coding the record length in the file statement, or by defining the record layout in full.

Easytrieve retrieves record size dynamically during run time. COBOL does not. It is essential to have the correct file record length in the converted COBOL program.

NON-VSAM Variable Length Records

NON-VSAM variable length record files can be one of: variable unblocked, variable blocked and spanned organization.

Make sure that the record size of variable length files includes 4 extra bytes for standard length as per IBM standards. This is also a standard Easytrieve rule. Thus, you need to worry about only those files that do not have record size included in the file definition.

Record length can be coded in the FILE statement.

PEngiEZT computes the usable record area by subtracting 4 from the declared length.

Easytrieve retrieves record size dynamically during the run time. COBOL does not. It is essential to have the correct file record length in the converted COBOL program.

VSAM Variable Length Records

Note:

VSAM file is considered a variable length file when the minimum record length, specified in the VSAM catalog, is not equal to the maximum record length. If the minimum and maximum lengths are equal, then the file is of fixed length format.

For VSAM files, Easytrieve obtains record and file characteristics from the VSAM Catalog, and it does not allow record size in the FILE definition.

COBOL does not dynamically allocate VSAM file characteristics. Therefore, an option was added to PEngiEZT to allow a record size on the FILE statement. If the size is not specified on the file statement, PEngiEZT defaults to the size of the defined record.

If the minimum record size is equal to the maximum record size in the VSAM catalog, the specified size must be equal to the maximum value specified in the VSAM catalog.

If the minimum record size is not equal to the maximum record size in the VSAM catalog, the specified size must be equal to the maximum value minus 4.

All output and UPDATE VSAM Variable length files must be specified with FILE . . . V (NNN) where NNN is the LRECL (Maximum LRECL in the catalog - 4). Variable length Read Only VSAM files do not need to be coded with a V. Refer to the "Defining VSAM Files" for full syntax.

VSAM Key Usage

COBOL requires that an alphanumeric VSAM file key for KSDS files is named in the FD statement.

Easytrieve retrieves the key characteristics from the catalog.

To overcome the problem and retain Easytrieve compatibility, PEngiEZT convention is to use the first defined field in the record as the file key. Therefore, one must ensure that the VSAM key field is the first defined field in the record definition. The key must be defined as an alphanumeric key for the full key length.

For relative files, PEngiEZT assigns an internal key in working storage.

VIRTUAL Files

Easytrieve VIRTUAL files are handled as regular sequential files in the translated COBOL. No special handling is needed.

Extended Printer Support

PEngiEZT does not support Extended Printing of Easytrieve. One way around it is to change the Easytrieve program to the standard Printing.

Index Usage

Easytrieve allows index usage for fields defined without the OCCURS. COBOL does not. Therefore, all such statements will be flagged by PEngiEZT.

Easytrieve allows the same index name to be used for more than one field. COBOL does not.

To resolve the problem, PEngiEZT assigns a unique internal index name to each indexed field.

These internal indexes are updated every time when an index assigned by the Easytrieve is changed. Therefore, there could be a substantial overhead maintaining an index that is used for more than one field.

The problem can be resolved by changing the Easytrieve program to use a unique index for each field.

Example of index usage

FILE FILEIN
NAME   27     40  A
SCAN1  27     10  A  INDEX (SUB1) OCCURS 4
SCAN2  27      3  A  INDEX (SUB1) OCCURS 13
SCAN3  27      9  A  INDEX (SUB1) OCCURS 5

In the above example, 3 internal indexes would be updated every time "SUB1" index is changed in the program, even if it is used to access one field only. To correct the problem, a unique index can be assigned to each of the fields as follows:

FILE FILEIN
NAME   27     40  A
SCAN1  27     10  A  INDEX (SUB1) OCCURS 4
SCAN2  27      3  A  INDEX (SUB2) OCCURS 13
SCAN3  27      9  A  INDEX (SUB3) OCCURS 5

Field Naming Conventions

Easytrieve allows up to 40 character field name length. PEngiEZT reduces all field names that are longer than 18 characters to 18 characters, automatically. The field names are reduced by taking the 1st three (3) characters of the words separated by a dash (-), until the name goes below 19 characters in length. Note that INDEX names are not reduced. Long INDEX names should be manually reduced to the acceptable size.

The process above might yield undesired or ambiguous field names. To avoid the problem, a translate table can be provided in PEngiEZT EZPARAMS options to translate specific words to a desired acronym, or ambiguous field names to acceptable names.

Use NAMETAB parameter of EZPARAMS to change any special characters found in Easytrieve field names to make field names COBOL compliant.

Use COBVERBS=YES option of EZPARAMS to alter names of Easytrieve fields that conflict with COBOL Reserved Words.

PEngiEZT Options are described in the "Installation and PEngiEZT Options" section in the Reference Manual.

Ambiguous Field Position

The biggest challenge writing the translator was to translate the Easytrieve defined record and working storage layouts to COBOL.

The problem is that Easytrieve allows fields to be defined out of sequence. As a result, many layouts in Easytrieve programs are badly fragmented and out of order.

To overcome the problem, PEngiEZT iterates thru the layout(s), expanding fields or group of fields sequentially by position. Then the record is redefined and the process is repeated until all fields are translated.

Group items are grouped together and any items out of group range are flagged by PEngiEZT. Also, numeric fields that destructively overlap another field within a group item are flagged.

If you do get errors during PEngiEZT translation, re-arrange field definitions such that they are in the correct sequence and do not destructively overlap.

Note: Programs with orderly record definitions generate fewer and simpler COBOLIl layouts.

Easytrieve allows duplicate work field names. It normally ignores all duplicate names that are consistent with its original definition. PEngiEZT also allows duplicate work field names only if the field type and length are consistent. Working storage is generated only for the first occurrence of the field definition. PEngiEZT flags all conditions that it cannot handle, some of which include elementary unique field names defined within a group field that was a duplicate.

Binary Field Handling

Two (2) byte and four (4) byte binary fields are passed on to COBOL in the Native mode.

The maximum value that can be accommodated by such fields in COBOL is different from the maximum value accommodated by Easytrieve. (For limits, see binary field description in "Defining Records and Working Storage" ). COBOL Compiler option TRUNC(BIN) is recommended.

One (1) and three (3) bytes binary fields are not supported by COBOL. PEngiEZT expands special logic for handling such fields.

Easytrieve allows a signed value in such fields. PEngiEZT does not. (For limits, see binary field description in "Defining Records and Working Storage" ).

Assigning Hex Values

Easytrieve allows hex values to be assigned to numeric fields. COBOL does not.

Illegal hex values will be flagged by PEngiEZT. The problem can be resolved by changing the hex value to a decimal equivalent, or converting the field to an alphanumeric field.

Common hex usage involves assigning low-value or high-value to the fields, i.e., binary zeros or all X"FF". For such cases, replace the hex value by the "LOW-VALUE" or "HIGH-VALUE" statements respectively.

Field Headings

The maximum string length of a heading in PEngiEZT is 30 characters. Easytrieve allows field headings longer than 30 characters. Headings longer than 30 characters must be downsized to 30 characters or less.

Paragraph Naming Conventions

Easytrieve allows duplicate paragraph names within the same program if such names are located in different Procs. Since COBOL does not allow duplicate paragraphs names in Procedure Division, PEngiEZT flags all duplicate paragraph names. The problem can be solved by assigning unique paragraph names in the Easytrieve program.

Easytrieve allows Paragraph and Proc names to be over 30 characters. COBOL does not. PEngiEZT alters paragraph names to conform to COBOL rules.

COBOLII/S390 and COBOL-VS Compatibility

The Easytrieve programs are translated to COBOLII/COBOL/390 compatible. Called subprograms that are written in other COBOL dialects such as COBOL-VS, and contain VSAM file I/O routines, may experience a problem. This is strictly a COBOL compatibility problem. Such subroutines must be compiled with COBOLII or COBOL/390 compiler to make them compatible.

Calling Subprograms

PEngiEZT converts calls to subprograms as follows:

• It generates a static call for program names that are enclosed in quotes
• It generates a dynamic call for program names that are not enclosed in quotes

Easytrieve does not accept quotes around the program name. By default, all called programs would be interpreted as dynamic calls by PEngiEZT. To force a static call, enclose program name in quotes.

Undetected Errors

Easytrieve is a very forgiving language. Many times it ignores extraneous statements or it does not impose strict rules. This is especially visible with REPORT related statements such as: NOPRINT, NEWPAGE, RENUM, etc.

PEngiEZT might flag such extraneous statements. If it does, remove them or resort to a simpler form of expression.

Sign of Numeric Fields

Easytrieve forces an "F" sign in positive zoned decimal numeric fields. This is true for signed (fields defined with decimal places, i.e., as quantity), and for unsigned fields (fields defined without decimal places).

COBOL forces a "C" sign in positive zoned decimal numeric fields that are defined with a sign. Refer to FSIGN= option in PEngiEZT Options in the Reference Manual for overriding options.

For example, if O-BALANCE field is defined as per below and it contains value 22222 then:

               Definitions                   Hex Value

Easytrieve     O-BALANCE 1 5 N 0             F2F2F2F2F2
COBOL          O-BALANCE   PIC S9(05)        F2F2F2F2C2

Obviously, the last byte is different i.e., F2 vs C2, which is numerically equal, but it is not equal if compared as an alphanumeric value. Altering the Easytrieve definition to a numeric unsigned field would yield the same in COBOL:

               Definitions                   Hex Value

Easytrieve     O-BALANCE 1 5 N               F2F2F2F2F2
COBOL          O-BALANCE   PIC 9(05)         F2F2F2F2F2

Make sure that your Easytrieve fields are properly defined. All quantitative fields should be defined with decimal places (even if zero) and all non-quantitative values should be defined without decimal places.

In general, the intermediate calculations are not a problem. The problem is visible on the output display numeric fields that are defined as quantity (with a sign) but they are truly not a quantity, i.e., account numbers, serial numbers, item numbers, etc.

Varying Length Fields

In Easytrieve, fields defined as "Varying" fields are composed of 2 bytes binary length followed by the text area. The length is maintained by Easytrieve as the content of the field changes.

PEngiEZT generates COBOL code that artificially maintains such fields, i.e., the field is defined as a group item with 2 byte binary length followed by the text. The length value is automatically changed as the content of the field changes. Note that this is exactly what the Easytrieve does.

The difference exist in the maximum value that can be represented by the length. In COBOL, a 2 byte binary field can accommodate up to 9,999 in value, while Easytrieve can accommodate up to 32,767.

The difference also exists in the compare instructions. While the generated COBOL uses the length of the first argument and the second argument for comparison, Easytrieve compares the values for the length of the first argument only. The problem exists only if the fields being compared are not of the same length. The remedy to this is to make sure that the fields being compared are of the same length.

Also note that when a value is moved into the field length, the Easytrieve moves the value as is, while COBOL converts it to the binary equivalent, i.e., moving 32 into the field length would result in X'F3F2' when performed by Easytrieve, and x'0020' when performed by COBOL.

It sounds like a Headache, does not it.? Fortunately the "Varying" option is so infrequently used that you will probably never have to contend with it.

Uninitialized Working Storage Fields

Be careful with Working Storage fields. The uninitialized fields might contain a different initial value in the translated program as we cannot predict what is in Working Storage at linking time. Using uninitialized field without placing a value into it might result in erroneous outcome.

PEngiEZT generates the initial values for Working Storage fields automatically, providing that the field is not an object of redefine. If you have a doubt, move a value into questionable fields at the beginning of the first (1st) JOB.

For initializing file records, refer to MEMINIT= parameter of EZPARAMS.

The MOVE Statement

In Easytrieve, the MOVE statement moves data from left to right as if both areas were alphanumeric. The data moved is not converted, i.e., the data is moved as is, even if from/to fields are packed or binary fields.

PEngiEZT generates a standard COBOL MOVE from Easytrieve MOVE. The data is moved according to the standard COBOL Conversion rules, i.e., a move from a binary field into a display numeric field will result in data conversion from binary to Display numeric format, yielding different result then the Easytrieve Move. Compatible results can be achieved by redefining the numeric field as an alpha field and using the alpha field name as the source or target in the move statement.

PEngiEZT issues a Warning (MNOTE) message for questionable moves. The messages should be reviewed and problems should be corrected if deemed as problematic.

FILE-STATUS (STATUS) Codes

Easytrieve I/O Status codes are different from those in COBOL. In general, changes are not needed if your program is not checking for a specific non-zero value. If your program is testing for a specific non-zero value, you must adjust the value in your Easytrieve Source to comply with the COBOL Status Codes. For additional information refer to the "System-Defined Fields" in the Reference Manual.

Labels Inside DO or IF Statements

Easytrieve allows Labels (paragraph names) inside the DO or IF statements. Programmers use Labels to loop within the DO/IF, or to jump around the code. COBOL cannot handle such syntax.

PEngiEZT automatically generates a separate COBOL paragraph if the Label is coded inside a DO/IF before the first "GO TO &LABEL" statement that refers to it. The generated paragraph is PERFORMED from within the original DO/IF.

PEngiEZT flags all Labels that are coded after the first "GO TO &LABEL", and the label is inside a DO/IF nest. Such conditions must be massaged by the programmer.

Example of Easytrieve:

FIELDB = 'N'
IF FIELDA = 'Y'
  DO WHILE FIELDB EQ  'N'
     FIELDC = FIELDC + 1
     IF FIELDC GT 100
        FIELDB = 'Y'
        GOTO LABEL1
     ELSE
        FIELDB = 'N'
     END-IF
LABEL1
  END-DO
END-IF

Before translating, the routine should be converted to something like this:

FIELDB = 'N'
IF FIELDA = 'Y'
  DO WHILE FIELDB EQ  'N'
     PERFORM LABEL1-CODE
  END-DO
END-IF
 .
 .
* THIS PROC MUST BE INSERTED OUTSIDE OF THE CURRENT JOB MAIN BODY.
* END OF CURRENT JOB STATEMENT BUT BEFORE FIRST REPORT WOULD DO.

LABEL1-CODE. PROC.
  FIELDC = FIELDC + 1
  IF FIELDC GT 100
     FIELDB = 'Y'
     GOTO LABEL1
  ELSE
     FIELDB = 'N'
  END-IF
LABEL1.
END-PROC.

In General, PEngiEZT will flag all improperly coded Labels inside the DO/IF(s). A good practice is to run the translator to get errors first and then fix them.

External Table Record Length

Easytrieve retrieves record size dynamically during the run time. COBOL does not. It is essential to have the correct file record length in the converted COBOL program.

Refer to the "External Table Coding Conventions" for syntax rules.

JCL for Converted Program

PEngiEZT can generate sample JCL for running the program.

To generate JCL, existing JCL can be optionally included in front of the program and JCL=YES can be specified on the Proc EXEC statement. (refer to the "Translating Guidelines").

PEngiEZT generates an Instream sample Proc by merging the existing JCL to any new JCL needed by the generated COBOL program. Statements that are not needed are bypassed.

The following rules are observed:

1. An Instream Proc is generated. A JOB statement and additional libraries must be added to the Proc.
2. All JCL for input and output files are included from the included JCL, if present, else a symbolic is generated with a dummy file name for each file. For concatenated input files, symbolic is used only for the 1st file. Other files are concatenated in the JCL.
3. Statements for Temporary and Sort Work files are also generated , however, the Proc must be changed to include proper allocation.
4. Temporary and Sort Work files are not transferred from the included JCL.
5. System related files such as SYSPRINT, SYSDUMP, SYSOUT, etc. are also generated.
6. The Proc is created on the FJSYSJC file as defined in the translator JCL.

PROGRAM CHECK S07 INTENTIONALLY CAUSED

This message is issued by the FSABECOB module. FSABECOB is the abend handler called from your COBOL program. All I/O errors are trapped by the FSABECOB module.

The problem is with one of your files when an OPEN/CLOSE or when an I/O is attempted.

Look at FJSYABE, SYSOUT and Console messages. FILE-STATUS is included in the messages.

FJSYABE contains additional information such as DDname and the description of the error as described in the COBOL-II/S390 Reference Manual.

The most frequent errors are:

• Wrong record length
• wrong key definition for KSDS files
• out of sequence I/O request
• inconsistent file definition defined in JCL

Solution Hints:

• Make sure that all file definitions in your Easytrieve Plus program are correct. Make adjustments, re-generate the program and try again.
• If a problem is with a temporary or sort work file generated by the translator, make sure that the file definitions in JCL match those in the COBOL program.

S07 DATA EXCEPTION

Possible Causes:

• Uninitialized Working Storage Fields
• Bad data on input files
• Overflow caused by arithmetic
• Bad IF statement (fell thru undesired logic)
• An Easytrieve Plus MOVE was translated improperly

FSVLNT90 - INCORRECT S/390 LE COMPILER VERSION

Note: This error applies to variable length files only.

The generated COBOL was compiled with an incorrect COBOL Compiler.

The FIB (File Information Block) could not be located by FSVLNT90.

Solution Hints:

Check PEngiEZT translator options located in EZPARAMS file.

• COBOL=COBOLII requires COBOL-II compiler and run time library.
• COBOL=COBO390 requires S390 LE compiler and run time library.

Program Loops

This is a very uncommon problem, but it can occur.

Program loops can be caused by improper "IF" statements, i.e., The "IF" statements of very complex nature that were not adequately translated by PEngiEZT, including dependencies on field data types that are handled differently by COBOL.

Solution Hints:

• Suspicious IF statements should be simplified in Easytrieve Plus program.
• Check for suspicious MOVEs into fields which are used in the IF.

Output COBOL Files do not match Easytrieve produced Files

Possible Causes:

• Sign of numeric fields, C vs F (see "Sign of Numeric Fields" in PEngiEZT Reference manual).
• Field Overflow ocured in arithmetic (COBOL handles overflow differently from Easytrieve Plus).
• A "MOVE" in Easytrieve Plus was coded into a numeric field using incompatible data.
• Uninitialized working storage.
• Translated Easytrieve program does not match Easytrieve program used for testing.
• Input files used by COBOL version do not match those used by Easytrieve Plus. (careful, using input files that are continuously updated will always yield differences).