This chapter shows you how to make explicit calls to the File Handler and the Sort Module from your program.
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.
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:
You must then follow these steps for each File Handler operation:
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. |
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).
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 ...
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 ...
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:
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.
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.
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.
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 |
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.
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:
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:
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.
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.
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.
You can use special operation codes to recreate an index file from the data file part of an existing indexed file as follows:
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.
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.
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
.