Handling C-ISAM Files

Byte-stream File Handling

Chapter 15: Handling Btrieve Files

Btrieve is the file handling system from Pervasive Software, Inc. For full details on Btrieve, consult the Btrieve documentation supplied by Pervasive Software.

This COBOL system provides call conversion modules which enable you to:

• Use the Callable File Handler API to process Btrieve files

• Use the Btrieve API to process COBOL format files

The call conversion modules are:

The following sections describe each call conversion module, how to invoke it, compatibility between Extfh and Btrieve I/O operations and, for Xfh2btr only, the environment variables which affect its behavior.

15.1 Handling Btrieve Files from COBOL

The Xfh2btr call converter, for Extfh to Btrieve call conversions, takes Extfh format I/O operations and converts them to Btrieve I/O calls. This enables you to handle Btrieve files from your COBOL programs.

The Xfh2btr call converter is compatible with versions of Btrieve 5.1x and above on the following environments:

• Btrieve for DOS

• Btrieve for OS/2

• Btrieve for Windows V3.0

• Btrieve for Windows 95 and Windows NT

• Btrieve NLM for NetWare

Notes:

• The Btrieve run-time is not supplied with this COBOL system. It is assumed that you already have a copy of the Btrieve run-time or a Btrieve Developer's Kit.

• The Pervasive Software requester software for use with the Btrieve interface is available from our Bulletin Board. For details of the Bulletin Board see your Getting Started.

• You are not allowed to distribute the Btrieve run-time to any third party unless you have entered into a License Agreement with Pervasive Software. Contact Pervasive Software for more information.

Xfh2btr 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 converter needs to call the Btrieve run-time 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 Record Manager. For example, the Btrieve Dynamic Link Library btrcalls.dll is called if the COBOL application is running on OS/2.

Notes:

• You can call the module _BTRV from your COBOL program using the same parameters as those used in Btrieve API calls.

• The _BTRV module for DOS must be called if the application is to be used with the Micro Focus Extended Memory Manager (XM). The dbtrv.obj module should be linked in if the application is to run as an executable file.

• When calling the _BTRV module when running under XM, the key buffer parameter on the API call must always be defined as at least 255 bytes long. In addition, valid parameters must be passed on every API call even if the Btrieve operation itself does not require the parameter. For example, the data buffer parameter must be a valid parameter of the length specified by the data buffer length parameter, even if this is not required by Btrieve itself.

When linking any application to a stand-alone executable file, you need to link in obtrv.obj for OS/2, dbtrv.obj for DOS and wbtrv.obj for Windows. Each of these modules has an entry point of _BTRV.

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.

15.1.1 Calling Xfh2btr

There are three ways to call the Xfh2btr call converter:

• Use the CALLFH Compiler directive

• Use the FILETYPE Compiler directive

• Use external filename mapping

Each of these methods is explained in the following sections.

15.1.1.1 CALLFH Compiler Directive

The CALLFH Compiler directive specifies the file handler used by your program for all COBOL I/O operations. If no file handler is specified, the default file handler, Extfh, is used.

To enable your program to pass all I/O to the Xfh2btr call converter so that COBOL I/O operations are converted to Btrieve I/O operations, you include CALLFH at the top of your source program as an initial $SET statement as follows:

$set callfh"xfh2btr"

All I/O performed by the program now passes to Xfh2btr.

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.

You can use this directive in combination with the FILETYPE directive. See the description of the FILETYPE directive below.

15.1.1.2 FILETYPE Compiler Directive

The FILETYPE Compiler directive specifies the file 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 so that it emulates ANSI behavior.

FILETYPE"6" is used when speed is important. In this mode of operation, each Extfh I/O operation is mapped to the nearest Btrieve run-time call. No attempt is made to conform to ANSI standards.

The differences between the two modes of operation are explained in the section File Operations without ANSI COBOL Conformance later in this chapter.

If you require sequential and relative files to be processed as Btrieve files, you must use the FILETYPE directive in conjunction with the CALLFH directive.

All I/O is initially passed to Extfh when used in conjunction with the CALLFH Compiler directive. Extfh then ensures that the file operation is supported by Btrieve before passing it to Xfh2btr.

You can mix different types of file within your program by putting the FILETYPE Compiler directive around individual SELECT statements, for example:

$set callfh
$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.

This causes I/O on testfile-1 to be handled by Extfh and I/O on testfile-2 to be handled by Xfh2btr.

15.1.1.3 External Filename Mapping

Using external filename mapping to call Xfh2btr enables you to direct file I/O for a particular file to the converter without the need to recompile your program with the CALLFH and/or FILETYPE Compiler directives. This method assumes that all I/O is currently being handled by Extfh.

