HP 3000 Manuals HP 3000 Manuals
Btrieve Call Conversion Modules
This COBOL system provides two call conversion modules which enable Extfh
to call Btrieve and Btrieve to call Extfh, where:
Extfh is the external file handler for this COBOL system.
Btrieve is the file handling system from Novell Inc. For further
details of Btrieve, you should consult your Novell
documentation.
The call conversion routines are:
Xfh2btr for Extfh to Btrieve call conversions (supported on DOS,
Windows and OS/2 only). Xfh2btr takes Extfh format I/O
operations and converts them to equivalent Btrieve I/O
calls. (DOS, Windows and OS/2)
Btr2xfh for Btrieve to Extfh call conversions. Btr2xfh takes
Btrieve format I/O operations and converts them to
equivalent Extfh format calls.
The following sections describe each call converter, how you invoke them,
compatibility between Extfh and Btrieve I/O operations and, for Xfh2btr,
environment variables that affect the behavior of this call converter.
Xfh2btr Call Converter (DOS, Windows and OS/2 only)
The Xfh2btr call converter, for Extfh to Btrieve call conversions, takes
Extfh format I/O operations and converts them to Btrieve I/O calls.
Xfh2btr is only available on DOS, Windows and OS/2 systems.
The Xfh2btr call converter is compatible with versions of Btrieve 5.1x
and above on the following platforms:
* Btrieve for DOS
* Btrieve for OS/2
* Btrieve for Windows
* Netware Btrieve NLM
NOTE
* The Btrieve run-time is not supplied with this COBOL system.
We assume that if you want to use the converter, you already
have a copy of the Btrieve run-time or a Btrieve Developer's
Kit.
* You are not allowed to distribute the Btrieve run-time to
any third party unless you have entered into a License
Agreement with Novell. Contact Novell for more information.
* The Novell requester software for use with the Btrieve
interface is available from our Bulletin Board. For details
of the Bulletin Board see your Getting Started.
Xfh2btr is supplied as part of the COBOL system and also as a linkable
module, XFH2BTR.OBJ, which can be linked with any application that is to
perform I/O via the converter 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 the module is to format the call
and pass the call to the Btrieve Record Manager that is being used. For
example, the Btrieve Dynamic Link Library BTRCALLS.DLLis called if the
COBOL application is running on OS/2.
NOTE
* You can call the module _BTRV direct from a COBOL program
using the same parameters that are used in Btrieve API
calls. However, the "key buffer" parameter must be at least
255 bytes long.
* The _BTRV module for DOS must be called if the application
is to be used with the Micro Focus Extended Memory Manager
(XM), which is available as an add-on product.
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 Novell in place of _BTRV.OBJ. These are
COBRBTRV.OBJand COBPBTRV.OBJ. For more details of these modules, see the
Novell documentation supplied with the Btrieve Developer's Kit.
Calling Xfh2btr.
There are three ways to call the Xfh2btr call converter and direct Extfh
I/O from a COBOL program to the converter:
* using the CALLFH compiler directive
* using the FILETYPE compiler directive
* using external file-name mapping
These are explained in the following sections.
CALLFH Compiler Directive .
The CALLFH directive specifies that your program uses a specific file
handler for all COBOL I/O operations. If no file handler is specified,
the default of 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 and not to Extfh
or the Run-Time System. See the appendix Directives for Compiler later
in this manual for further details of CALLFH.
Note that some file operations and formats are not supported with
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 at run time.
You can use this directive with the FILETYPE directive to determine if
ANSI conformance is to be emulated. See the description of the FILETYPE
directive below.
FILETYPE Compiler Directive .
The FILETYPE directive tells the COBOL system which file type you want
your file to be.
You can put the FILETYPE Compiler directive at the top of the source
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 with the file operations. 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 for the application. 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.
All I/O is initially passed to Extfh. Extfh then ensures that the file
operation is supported by Btrieve before passing it to Xfh2btr.
You can also put this compiler directive around individual SELECT
statements in the source program so that you can mix files of different
formats within the same program. 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 is directed via the Xfh2btr call converter.
The differences between the two mode of operation are explained in the
section File Operations without ANSI COBOL Conformance later in this
chapter.
See the appendix Directives for Compiler later in this manual for further
information on FILETYPE.
External File-name Mapping.
Using external file-name mapping to call Xfh2btr allows 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.
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 file-name 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.
Before running your program, if you enter the following command line:
set test-1.dat=test-1.dat[BtrieveA]
and then run your program, an environment variable with the same name as
the file is found and the file is mapped to the same name but in Btrieve
format. The [BtrieveA] parameter following the name defines the file as
Btrieve format with ANSI emulation. You specify [BtrieveN] for non-ANSI
emulation. See the section Environment Variables below for further
information.
External file-name mapping uses the Xfhname modulewhich you should also
link to any application that uses this method of mapping file-names.
For further details of file-name mapping, see the chapter External File
Mapper.
Changing Xfh2btr Operation using Environment Variables.
There are two environment variables that you can set which 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.
BTRPAGE Environment Variable.
The BTRPAGE environment variable specifies the page size that is used
when Btrieve files are created. Set it using the following operating
system command line:
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.
NOTE
* 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 Novell for details.
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 set BTRMAXREC using the following operating system command line:
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 that
will be accessed.
If you do not set BTRMAXREC, the default value of 32 Kilobytes is used.
File Operation 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 when the behavior and characteristics of Btrieve will be
different.
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 behaves differently to Extfh are:
Keys
Locked record detection
OPEN OUTPUT
Record lengths
Record reading position
Transaction processing
Write-locks
The differences between these file operations and how they vary if ANSI
emulation is to be performed are explained in the following sections.
Keys.
Using Btrieve, the total number of key components (a normal key has one
component, a split key has more than one) cannot exceed 24. Therefore,
you can have one key of 24 components, 24 keys of one component or any
combination of these.
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.
Locked Record Detection.
When this COBOL system reads a record that is locked by another user, the
record data and a "record-locked" status is returned. The current
reading position in the file is unaffected.
With Btrieve, locked record 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 obtain record
locking statuses are not performed. This is because the file is
locked exclusively and so records do not need to be individually
locked.
* 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 within a transaction.
When you access a Btrieve file from within a transaction, a
temporary exclusive lock is obtained on the file. Btrieve does
not use record locks on files in transactions and so calls the
Btrieve run-time to detect that record locks are not required.
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. So, it is 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 will find the file empty and an attempt to
read the file will result in an "at end" error. The user performing the
OPEN OUTPUT receives a "file locked" error because the exclusive OPEN
call fails.
Record Lengths.
The maximum length of a fixed length record depends on the number of keys
which allow duplicates and the page size used for the file. See the
section BTRPAGE Environment Variable earlier in this chapter for details
of page size.
If the page size is P and the number of keys that allow duplicates is K,
the maximum fixed record length is given by the following formula:
Maximum Fixed Record Length = P - 6 - (8*K)
If you attempt to create a Btrieve file with a fixed record length
greater than that allowed by the above formula, the file is created as a
variable length file and an error is not returned. However, all keys in
the file must be contained in the fixed part of the record.
For variable length files, if the minimum record length is greater than
the maximum fixed record length, the minimum record length is set to the
maximum fixed record length for that file. All the keys in the file have
to be contained within the minimum record length.
For example, with a page size of 4096 and a file which has three keys,
two of which allow duplicates, the maximum fixed record length is:
4096 - 6 - (8*2) = 4074
As the maximum page size for a Btrieve file is 4096, the same algorithm
should be used to determine the byte range for keys in variable length
files since Btrieve requires that all keys reside in the fixed portion of
the record.
Using the above example, again on a file which has three keys, two of
which allow duplicates:
* a fixed length record of length 8000 bytes is stored as a variable
length Btrieve file with a minimum record length of 4074. All
keys in the file must be within the first 4074 bytes of the
record.
* a variable length record with a size varying between 5000 and 8000
bytes is stored as a variable length Btrieve file with a minimum
record length of 4074 bytes. All keys in the file must be within
the first 4074 bytes of the record.
* a fixed length record of length 4000 bytes is stored as a fixed
length Btrieve file with a record length of 4000 bytes. This is
because 4000 bytes is within the limit of 4074 bytes for this
file.
Record Reading Position.
The file position indicatorindicates 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 CurrentRecord 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 repositioning of the CRP can fail if the
record to be repositioned on has been deleted by another user. In which
case, any attempt to perform a sequential READ returns an error.
You should note that if the file is opened exclusively, it is not
possible for a user to delete the record and the repositioning will
always succeed.
In the following sections, repositioning 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 repositioning the CRP.
NOTE The non-ANSI conforming mode of operation makes no attempt to
reposition the CRP and can, therefore, be significantly faster.
Sequential READ Operations after WRITE Operations.
For shared files opened I/O, 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 WRITELOCKdirective, the inserted
record has to be read back with a lock and this changes the CRP in the
file.
You should note that repositioning the Btrieve file position indicator
after a WRITE operation can only fail if WRITELOCK directives are used
and the file is shareable. If the repositioning 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 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 reposition on has been deleted.
You should note that 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 repositioning is not necessary.
Sequential READ Operations after REWRITE Operations.
For files opened I/O with random 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
reposition has been deleted.
You should note that 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 repositioning is not necessary.
Transaction Processing.
In this COBOL system, Transaction Processing is only available if you
have the Fileshare Version 2 product installed. This is supplied as part
of an add-on product. However, Transaction Processing is available to
users of Btrieve without Fileshare.
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 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.
A Btrieve transaction starts the first time I/O is performed on a file
that 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.
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 restart 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.
Write-locks.
The WRITELOCK directive enables a user of this COBOL system to write
records in a file and obtain a lock on the record written. Locks are
also obtained on records that are rewritten to the file.
With Btrieve the record is first written or rewritten 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 during which small time lapses exist
between the calls. It is, therefore, possible 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 will be kept. See the section Locked Record Detection.
See the appendix Directives for Compiler for further information on the
WRITELOCK directive.
File Operations without ANSI COBOL Conformance.
The following file operations differ when you choose non-ANSI conformance
mode (using the FILETYPE"6" directive):
* Any run-time switches you set within this COBOL system are ignored
by the Xfh2btr converter.
* Operation proceeds as if you had specified the NODETECTLOCK
directive.
* No attempt is made to reposition the CRP after deleting, rewriting
or writing records in the file.
* Each COBOL I/O verb is mapped to its nearest corresponding Btrieve
run-time call as follows:
COBOL I/O Verbs Btrieve run-time calls
OPEN Open
CLOSE Close
WRITE Insert
READ Get
START Get
DELETE Get/Delete
REWRITE Get/Update
UNLOCK Unlock
ROLLBACK Abort transaction
COMMIT End transaction
Your Btrieve Programmer's Manual contains more information of how
these Btrieve functions operate.
Btr2xfh Call Converter
The Btr2xfh call converter, for Btrieve to Extfh call conversions, takes
Btrieve I/O calls and converts them to Extfh format I/O operations.
Btr2xfh and Extfh replace the modules supplied by Novell. 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. (DOS, Windows and OS/2)
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 Novell's Btrieve Developer's Kit that would normally be
linked to the application.
If you have Fileshare Version 2, supplied in an add-on product, you use
Fhredir instead of Extfh. Fhredir is the client module of the Fileshare
system. It sends I/O requests to Extfh on the server for server based
files and a local copy of Extfh for local files. The call interface to
Fhredir is exactly the same as that for Extfh and its use is transparent.
Btr2xfh calls Fhredir when it needs to perform I/O. If you do not have
Fileshare active, then Fhredir calls a local copy of Extfh.
The following sections refer to calling Extfh even though it is Fhredir
that is called.
File Operation Differences between Btrieve and Extfh.
The majority of Btrieve file operations behave in exactly the same way
when Extfh is used. However, due to the underlying differences
between the two systems, there are instances when the behavior and
characteristics of Extfh are different to those of Btrieve.
The areas in which Extfh behaves differently from Btrieve are:
Data compression
File operations
Indices
Key lengths
Key types
Page size
Record size
Stat Operation
These differences are described in the following sections.
Data Compression.
Creating a file with data compression causes data and key compression
to be used on the file.
File Operations.
The following Btrieve file operations are supported by Extfh:
Abort Transaction
Begin Transaction
Close
Create
Delete
End Transaction
Open
Insert
Get Direct
Get Equal
Get Next
Get Previous
Get First
Get Last
Get Greater
Get Greater or Equal
Get Less than
Get Less than or Equal
Get Key
Get Position
Get Directory
Step Next
Step Previous
Step First
Step Last
Set Directory
Stat
Unlock
Update
The locking and key-only operations are also supported.
Indices.
Only permanent indices are supported. You cannot add or delete a file
index once you have created it.
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.
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 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.
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.
Record Size.
The maximum record size with Extfh is 62 Kbytes.
Stat Operation.
The bits set in 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)