Easytrieve: The LIBRARY Section

As previously stated, all files used by the module and all variables local to the module must be defined in this section.. It is not possible to define variables within the JOB section.

File Definitions

Input and output files are declared in the same manner, it is not necessary to define a file as input or output, this is handled by the DISP parameter of the file in the JCL.

Files are identified by the keyword FILE followed by the DD name from the JCL.

Field Definitions

There is no keyword identifier for field definitions, they are defined by their position (following a previous FILE statement).

The basic field definition statement for a file is structured like this:-

field-name start-location field-length data-type [decimal-positions]

Field-name is the name by which the field will be known in the module, this must be unique within a file (although it may be repeated in a different file definition).  It’s format is 1-40 bytes alphanumeric.

Start-location represents the number of bytes from the beginning of the file record where the  field starts.

Field-length is the length of the field (in bytes).

Data-type contains the format of the data as it is held on the file, the available data types are as follows:-

IDENTIFIER	TYPE	MAX. BYTES
A	Alphanumeric	32,767
B	Binary	4
N	Numeric	18
P	Packed Decimal	10
U	Unsigned Packed Decimal	9

All numeric fields can have a number of decimal places defined from 0 (zero) up to the size of the field.

This means that a field defined as 5 N 2 will allow 3 integer digits and 2 decimal places, thus numbers up to 999.99 may be represented.  A definition of 5 N 5 will hold only decimal fractions.

When decimal places are defined, they are regarded as ‘virtual’ decimals, i.e. looking at the output representation of the digit will not show the decimal point, a knowledge of the field layout is required to be able to assess the actual value represented.

To allow the sign of a number to be stored along with the value, the definition must indicate that at least 0 (zero) decimal places are allowed.  So to define a numeric field as integer but with a sign, the definition must be 5 N 0.

It should be noted that Binary, Packed and Unsigned Packed values contain 2 digits for each byte defined.

The following shows a file definition with examples of the fields defined:-

002200 FILE  OTFILE                                                        

002210   OT-RCD                   1  14   A                                

002300   OT-DUNS                  1   4   B                                

002320   OT-OOB-IND               7   1   A                                

002330   OT-RPT-TYP               8   1   A                                

002350   OT-LAST-UPD-DATE         9   6   N                                 

Note that it is not necessary to define all of the fields in a file.  Particularly when using the file for input, it is often more useful to define only those fields which will be used as this will aid the clarity of the code.

Working Storage Definitions

The other type of fields which are required in the Library section are those fields which are not on input or output files, but which are required for processing of the data within an EasyTrieve module.  These are termed as working storage fields.  Their definition is similar to that of fields within files and is laid out below:-

field-name W field-length data-type [decimal-positions] [ MASK ( [letter] [BWZ] [‘literal’] ) ]

Most of the definitions are the same with the exception of the W replacing the start-field identifier and the addition of the MASK identifier.

Numeric Field Masks

The MASK identifier allows the contents of a numeric field to be formatted for output.  This is particularly useful when data is being presented to the user, either at the end of a module to display record counts or during the course of debugging code.

The letter identifier allows the mask which has been defined to be reused by entering a MASK letter parameter after a normal field identifier.

The BWZ parameter prevents the field from printing at all when the value contained in the field is 0 (zero).

The literal parameter gives the format in which the field is to be displayed.  Every byte in the field must be accounted for in the mask literal although non-formatting characters may be interspersed with the individual bytes of the field.  The most usual formatting characters are shown below.

MASK CHARACTER	FORMATTING
9	Formats a digit
Z	Suppresses leading zeros
-	Displays a ‘-’ sign in front of the leading non-zero digit if the field is negative

The following gives examples of how the mask is used:

VALUE OF FIELD	MASK	RESULT
012345	’ZZZ,ZZ9’	12,345
-2750	’---,--9’	-2,750
12345	’999,999’	012,345

Field Redefintions

The final part of the Library section covers field redefinition.  It is often required that fields within files and working storage fields are broken down into finer detail.

A good example of this is when performing date processing, where a 6 byte date field (in the format DDMMYY), is required in a calculation, for example to see if the date is before 1995.

There are two ways of getting to the YY information from the above field, one can be used only in a file definition, the other is more complicated but can be used in both file definitions and working storage definitions.

File Definitions

Fields in file definitions can be created so that they overlap and use the same byte(s) more than once.  This involves defining a field which wholly or partly overlaps one or more existing fields like this:-

FILE  OTFILE                       

    OT-RCD                   1  14   A

    OT-DUNS                  1   4   B

    OT-CTRY-CD               5   2   A

    OT-OOB-IND               7   1   A

    OT-RPT-TYP               8   1   A

    OT-LAST-UPD-DATE         9   6   N

      OT-LAST-UPD-DD         9   2   N

      OT-LAST-UPD-MM        11   2   N

      OT-LAST-UPD-YY        13   2   N

Working Storage Definitions

The redefinition of a field in working storage is a bit more difficult.  Because there is no file layout to refer to it is necessary to use the original working storage field as a base.  The redefinition for a working storage fields is shown below:-

W20-DATE-INFO                  W   6   N

    W20-DATE-DD    W20-DATE-INFO       2   N

    W20-DATE-MM    W20-DATE-INFO  +2   2   N

    W20-DATE-YY    W20-DATE-INFO  +4   2   N

Arrays

A major use of the EasyTrieve redefinition process is to produce arrays for later processing.

Arrays can exist in both file and working storage definitions, and are defined like the example below:-

W20-SICS                       W  24   A          

      W20-SIC           W20-SICS   4   A   OCCURS 6

From this it can be seen that a 24 byte field is redefined into six 4 byte fields.  Each of the elements of the array can now be accessed by using the command W20-SIC( I ) where I is an integer value between 1 and 6.