PreviousFile Handler Configuration Sorting FilesNext

Chapter 7: File Handler API

7.1 Overview

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

call "EXTFH" using opcode fcd

where the parameters are:

"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.

You must follow these steps before the first call:

  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.

7.2 Data Structures

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

7.2.1 File Control Description (FCD)

The File Control Description (FCD) is a data area which contains information about the file in use. In Server Express 2.0, the format of the FCD has been changed from FCD2 to FCD3. Only FCD3 format can be used in 64-bit compilations. 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 P64 directive. 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 fields contained in the FCD are shown in the following table. For flags, the description refers to when the bit is set on. Bit 7 is the most significant (leftmost) bit. Unused bits are reserved for future use.

Field name Type Description of the Field
fcd-file-status
User file status. After every operation except a COMMIT or ROLLBACK operation, this field is updated with a standard file status value telling you the status of the operation. See also fcd-access-mode and fcd-status-type.
fcd-status-key-1 pic x
fcd-status-key-2 pic x
fcd-length pic xx comp-x FCD length. For FCD3 only
fcd-version pic x comp-x Version number:
Value Description
0 FCD2
1 FCD3
fcd-organization pic x comp-x File organization:
Value Description
0 Line sequential
1 Sequential
2 Indexed
3 Relative
fcd-access-mode pic x comp-x User status and access mode indicators.

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. When calling the File Handler directly, this bit should be set. However, file status is obtained directly from fcd-file-status.

Access mode is indicated by bits 6 through 0:

Value Description
0 Sequential access mode
4 Random access mode
8 Dynamic access mode
fcd-open-mode pic x comp-x Open mode:
Value Description
0 Open for input
1 Open for output
2 Open for input and output
3 EXTEND
128 File is closed

You must set this field to 128 before opening a file.

fcd-recording-mode pic x comp-x Recording mode:
Value Description
0 Fixed
1 Variable
fcd-file-format pic x comp-x File format:
Value Description
0 Default format
1 C-ISAM format
3 IDXFORMAT"3" format
4 IDXFORMAT"4" format
8 IDXFORMAT"8" format
11 Mainframe print format
14 Heap file
15 ESDS file
fcd-device-flag pic x comp-x Device flag:
Value Description
0 Normal
1 Device
2 Stdin
3 Stdout
4 Stderr
5 Badname
6 Input pipe
7 Output pipe
8 I/O pipe
9 Library
10 Disk file
11 Null
12 Disk redir
13 No map
fcd-lock-action pic x comp-x Reserved
fcd-data-compress pic x comp-x Data compression routine indicator:
Value Description
0 No compression
1-127 Micro Focus data compression routine number (1=CBLDC001)
128-255 User-defined data compression routine number (128=USRDC128).
fcd-blocking pic x comp-x NODESIZE indicated as follows (in bytes):
Value Description
0 Node length determined by system
1 512
2 1024
4 4096
6 16384
fcd-idxcache-size pic x comp-x Number of index nodes held in cached memory. The number specified should be between 4 and 64. When set to 0, a default of 16 is used.
fcd-percent pic x comp-x Percentage indicator
fcd-block-size pic x comp-x Block size for data records (in bytes):
Value Description
0 No blocking
12 4096
13 8192
14 16384
15 32768
16 65536

For indexed and relative files, non-zero settings can degrade performance.

fcd-flags-1 pic x comp-x
Bit 7 Mainframe compatibility bit. When set, file characteristics are not required to match those specified in program.
Bit 5 READ and START operations will return the key (only) in the record area
Bit 1 TRACE=ON
Bit 0 Program includes a Declarative for this file
fcd-flags-2 pic x comp-x
Bit 0 CONVERTDBSPACE=ON
fcd-mvs-flags pic x comp-x Mainframe emulation flags:
Bit 2 File is implicit file (ACCEPT or DISPLAY)
Bit 1 Amode = 31 bit
Bit 0 Amode = 24 bit
fcd-status-type pic x comp-x Status type:
Bit 7 ON = ANSI 85 COBOL; OFF = ANSI 74 COBOL
Bit 6 SPACEFILL=OFF
Bit 5 STRIPSPACE=OFF
Bit 4 EXPANDTAB=OFF
Bit 3 LSRECDELIM=0A
Bit 2 INSERTTAB=ON
Bit 1 INSERTNULL=ON

