HP 3000 Manuals

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