Chapter 16: File Structures

This chapter explains the structure of data files in some depth.

Overview

This information is provided for anyone who wants to understand the structure of COBOL files. It can also be useful for debugging programs. However, you do not need to understand these file structures to use data files from COBOL programs.

This COBOL system provides three types of data file organization: relative, indexed and sequential. Additionally, sequential files fall into one of three categories: record sequential, printer sequential and line sequential.

Caution: You are advised not to process the files yourself using byte-stream I/O, but to use COBOL syntax or the Micro Focus File Handler API. This ensures that applications will function properly if file structures are enhanced or developed in the future.

Files without Headers

Line sequential files, printer sequential files, record sequential files with fixed length records and relative files with fixed length records contain neither file nor record headers.

Line Sequential

Line sequential files are designed to enable you to read source or text files created with the system editor. As such, the structure is operating system dependent but typically contains variable length records with trailing spaces removed.

In a line sequential file, each record in the file is separated from the next by a record delimiter.

Figure 16-1: Line Sequential Structure

For files created on UNIX systems the default record delimiter is the Line Feed character specified by the single byte x"OA". For files created on DOS or Windows the default record delimiter is the carriage return/line feed character specified by the byte pair x"ODA". Files created using this COBOL system on UNIX can be read on DOS and Windows, and vice versa.

If you set the INSERTNULL configuration parameter to OFF, you must make sure that any COMP data does not contain bytes with a value of x"0A" (record delimiter).

Printer Sequential

Printer sequential is the structure of files that are destined for a printer, either directly or by spooling to a disk file. The structure of these files reflects what is required to drive a printer and is independent of the operating system.

A printer sequential file consists of a sequence of print records with zero or more vertical positioning characters (such as line-feed) between print records.

A print record consists of zero or more printable characters and is terminated by a carriage return (x"0D").

Figure 16-2: Printer Sequential Structure

Record Sequential Files with Fixed Length Records

In record sequential files with fixed length records, each record immediately follows the previous record in the file and each record is the same length as the maximum length record.

Figure 16-3: Record Sequential File with Fixed Length Records

Relative Files with Fixed Length Records

A relative file with fixed length records is the same as a record sequential file with fixed length records, except that each record is followed by a record marker.

The current state of a record for fixed length relative records is indicated by a one-byte marker as follows:

Figure 16-4: Relative File with Fixed Length Records

Files with Headers

A file header is a block of 128 bytes at the start of the file. Indexed files, record sequential files with variable length records and relative files with variable length records all contain file headers. In addition, each record in these files is preceded by a 2 or 4 byte record header.

Note: The file header and record header information is maintained by this COBOL system and must not be altered in any way.

Standard File Header

The first record in every variable structure file is a system record called the file header. This is normally 128 bytes in length and takes the following form:

Standard Record Header

Each record in a variable structure file is preceded by a two- or four-byte record header. The first 4 bits of this indicate the status of the record, for example, a value of 0100 means that this record is a normal user data record.

The remainder of the record header contains the length of the record. For all files where the maximum record size is less than 4095 bytes (excluding the record header), the record header is 2 bytes long. For all other files, the record header is 4 bytes long.

The record header for each record starts at an address which is an exact multiple of the data alignment value for the file type (see the section Indexed Files for details of data alignment values). Consequently, a record may be followed by up to n padding characters, usually spaces. These padding characters are not included in the record length.

Record Sequential File with Variable Length Records

In a record sequential file with variable length records, each record written is preceded by a record header containing the length of the record.

Up to three padding characters can follow a record to ensure that the next record starts on a four-byte boundary.

The file contains a standard file header record.

Figure 16-5: Record Sequential File with Variable Length Records

Relative File with Variable Length Records

A relative file with variable length records follows the basic variable structure but each record is placed into a fixed length slot, the length of the slot being the length of the longest record defined, plus the header and terminator characters.

The record header for each record contains the length of the logical record written, not the length of the physical fixed length slot.

The current state of a record is indicated by a two-byte marker as follows:

Figure 16-6: Relative File with Variable Length Records