Bits 1 and 2 are set or unset by the File Handler at open time, depending on the settings of the N and T run-time system switches. These bits can be set or unset after an OPEN operation to override the N and T run-time system switches.

fcd-other-flags pic x comp-x
Bit 7 OPTIONAL file (OPEN INPUT)
Bit 6 IGNORELOCK=ON
Bit 5 Not OPTIONAL (OPEN I/O and EXTEND)
Bit 4 Filename is EXTERNAL
Bit 2 NODETECTLOCK directive enabled
Bit 1 Multiple reel file (record sequential)
Bit 0 Line advancing file (record sequential)
fcd-trans-log pic x comp-x
Bit 7 OPENINPUTSHARED=ON
Bit 5 READSEMA=OFF
Bit 4 EXPANDPOSITIONING=ON
Bit 1 FASTREAD=OFF
Bit 0 SUPPRESSADV=ON
fcd-locktypes pic x comp-x
Bit 7 Interlanguage locking (LOCKTYPE 1 or 2)
Bit 6 SHARING WITH READ ONLY
Bit 5 Separate lock file (LOCKTYPE 2)
Bit 4 RUNITLOCKDETECT=OFF
Bit 3 Use NFS file locking
Bit 2 Use NFS file locking with HP compatibility
fcd-fs-flags pic x comp-x Fileshare flags:
Bit 7 Transaction logging
fcd-config-flags pic x comp-x
Bit 7 WRITETHRU
Bit 6 Use relative byte address
Bit 5 Update current record pointer
Bit 4 For FCD2, use fcd-reladdr-big for relative byte address, instead of fcd-reladdr-offset
Bit 1 Call status conversion routine
Bit 0 Set if IGNORELOCK required.
fcd-misc-flags pic x comp-x
Bit 7 HOSTFD option (record areas allocated at OPEN time)
Bit 1 File defined with EXTERNAL syntax
Bit 0 File closed with lock
fcd-config-flags2 pic x comp-x
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 specified
Bit 3 Ignore minimum length checking on variable-length files
fcd-lock-mode pic x comp-x Lock mode flags for shareable files:
Bit 7 Lock on multiple records
Bit 6 WRITELOCK directive enabled
Bit 5 RETRYOPEN=ON
Bit 4 SKIPLOCK =ON
Bit 3 RETRYLOCK=ON
Bit 2 Lock mode MANUAL
Bit 1 Lock mode AUTOMATIC
Bit 0 Lock mode EXCLUSIVE
fcd-shr2 pic x comp-x Miscellaneous flags:
Bit 1 RETRYTIME=ON
Bit 0 STARTUNLOCK=ON
fcd-nls-id pic xx comp-x NLS identifier
fcd-fs-file-id pic xx comp-x Reserved
fcd-retry-open-count pic xx comp-x RETRYOPEN count field
fcd-name-length pic xx comp-x Length of filename.
fcd-idxname-length pic xx comp-x Reserved
fcd-retry-count pic xx comp-x Retry count (used when RETRYLOCK is on)
fcd-key-id pic xx comp-x Key-of-Reference (for indexed files).

This field identifies the Key-of-Reference, used for random READ operations. To specify the prime key, set this field to zero. For example, to specify the first alternate key defined, use a value 1; to specify the second alternate key defined use value 2.

fcd-line-count pic xx comp-x Line count (for sequential files).

This field specifies the number of lines to skip when writing a file. For example:

WRITE AFTER ADVANCING line-count LINES
fcd-use-give pic xx comp-x Reserved
fcd-key-length pic xx comp-x Effective key length.

When using a START operation on indexed files, you can 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 comparison. It must be greater than zero and no bigger than the key being used.

fcd-current-rec-len FCD3: pic x(4) comp-x Current record length (in bytes)
FCD2: pic x(2) comp-x
fcd-min-rec-length pic x(4) comp-x Minimum record length (in bytes)
fcd-max-rec-length pic x(4) comp-x Maximum record length (in bytes)
fcd-session-id pic x(4) comp-x Reserved
fcd-reladdr-offset FCD3: pic x(8) comp-x Relative byte address. (See also fcd-config-flags, bit 4). The value of this field is undefined following the OPEN statement
FCD2: pic x(4) comp-x
fcd-reladdr-big pic x(8) comp-x An eight-byte relative byte address. For FCD2, this is a separate field. For FCD3, it redefines fcd-reladdr-offset. Provided for compatibility between FCD2 and FCD3.
fcd-max-rel-key pic x(8) comp-x Maximum relative key
fcd-relative-key pic x(8) comp-x Relative key
fcd-handle pointer File handle
fcd-record-address pointer Pointer to the record area
fcd-filename-address pointer Pointer to the filename area
fcd-idxname-address pointer Reserved
fcd-key-def-address pointer Pointer to key definition block
fcd-col-seq-address pointer Pointer to a collating sequence (null if none is used)
fcd-fildef-address pointer Reserved
fcd-dfsort-address pointer Reserved