On opening a file, Extfh automatically searches the run-time environment space to see if an environment variable of the same name as the file exists. If it does, the filename is mapped to the new name (if one is given) and the new format (if one is given). For example, in your program you may have the following SELECT statement:

$set callfh 
     select testfile-1 assign to "test-1.dat" 
         organization indexed 
         record key prime-key 
         access sequential.

If you enter the following command before running your program:

set test-1.dat=test-1.dat[BtrieveA]

an environment variable with the same name as the file is found and the file is mapped to a file of the same name, but in Btrieve format. The [BtrieveA] parameter following the name defines the file as Btrieve format with ANSI emulation. Specify [BtrieveN] for non-ANSI emulation.

External filename mapping requires the Xfhname module which you must link to any application that uses external filename mapping.

For further details of filename mapping, see the chapter File Naming.

15.1.2 Xfh2btr Environment Variables

There are two environment variables that you can set in order to change the way in which the Xfh2btr call converter operates: BTRPAGE and BTRMAXREC. These are described in the following sections and refer to both ANSI and non-ANSI modes of operation.

It is possible to specify the value of BTRPAGE and BTRMAXREC on a per-file basis using the xfh2btr configuration file. This provides more flexibility in defining page sizes and record lengths. See the section Xfh2btr Configuration File for more details.

15.1.2.1 BTRPAGE Environment Variable

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:

• The page size affects the number of keys you can define in the file and where the keys can occur in the record. See the sections Keys and Record Lengths later in this chapter for details.

• The Btrieve Record Manager needs to be loaded with the correct page size. See the Btrieve documentation provided by Pervasive Software for details.

15.1.2.2 BTRMAXREC Environment Variable

The BTRMAXREC environment variable determines the maximum record size returned on a direct opcode 06 call to the converter. The opcode 06 call is used by file utilities to determine details about the files being used.

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.

15.1.3 Differences Between Extfh and Xfh2btr

The majority of COBOL file operations performed by Extfh 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.

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 the same file.

The areas in which Btrieve differs from Extfh are:

Keys
Locked record detection
OPEN OUTPUT
Record lengths
Record reading position
Transaction processing
Write-locks

Each of these areas is described in the following sections.

15.1.3.1 Keys

Using Btrieve v5.x or earlier, the total number of key components (a normal key has one component, a split key has more than one) cannot exceed 24. So, you can have one key of 24 components, 24 keys of one component or any combination of these.

Using Btrieve v6.x or later, the maximum number of key components is 119, and varies depending on the page size of the file.

The Xfh2btr module does not verify the number of key components in the file; if your version of Btrieve does not support the required number of key components then any error returned from the Btrieve run-time system is reported to the application program.

The total length of any key in a Btrieve file cannot be greater than 255 bytes. The total length of a key is the sum of the lengths of all the components making up the key.

All keys in a Btrieve file must be completely contained within the fixed part of any variable length file. See the section Record Lengths later in this chapter for further information.

15.1.3.2 Locked Record Detection

When this COBOL system reads a record that is locked by another user, the record data is returned to the program together with a file status of "record-locked". The current reading position in the file is unaffected.

With Btrieve, if a record is locked, the data is not returned. Reading a record requires multiple calls to the Btrieve run-time, making the default record reading slower than if the non-ANSI conforming mode is used.

You can improve the speed of the read operations by:

• Opening the file with an exclusive lock.

  When you do this, calls to the Btrieve run-time to detect record locks are not required. This is because the file is locked exclusively and so records do not need to be individually checked.

• Using the NODETECTLOCK directive.

  Using this directive removes the need to call Btrieve to see if the record is locked by another user.

  Note that the non-ANSI conforming mode of operation includes the use of NODETECTLOCK.

• Accessing the file from within a transaction.

  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. When using Btrieve v6.x or later, concurrent transactions are used.

15.1.3.3 OPEN OUTPUT Operations

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. This means that a small time lapse exists between these two calls. It is therefore possible for a second user to access the file between the time 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.

15.1.3.4 Record Lengths

Variable length record Btrieve files consist of two parts - a fixed length part and a variable length part. Fixed length record Btrieve files consist of only the fixed length part.

Generally, the minimum record length defined in the COBOL program determines the length of the fixed part of the record. However, Btrieve imposes restrictions upon the maximum length of the fixed part of the record. This depends upon the number of keys which allow duplicates and the page size used for the file. See the section Specifying the Btrieve Page Size - BTRPAGE Environment Variable earlier in this chapter for details of page size.

The formula for determining the maximum size that the fixed part of the record can be 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

