Using Externally Described Disk Files - IBM - RPG

Externally described DISK files are identified by an E in position 22 of the file description specifications. The E indicates that the compiler is to retrieve the external description of the file from the system when the program is compiled. Therefore, you must create the file before the program is compiled.

The external description for a DISK file includes:

  • The record-format specifications that contain a description of the fields in a record
  • Access path specifications that describe how the records are to be retrieved.

These specifications result from the DDS for the file and the OS/400 create file command that is used for the file.

Record Format Specifications
The record-format specifications allow you to describe the fields in a record and the location of the fields in a record. The fields are located in the record in the order specified in the DDS. The field description generally includes the field name, the field type, and the field length (including the number of decimal positions in a numeric field). Instead of specifying the field attributes in the record format for a physical or logical file, you can define them in a field-reference file.

In addition, the DDS keywords can be used to:

  • Specify that duplicate key values are not allowed for the file (UNIQUE)
  • Specify a text description for a record format or a field (TEXT).

This shows an example of the DDS for a database file, and Figure for a field-reference file that defines the attributes for the fields used in the database file. See the above Web site for more information on field-reference files.

Access Path
The description of an externally described file contains the access path that describes how records are to be retrieved from the file. Records can be retrieved based on an arrival sequence (non-keyed) access path or on a keyed-sequence access path.

The arrival sequence access path is based on the order in which the records are stored in the file. Records are added to the file one after another.

For the keyed-sequence access path, the sequence of records in the file is based on the contents of the key field that is defined in the DDS for the file. For example, in the DDS shown in Figure CUST is defined as the key field. The keyed-sequence access path is updated whenever records are added, deleted, or when the contents of a key field change.

Example of the Data Description Specifications for a Database File
Example of the Data Description Specifications for a Database File

The sample DDS are for the customer master logical file CUSMSTL. The file contains one record format CUSREC (customer master record). The data for this file is contained in the physical file CUSMSTP, which is identified by the keyword PFILE. The UNIQUE keyword is used to indicate that duplicate key values are not allowed for this file. The CUST field is identified by a K in position 17 of the last line as the key field for this record format.

The fields in this record format are listed in the order they are to appear in the record. The attributes for the fields are obtained from the physical file CUSMSTP. The physical file, in turn, refers to a field-reference file to obtain the attributes for the fields. The field-reference file is shown below.

Example of a field Reference File
Example of a field Reference File

This example of a field-reference file shows the definitions of the fields that are used by the CUSMSTL (customer master logical) file as shown in Figure. The field- reference file normally contains the definitions of fields that are used by other files. The following text describes some of the entries for this field-reference file.

  1. The BASDAT field is edited by the Y edit code, as indicated by the keyword EDTCDE(Y). If this field is used in an externally described output file for an ILE RPG program, the edit code used is the one specified in this field-reference file; it cannot be overridden in the ILE RPG program. If the field is used in a program-described output file for an ILE RPG program, an edit code must be specified for the field in the output specifications.
  2. The CHECK(MF) entry specifies that the field is a mandatory fill field when it is entered from a display work station. Mandatory fill means that all characters for the field must be entered from the display work station.
  3. The ADDR and CITY fields share the same attributes that are specified for the NAME field, as indicated by the REFFLD keyword.
  4. The RANGE keyword, which is specified for the CUSTYP field, ensures that the only valid numbers that can be entered into this field from a display work station are 1 through 5.
  5. The COLHDG keyword provides a column head for the field if it is used by the Interactive Database Utilities (IDU).
  6. The ARBAL field is edited by the J edit code, as indicated by the keyword EDTCDE(J).
  7. A text description (TEXT keyword) is provided for some fields. The TEXT keyword is used for documentation purposes and appears in various listings.

Valid Keys for a Record or File
For a keyed-sequence access path, you can define one or more fields in the DDS to be used as the key fields for a record format. All record types in a file do not have to have the same key fields. For example, an order header record can have the ORDER field defined as the key field, and the order detail records can have the ORDER and LINE fields defined as the key fields.

The key for a file is determined by the valid keys for the record types in that file. The file’s key is determined in the following manner:

  • If all record types in a file have the same number of key fields defined in the DDS that are identical in attributes, the key for the file consists of all fields in the key for the record types. (The corresponding fields do not have to have the same name.) For example, if the file has three record types and the key for each record type consists of fields A, B, and C, the file’s key consists of fields A, B, and C. That is, the file’s key is the same as the records’ key.
  • If all record types in the file do not have the same key fields, the key for the file consists of the key fields common to all record types. For example, a file has three record types and the key fields are defined as follows:
    – REC1 contains key field A.
    – REC2 contains key fields A and B.
    – REC3 contains key fields A, B, and C.
  • The file’s key is field A–the key field common to all record types.

  • If no key field is common to all record types, there is no key for the file.

In an ILE RPG program, you can specify a search argument on certain file operation codes to identify the record you want to process. The ILE RPG program compares the search argument with the key of the file or record, and processes the specified operation on the record whose key matches the search argument.

Valid Search Arguments
You can specify a search argument in the ILE RPG operations CHAIN, DELETE, READE, READPE, SETGT, and SETLL that specify a file name or a record name.

For an operation to a file name, the maximum number of fields that you can specify in a search argument is equal to the total number of key fields valid for the file’s key. For example, if all record types in a file do not contain all of the same key fields, you can use a key list (KLIST) to specify a search argument that is composed only of the number of fields common to all record types in the file. If a file contains three record types, the key fields are defined as follows:

  • REC1 contains key field A.
  • REC2 contains key fields A and B.
  • REC3 contains key fields A, B, and C.