7.2.2 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
   ...

7.2.3 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
   ...

7.2.4 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:

7.2.4.1 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.

All unused or reserved areas must be initialized to binary zeros.

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.

7.2.4.2 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 shown below. All unused or reserved areas must be initialized to binary zeros.

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 Set to indicate that this is the prime key. If this is not set for any key, the File Handler assumes that the first key is the prime key.
Bits 3-2 Reserved. Must be set to binary zeros
Bit 1 Sparse key. See offset 6
Bit 0 Reserved. Must be set to binary zeros.
5 1 Compression flags:
Bit 7-4 Reserved. Must be set to binary zeros
Bit 3 Compression of trailing nulls
Bit 2 Compression of trailing spaces
Bit 1 Compression of leading characters
Bit 0 Compression of duplicates
6 1 Sparse character.

If bit 1 of the key flags (offset 4) is set, the key is suppressed if it is entirely made up of this character.

7 9 Reserved. Must be set to binary zeros.

7.2.4.3 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 shown below. All unused or reserved areas must be initialized to binary zeros.

Offset Size Description
0 1 bit 7 (x"80") indicates duplicates to be returned in order
bit 6 (x"40") indicates DESCENDING key component
1 1

bit 7 (x"80") indicates that the field is NUMERIC

If bit 7 is set (numeric):

bit 6 (x"40") indicates that the field is SIGNED NUMERIC
bit 5 (x"20") indicates that the field is a non-display field
If bit 5 is set (non-DISPLAY field) bits 0 and 1 are used as follows:
0 - indicates that the field is BINARY
1 - indicates that the field is PACKED-DECIMAL
2 - indicates that the field is COMP-X format
3 - indicates that the field is COMP-5 format
bit 2 (value x"04") indicates floating point

If bit 5 is not set, (DISPLAY field) but bit 6 is set (SIGNED) bits 0 and 1 are used as follows:

0 - indicates SIGN TRAILING INCLUDED
1 - indicates SIGN TRAILING SEPARATE
2 - indicates SIGN LEADING INCLUDED
3 - iindicates SIGN LEADING SEPARATE
Compression of leading characters
Compression of duplicates
2 4 Offset of component in the record (starting at 0)
6 4 Length of the component (in bytes)

7.3 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 file, XFHFCD.CPY (which can be located using Infomgr). This definition can be mapped onto the FCD you want 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:

fcd The name of the FCD definition in the Linkage Section of your program.
fh--fcd (note the double hyphen) The FCD that is being used by this COBOL system to access the file.
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
kdb The name of the Key Definition Block in the Linkage Section of your program.
fh--keydef (note the double hyphen) The key definition that is being used by this COBOL system to access the file.
file The FD name of the file.

An example of accessing the FCD is given below.

Example of Accessing the FCD

The following program turns on key compression in a file by setting the appropriate bits in the file's Key Definition Block.

$set fcdreg
     select masterfile 
         assign to ... 
         organization is indexed 
         record key is rec-key 
         alternate key is m-alt-key-1 with duplicates 
         alternate key is m-alt-key-2 
         alternate key is m-alt-key-3 with duplicates. 
     select indexfile 
         assign to ... 
         organization is indexed 
         record key is rec-key 
         alternate key is t-alt-key-1 with duplicates. 
   ... 
 working-storage section. 
   ... 
 linkage section. 
 01 key-def-block. 
    03 filler pic x(6). 
    03 key-count pic 9(4) comp-x. 
    03 filler pic x(6). 
    03 key-def occurs 1 to 4 times depending on key-count. 
       05 filler pic x(5). 
       05 key-compression pic 9(2) comp-x. 
       05 filler pic x(10). 
  ... 
 procedure division. 
     set address of key-def-block 
                      to address of fh--keydef of masterfile
     move 6 to key-compression (1) 
     move 7 to key-compression (2) 
     move 6 to key-compression (3) 
     move 7 to key-compression (4) 
     open I-O masterfile 
  ... 
     set address of key-def-block 
                       to address of fh--keydef of indexfile
     move 4 to key-compression (1) 
     move 1 to key-compression (2) 
     open input indexfile