If you try to create a fixed length record Btrieve file with a record length greater than the maximum size allowed for the fixed part, then the file is created as a variable length Btrieve file. The size of the fixed part of the record used in the file definition is determined using the above formula.

If you attempt to create a variable length record Btrieve file with a minimum record length greater than the maximum size allowed for the fixed part, then the file is created with the fixed part set to the maximum size allowed.

Notes:

• Btrieve requires that all the keys are defined within the fixed part of the Btrieve record.

• Relative files are created as Btrieve keyed files with a four-byte auto-increment key at the front of each record. This processing of the key is transparent to the user program. However, the physical Btrieve file has a fixed record length four bytes larger than that calculated using the above formula.

Examples

The following examples use a page size of 1024 bytes:

• A fixed length record index file with a record length of 1018 bytes creates a fixed length record Btrieve file with a fixed record length of 1018 bytes.

  All the keys must be in the first 1018 bytes of the record.

• A fixed length record index file with a record length of 1019 bytes creates a variable length record Btrieve file with a fixed record length of 1014 bytes.

  All the keys must be in the first 1014 bytes of the record.

• A fixed length record index file with a record length of 1010 bytes and one key which allows duplicates creates a fixed length record Btrieve file with a fixed record length of 1010 bytes.

  All of the keys must be in the first 1010 bytes of the record.

• A fixed length record index file with a record length of 1011 bytes and one key which allows duplicates creates a variable length record Btrieve file with a fixed record length of 1006 bytes.

  All of the keys must be in the first 1006 bytes of the record.

• A fixed length record relative file with a record length of 1014 bytes creates a fixed length record Btrieve file with a fixed record length of 1018 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 Callable File Handler call interface, the record length returned is 1014 bytes.

• A fixed length relative file with a record length of 1015 bytes creates a variable length Btrieve file with a fixed record length of 1014 bytes. This is because you are limited to a maximum of 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 Callable File Handler call interface, the record length returned is 1010 bytes.

• A variable length record index file with a minimum record length of 1014 bytes creates a variable length record Btrieve file with a fixed record length of 1014 bytes.

  All of the keys must be in the first 1014 bytes of the record.

• A variable length record index file with a minimum record length of 1015 bytes creates a variable length record Btrieve file with a fixed record length of 1014 bytes.

  All of the keys must be in the first 1014 bytes of the record.

• A variable length record index file with a minimum record length of 1006 bytes and one key which allows duplicates creates a variable length record Btrieve file with a fixed record length of 1006 bytes.

  All of the keys must be in the first 1006 bytes of the record.

• A variable length record index file with a minimum record length of 1007 bytes and one key which allows duplicates creates a variable length record Btrieve file with a fixed record length of 1006 bytes.

  All of the keys must be in the first 1006 bytes of the record.

• A variable length record relative file with a minimum record length of 1010 bytes creates a variable length record Btrieve file with a fixed record length of 1014 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 Callable File Handler call interface, the record length returned is 1010 bytes.

• A variable length record relative file with a minimum record length of 1011 bytes creates a variable length record Btrieve file with a fixed record length of 1014 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 Callable File Handler call interface, the record length returned is 1010 bytes.

15.1.3.5 Record Reading Position

The file position indicator indicates the position in the file from which sequential READ operations are performed. So, for example, if the file position indicator is on the third record and a READ NEXT operation is performed, this system returns record number 4. Record number 4 is now defined by the Current Record Pointer (CRP).

With this COBOL system, the CRP is only affected when START, READ (sequential or random) and OPEN operations are performed on the file.

With the Btrieve run-time, the CRP is affected when WRITE, REWRITE and DELETE operations are performed on the file. This means that 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. In which case, 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.

Sequential READ Operations After WRITE Operations

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.

Sequential READ Operations After DELETE Operations

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.

Sequential READ Operations After REWRITE Operations

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

15.1.3.6 Transaction Processing

In this COBOL system, transaction processing is only available if you have installed Fileshare Version 2. However, Btrieve users do not require Fileshare Version 2 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. (Prior to COBOL V3.2 the READ, START or STEP operations also started a transaction.) 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).

Note: For Btrieve v6.x or above, concurrent Btrieve transactions are used. Btrieve then performs locking at the page level. (See the Btrieve documentation for details.)

A transaction finishes when a COMMIT or ROLLBACK operation is performed. The transaction restarts when I/O is performed again on a file which is opened with ROLLBACK.

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 the converter 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 the converter which is a status that could legitimately be returned by this COBOL system when accessing files with transactions.

15.1.3.7 Write-locks

With this COBOL system you can use the WRITELOCK directive to write records in 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.

