Callable File Handler Call Interface [ Micro Focus COBOL System Reference, Volume 1 ] MPE/iX 5.0 Documentation
Micro Focus COBOL System Reference, Volume 1
Callable File Handler Call Interface
If you want to call the Callable File Handler yourself, rather than using
COBOL syntax to handle your files, you need to create a definition for
each file in your Data Division, and use a call for each operation.
The file definition consists of a File Control Description (FCD), a
file-name area, where the name recognized by the operating system is
held, a record area, and, for indexed files, a key definition block.
These are described below.
The operations that the file handler can perform are defined by the
action code. For each COBOL I/O operation there is an equivalent action
code to pass to the file handler. In addition, the file handler has some
special functions which cannot be performed using COBOL syntax.
The Callable File Handler is invoked using a simple call with two
parameters:
call "EXTFH" using action-code, fcd
where:
EXTFH is the file handler. You can use the name of your
own file handler here.
action-code is a 2-byte COMP-X data item which describes the
action you want the file handler to take. The first
byte contains x"FA" for those operations
corresponding to normal COBOL I/O verbs. It can
contain other values for certain special-purpose
functions. The second byte depends on the operation.
See the section Action Codes for further details.
fcd is the File Control Description for the required
file. The FCD points to the file name area, the
record area, and, for indexed files, to the key
definition block. See the section File Control
Description for further details.
Step Operations (DOS, Windows and OS/2 only)
STEP operations are a method of sequentially retrieving the data in a
record file under DOS, Windows and OS/2 without having to read via a key
or relative record number. This is, generally, a faster method of
accessing data in the file.
A Step Next operation returns the next record stored physically in the
file after the one that was last retrieved (either by a STEP or READ
operation).
If you are using relative byte addressing and you have specified that the
current record pointer should be updated to the record you have just
accessed, STEP operations are relative to this new position.
The relative address is returned on every STEP operation, so if you need
to update the current record pointer to the record just retrieved, you
can use the READ (direct) operation using the address returned.
NOTE The current record pointer is not affected by STEP operations.
Action Codes
Normal COBOL I/O operations are identified by x"FA" in the first byte of
the action code. The second byte indicates the operation, as shown in
the following table. The opcodes are in hexadecimal format.
File Types are abbreviated as:
L Line Sequential
S Record Sequential
R Relative
I Indexed
vS Variable format
Sequential
vR Variable format Relative
Op Code Description File Type
---------------------------------------------------------------------------------------------------
00 OPEN INPUT L S R I
01 OPEN OUTPUT L S R I
02 OPEN I/O L S R I
03 OPEN EXTEND L S R I
04 OPEN INPUT WITH NO L S
REWIND
05 OPEN OUTPUT WITH NO L S
REWIND
08 OPEN INPUT REVERSED L S
80 CLOSE L S R I
81 CLOSE WITH LOCK L S R I
82 CLOSE WITH NO REWIND L S
84 CLOSE REEL/UNIT L S
85 CLOSE REEL/UNIT FOR L S
REMOVAL
86 CLOSE REEL/UNIT WITH NO L S
REWIND
8D READ(sequential) WITH NO L S R I
LOCK
D8 READ (sequential) WITH L S R I
LOCK
D9 READ (sequential) WITH L S R I
KEPT LOCK
F5 READ (sequential) L S R I
8C READ PREVIOUS WITH NO R I
LOCK
DE READ PREVIOUS WITH LOCK R I
DF READ PREVIOUS WITH KEPT R I
LOCK
F9 READ PREVIOUS R I
8E READ (random) WITH NO R I
LOCK
DA READ (random) WITH LOCK R I
DB READ (random) WITH KEPT R I
LOCK
F6 READ (random) R I
8F READ (direct) WITH NO L S R I
LOCK
D6 READ (direct) WITH LOCK L S R I
D7 READ (direct) WITH KEPT L S R I
LOCK
C9 READ (direct) L S R I
F1 READ (position) L S R I
E1 WRITE BEFORE L S
E2 WRITE AFTER L S
E3 WRITE BEFORE TAB L S
E4 WRITE AFTER TAB L S
E5 WRITE BEFORE PAGE L S
E6 WRITE AFTER PAGE L S
F3 WRITE L S R I
F4 REWRITE L S R I
E8 START equal to full R I
length prime key
E9 START equal to (any R I
key/record number)
EA START greater than (>) R I
EB START with not less than R I
(>=)
FE START with less than (<) R I
FF START with less than or R I
equal to (<=)
90 STEP NEXT WITH NO LOCK L S R I
D4 STEP NEXT WITH LOCK L S R I
D5 STEP NEXT WITH KEPT LOCK L S R I
CA STEP NEXT L S R I
92 STEP FIRST WITH NO LOCK L S R I
D0 STEP FIRST WITH LOCK L S R I
D1 STEP FIRST WITH KEPT L S R I
LOCK
CC STEP FIRST L S R I
F7 DELETE vS R I
F8 DELETE file L S R I
0E UNLOCK L S R I
DC COMMIT (UNLOCKs all L S R I
files)
DD ROLLBACK (UNLOCKs all L S R I
files)
Special Action Codes
The file handler special operations are identified by the hexadecimal
code x"00" in the first byte of the action code. The second byte
contains the opcode as defined in the following table:
Op File Type Description
code
-------------------------------------------------
06 IvSvR Return file information
This code, actioned on an
indexed file before opening,
will cause key information for
that file to be returned in the
format of the Key Definition
Block (see below) together with
the maximum and minimum record
lengths in their respective fcd
fields, the file size at offset
72 of the FCD (normally used for
fcd-reladdr-offset), and the
data compression flag at offset
78 of the FCD. It is your
responsibility to ensure that
you have enough space allocated
for the key definition block to
hold all the information
returned. Failure to allocate
sufficient space will cause
corruption of some Data Division
areas.
This opcode also works on
variable length sequential files
and variable length relative
files, but in this case there is
no key definition information.
If the organization byte of the
FCD (fcd-organization) is set to
hex FF, this will try to
determine the file type and
return with the relevant
information set. This mode of
operation is not recommended if
fixed length sequential files
are involved as it may be
impossible to determine the
difference between the first
record of a fixed length
sequential file and the header
of a variable length sequential
file. When the file type is
determined as incompatible the
error code 9/161 is returned.
07 I Open new index
08 I Get next record
09 I Add key value
These three codes are used
together to allow the recreation
of an indexed file index,
without affecting the data file.
0F I Unlock record
This code uses the prime key to
locate and unlock a specific
record.
File Control Description
The File Control Description
(FCD) is a 100 byte area in the Data Division that describes the file.
The structure of the FCD is explained below. All fields within the FCD
are held in COBOL format. If, however, the calling program is a C
program, all fields should be CHAR type. All unused or reserved areas of
the FCD must be set to LOW-VALUES (binary zeros).
The FCD returned from the file handler on an OPEN call must be the one
used on all subsequent accesses to the file.
On DOS, Windows and OS/2 systems, the supplied COPY-file XFHFCD.CPY
contains a COBOL definition of the FCD. (DOS, Windows and OS/2)
Bit 7 is always the most significant (leftmost) bit.
Offset SizeDescription of the Field
0 2 User file status. Also see offsets 6 and
33.
After every operation except a COMMIT or
ROLLBACK operation, this field will be
updated with a standard file status value
telling you the status of the operation.
See your COBOL System Reference for
details of file status.
2 3 Reserved. Must contain binary zeros.
5 1 File organization.
0 - Line sequential
1 - Sequential
2 - Indexed
3 - Relative
6 1 Access Mode and User Status indicators.
Access mode is indicated by bits 6-0:
0 - Sequential access mode
4 - Random access mode
8 - Dynamic access mode
User Status is indicated by bit 7. The
bit is set if you have defined a file
status. Defining a file status can affect
how some operations (such as RETRYLOCK)
are performed.
Table 5-0. (cont.)
Offset SizeDescription of the Field
Note:
When calling the File Handler directly,
this bit should be set. However, file
status is obtained directly from offset 0.
7 1 Open mode:
0 - INPUT
1 - OUTPUT
2 - I/O
3 - EXTEND
128 - File is closed.
You must set this field to 128 before
opening a file.
8 3 Reserved. Must contain binary zeros.
11 2 Length of file-name.
13 9 Reserved. Must contain binary zeros.
22 1 Reserved. Must contain binary zeros.
23 1 Reserved. Must contain binary zeros.
24 1 Lock mode flags for shareable files:
Bit 7 = Lock on multiple records
Bit 6 = WRITELOCK directive enabled
Bit 5 = Reserved
Bit 4 = SKIPLOCK directive enabled
Bit 3 = RETRYLOCK directive enabled
Bit 2 = Lock mode MANUAL
Bit 1 = Lock mode AUTOMATIC
Bit 0 = Lock mode EXCLUSIVE
25 1 Other flags:
Bit 7 = OPTIONAL file (OPEN INPUT)
Bit 6 = Reserved
Bit 5 = Not Optional (OPEN I/O and EXTEND)
Bit 4 = File-name is EXTERNAL
Bit 3 = Reserved
Bit 2 = NODETECTLOCK directive enabled
Bit 1 = Multiple Reel file (Record
Sequential)
Bit 0 = Line Advancing file (Record
Sequential)
Table 5-0. (cont.)
Offset SizeDescription of the Field
26 2 Reserved. Must be set to binary zeros.
28 4 File handle.
32 1 Reserved. Must be set to binary zeros.
33 1 File status type. Also see offsets 0 and
6:
Bit 7 = set for ANSI'85 file status by
default, if not ANSI'74
Bits 6-3 = Reserved
Bit 2 = enables tab insertion for line
sequential files
Bit 1 = enables null insertion for line
sequential files
Bit 0 = Reserved
Bits 1 and 2 are set/unset at open time,
depending on the settings of the N and T
run-time switches. These bits can be
set/unset after an OPEN operation to
override the N and T run-time switches.
Bits 0-6 are reserved.
34 1 File format:
0 - Default format
1 - C-ISAM format
2 - LEVEL II format
3 - File format used by this COBOL system
4 - IDXFORMAT"4" format
DOS and OS/2 only:
5 - Btrieve format with ANSI emulation
6 - Btrieve format without ANSI emulation.
35 3 Reserved. Must be set to binary zeros.
38 2 Maximum record length (in bytes).
40 3 Reserved. Must be set to binary zeros.
43 4 Relative record number.
47 1 Recording mode:
Bits 7-1 = Reserved
Bit 0 = 0 - Fixed
1 - Variable.
Table 5-0. (cont.)
Offset SizeDescription of the Field
48 2 Current record length (in bytes).
50 2 Minimum record length (in bytes).
52 2 Key identifier or Key-of-Reference
(indexed files).
This field identifies the
Key-of-reference, used for random READ. To
specify the prime key, set this field to
zero. To specify the first alternate key
defined, use a value 1; second alternate
key defined uses value 2, and so on.
Or:
Line count (Line Sequential files)
This field specifies the number of lines
to skip when writing a file (for example,
WRITE AFTER ADVANCING line-count LINES).
54 2 Effective key length.
When using START on indexed files, it is
possible for you to specify only the
leading part of a key instead of the whole
key. You should set this field to the
number of bytes to be used in the START
comparison. It must be greater than zero,
and no bigger than the key being used.
56 4 Pointer to the record area. This and the
following pointers are USAGE POINTER
items, set using the COBOL syntax:
set pointer to address of data-item
where:
pointer is one of these fields
data-item is the relevant data area.
60 4 Pointer to the file-name area.
64 4 Pointer to key definition block.
68 4 Reserved. Must be set to binary zeros.
72 4 Relative Byte Address
76 2 Reserved. Must be set to binary zeros.
Table 5-0. (cont.)
Offset SizeDescription of the Field
78 1 Data compression routine indicator:
0 = no compression
1-127 = Micro Focus data compression
routine number (1=CBLDC001)
128-255 = User defined data compression
routine number
79 4 Fileshare 2 session-id
83 2 Fileshare 2 file-id
85 6 Reserved. Must be set to binary zeros.
91 1 Bit 7 = Interlanguage locking (LOCKTYPE 1)
Bits 6-0 = Reserved
92 1 Fileshare flags:
Bit 7 = Transaction logging
Bits 6-0 = Reserved
93 1 Configuration flags:
Bit 7 = WRITETHRU
Bit 6 = Use Relative Byte Address
Bit 5 = Update current record pointer
Bits 4-1 = Reserved
Bit 0 = Set if IGNORELOCK required
94 1 Reserved. Must be set to binary zeros.
95 1 Bit 7 = Use EBCDIC Collating Sequence
Bit 6 = Set if file is to have WRITE AFTER
ADVANCING
Bit 5 = Set if file is to have WRITE
BEFORE ADVANCING
Bit 4 = ADV byte
Bit 3 = Ignore minimum length checking on
variable length files
Bits 2-0 = Reserved
96 3 Reserved. Must be set to binary zeros.
99 1 Reserved for internal use.
Record Area
The record area is an area in the Data Division 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.
NOTE The record length fields in the FCD always contain true record
lengths, not the length of the record area. (See offsets 38, 48
and 50 in the FCD)
File-name Area
The file-name area is an area in the Data Division which contains the
name of the file 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.
Any name conforming to OS/2's High Performance File System (HPFS) can be
handled, provided it does not contain embedded spaces. (OS/2)
Example.
01 record-area pic x(85).
01 file-name-area pic x(65) value "master.dat".
. . . .
set file-name-pointer of fcd to address of file-name-area
set record-pointer of fcd to address of record-area
move 81 to maximum-record-length of fcd
move 41 to minimum-record-length of fcd
Key Definition Block.
The Key Definition block describes the keys for indexed files. It is
made up of three parts:
* Global Information area
* Key Definition area
* Component Definition area
All unused or reserved areas must be initialized to binary zeros. Each
part of the Key Definition Block is discussed below.
Global Information Area.
The Global Information area tells the file handler the size of the Key
Definition area and how many keys are in the file. All unused or
reserved areas must be initialized to binary zeros. The structure is as
follows:
Offset SizeDescription of the field
-----------------------------------------
0 2 Length of the Key Definition
Block
2 4 Reserved. Must be set to
binary zeros.
6 2 Number of keys.
8 6 Reserved. Must be set to
binary zeros.
Key Definition Area.
The Key Definition area describes the keys used in the indexed file. It
follows the Global Information area and consists of one Key Definition
for each key in the file. You must define all keys before their
components. The order of definition is important. 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
would contain three key definitions. The prime key is key 0, the first
alternate is key 1, and the second alternate is key 2. All unused or
reserved areas must be initialized to binary zeros. The structure of a
Key Definition is as follows:
Offset SizeDescription of the field
-----------------------------------------
0 2 Component count
For ordinary keys, the
component count is 1. For
split keys, the component
count is the number of
components making up the split
key.
2 2 Offset to first Component
Definition area for this key.
This offset is relative to the
start of the Global
Information area, starting at
0.
4 1 Key Flags:
Bit 7- Reserved. Must be set
to binary zeros.
Bit 6 - Duplicates allowed.
Bit 5 - Reserved. Must be set
to binary zeros.
Bit 4 - Prime key.
Bit 3 - Reserved. Must be set
to binary zeros.
Bit 2 - Reserved. Must be set
to binary zeros.
Bit 1 - Sparse key.
Bit 0 - Reserved. Must be set
to binary zeros.
5 1 Compression flags:
Bits 7-3 - Reserved. Must be
set to binary zeros.
Bit - 2 - Compression of
trailing spaces.
Bit - 1 - Compression of
leading characters.
Bit - 0 - Compression of
duplicates.
6 1 Sparse character.
If the entire key contains
this character and bit 1 of
the key flags field is set,
the key will be suppressed.
7 9 Reserved. Must be set to
binary zeros.
Component Definition Area.
The Component Definition area follows the Key Definition area. It
contains one component 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 location within the record and length of
the key. All unused or reserved areas must be initialized to low-values.
The structure of a Component Definition is as follows:
Offset SizeDescription of the field
-----------------------------------------
0 2 Reserved. Must be set to
binary zeros.
2 4 Offset of component within the
record (starting at 0).
6 4 Length of the component (in
bytes).
FCD Fields Input to the File Handler.
Areas of the FCD are used internally by this file handling system. To
ensure COBOL compatible functionality when using Extfh's call interface,
you should save the entire FCD on completion of a file open operation and
resubmit it on subsequent operations, changing only those fields
indicated in the following table. You should then save the FCD on
completion of all subsequent operations.
The following table indicates, for each operation, which fields in the
FCD and which areas must be set up prior to calling the file handler.
Function Input fields
-------------------------------------------------
OPEN File organization (offset 5)
Access mode (offset 6)
Length of file name (offset 11)
Lock mode flags (offset 24)
Other flags (offset 25)
Maximum record length (offset 38)
Recording mode (offset 47)
Minimum record length (offset 50)
Pointer to the file name area
(offset 60)
Open mode (offset 7) (this must be
set to 128)
Data Compression (offset 78)
File name area
If indexed or Btrieve file:
File format (offset 34)
Pointer to the key definition block
(offset 64)
Key definition block
WRITE Current record length (offset 48)
REWRITE Pointer to the record area (offset
56)
Record area
If WRITE BEFORE/AFTER or AFTER
POSITIONING: Line count (offset 52)
If Relative file, non-sequential
access: Relative record number
(offset 43)
Table 5-0. (cont.)
Function Input fields
READ Pointer to the record area (offset
56).
If relative file, non-sequential
access: Relative record number
(offset 43)
If indexed file, non-sequential
access: Key identifier (offset 52)
START Pointer to the record area (offset
56).
If relative file: Relative record
number (offset 43)
If indexed file: Key identifier
(offset 52) Effective key length
(offset 54)
CLOSE None.
UNLOCK None
DELETE If indexed file: non sequential
access to the record pointer (offset
56)
If relative file: non sequential
access to the relative record number
(offset 43)
DELETE file File organization (offset 5)
File name length (offset 11)
File format (offset 34)
Recording mode (offset 47)
Pointer to the file name area
(offset 60)
File name area
COMMIT None.
ROLLBACK None
06 File organization (offset 5) (can be
x"FF")
Length of file name (offset 11)
Pointer to the file name area
(offset 60)
Pointer to the key definition area
(offset 64) (for indexed files)
STEP Pointer to the record area (offset
56)
FCD Fields Returned by the File Handler.
The following table indicates, for each operation, which fields in the
FCD and which areas will be set up on return from calling the file
handler.
Function Input fields
-------------------------------------------------
All (except User file status (offset 0)
COMMIT
and
ROLLBACK
OPEN Open mode (offset 7)
File handle (offset 28)
READ Current record length (offset 48)
Relative Byte Address (offset 72)
Record area
WRITE Relative Byte Address (offset 72)
REWRITE Relative Byte Address (offset 72)
06 For indexed files:
Key definition block
File organization (offset 5)
File format (offset 34)
Maximum record length (offset 38)
Recording mode (offset 47)
Minimum record length (offset 50)
File size (offset 72)
MPE/iX 5.0 Documentation