7.4 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 - standard and special.

7.4.1 Standard Operation Codes

Standard operation codes contain x"FA" in the most significant byte. The least significant byte indicates the specific operation.

Not all operation codes are appropriate with all file organizations. Each operation code description includes a list of the file organizations for which it is valid, using the following key:

L    Line sequential
S    Record sequential (including vS)
R    Relative (including vR)
I    Indexed

vS    Variable format sequential only

vR    Variable format relative only


Close

Terminates the processing of files and reels or units with optional rewind and locking where appropriate. For record sequential files, the terms "reel" and "unit" are interchangeable; the treatment of sequential disk files is logically equivalent to the treatment of a file on tape or similar sequential media.

Opcode Operation File Type
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
Input Fields

None

Output Fields
fcd-file-status User file status


Commit

Releases all record locks in all files held by this run unit.

Opcode Operation File Types
DC COMMIT (UNLOCK all files) L S R I
Input Fields

Always requires FCD used by the file.

Output Fields

None


Delete

Logically removes a record from a disk file. It can be specified only for files with relative or indexed organization.

Opcode Operation File Types
F7 DELETE vS R I
Input Fields
fcd-relative-key Non-sequential access to relative record number (R)
fcd-record-address Non-sequential access to record pointer (I)
Output Fields
fcd-file-status User file status


Delete File

Physically removes the specified file from the physical devices on which it resides.

Opcode Operation File Types
F8 DELETE FILE L S R I
Input Fields

Filename area

fcd-organization File organization
fcd-name-length Filename length
fcd-file-format File format
fcd-filename-address Pointer to the filename area
Output Fields
fcd-file-status User file status


Open

Initiates the processing of files. It also performs checking and/or writing of labels and other I/O operations.

Opcode Operation File Types
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
Input Fields

Filename area

Key Definition Block (I)

fcd-organization File organization
fcd-access-mode Access mode
fcd-open-mode Open mode
fcd-name-length Filename length
fcd-lock-mode Lock mode flags
fcd-other-flags Other flags
fcd-file-format File format
fcd-max-rec-length Maximum record length
fcd-recording-mode Recording mode
fcd-min-rec-length Minimum record length
fcd-filename-address Pointer to the filename area
fcd-key-def-address Pointer to the Key Definition Block (I)
fcd-data-compress Data compression
fcd-locktypes Interlanguage locking
Output Fields
fcd-file-status User file status
fcd-open-mode Open mode
fcd-handle Use this file handle for all subsequent accesses to this file

Opening a File More Than Once

You can assign several FCDs to the same physical file and have them all open at the same time. The operating system counts it as just one open file. The physical file is not closed until every logical file assigned to it has been closed.


Read

For sequential access, READ makes available the next or previous logical record from a file. For random access, READ makes available a specified record from a disk file.

Opcode Operation File Types
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
C9 READ (direct) L S R I
F1 READ (position) L S R I
Input Fields
fcd-relative-key Relative record number (R) if READ random or direct
fcd-key-id Key identifier (I)
fcd-record-address Pointer to the record area
Output Fields
fcd-file-status User file status
fcd-current-rec-len Current record length
fcd-reladdr-offset or fcd-rel-addr-big (FCD2 only) Relative byte address

Rollback

Releases all record locks in all files held by this run unit.

Opcode Operation File Types
DD ROLLBACK (UNLOCKs all files) L S R I
Input Fields

None

Output Fields

None


Start

Provides a basis for logical positioning in a relative or indexed file, for subsequent retrieval of records.

Opcode Operation File Types
E8 START equal to full length prime key R I
E9 START equal to (any key/record number) R I
EA START greater than (>) R I
EB START not less than (>=) R I
FE START less than (<) R I
FF START less than or equal to (<=) R I
Input Fields
fcd-relative-key Relative record number (relative files)
fcd-key-id Key identifier (indexed files)
fcd-key-length Effective key length (indexed files)
fcd-record-address Pointer to the record area
Output Fields
fcd-file-status User file status


