HP 3000 Manuals HP 3000 Manuals
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 I/O 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.
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, as listed below. 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
Step operations are a method of sequentially retrieving the data in a
variable record length or IDXFORMAT(4) file 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, the 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 the Step operations.
Action Codes
The 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.
Key: Op code is in hexadecimal format.
File Types are:
L - Line Sequential
S - Record Sequential
R - Relative
I - Indexed
vS - Variable format Sequential
vR - Variable format Relative
-------------------------------------------------------------------
Op Description File Type
code
-------------------------------------------------------------------
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 REWIND L S
05 OPEN OUTPUT WITH NO REWIND L S
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 REMOVAL L S
86 CLOSE REEL/UNIT WITH NO REWIND L S
8D READ (sequential) WITH NO LOCK L S R I
D8 READ (sequential) WITH LOCK L S R I
D9 READ (sequential) WITH KEPT LOCK L S R I
F5 READ (sequential) L S R I
8C READ PREVIOUS WITH NO LOCK R I
DE READ PREVIOUS WITH LOCK R I
DF READ PREVIOUS WITH KEPT LOCK R I
F9 READ PREVIOUS R I
8E READ (random) WITH NO LOCK R I
DA READ (random) WITH LOCK R I
DB READ (random) WITH KEPT LOCK R I
F6 READ (random) R I
8F READ (direct) WITH NO LOCK L S R I
D6 READ (direct) WITH LOCK L S R I
D7 READ (direct) WITH KEPT LOCK L S R I
-------------------------------------------------------------------
Op Description File Type
code
-------------------------------------------------------------------
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 length prime key R I
E9 START equal to (any key) R I
EA START greater than (>) R I
EB START with key not less than (>=) R I
FE START with key less than (<) R I
FF START with key less than or equal to (<=) R I
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 LOCK L S R I
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 files) L S R I
DD ROLLBACK S R I
-------------------------------------------------------------------
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 op code as
defined below:
-------------------------------------------------------------------
Op Description File Type
code
-------------------------------------------------------------------
06 Return file information IvSvR
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 (fcd-reladdr-offset is used for this), 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 Open new index I
08 Get next record I
09 Add key value I
These three codes are used together to allow the
recreation of a variable length record file or
IDXFORMAT(4) indexed file index without affecting the
data file.
0F Unlock record I
This code uses the prime key to locate and unlock a
specific record within a variable record length file.
-------------------------------------------------------------------
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 areas of the FCD must be set to LOW-VALUES (binary zeros).
The supplied copy file xfhfcd.cpy contains a COBOL definition of the FCD.
Bit 7 is always the most significant (leftmost) bit.
---------------------------------------------------------------------
Offset Size Description of the field
---------------------------------------------------------------------
0 2 User file status. Also see offsets 6 and 33.
After every operation, this field will be updated
with a standard file status value telling you the
status of the operation. See Chapter 18 , File
Status for details of file status.
2 3 Reserved. Must be set to binary zeros.
5 1 File organization
0 - Line sequential
1 - Sequential
2 - Indexed
3 - Relative
4 - Sort
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.
---------------------------------------------------------------------
Offset Size Description 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 be set to binary zeros.
11 2 Length of file name
13 9 Reserved. Must be set to binary zeros.
22 1 Reserved. Must be set to binary zeros.
23 1 Reserved. Must be set to 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 = Filename is EXTERNAL
Bit 3 = Reserved
Bit 2 = NODETECTLOCK directive enabled
Bit 1 = Multiple Reel file (Record Sequential)
Bit 0 = Line Advancing file (Record
Sequential)
---------------------------------------------------------------------
Offset Size Description of the field
---------------------------------------------------------------------
26 2 Reserved. Must be set to binary zeros.
28 4 File handle The file handle is returned after an
OPEN, and is used in all subsequent operations to
identify the file.
32 1 Reserved. Must be set to binary zeros.
33 1 File status type. Also see offsets 0 and 6.
Bit 7 identifies the file status type:
0 - ANSI'74
1 - ANSI'85
Bits 0-6 are reserved.
34 1 File format
0 - Default format
1 - C-ISAM format
2 - Level II format
3 - Micro Focus file format
4 - IDXFORMAT(4) format
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
0 - Fixed
1 - Variable
---------------------------------------------------------------------
Offset Size Description 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
---------------------------------------------------------------------
Offset Size Description of the field
---------------------------------------------------------------------
76 2 Reserved. Must be set to binary zeros.
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)
92 1 Fileshare flags
Bit 7 = Transaction logging
93 1 Configuration flags
Bit 7 = WRITETHRU
Bit 6 = Use Relative Byte Address
Bit 5 = Update current record pointer
94 6 Reserved. Must be set to binary zeros.
95 1 Bit 7= Use EBCDIC Collating Sequence
96 3 Reserved. Must be set to binary zeros.
99 1 Reserved for internal use by Micro Focus.
---------------------------------------------------------------------
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 4 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 may contain path
information as well as the actual name of the file. The name must be
terminated by a space.
Example
01 record-area pic x(85).
01 file-name-area pic x(65) value
"/preval/data/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 Size Description 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 Size Description 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; 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 Definition defines 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 Size Description 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 the Micro Focus 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) (=128)
Data Compression (optional) (offset 78)
File name area
If indexed file:
File format (offset 34)
Pointer to the key definition block (offset
64)
Key definition block
WRITE/ File handle (offset 28)
REWRITE Current record length (offset 48)
File organization (offset 5)
Pointer to the record area (offset 56)
Recording mode (offset 47)
Record area
If WRITE BEFORE/AFTER:
Line count (offset 52)
If Relative file, non-sequential access:
Relative record number (offset 43)
READ File handle (offset 28)
File organization (offset 5)
Pointer to the record area (offset 56)
Recording mode (offset 47)
If relative file, non-sequential access:
Relative record number (offset 43)
If indexed file, non-sequential access:
Key identifier (offset 52)
START File handle (offset 28)
File organization (offset 5)
Current record length (offset 48)
Pointer to the record area (offset 56)
Recording mode (offset 47)
If relative file:
Relative record number (offset 43)
If indexed file:
Key identifier (offset 52)
Effective key length (offset 54)
----------------------------------------------------------------
Function Input fields
----------------------------------------------------------------
CLOSE File handle (offset 28)
File organization (offset 5)
Recording mode (offset 47)
UNLOCK File handle (offset 28)
File organization (offset 5)
Recording mode (offset 47)
DELETE File handle (offset 28)
File organization (offset 5)
Recording mode (offset 47)
DELETE file File organization indicator (offset 5)
File format (offset 34)
File name length (offset 11)
File organization (offset 5)
Pointer to the file name area (offset 60)
Recording mode (offset 47)
File name area
COMMIT None
ROLLBACK None
06 File organization (offset 5)
Length of file name (offset 11)
Pointer to the file name area (offset 60)
Pointer to the key definition area (offset 64)
STEPs File handle (offset 28)
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 User file status (offset 0)
OPEN File handle (offset 28)
Open mode (offset 7)
READ Current record length (offset 48)
Record area
Relative Byte Address (offset 72)
WRITE Relative Byte Address (offset 72)
REWRITE Relative Byte Address (offset 72)
06 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)
----------------------------------------------------------------