Indexed Files

An index file comprises:

• File header record

  The file header contains information about the file and points to the first free space record and the key information record.

• Free space records

  Free space records are used to maintain a list of free records in the index file and the data file.

• Key information record

  The key information record contains details of every key defined for the file, and, for each key, points to its root index node.

• Index node record

  For each key defined, a complete and independent index is constructed. It consists of a tree of index node records which contain actual key values. Every key value in a node points either to a subordinate index node record or to the actual data record associated with the key.

  The records in an index file are always the same length, whether they are index nodes, file header or key information records. The size of the records is determined at the time the file is created and cannot be changed subsequently.

Table 16-1 and Table 16-2 below illustrate the different types of indexed file available and the features that they support.

Index File - File Header

The file header is located at offset 0 within the index file. The first 128 bytes are the same as a standard variable structure file header, except for the fields below.

The remainder of the file header contains the following fields:

Index File - Free Space Record

The free space record points to the location of free records in the index file or data file (fixed length files only). Continuation records of the same size and structure are created as needed, each pointing to the next continuation record.

The first free space record is pointed to by the file header.

A free space record contains:

Note: The size of file-pointer-size varies according to the type of indexed file. See the section Indexed Files for details.

Index File - Key Information Record

The key information record describes the physical characteristics of all the keys used in the file, including the length of each key; where the key is defined within the data record; whether duplicates are permitted, and so on. Within the key information record structure is a substructure, the key block. A key block is created for each key defined. The first key block always describes the primary key. Subsequent key blocks define the alternate keys in the order specified when the file was created. If the key information record is not big enough to hold key blocks for all the keys defined, equal sized continuation records are created, each pointing to the next, until all the keys have been defined.

The key information record contains:

For every type of indexed file except IDXFORMAT"8", the key block contains:

For IDXFORMAT"8" files, the key block contains:

For every type of indexed file except IDXFORMAT"8", the key component block contains:

For IDXFORMAT"8" files, the key component block contains:

Index File - Index Node Record

For each key defined, a complete and independent index is constructed which consists of a tree of index node records. Each index node record contains actual key values associated with data records written to the indexed file. Every key value in a node points either to a subordinate index node record or, if it is a leaf node, to the data record associated with the key.

The top level node record is called the root.

The default node size is 1024 bytes, but can change depending on the largest key size defined for the file. If the largest key is greater than 238 bytes, the node size is 4096 bytes.

Note: It is possible to change the default node size by setting the XFHNODE environment variable to one of 512, 1024 (the default) or 4096 bytes. However, if you set XFHNODE to 512 and the largest key value is greater than 120 bytes, the value of XFHNODE will be overwritten by 1024. Also, if you set XFHNODE to 512 or 1024 and the largest key value is greater than 248, the value of XFHNODE will be overwritten by 4096. The setting of XFHNODE is only effective at the time that the file is created - you cannot alter the node size of an existing file.

The index node record contains:

The key value block contains:

Indexed File - Data File Structure

The data file part of an indexed file contains all the data records.

Information about free records in the data file is maintained so that space created by deleting records can be re-used, preventing the file from growing too quickly.

In a fixed format indexed file, this information is held in a free space record in the index file. This record has the same structure as the index free space record, but the addresses point to data file records.

In a variable format indexed file, the information is held in a system record in the data file. All records are a multiple of the data record alignment size. For each slot length, a chain is maintained for all slots of that length that are free. The start of the chain for all lengths is maintained in the data free space record in the data file. This system record is always the same length as the maximum slot length or possible maximum compressed length (a record's length may increase when it is compressed) for the file. Each free slot pointed to contains, in the first n bytes after the record header, the address of the next free slot of the same length. For the last slot in the chain, this address contains zero.

The data free space record contains:

Multiple-reel File Header Record

Multiple-reel files have a block of header information that is 256 bytes long. This header occupies the first 256 bytes of each reel and contains information that describes the reel. It also contains 44 bytes which are reserved; you cannot alter this reserved space.

A multiple reel file header has the following structure:

Copyright © 2003 Micro Focus International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.