Step

Steps to the next physical record. This operation enables very fast access to a record.

Opcode Operation File Types
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
Input Fields
fcd-record-address Pointer to the record area
Output Fields
fcd-file-status User file status
Comments

STEP operations are a method of sequentially retrieving records in a relative or indexed file without having to read via a key or relative record number. Generally, this is a faster method of accessing data in the file.

A STEP NEXT operation returns the record that is physically stored immediately after the one that was last retrieved in the file (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 byte 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.


Unlock

Releases all record locks held by the run unit on a named file.

Opcode Operation File Types
0E UNLOCK L S R I
Input Fields

None

Output Fields
fcd-file-status User file status

Write

Writes a new record to a file.

For sequential files, it can also be used for vertical positioning of lines in a logical page.

The REWRITE operation replaces an existing record.

Opcode Operation File Types
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
EC WRITE BEFORE mnemonic-name S
ED WRITE AFTER mnemonic-name S
F3 WRITE L S R I
F4 REWRITE L S R I
Input Fields
fcd-relative-key Relative record number (R)
fcd-current-rec-len Current record length
fcd-line-count Line count (WRITE only) (S)
fcd-record-address Pointer to the record area
Output Fields
fcd-file-status User file status
fcd-reladdr-offset or fcd-rel-addr-big (FCD2 only) Relative byte address

7.4.2 Special Operation Codes

Special operation codes contain x"00" in the most significant byte. The least significant byte indicates the specific operation.


File Information

Returns general file information for all file organizations and, for indexed files, information on the file keys in the form of the Key Definition Block.

Opcode Operation File Types
06 Return file information I vS vR
Input Fields
fcd-organization File organization (can be x"FF")
fcd-name-length Filename length
fcd-filename-address Pointer to the filename area
fcd-key-def-address Pointer to the Key Definition Block (I)
Output Fields

Key Definition Block (I)

fcd-file-status User file status
fcd-organization File organization
fcd-file-format File format
fcd-max-rec-length Maximum record length
fcd-recording-mode Recording mode
fcd-min-rec-length Minimum record length
fcd-file-status File size
fcd-data-compress Data compression routine

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 enough space causes corruption of some data areas.

For variable-length sequential files and variable-length relative files, no key definition information exists.

If the organization byte of the FCD is set to x"FF", this tries 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 might 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.


Create Index File

Creates a new .idx file, containing only header information for the file to allow new indexes to be added.

Opcode Operation File Types

07

Open new index

I

Input Fields

As OPEN.

Output Fields

As OPEN


Get Next Record

Gets the next physical record from the data file part of an indexed file.

Opcode Operation File Types

08

Get next record

I

Input Fields
fcd-record-address Pointer to the record area
Output Fields
fcd-file-status User file status
fcd-current-rec-len Current record length
fcd-reladdr-offset or fcd-rel-addr-big (FCD2 only) Relative byte address

Add Key Value

Adds a key value to the index file part of an indexed file.

Opcode Operation File Types

09

Add key value

I

Input Fields
fcd-key-id Key identifier
fcd-record-address Pointer to the record area
Output Fields
fcd-file-status User file status

Re-index File

Re-indexes the file using a supplied Key Definition Block.

Opcode Operation File Types

0B

Re-index file

I

Input Fields
fcd-key-def-address Pointer to Key Definition Block
Output Fields

None


Flush File

Flushes all data for a specific file to disk.

Opcode Operation File Types

0C

Flush file

L S R I

Input Fields

None

Output Fields

None


Unlock Record

Unlocks a specific record in a file.

Opcode Operation File Types

0F

Unlock record

I

Input Fields
fcd-record-address Pointer to the record area
Output Fields

None

7.5 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:

7.5.1 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.

7.5.2 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 want to update the current record pointer, set bit 5 of fcd-config-flags in the FCD.

You then perform a REWRITE operation.

7.5.3 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.

7.6 Creating Your Own File Handler

You can create your own, customised, file handler and use this is place of the File Handler supplied with Server Express. Alternatively, you can create file handlers that handle files of a specific type, such as relative files.

7.6.1 Using Your Own File Handler

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 the program 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.


7.6.2 Using Your Own File-type Specific File Handler

You can create your own file handler for a specific file type, and use this in place of the default file handler.

The default file handlers for the various types of file organization and record format are:

File Type
Default File Handler
Fixed-length Records
Variable-length Records
line-sequential lsfile lsfilev
sequential sqfile sqfilev
indexed ixfile ixfilev
relative rlfile rlfilev

The file handlers you link to your application instead of any of the default file handlers shown here must conform to the format of the call interface described in this chapter.

To link your own file handlers to your application, you must include the -m option on the cob command line. See the chapter Descriptions of cob Flags in your Server Express User's Guide for details of this option.

For example, to redirect all fixed length sequential file handling to your own file handler (myseqfh) you should use the following command line:

cob -x -msqfile=myseqfh myapp.cbl myseqfh.o

7.7 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 within 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.

7.8 Compression Routines

The compression routines that the File Handler uses to compress data are standalone modules. This means that you can:

There can be up to 127 Micro Focus compression routines, and up to 127 user-supplied compression routines.

7.8.1 Micro Focus Compression Routines

Micro Focus compression routines are stored in modules called CBLDCnnn, where nnn is within the range 001 to 127.

To use a Micro Focus compression routine, set fcd-data compress in the FCD to a value of 001 to 127, as appropriate.

7.8.1.1 CBLDC001

The Micro Focus compression routine, CBLDC001, uses a form of run-length encoding. This is a method of compression that detects strings (runs) of the same character and reduces them to an identifier, a count and one occurrence of the character.


Note: This routine is not effective for use with files that contain significant occurrences of double-byte characters, including double-byte spaces, as these are not compressed.


CBLDC001 puts special emphasis on runs of spaces, binary zeros and character zeros (that can be reduced to a single character) and printable characters (that are reduced to two characters consisting of a count followed by the repeated character).

In the compressed file, bytes have the following meanings (hex values shown):

20-7F Most printable characters - normal ASCII meaning.
80-9F 1-32 spaces respectively.
A0-BF 1-32 binary zeros respectively.
C0-DF 1-32 character zeros respectively.
E0-FF 1-32 occurrences of the character following.
00-1F 1-32 occurrences of the character following, and that it should be interpreted literally, not as a compression code. This is used when characters in the range 00-1F, 80-9F, A0-BF, C0-DF or E0-FF occur in the original data. (Thus, one such character is expanded to two bytes; otherwise, no penalty is incurred by the compression.)

7.8.1.2 CBLDC003

Like CBLDC001, this routine uses run length encoding, but detects strings (runs) of single- or double-byte characters. This routine is therefore suitable for DBCS characters, but can also be used in place of CBLDC001.

The format of the compression is two header bytes followed by one or more characters. The bits in the header bytes indicate:

Bit 15 Unset - single character
Bit 14 Set - compressed sequence
Unset - uncompressed sequence
Bits 0-13 Compressed character(s) or count of uncompressed characters

The length of the character string depends on the header bits:

Bits 14 and 15 set Two repeating characters.
Only bit 14 is set One repeating character.
Otherwise Between 1 and 63 uncompressed characters.

7.8.1.3 Calling a Micro Focus Compression Routine

For data file compression the File Handler calls the compression routine that you specify in the DATACOMPRESS Compiler directive.

If you want to use the compression routines for compressing your own data, you can call them directly from your program:

        call "CBLDCnnn" using input-buffer,
			      input-buffer-size,
			      output-buffer,
			      output-buffer-size,
			      compression-type

where the parameters are:

nnn A data compression routine in the range 001 to 127.
input-buffer A PIC X data item: the data to compress or decompress; maximum size is 65,535 bytes.
input-buffer-size A two byte (PIC XX COMP-5) data item: specifies the length of the data in input-buffer.
output-buffer A PIC X data item: buffer to contain the resulting data.
output-buffer-size A two-byte (PIC XX COMP-5) data item. On entry to the routine this data item must contain the size of the output buffer available; on exit it contains the length of the data in output-buffer.
compression-type A one-byte (PIC X) data item: specifies whether the input data is to be compressed or decompressed:
0 - compress
1 - decompress

The RETURN-CODE special register indicates whether the operation succeeded or not. Compression or decompression fails only if the output buffer is too small to accept the results.

7.8.2 User-supplied Compression Routines

User-supplied compression routines must be stored in modules called USRDnnn where nnn is within the range 128 through 255.

When creating compression routines, you should bear the following in mind:


Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousFile Handler Configuration Sorting FilesNext