Note: Using write-locks does not guarantee that the reading position in the file is kept. See the section Locked Record Detection.

15.1.4 File Operations Without ANSI COBOL Conformance

The following file operations differ when you choose non-ANSI conformance mode (use the FILETYPE"6" Compiler directive):

• Any run-time switches you set within this COBOL system are ignored by the Xfh2btr converter.

• The operation proceeds as if you had specified the NODETECTLOCK directive.

• No attempt is made to re-position the CRP after deleting, re-writing or writing records in the file.

• Each COBOL I/O call is mapped to its nearest corresponding Btrieve run-time call as follows:

  COBOL I/O Call	Btrieve Run-time Call
  OPEN	Open
  CLOSE	Close
  WRITE	Insert
  READ	Get
  START	Get
  DELETE	Get/Delete
  REWRITE	Get/Update
  UNLOCK	Unlock
  ROLLBACK	Abort transaction
  COMMIT	End transaction

15.1.5 Xfh2btr Configuration File

Note: If you want to use the Xfh2btr configuration file, you must link your program with mfini.obj.

Using the Xfh2btr configuration file, it is possible to define the following file attributes on a per-file basis:

• The page size that the file should have when it is created.

• The maximum record length that should be returned on an opcode 06 call.

• The open mode that should be used when making the Btrieve API call to open the file.

It is also possible to turn on a trace option which displays Btrieve error codes when they are returned and also the COBOL status that is returned to the application program.

The format of the configuration file is the standard Micro Focus configuration file format. The name of the configuration file is specified by the XFH2BTR environment variable. If this environment variable is not set then the default configuration filename of xfh2btr.cfg is used. This is searched for first in the current directory and then along the path specified by the COBDIR environment variable.

When using a configuration file the settings of the environment variables BTRPAGE and BTRMAXREC are ignored.

The tag "[X2B-DEFAULTS]" is used to specify the default page size and maximum record lengths and also the default open modes to use when opening a file.

A tag containing a filename (for example "[test1.dat]") can be used to specify the page size and maximum record length and also the open modes to use when processing a particular file.

The attributes that can be specified after each tag section are outlined below. The attribute-name can be separated from the attribute value by a space or colon (:) character.

BTRPAGE:nnnn

This specifies the page size that should be used when the file is created. See the section BTRPAGE Environment Variable for details of valid values for this attribute. If a configuration file is used, the settings of the environment variable BTRPAGE are ignored.

BTRMAXREC:nnnn

This specifies the maximum record length that should be returned on an opcode 06 call to this file. See the section BTRMAXREC Environment Variable for valid values for this attribute. If a configuration file is used, the settings of the environment variable BTRMAXREC are ignored.

Specifying File Open Modes

INPUT-EXCLUSIVE:    open-mode
INPUT-SHAREABLE:    open-mode
OUTPUT:             open-mode
EXTEND-SHAREABLE:   open-mode
EXTEND-EXCLUSIVE:   open-mode
I-O-SHAREABLE:      open-mode
I-O-EXCLUSIVE:      open-mode

These attributes can be used to change the Btrieve open mode that Xfh2btr uses when it opens the file. The possible values of open-mode are as follows:

normal
accelerated
read-only
verify
exclusive

Some of these open modes implicitly open the file exclusively on some versions of Btrieve. For example, with the single-user version of Btrieve, accessing a file in accelerated access implicitly makes the file exclusive to that user.

For details of these open modes, consult your Btrieve documentation.

If you do not specify open modes in a configuration file, the default open modes used by Xfh2btr are as follows:

Example

The following is an example of a configuration file:

