| File Handler API | Sorting Files | |
Btrieve is the file handling system from Pervasive Software Inc. For full details on Btrieve, consult the Btrieve manuals supplied by Pervasive Software.
The Xfh2btr call conversion module which enables you to use the Micro Focus File Handler API to process Btrieve files is supplied with NetExpress.
Notes:
The Xfh2btr call conversion module enables you to use the Micro Focus File Handler API to access Btrieve files from this COBOL system.
Btrieve does not normally conform to ANSI standards but, by default, the Xfh2btr call conversion module makes the necessary calls to the Btrieve run-time system in order to force it to emulate ANSI behavior. You can, however, choose to operate in non-ANSI mode.
Xfh2btr is compatible with versions of Btrieve 6.1x and above.
It is supplied as part of this COBOL system and also as a linkable module, xfh2btr.obj, which can be linked with any application that needs to perform I/O on Btrieve files.
When the call conversion module needs to call the Btrieve run-time system to perform I/O, it calls the module _BTRV. The function of this module is to format the call and pass it to the Btrieve Microkernel Interface (wbtrv32.dll for Windows NT and Windows 95). Note that you can call the module _BTRV directly from your COBOL program using the same parameters as those used in Btrieve API calls (see your Btrieve Programmer's Reference Manual).
When linking any application to a standalone executable file, you need to link in _btrv.obj. Alternatively, if you have the Btrieve Developer's Kit, you can link the modules supplied by Pervasive Software in place of _btrv.obj. These are cobrbtrv.obj and cobpbtrv.obj. For more details of these modules, see the documentation supplied with the Btrieve Developer's Kit.
There are three ways of calling the Xfh2btr call conversion module:
Note that some file operations and formats are not supported by Btrieve; for example, WRITE AFTER and line sequential files. Attempting to direct file I/O to the converter in these situations causes an error to be returned to your program.
The CALLFH Compiler directive specifies the file handler used by your program to perform all COBOL I/O operations. By default, if no file handler is specified, the Micro Focus File Handler is used.
If you use the CALLFH Compiler directive to specify the Xfh2btr call conversion module, your program passes all I/O to the Xfh2btr call conversion module so that COBOL I/O operations are converted to Btrieve I/O operations.
You can include CALLFH at the top of your source program as an initial $SET statement as follows:
$set callfh"xfh2btr"
The FILETYPE Compiler directive specifies the format of files created by your program.
You can put the FILETYPE Compiler directive at the top of your program as an initial $SET statement as follows:
$set filetype"n"
where n, in this case, can be either 5 or 6.
FILETYPE"5" is used when it is important for file operations to conform to ANSI standards. Btrieve does not normally conform to ANSI standards and this mode of operation requires a number of calls to the Btrieve run-time system in order to force it to emulate ANSI behavior.
FILETYPE"6" is used when speed is important. In this mode of operation, each Micro Focus File Handler operation is mapped to the nearest Btrieve run-time call. No attempt is made to conform to ANSI standards.
You can mix different types of file within your program by putting the FILETYPE Compiler directive around individual SELECT statements, for example:
$set filetype"0" select testfile-1 assign to "test-1.dat" organization indexed record key prime-key access sequential. $set filetype"5" select testfile-2 assign to "test-2.dat" organization relative access sequential.
In the above example, all I/O on test-1.dat is handled by the Micro Focus File Handler while all I/O on test-2.dat is handled by the Xfh2btr call conversion module.
Note: To specify the format to use when creating an indexed file, you can include the IDXFORMAT parameter under that file's settings in your file handler configuration file. Set IDXFORMAT to either 5 or 6 to indicate Btrieve with or without ANSI conformance respectively. For more information, see File Handler Configuration in the File Handling book.
There are two environment variables that you can set in order to change the way in which the Xfh2btr call conversion module operates: BTRPAGE and BTRMAXREC.
The BTRPAGE environment variable specifies the page size that is used when Btrieve files are created. You can set it using the following command:
set BTRPAGE=nnn
where nnn is a byte value in the range 512 to 4096 inclusive, in multiples of 512 bytes.
If you do not set BTRPAGE, or you specify an incorrect value, the page size defaults to 1024 bytes.
Notes:
You can specify the value of BTRPAGE on a per-file basis using the xfh2btr configuration file.
The BTRMAXREC environment variable specifies the maximum record size.
You can set BTRMAXREC using the following command:
set BTRMAXREC=nnnn
where nnnn is a byte value specifying the maximum record length.
You should set BTRMAXREC to the record size of the largest record to be accessed.
If you do not set BTRMAXREC, the default value of 32 Kilobytes is used.
You can specify the value of BTRMAXREC on a per-file basis using the xfh2btr configuration file.
Note: If you want to use the Xfh2btr configuration file you must link your program with mfini.obj.
The Xfh2btr configuration file enables you to specify the page size, maximum record length and Btrieve open mode for all files or for an individual file.
You can specify the name of the configuration file via the XFH2BTR environment variable. If this environment variable is not set, the default configuration filename of xfh2btr.cfg is used. The configuration file is searched for first in the current directory and then along the path specified by the COBDIR environment variable.
The tag [X2B-DEFAULTS] is used to specify default values for page size, maximum record length and Btrieve open mode while a tag containing a filename (for example [test.dat]) is used to specify values for a particular file.
Attribute names can be separated from attribute values by a space or a colon (:) character.
Note: If a configuration file exists, the settings of the Btrieve environment variables BTRPAGE and BTRMAXREC are ignored.
You can also turn on the Xfh2btr trace option and specify the name of the trace file via the Xfh2btr configuration file.
You can specify the page size to use when creating a Btrieve file by setting an attribute within the Xfh2btr configuration file as follows:
BTRPAGE:nnn
where nnn is a byte value in the range 512 to 4096 inclusive, in multiples of 512 bytes.
If you do not set BTRPAGE, or you specify an incorrect value, the page size defaults to 1024 bytes.
You can specify the maximum record size for a Btrieve file by setting an attribute within the Xfh2btr configuration file as follows:
BTRMAXREC:nnnn
where nnnn is a byte value. You should set BTRMAXREC to the record size of the largest record to be accessed. If you do not set BTRMAXREC, the default value of 32 Kilobytes is used.
You can use the Xfh2btr configuration file to specify the Btrieve open mode used to open a file:
INPUT-EXCLUSIVE:open-mode
INPUT-SHAREABLE:open-mode
OUTPUT:open-mode
EXTEND-EXCLUSIVE:open-mode
EXTEND-SHAREABLE:open-mode
I-O-EXCLUSIVE:open-mode
I-O-SHAREABLE:open-mode
The possible values of open-mode are: normal, accelerated, read-only, verify, exclusive. For further details on these open modes, consult your Btrieve documentation.
[X2B-DEFAULTS]
output:accelerated
i-o-shareable:accelerated
i-o-exclusive:accelerated
btrpage:2048
btrmaxrec:2000
[test1.dat]
output:exclusive
i-o-shareable:normal
btrpage:4096
The above is an example Xfh2btr configuration file which specifies the following:
If the Xfh2btr trace option is set, every operation performed by the Xfh2btr call conversion module and every error code returned by the Btrieve Record Manager are either displayed on the screen or recorded in a trace file.
If an error is returned by the Btrieve Record Manager, the Xfh2btr call conversion module maps the Btrieve error to a COBOL file status code which it returns to your program. The COBOL file status code to which a Btrieve error has been mapped is also displayed in the trace file.
If a Btrieve error is not shown on the trace but a COBOL file status is returned, the error has been generated within the Xfh2btr call conversion module. For example, attempting to write to a file opened for input would generate such an error.
There are two attributes that effect the trace option: TRACE-FILE and TRACE.
TRACE-FILE:filename
This specifies that the trace information is to be directed to the specified file and not to the screen. If no filename is specified, the default filename, xfh2btr.lst, is used. The trace-file attribute can only be specified under the [X2B-DEFAULTS] tag. If a number of client applications are writing trace information to the same trace file, the order in which the information appears in the file is undetermined.
Note: Specifying a trace filename does not turn on the TRACE facility.
TRACE
The TRACE attribute switches tracing on. It can be specified under the [X2B-DEFAULTS] tag (in which case operations on all files are traced) or under a filename tag (in which case only operations on that file are traced).
The following entries in the Xfh2btr configuration file:
[X2B-DEFAULTS] trace-file:x2btrace.dat trace:
specify that tracing is on for every file and that the trace information is written to the file x2btrace.dat.
The following entries in the Xfh2btr configuration file:
[X2B-DEFAULTS] trace-file: [test1.dat] trace:
specify that tracing is on for the file test1.dat and that the trace information is written to the file xfh2btr.lst (the default trace filename).
Below is an example of the output produced when the trace option is used:
Line Input FA01 ifile1.tmp 1 Output Btrieve Error=+0000 COBOL Error=0/0 2 Input FAF3 ifile1.tmp 3 Output Btrieve Error=+0000 COBOL Error=0/0 4 Input FAF3 ifile1.tmp 5 Output Btrieve Error=+0000 COBOL Error=0/0 6 Input FADC All Files 7 Output Btrieve Error=+0000 COBOL Error=0/0 8 Input FA80 ifile1.tmp 9 Output Btrieve Error=+0000 COBOL Error=0/0 10 Input FA02 ifile1.tmp 11 Output Btrieve Error=+0000 COBOL Error=0/0 12 Input FAF5 ifile1.tmp 13 Output Btrieve Error=+0000 COBOL Error=0/0 14 Input FAF5 ifile1.tmp 15 Output Btrieve Error=+0000 COBOL Error=0/0 16 Input FAF5 ifile1.tmp 17 Output Btrieve Error=+0009 COBOL Error=1/0 18 Input FA80 ifile1.tmp 19 Output Btrieve Error=+0000 COBOL Error=0/0 20 Input FA01 test.dat 21 Output Btrieve Error=+0029 COBOL Error=9/078 22 Input FA00 ifile1.tmp 23 Output Btrieve Error=+0000 COBOL Error=0/0 24 Input FAF3 ifile1.tmp 25 Output Btrieve Error=+0000 COBOL Error=4/8 26 Input FA80 ifile1.tmp 27 Output Btrieve Error=+0000 COBOL Error=0/0 28
Line 1 shows an example input line: the operation code and the name of the file on which the operation is being performed.
Line 2 shows an example output line: the Btrieve error status and the error being returned to the COBOL application.
Line 7 shows an example of an operation (in this case, COMMIT) being performed on all open files.
Line 22 shows the error status 29 being returned from the Btrieve run-time system and that this is returned to the COBOL application as a 9/078 status. For details of the Btrieve error status 29, see the relevant Btrieve documentation.
Line 26 shows an error that is generated within the Xfh2btr module. An attempt is being made to write to a file which is opened for INPUT.
The majority of COBOL file operations performed by the Micro Focus File Handler operate in exactly the same way when performed by Xfh2btr on Btrieve files. However, due to underlying differences between the two systems, there are instances where behavior differs. These include:
Note: You should especially note the positioning of the current record pointer (CRP) when performing sequential read operations after having written, rewritten or deleted records in a file.
When this COBOL system reads a record that is locked by another user, the record data is returned to the program together with a COBOL file status of 9/068 (record locked).
With Btrieve, if a record is locked, the data is not returned and so reading a locked record requires multiple calls to the Btrieve run-time, making default record reading slower.
You can improve the speed of read operations by:
When you do this, calls to the Btrieve run-time to detect record locks are not required because the file is locked exclusively and so individual records do not need to be checked.
If this directive is set no calls are made to the Btrieve run-time to see if the record is locked by another user.
When you access a Btrieve file from within a transaction, a temporary exclusive lock is obtained on the file and so calls to the Btrieve run-time to detect record locks are not required.
The COBOL OPEN OUTPUT operation creates a file and opens it with an exclusive lock. This is performed in a single operating system call. With Btrieve, this operation requires two calls to the Btrieve run-time, the first to create the file and the second to open the file with an exclusive lock. Because a small time lapse exists between these two calls, it is possible for a second user to access the file between the time that the file is created and the time that it is opened. If this happens, the second user finds the file empty and an attempt to read the file results in an "at end" error. The user performing the OPEN OUTPUT receives a "file locked" error because the exclusive OPEN call fails.
Within a Btrieve file, variable length records consist of two parts: a fixed length part and a variable length part. Fixed length records consist of only the fixed length part.
For variable length records, the fixed length part of the record is usually determined by the minimum record length defined in your COBOL program. However, depending on the number of keys which allow duplicates and the page size used, Btrieve may impose restrictions on the maximum length of the fixed part of the record. The formula for determining the maximum length of the fixed part of a record is given below:
p - 6 - ( 8 * k ) [- 4 for variable length records] [- 4 for relative files]
where:
p is the page size of the file
k is the number of keys that allow duplicates
Notes:
The following examples use a page size of 1024 bytes:
All the keys must be in the first 1018 bytes of the record.
All the keys must be in the first 1014 bytes of the record.
All of the keys must be in the first 1010 bytes of the record.
All of the keys must be in the first 1006 bytes of the record.
The additional four bytes is due to the auto-increment key that is added automatically to the front of each record. If you are using the opcode 06 action-code for the Micro Focus File Handler call interface, the record length returned is 1014 bytes.
This length includes the additional four bytes automatically added to the front of each record, due to the auto-increment key. If you are using the opcode 06 action-code for the Micro Focus File Handler call interface, the record length returned is 1010 bytes.
All of the keys must be in the first 1014 bytes of the record.
All of the keys must be in the first 1014 bytes of the record.
All of the keys must be in the first 1006 bytes of the record.
All of the keys must be in the first 1006 bytes of the record.
The additional four bytes is due to the auto-increment key that is added automatically to the front of each record. If you are using the opcode 06 action-code for the Micro Focus File Handler call interface, the record length returned is 1010 bytes.
The additional four bytes is due to the auto-increment key that is added automatically to the front of each record. If you are using the opcode 06 action-code for the Micro Focus File Handler call interface, the record length returned is 1010 bytes.
With this COBOL system, the Current Record Pointer (CRP) is only affected when START, READ (sequential or random) and OPEN operations are performed on the file.
With the Btrieve run-time system, however, the CRP is affected by WRITE, REWRITE and DELETE operations. This means that, following these operations, the CRP in a Btrieve file has to be restored to its original position so that sequential READ statements are not affected.
In a shared environment, the re-positioning of the CRP can fail if the record to be re-positioned on has been deleted by another user. If this happens, any attempt to perform a sequential READ returns an error.
In the following sections, re-positioning of the CRP is performed after the operation has completed and not at the time of the next sequential READ statement. This reduces the possibility of the record being deleted and increases the possibility of successfully re-positioning the CRP.
Note: The non-ANSI conforming mode of operation makes no attempt to re-position the CRP and can, therefore, be significantly faster.
For shared files opened I/O that are not in transactions where the ANSI conforming mode of operation is being used, the file is actually opened twice. The first open of the file is used to read records from the file. The second open of the file is used to write records to the file. Therefore, it is not possible for the reading position to be affected by normal WRITE operations. However, if you use the WRITELOCK directive, the inserted record has to be read back with a lock and this changes the CRP in the file.
Re-positioning the Btrieve file position indicator after a WRITE operation can only fail if WRITELOCK directives are used and the file is shareable. If the re-positioning after the WRITE operation fails, an error is returned when the sequential READ is attempted.
For files opened I/O with random or dynamic access, the Btrieve file position indicator has to be moved to the position of the record to be deleted. After performing the DELETE operation, the file position indicator is restored to its original position, although this could fail if the record to re-position on has been deleted.
This problem does not occur for files with sequential access because the file position indicator is already on the record to be deleted and so re-positioning is not necessary.
Note: It is not possible to perform a sequence of sequential READ and DELETE statements when the key of reference is on a key which allows duplicates. This is because it is not possible to re-position the CRP after the DELETE operation.
For files opened I/O with random or dynamic access, the Btrieve file position indicator is moved to the position of the record to be changed. After performing the REWRITE operation, the file position indicator is restored to its original position, although this could fail if the record to re-position on has been deleted.
This problem does not occur for files with sequential access because the file position indicator is already on the record to be rewritten and so re-positioning is not necessary.
In this COBOL system, transaction processing is only available if you are using Fileshare but Btrieve users do not require Fileshare in order to implement transaction processing.
When you update records in a file within a transaction with Fileshare, the individual records in the file are locked to prevent another user from reading the record. This is because there is the possibility of a ROLLBACK operation being performed when a record has been removed from the file. However, when you access a Btrieve file via Xfh2btr from within a transaction, the whole file is given a temporary exclusive file lock which prevents other users from accessing the file at the same time. In Btrieve v6.x and later, concurrent transactions are used, so files can be shared in a transaction.
A Btrieve transaction starts whenever a REWRITE, WRITE or DELETE operation is performed for a file that has no transaction in progress and has been opened with ROLLBACK. At this point, Btrieve obtains an exclusive lock on the file and this file lock remains until the transaction finishes, except when concurrent transactions are in use (Btrieve v6.x and later).
Notes:
The CLOSE operation does not re-start transactions because Btrieve CLOSE operations can only be performed when transactions are not active.
File-locked errors are returned by Xfh2btr at the time files are opened, as this is the only time that this COBOL system returns a file-locked error. Btrieve can return a file-locked error on accessing a file within a transaction, although this is converted to a record-locked error by Xfh2btr which is a status that could legitimately be returned by this COBOL system when accessing files within transactions.
With this COBOL system you can use the WRITELOCK directive to write a record to a file and obtain a lock on the record written. Locks are also obtained on records that are re-written to the file.
With Btrieve the record is first written or re-written to the file and then read back to obtain a lock on the record. This requires a number of calls to the Btrieve run-time with small time lapses between the calls. It is possible, therefore, for a second user to access the record and obtain a lock on the written record before it can be read back with a lock by the first user.
Btrieve does not normally conform to ANSI standards but, by default, the Xfh2btr call conversion module makes the necessary calls to the Btrieve run-time system in order to force it to emulate ANSI behavior. You can, however, choose to operate in non-ANSI mode by setting the FILETYPE Compiler directive to FILETYPE"6".
In this mode of operation, each Micro Focus File Handler operation is mapped to the nearest Btrieve run-time call and no attempt is made to conform to ANSI standards:
| COBOL I/O Call |
Btrieve Run-time Call |
|---|---|
| OPEN | Open |
| CLOSE | Close |
| WRITE | Insert |
| READ | Get |
| START | Get |
| DELETE | Get/Delete |
| REWRITE | Get/Delete |
| UNLOCK | Unlock |
| ROLLBACK | Abort transaction |
| COMMIT | End transaction |
A full list of Btrieve error messages is provided in the NetExpress online help file - look under Btrieve in the help file index.
If an error is returned by the Btrieve Record Manager, the Xfh2btr call conversion module maps the Btrieve error to a COBOL file status code which it returns to your program. These mappings are shown in the NetExpress online help file - look under Btrieve in the help file index.
Copyright © 1998 Micro Focus Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| File Handler API | Sorting Files | |