File Handler and Sort APIs

This chapter shows you how to make explicit calls to the File Handler and the Sort Module from your program.

In this Chapter

Calling the File Handler

You can call the File Handler to perform common actions such as opening a file and reading a record in an efficient and consistent way.

Overview

You can make explicit calls to the Callable File Handler from your program using the following syntax:

call "EXTFH" using opcode fcd

where the parameters are:

Parameter Description
"EXTFH" The module name of the File Handler interface.
opcode A File Handler operation code. See the section Operation Codes below.
fcd The data area, known as the FCD (File Control Description) which is used by the File Handler to hold details of the file being accessed. See the section Data Structures below.

Before the first call, you must follow these steps:

  1. Allocate data areas for the File Control Description (FCD), the record area, the filename area and the key definition block (if the file is indexed)
  2. Initialize all the data areas to binary zeros to ensure that the File Handler does not receive invalid values
  3. Set the pointers in the FCD to point to the:

You must then follow these steps for each File Handler operation:

  1. Fill in the appropriate fields in the FCD for the selected operation code
  2. Call the File Handler
  3. Determine the success of the file I/O operation by checking the file status
  4. Process the FCD fields and/or any data in the record area

Data Structures

The File Handler uses four data structures during file I/O operations:

Data Structure Description
File Control Description (FCD) A 100-byte data area containing information about the file in use.
Record area A data area into which records are read and from which records are written.
Filename area A data area which contains the name of the file in use, as recognized by the operating system.
Key definition block Used by the File Handler to hold index key information during operations on indexed files.

File Control Description (FCD)

The File Control Description (FCD) is a data area which contains information about the file in use.There are two versions of the FCD, and which one is used depends on whether your COBOL development system runs on a 32-bit or 64-bit operating system, as shown in the following table:

COBOL Development System FCD Used
Mainframe Express FCD2
32-bit Net Express FCD2
64-bit Net Express FCD3
.NET Support and Net Express with .NET FCD3
32-bit Server Express FCD2 or FCD3
64-bit Server Express FCD3

Both FCD2 and FCD3 format can be used in 32-bit compilations. The copyfile XFHFCD.CPY defines an FCD3 record if the program is compiled with the Compiler directive P64. If the program is not compiled with the P64 directive XFHFCD.CPY defines an FCD2 record. The FCD3 record is directly and unconditionally defined in the file xfhfcd3.cpy and the FCD2 record is directly and unconditionally defined in the file xfhfcd2.cpy.

To use the File Handler your program must set up an FCD, complete the appropriate fields (these vary according to the operation code) and then call the File Handler. The File Handler returns information to your program by writing it to the appropriate fields in the FCD.

All unused or reserved areas of the FCD must be set to binary zeros.

The FCD used on the call to open a file must be the one used on all subsequent accesses to that file. You can perform multiple open operations on a file but you must use a different FCD for each open.

The FCD includes pointers (that is, USAGE POINTER data items) which point to the record area, filename area and key definition block.

The FCD structure is detailed in the topic File Control Description (FCD).

Record Area

The record area is a data area into which records are read, and from which records are written.

The size of the record area must be four bytes larger than the largest record in the file.

The following example shows how the FCD is set up to point to the record area:

 01 RECORD-AREA      PIC X(85).
   ...
     SET FCD-RECORD-ADDRESS TO ADDRESS OF RECORD-AREA
       ...

Filename Area

The filename area is a data area which contains the name of the file in use, as recognized by the operating system.

It can contain drive and/or path information as well as the actual name of the file. The name must be terminated by a space.

This filename area must be filled before the first operation on the file.

The following example shows how the FCD is set up to point to the filename area:

 01 FILENAME-AREA    PIC X(65) VALUE "master.dat".
   ...
     MOVE 65 TO FCD-NAME-LENGTH
     SET FCD-FILENAME-ADDRESS TO ADDRESS OF FILENAME-AREA
       ...

Key Definition Block

The key definition block is used to pass index key information to the File Handler when opening an indexed file. It consists of three data areas:

Global Information Area

The size of the key definition area and the number of keys that are in the file are held in the global information area. The layout is detailed in the topic Global Information Area.

Key Definition Area

The key definition area describes the keys used in the indexed file.

The key definition area follows the global information area and contains one key definition for each key in the file.

You must define all keys before their components.

The order in which keys are defined is important as the ordinal position of the key is used to identify it. For example, if you have an indexed file with a prime key and two alternate keys, the Key Definition area contains three key definitions: the prime key is key 0, the first alternate is key 1, and the second alternate is key 2.

The layout of the key definition area is detailed in the topic Key Definition Area.

Component Definition Area

The component definition area follows the key definition area.

It contains a definition for each key component. Each key consists of one component, unless defined as a split key, when each component of the key requires its own component definition.

The component definitions define the position and length of the key component.

For numeric keys, you can use the component definition Area to specify the numeric type. You can then use the IXNUMKEY Compiler directive to specify that keys are ordered according to numeric type (the default situation is that keys are ordered according to their alphanumeric value).

The layout of the component definition area is detailed in the topic Component Definition Area.

Accessing the FCD

When file I/O operations are performed by your program, using ordinary COBOL syntax, a File Control Description (FCD) is created automatically for each file. You can access this automatically created FCD by compiling your program with the FCDREG Compiler directive. This enables you to read or change the FCD or to use it to make explicit calls to the File Handler.

To access the FCD, you must set up an FCD definition in the Linkage Section of your program. An example FCD definition is supplied in the copybook XFHFCD.CPY. This definition can be mapped onto the FCD you need to read or alter using the following SET statement in your program:

     set address of fcd to address of fh--fcd of file

where the parameters are:

Parameter Description
fcd The name of the FCD definition in the Linkage Section of your program
fh--fcd The FCD used by this COBOL system to access the file (note the double hyphen)
file The FD name of the file

Following this SET operation, you can access the file's FCD by accessing the data items in the FCD which you set up in your Linkage Section.

Similarly, you can access the key definition block as follows:

     set address of kdb to address of fh--keydef of file

where the parameters are:

Parameter Description
kdb The name of the key definition block in the Linkage Section of your program
fh--keydef The key definition used by this COBOL system to access the file (note the double hyphen)
file The FD name of the file

Operation Codes

Each file operation which can be performed by the File Handler is identified by a two-byte operation code.

There are two types of operation code:

Type of Operation Code Description
Standard operation codes The codes contain x"FA" in the most significant byte. The least significant byte indicates the specific operation.
Special operation codes The codes contain x"00" in the most significant byte. The least significant byte indicates the specific operation.

Full lists of standard and special operation codes and links to detailed information are provided in the topics Standard Operation Codes - Overview and Special Operation Codes - Overview.

Relative Byte Addressing

The relative byte address of a record is placed in fcd-reladdr-offset in the FCD (or fcd-reladdr-big if bit 4 of fcd-config-flags is set) by all File Handler operations that involve specific records. To use the relative byte address of a record, simply save the contents of this field after a READ operation.

Using the relative byte address is a fast method of accessing records, but has limitations of which you should be aware:

Record locking is supported with relative byte address operations.

Once you have obtained the relative byte address of a record, you can use it to perform the following operations:

Read a Record

You can read a specific record from a file in two ways using the relative byte address:

The READ (direct) operations work in the same way, but do not require the bits in the FCD to be set. The READ (direct) operations always return the record at the address given in the relative byte address field of the FCD and update the current record pointer.

Both of the above methods provide a way of switching the current key-of-reference to a different key. For example, if READ (sequential) operations are performed via the prime key, you can start reading via the first alternate key from the current record using the following steps:

  1. Read the next record in the file (the address of this record is in the FCD relative byte address field)
  2. Put the new key-of-reference in fcd-key-id in the FCD
  3. Perform a READ (direct) operation to return the record at this address. The key-of-reference is changed to the new one
  4. Read the next record in the file. This is the next record in the new key-of-reference index

Rewrite a Record

You can rewrite a record to a specific address by putting that address in fcd-reladdr-offset or fcd-reladdr-big in the FCD and setting bit 6 of fcd-config-flags in the FCD.

If you need to update the current record pointer, set bit 5 of fcd-config-flags in the FCD.

You then perform a REWRITE operation.

Delete a Record

You can delete a record at a specific address by putting that address in fcd-reladdr-offset or fcd-reladdr-big in the FCD and setting bit 6 of fcd-config-flags in the FCD.

You then perform a DELETE operation.

Creating Your Own File Handler

You can create your own, customised, file handler and use this in place of the File Handler supplied with your COBOL system.

To force programs to use your file handler for processing COBOL I/O syntax, use the CALLFH Compiler directive. For example, if you have a file handler called USERFH, compile your programs with the directive:

CALLFH"USERFH"

This causes all COBOL I/O operations to be compiled into calls to USERFH.

Note: If you use CBL_EXIT_PROC, you must set the priority to 200, so that when the application calling your file handler terminates, your file handler shuts down properly.

Creating a New Index File

You can use special operation codes to recreate an index file from the data file part of an existing indexed file as follows:

  1. Create the new index file using CREATE INDEX FILE (special operation code x"07")
  2. Read each record from the data file using GET NEXT RECORD (special operation code x"08")
  3. For each key value in the record, add the key value to the index file using ADD KEY VALUE (special operation code x"09")

The following example shows you how to create a new index file from an existing data file:

 78 close-file                  value x"fa80"
 78 open-new-index              value x"0007".
 78 get-next-rec                value x"0008".
 78 add-key-value               value x"0009".
   ...
     move open-new-index to fh-opcode
     perform extfh-op
     move get-next-rec to fh-opcode
     perform extfh-op
     perform until fcd-status (1:1) not = "0"
         perform varying fcd-key-id from 0 by 1
                   until fcd-key-id = key-count 
                      or fcd-status (1:1) not = "0"  
             move add-key-value to fh-opcode
             perform extfh-op
         end-perform
         move get-next-rec to fh-opcode
         perform extfh-op
     end-perform
     move close-file to fh-opcode
     perform extfh-op
     ...
 extfh-op.
     call "EXTFH" using fh-opcode, fcd
     if fcd-status of fcd (1:1) = "1"
         move 1 to return-code
     end-if.

Compression Routines

You can call the compression routines that the File Handler uses to compress data and keys in your own applications. For full details see the section Compression Routines in the chapter Data and Key Compression.

Sort Module

The Sort Module is a standalone sort module that enables you to sort and merge data files. It is invoked implicitly when your COBOL program uses the SORT or MERGE statements.

When you perform a SORT operation on a data file, any records with duplicate keys are returned in their original order, regardless of whether or not the DUPLICATES IN ORDER phrase was specified on the SORT statement.

To call the Callable Sort Module explicitly to sort or merge your files, include the following call statement in your program:

call "EXTSM" using function-code, sort-fcd

where the parameters are:

Parameter Description
function-code A two-byte code indicating the type of operation to be performed. For more information see the topic Sort Module Function Codes.
sort-fcd The name of the Sort File Control Description (FCD) as specified in the Data Division of your program. The FCD contains pointers to the record area, filename, collating sequence, key definition block and file definition block for the file. You need to specify, in the Data Division of your program, a Sort FCD for each file involved in the SORT operation. For more information see the topic Sort File Control Description.

For more information including a full list of function codes and a detailed description of the Sort FCD see the topics under

.