[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 configuration file specifies the following:

• The default open mode for files opened output is accelerated.

• The default open mode for files opened I/O which are shareable is accelerated.

• The default open mode for files opened I/O which are exclusive is accelerated.

• The default page size to use when creating files is 2048 bytes.

• The default maximum record length to return on an opcode 06 call is 2000 bytes.

• For the file test1.dat, open output operations open the file exclusively.

• For the file test1.dat, open I/O operations which are shareable use the normal open mode.

• For the file test1.dat, the page size to use when creating the file is 4096 bytes.

15.1.6 Trace Option

Using a configuration file, it is possible to use a trace option to display the operations that the Xfh2btr module is performing and also the error codes returned from the Btrieve Record Manager. This option is especially useful when investigating problems with the configuration of the Btrieve Record Manager.

If a Btrieve error is not shown on the trace but a COBOL error is returned, this error is generated within the Xfh2btr module. For example, attempting to write to a file open for input would generate such an error. Even though a number of Btrieve API calls might be made to process one COBOL I/O statement only one Btrieve error status is displayed.

There are two attributes that effect the trace option: TRACE-FILE and TRACE. These are described below:

TRACE-FILE: filename

This specifies that the trace information is to be directed to a file and not to the screen. The name of the trace-file can be specified as an attribute value. If no trace-file is specified then the default trace filename of xfh2btr.lst is used. The trace-file attribute can only be specified under the [X2B-DEFAULTS] tag. When 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: This does not turn on the TRACE facility.

TRACE

This specifies that operations to this file are to be traced. The default is for the trace information to be displayed on the screen. This information can be directed to a file using the TRACE-FILE attribute described above. The trace attribute can be specified under the [X2B-DEFAULTS] tag (in which operations to all files are displayed) or under a filename tag (in which operations to only a select few files are displayed).

Examples

The following are examples of configuration files:

[X2B-DEFAULTS]
trace-file:x2btrace.dat
trace:

This configuration file specifies that the trace option is to be used for every file that is accessed and the trace is to be written to the file x2btrace.dat.

[X2B-DEFAULTS]
trace-file:
[test1.dat]
trace:

This configuration file specifies that the trace option is to be used for all accesses to the file test1.dat and the trace is to be written to the file xfh2btr.lst (the default trace filename).

[test1.dat]
trace: 

This configuration file specifies that the trace option is to be used for all accesses to the file test1.dat with the trace written to the screen.

[X2B-DEFAULTS]
trace:

This configuration file specifies that the trace option is to be used for every file that is accessed with the trace written to the screen.

[X2B-DEFAULTS]
open-output:exclusive
trace-file:trace.lst
[test1.dat]
btrpage:1024
[test2.dat]
open-output:accelerated
btrpage:4096
trace:

This configuration file specifies that, by default, files opened output are opened in exclusive mode. The trace-file trace.lst is used for all trace information. For the file test1.dat the page size to use when the file is created is 1024 bytes. When the file test2.dat is opened output, accelerated open mode is used. The page size to use when test2.dat is created is 4096 bytes, and all access to the file is traced.

The following is an example of the trace output produced when the trace option is used:

Line 1 shows an example input line: the operation code and the name of the file on which the operation is being performed. For details on operation codes see the chapter The Callable File Handler.

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.

15.2 Handling COBOL Files from Btrieve

The Btr2xfh call converter takes Btrieve I/O calls and converts them to Extfh I/O operations enabling you to handle COBOL format files from Btrieve.

The Btr2xfh call converter is compatible with Btrieve 5.1x and above.

Btr2xfh and Extfh replace the modules supplied by Pervasive Software. All of the calls that would normally go to the Btrieve Record Manager are passed to Btr2xfh and are then passed to the COBOL file handling system.

The converter is supplied as a linkable module, btr2xfh.obj , which you should link with any application that is to perform I/O via Btr2xfh on COBOL files.

The entry point into the module is _BTRV and requires the same seven parameters that would normally be passed from a COBOL application to a Btrieve record manager.

The Btr2xfh module is designed to replace the COBOL interface module supplied with the Btrieve Software Developer's Kit by Pervasive Software.

15.2.1 Differences between Btrieve and Extfh

The majority of Btrieve file operations behave in exactly the same way when Extfh is used. However, due to underlying differences between the two systems, there are instances where behavior differs. Those areas are:

Data compression
File operations
Indices
Key lengths
Key types
Page size
Record size
Stat operation

Each of these areas is described in the following sections.

15.2.1.1 Data Compression

Creating a file with data compression causes data and key compression to be used on the file.

15.2.1.2 File Operations

The following Btrieve file operations are supported by Extfh:

Abort Transaction
Begin Transaction
Close
Create
Delete
End Transaction
Get Direct
Get Directory
Get Equal
Get First
Get Greater
Get Greater or Equal
Get Key
Get Last
Get Less than
Get Less than or Equal
Get Next
Get Position
Get Previous
Insert
Open
Set Directory
Stat
Step First
Step Last
Step Next
Step Previous
Unlock
Update

The locking and key-only operations are also supported.

15.2.1.3 Indices

Only permanent indices are supported. Once you have created a file you cannot add or delete a file index.

15.2.1.4 Key Lengths

The total length of a single key in Extfh cannot exceed 1016 bytes. This is the sum of the lengths of any component making up a split or segmented key. The total number of key components in a file cannot exceed 255.

15.2.1.5 Key Types

The following points apply to keys when using Btr2xfh:

• Extfh has only one type of key. This is the equivalent of the Btrieve format string and on a Btrieve Stat operation , all of the keys are returned as having string format.

• Keys are stored in ascending order and are always modifiable.

• When performing comparisons, the keys are compared on a byte by byte basis from left to right.

• Null keys are supported, although the NULL character is not returned on a Btrieve Stat operation.

• The key attributes Duplicates and Segmented are supported.

15.2.1.6 Page Size

Extfh has no concept of page size, so page size parameters are not required. Page size is not returned on a Btrieve Stat operation.

15.2.1.7 Record Size

The maximum record size with Extfh is 62 Kbytes.

15.2.1.8 Stat Operation

The bits set in the file flags and the fields set in the file specification in Extfh differ from those set when the Btrieve Stat operation is used. The following lists the bits and fields set when using the Stat operation. All other flags and fields are returned set to zero.

Bits set in the file flags:

    variable length record
    data compression

Bits set in the key flags:

    duplicates allowed
    key has another segment

    The modifiable flag is always set.

Fields set in the file specification:

    record length
    number of indices
    file flags (see above)

15.3 Btrieve Error Codes

The following is a list of Btrieve error codes which have been adapted from the Btrieve Installation and Operations manual supplied by Pervasive Software. Where appropriate, an action to resolve the problem is given.

For each Btrieve error status, the COBOL status it is mapped to is also shown.

 The operation parameter is invalid.

• This status should not be encountered if using the XFH2BTR module. Ensure that the version of Btrieve being used is 5.1x or above.

 The application encountered an I/O error.

 The file is not open.

• This status should not be encountered if using the XFH2BTR module as the XFH2BTR module generates the appropriate status without calling the Btrieve run-time system.

 The key value cannot be found.

 The record has a key field containing a duplicate key value.

 The key number parameter is invalid.

• If calling XFH2BTR directly, this indicates that the key-id field in the FCD is incorrect

 The key number has changed.

• This error should not be encountered if using the XFH2BTR module.

 The current positioning is invalid.

• This indicates that it is not possible to reposition the current record pointer after an operation and that the current positioning is invalid. The positioning needs to be re-established using a READ or START operation.

 The operation encountered an end-of-file mark.

 The key field is not modifiable.

• An attempt was made to perform a REWRITE operation where an attempt to change a key value was made when the key is defined as non-modifiable in the file.

• The XFH2BTR module will create the primary key as non-modifiable and the alternate keys as modifiable. This error implies that the Btrieve file was created outside of the COBOL system, and that an alternate key is defined as non-modifiable.

 The specified filename is invalid.

• Note that Btrieve filenames cannot have an extension '^^^'.

 Btrieve cannot find the specified file.

• Note that you must have FILE SCAN access rights to the directory to where the file resides if the file is on a server.

 Extended file error.

• Btrieve v5.x or earlier could not find the extension file for an extended file that the application tried to open. The XFH2BTR module does not extend files and so that implies that the file was created outside of the COBOL system. Ensure that the required extended file is available (extension files must be loaded on the logical disk drive specified when the extension was created). Both the primary file and its extension file must be online to access an extended file.

 Btrieve cannot create or open the pre-image file.

• Note that pre-image files are only used of file versions prior to v6.0

 The application encountered an I/O error during pre-imaging.

• Note that pre-image files are only used of file versions prior to v6.0

 The application encountered an expansion error.

• The XFH2BTR module does not expand files and so this error should not be encountered.

 The application encountered a close error.

 The disk is full.

 The application encountered an unrecoverable error.

 The Btrieve Engine or Requester is inactive.

• In DOS and NetWare, you must load Btrieve and, if applicable, the Btrieve Requester before generating any requests.

• By default, in the Windows environment, the Setup utility turns on the Client Engine Usage option. If you want to access server-based Btrieve but do not want to access client-based Btrieve, turn the Client option off and turn the Requester option on. If you want to access both client-based Btrieve and server-based Btrieve, turn the Requester option on and leave the Client option on.

• Also, in the Windows environment, be sure that the Btrieve for Windows DLLs and WBTR32.EXE are on your PATH or in the top level of your Windows directory. In the OS/2 environment, be sure that the Btrieve DLLs are in your LIBPATH directory.

• If the problem persists, ensure that the Btrieve run-time system is configured and running by performing a -STAT function on the file you are attempting to access. The -STAT operation is available with the BUTIL and BTRTOOLS utilities supplied by Pervasive Software.

 The key buffer parameter is too short.

• This error should not be encountered if using XFH2BTR.

 The data buffer parameter is too short.

• This implies that the record area defined in the program is not large enough to hold the record that is being read from the Btrieve file. Ensure that the record area is large enough.

• This status can also indicated a file corruption, especially in files with variable length records.

 The position block parameter is not 128 bytes long.

• This error should not be encountered if using XFH2BTR.

 The page size or date buffer size is invalid.

• Ensure that the setting of the BTRPAGE environment variable is correct. The page size must be a multiple of 512 bytes, with a maximum value of 4096. With Btrieve versions prior to 6.1, this status code can indicate that the page size of the file being opened is larger than that specified in the Largest Page Size configuration option. Configure Btrieve with the correct Largest Page Size option.

 The application cannot create the specified file.

 The number of keys is invalid.

• The number of keys allowed for the page size is invalid. The number of key segments must be within the following limits (for Btrieve v6.x format files):

  Page Size	Max. Number Key Components
  512	8
  1024	23
  1536	24
  2048	54
  2560	54
  3072	54
  3584	54
  4096	119

 The key position is invalid.

• The key field position specified is less than 1 or exceeds the defined (fixed) record length for the file. Either the key position is greater than the fixed record length or the key position plus the key length exceeds the fixed record length.

 The record length is invalid.

• The record length specified (plus overhead for duplicates, record usage count, variable record pointer, key pointer and blank truncation information) must be less than or equal to the page size minus 8 bytes and greater than or equal to 4 bytes.

• Ensure that the page size is set correctly. See the section Specifying the Btrieve page size, BTRPAGE Environment Variable.

 The key length is invalid.

• The key length specified must be greater than 0 but cannot exceed 255 bytes. Btrieve requires that each key page in the file is large enough to hold at least 8 keys.

• Ensure that the page size is set correctly. See the section Specifying the Btrieve Page Size - BTRPAGE Environment Variable.

 The file specified is not a Btrieve file.

 The file is already extended.

• This status should not be encountered by XFH2BTR as files are never extended.

 The file cannot be extended.

• This status should not be encountered by XFH2BTR as files are never extended.

 Btrieve cannot be unloaded.

• This status should not be encountered by XFH2BTR.

 The specified extension name is invalid.

• This status should not be encountered by XFH2BTR as files are never extended.

 The application encountered a directory error.

• This status should not be encountered by XFH2BTR as directory operations are not used.

 The application encountered a transaction error.

• Btrieve tried to perform a Begin Transaction operation without configuring Btrieve to allow transactions. Ensure that the Btrieve Record Manager is configured to allow transactions.

  Note that the XFH2BTR module will attempt to start a transaction on the first updating operation (REWRITE, WRITE, DELETE) after a file (with the WITH ROLLBACK clause specified in the SELECT statement) has been opened or after a COMMIT or ROLLBACK statement has been processed.

 Another transaction is active.

• This status should not be encountered by XFH2BTR.

 Btrieve enountered a transaction control file I/O error.

 A Begin Transaction operation must precede an End/Abort Transaction operation.

• This status should not be encountered by XFH2BTR

 The file access request exceeds the maximum number of files allowed.

 Btrieve does not allow the attempted operation.

• This status should not be encountered by XFH2BTR

 A file previously opened in Accelerated mode was not closed.

• The application tried to open a Btrieve v5.x file that was previously accessed in Accelerated mode by Btrieve v5.x and never successfully closed. Another cause is that your application tried to open a v5.x format Btrieve file using a v5.x Btrieve engine, however that same file was previously accessed by a Btrieve v6.x engine, which failed to close the file successfully due to an unrecoverable error.

 The specified record address is invalid.

• The record address specified in a READ DIRECT (Get Direct) operation is invalid. This can occur if an invalid record address is specified when doing a READ DIRECT operation (calling XFH2BTR directly) is invalid.

 The specified key path is invalid.

• The application tried to use the Get Direct operation to establish an index path for a key whose value is null in the corresponding record. Btrieve cannot establish positioning based on a null key value.

 The specified key flags are invalid.

• This status should not be encountered if using XFH2BTR.

 Access to the requested file is denied.

• The application opened a file in read-only mode and tried to perform an Insert, Update or Delete operation on that file.

• An attempt was made to perform an Insert, Update or Delete operation on a file that is flagged read-only to NetWare, DOS, Windows 95 or Windows NT.

  Note that XFH2BTR attempts to perform an Update operation in order to detect record locks. Use the NODETECTLOCK directive is this error is returned and you are not performing a WRITE, DELETE or REWRITE operation.

• The owner name required for updates was not specified correctly when the file was opened.

  It is not possible to specify an owner name when using XFH2BTR to access Btrieve files.

 The number of files opened exceeds the maximum allowed.

• The number of files opened in Accelerated mode exceeded the number of buffers available in Btrieve's cache. In client-based versions of Btrieve prior to v6.0, you should reconfigure Btrieve both with a smaller page size configuration (to allocate more buffers) and a larger memory size option. You will not encounter this error either in v6.x client-based Btrieve, or in server-based Btrieve.

 The alternate collating sequence definition is invalid.

• This error should not be encountered as XFH2BTR does not use alternate collating sequences.

 The extended key type is invalid.

• This error should not be encountered as XFH2BTR does not use extended key types or alternate collating sequences.

 The file owner is already set.

• This error should not be encountered as XFH2BTR does not set ownership of files.

 The owner name is invalid.

• This error should not be encountered as XFH2BTR does not set ownership of files.

 The language interface version is invalid.

• This error should not be encountered as XFH2BTR uses the v5.1 language interface.

 The variable-length portion of the record is corrupt.

 The application specified an invalid attribute for an auto-increment key.

• This error should not be encountered using XFH2BTR.

 An index is incomplete.

• An index can be damaged if a Create Index operation or a Drop Index operation is interrupted before it runs to compilation. Perform a Drop Index operation to completely remove the damaged index from the file.

 The compression buffer length is too short.

• The application tried to read or write a record that is longer than the value specified for the size of the compression buffer. Reconfigure Btrieve specifying a higher value for the Largest Compressed Record Size option.

 The specified file already exists.

• This error should not be returned using XFH2BTR.

 The specified reject count has been reached.

• This error should not be returned using XFH2BTR as Extended operations are not used.

 The work space is too small.

• This error should not be returned using XFH2BTR as Extended operations are not used.

 The descriptor is incorrect.

• This error should not be returned using XFH2BTR as Extended operations are not used.

 The data buffer parameter specified on an Insert Extended operation is invalid.

• This error should not be encountered as XFH2BTR does not use the Insert Extended operation.

 The filter limit has been reached.

• This error should not be encountered as XFH2BTR does not use Extended operations.

 The field offset is incorrect.

• This error should not be encountered as XFH2BTR does not use Extended operations.

 The maximum number of open databases has been exceeded.

 Btrieve cannot open the SQL data dictionary files.

 Btrieve cannot perform the RI Delete Cascade operation.

 The Delete operation specified a file that is damaged.

 There is a violation of the RI definitions.

 Btrieve cannot open the RI-referenced file.

 The RI definition is out of sync.

 Btrieve aborted the transaction.

 Server routing list too small.

 There is a conflict on the referenced file.

 The application encountered a wait error.

 Btrieve detected a deadlock condition.

 A programming error occurred.

 Btrieve encountered a record-level conflict.

 Btrieve encountered a lock error.

 Btrieve lost positioning.

• The position of the current record pointer must be re-established using a START or READ (random) operation.

 Btrieve attempted to read a record outside the transaction.

 The record or page is locked.

 The file is locked.

 The file table is full.

 The handle table is full.

 The application encountered an incompatible mode error.

 Redirected device table full.

• Reload the Requester specifying a larger number for either the Number of File Servers (/S) option or the Number of Mapped Drives (/R) option.

 The application encountered a server error.

 The transaction table is full.

• Reconfigure Btrieve specifying a higher value for the Number of Transactions configuration option.

 The record lock types are incompatible.

• This error should not be encountered if using XFH2BTR.

 The application encountered a permission error.

 The session is no longer valid.

 A communications environment error occurred.

 The data buffer is too small.

• Perform one or both of the following:
  • Increase the size of the message buffer by configuring Btrieve with a higher value for the Largest Record Size .

  • Reload the Btrieve Requester and specify a higher value for the Message Buffer Size.

 Btrieve detected an internal transaction error.

 Btrieve requester unable to access NetWare Runtime server.

 No cache buffers are available.

• Reconfigure Btrieve with a higher value for the Cache Allocation option.

 Insufficient operating system memory is available.

 Insufficient stack space is available.

 The chunk offset is too big.

• This error should not be encountered as XFH2BTR does not use the Chunk operations.

 Btrieve does not recognize the locale.

 The file cannot be created with Variable-tail Allocation Tables (VATs).

 The chunk cannot perform a Get Next operation.

• This error should not be encountered as XFH2BTR does not use the Chunk operations.

 The application attempted to perform a chunk operation on a pre-v6.0 file.

• This error should not be encountered as XFH2BTR does not use the Chunk operations.

 The application's transaction has become too complex.

 Btrieve ran out of system locks.

 More than 5 concurrent users attempted to access the same Btrieve file.

• This error only occurs on the Developer Kit version of client-based Btrieve which limits the number of concurrent users of a file to five engines.

15.3.1 Summary of COBOL Status Codes

• Any error returned by Btrieve that is not in the above list will be returned as a 9/025 error.

Handling C-ISAM Files

Byte-stream File Handling