The search argument can only be a single field with attributes identical to field A because field A is the only key field common to all record types. The search argument cannot contain a floating point or null-capable field.

For an operation to a record name, the maximum number of fields that you can specify in a search argument is equal to the total number of key fields valid for that record type.

If the search argument consists of one or more fields, you can specify a KLIST, a figurative constant, and in free-form calculations only, a list of expressions (enclosed by parentheses) or a %KDS. If the search argument consists of only one field, in addition to the above, you can also specify a literal or variable name.

To process null-valued keys, you can:

  • code the search argument using KLIST, in which case the null indicator can be specified in Factor 2 of the KFLD opcode
  • code a null-capable field as the search argument in a list (enclosed by parentheses)
  • code a null-capable field in the data structure specified in %KDS

For the latter two, the current value of the %NULLIND() for the search argument is used in the search.

The attributes of each field in the search argument must be identical to the attributes of the corresponding field in the file or record key. The attributes include the length, the data type and the number of decimal positions. The attributes are listed in the key-field-information data table of the compiler listing. See the example in “Key Field Information”. For search arguments in a list or %KDS used in an I/O operation in free-form calculations, the search argument only needs to match in type. Length and format may be different than the key defined in the file.

In all these file operations (CHAIN, DELETE, READE, READPE, SETGT, and SETLL), you can also specify a search argument that contains fewer than the total number of fields valid for the file or record. Such a search argument refers to a partial key.

Referring to a Partial Key
To specify a partial key, you can use a KLIST with fewer KFLD specifications. In free-form calculations, you can also use %KDS with a second parameter indicating the number of keys, or a list of expressions with as many keys as you want. For example, if the file has three keys, but you only want to specify two keys, you can specify the partial key in any of the following ways.

Referring to a Partial Key

Referring to a Partial Key

The rules for the specification of a search argument that refers to a partial key are as follows:

  • The search argument is composed of fields that correspond to the leftmost (high-order) fields of the key for the file or record.
  • Only the rightmost fields can be omitted from the list of keys for a search argument that refers to a partial key. For example, if the total key for a file or record is composed of key fields A, B, and C, the valid search arguments that refer to a partial key are field A, and fields A and B.
  • Each field in the search argument must be identical in attributes to the corresponding key field in the file or record. For search arguments in a list or %KDS used in an I/O operation in free-form calculations, the search argument only needs to match in type. Length and format may be different than the key defined in the file. The attributes include the length, data type, the number of decimal positions, and format (for example, packed or zoned).
  • A search argument cannot refer to a portion of a key field.

If a search argument refers to a partial key, the file is positioned at the first record that satisfies the search argument or the record retrieved is the first record that satisfies the search argument. For example, the SETGT and SETLL operations position the file at the first record on the access path that satisfies the operation and the search argument. The CHAIN operation retrieves the first record on the access path that satisfies the search argument. The DELETE operation deletes the first record on the access path that satisfies the search argument. The READE operation retrieves the next record if the portion of the key of that record (or the record of the specified type) on the access path matches the search argument. The READPE operation retrieves the prior record if the portion of the key of that record (or the record of the specified type) on the access path matches the search argument.

Record Blocking and Unblocking
By default, the RPG compiler unblocks input records and blocks output records to improve run-time performance in SEQ or DISK files when the following conditions are met:

  1. The file is program-described or, if externally described, it has only one record format.
  2. The keyword RECNO is not used in the file-description specification.
  3. Note: If RECNO is used, the ILE RPG compiler will not allow record blocking. However, if the file is an input file and RECNO is used, Data Management may still block records if fast sequential access is set. This means that updated records might not be seen right away.

  4. One of the following is true:
    a. The file is an output file.
    b. If the file is a combined file, then it is an array or table file.
    c. The file is an input-only file; it is not a record-address file or processed by a record-address file; and uses only the OPEN, CLOSE FEOD, and READ file operations. (In other words, the following file operations are not allowed: READE, READPE, SETGT, SETLL, and CHAIN.)

The RPG compiler generates object program code to block and unblock records for all SEQ or DISK files that satisfy the above conditions. Certain OS/400 system restrictions may prevent blocking and unblocking. In those cases, performance is not improved.

You can explicitly request record blocking by specifying the keyword BLOCK(*YES) on the file-description specification for the file. The only difference between the default record blocking and user-requested record blocking is that when BLOCK(*YES) is specified for input files, then the operations SETLL, SETGT and CHAIN can be used with the input file and blocking will still occur. If the BLOCK keyword is not specified and these operations are used, no record blocking will occur.

You can also prevent the default blocking of records by specifying the keyword BLOCK(*NO) on the file-description specification. If BLOCK(*NO) is specified, then no record blocking is done by the compiler, nor by data management. If the keyword BLOCK is not specified, then default blocking occurs as described above.

The input/output and device-specific feedback of the file information data structure are not updated after each read or write (except for the RRN and Key information on block reads) for files in which the records are blocked and unblocked by the RPG compiler. The feedback area is updated each time a block of records is transferred.

You can obtain valid updated feedback information by preventing the file from being blocked and unblocked. Use one of the following ways to prevent blocking:

    • Specify BLOCK(*NO) on the file description specification.
    • At run time, use the CL command OVRDBF (Override with Database File) with SEQONLY(*NO) specified.

All rights reserved © 2018 Wisdom IT Services India Pvt. Ltd DMCA.com Protection Status

IBM - RPG Topics