|Issues and Solutions|
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
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
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.
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.
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
Example of index usage
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:
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
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.
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.
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
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
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
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'
FIELDB = 'N'
Before translating, the routine should be converted to something like this:
FIELDB = 'N'
IF FIELDA = 'Y'
DO WHILE FIELDB EQ 'N'
* THIS PROC MUST BE INSERTED OUTSIDE OF THE CURRENT JOB MAIN BODY.
* END OF CURRENT JOB STATEMENT BUT BEFORE FIRST REPORT WOULD DO.
FIELDC = FIELDC + 1
IF FIELDC GT 100
FIELDB = 'Y'
FIELDB = 'N'
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:
- An Instream Proc is generated. A JOB statement and additional libraries must be added to the Proc.
- 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.
- Statements for Temporary and Sort Work files are also generated , however, the Proc must be changed to include proper allocation.
- Temporary and Sort Work files are not transferred from the included JCL.
- System related files such as SYSPRINT, SYSDUMP, SYSOUT, etc. are also generated.
- 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
- 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
- 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.
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.
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.
- 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
- 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).