BTRIEVE Gateway

Comet includes the ability to communicate with specialized external software routines. These interfaces are accomplished via Comet gateways. The BTRIEVE gateway provides an interface between Internet Basic programs and the BTRIEVE file system.

BTRIEVE files are files that are standard for many network applications. These files are basically B-TREE or ISAM-type files that can be accessed via a unique index. With Comet's networking capabilities, Comet applications may want to access files on the network that are BTRIEVE files created by non-Comet applications. The BTRIEVE gateway supports access to these records from an Internet Basic application.

The BTRIEVE Record Manager must be loaded into the Comet workstation prior to the time that the BTRIEVE gateway is opened. The Record Manager then exists as a TSR in memory prior to the time that Comet is loaded. There are a number of parameters relevant to the start-up, all of which are described in the BTRIEVE documentation.

Note that the BTRIEVE application interface uses software interrupt 7BH to communicate with the Record Manager. This interrupt vector should be reserved for BTRIEVE.

Once the Record Manager is loaded, the following operation codes are available:

Code	Meaning
0	OPEN
1	CLOSE
2	INSERT
3	UPDATE
4	DELETE
5	GET EQUAL
6	GET NEXT
7	GET PREVIOUS
8	GET GREATER
9	GET GREATER OR EQUAL
10	GET LESS THAN
11	GET LESS THAN OR EQUAL
12	GET FIRST
13	GET LAST
14	CREATE
15	STAT
16	EXTEND
17	SET DIRECTORY
18	GET DIRECTORY
19	BEGIN TRANSACTION
20	END TRANSACTION
21	ABORT TRANSACTION
22	GET POSITION
23	GET DIRECT
24	STEP NEXT
25	STOP
26	VERSION
27	UNLOCK
28	RESET
29	SET OWNER
30	CLEAR OWNER
31	CREATE SUPPLEMENTAL INDEX
32	DROP SUPPLEMENTAL INDEX
33	STEP FIRST
34	STEP LAST
35	STEP PREVIOUS

The BTRIEVE Record Manager returns a status value after each operation an application performs. A value of 0 indicates that the operations was successful. The possible non-zero status codes that the Record Manager returns are described in the BTRIEVE documentation, and are too lengthy to list here.

Each BTRIEVE operation expects certain parameters to be supplied, and returns certain expected values. See the BTRIEVE documentation for the expected and returned values for each operation.

The BTRIEVE gateway expects the following parameters from an Internet Basic applications:

Data item	Length	Description
OPCODE	4.0	One of the codes from above
DATELEN	4.0	Length of the data buffer
KEYNUM	4.0	Which index you want to use
STATUS	4.0	Returned after an operation
FCB$	128	Returned by BTRIEVE after an OPEN. Must be used as supplied in all subsequent operations.
DATA$	xxx	Data to be written/read from/to a BTRIEVE file must be placed in the user's buffer with a WRITE or READ using a FORMAT statement to the gateway. The maximum buffer size is 1024 made up of variables of 254 bytes maximum.
KEY$	xxx	The BTRIEVE key

The parameters listed above must be supplied to the gateway by a PRINT followed by a variable list. The syntax of the PRINT statement is:

     PRINT (lun) OPCODE;DATALEN;KEYNUM;KEY$;FCB$;STATUS

where (lun) corresponds to the lun of the opened gateway. You will note that the actual data is not included in the PRINT list above. This is because BTRIEVE access requires a separate segment of memory to be used for the data. Under Internet Basic, this data segment is the user's buffer contained in the partition. Therefore, prior o each PRINT through the gateway to write data to the BTRIEVE file, the data must be written to the user's buffer. This is accomplished by an Internet Basic formatted WRITE of the data to the lun opened as the gateway. This WRITE places the data in the user's buffer. The next PRINT to the gateway with a OPCODE for WRITE will take the data from the user's buffer and write it to the BTRIEVE file.

In the same manner, following each PRINT to the gateway with an OPCODE for READ, the data from the BTRIEVE file must be read from the user's buffer. This is accomplished by an Internet Basic formatted READ of the lun opened as the gateway. The data will be moved from the user's buffer to the data variables specified in the READ format.

There are several different OPCODES that provide variants to the standard READ or WRITE. Note: PRINT with a list is always used to supply the BTRIEVE operation to the gateway. READs and WRITEs of data to the gateway should always be done with a FORMAT statement.

Example:

The following example shows how to read and write from the BTRIEVE gateway.

  4100    CLOSE (1) & OPEN (1) "G06"         ! open the gateway
          OPCODE = 0                         ! set opcode to OPEN
          DATALEN = 1024                     ! maximum buffer size
          KEYNUM = 255                       ! use index route #255
          KEY$="D:\BTRIEVE\ALPHA.SYS@00@"    ! set path for OPEN

          PRINT (1) OPCODE;DATALEN;KEYNUM;KEY$;FCB$;STATUS  ! open

          PRINT (0) "OPEN STATUS IS:";STATUS ! display the status

  4110    PRINT (0) "ENTER KEY NUMBER"       ! prompt
          INPUT (0) KEYNUM                   ! get key number
          IF KEYNUM EQ 999 THEN GOTO 4199    ! branch to end
          PRINT (0) "ENTER OPCODE"           ! prompt
          INPUT (0) OPCODE                   ! get opcode
                                             ! 12 = GET FIRST
                                             !  6 = GET NEXT

          DATELEN = 1024                     ! maximum data length
          KEY$ = STRING(" ",128)             ! fill with blanks

          PRINT (1) OPCODE;DATALEN;KEYNUM;KEY$;FCB$;STATUS

          READ (1,4100)                      ! read user's buffer

          PRINT (0) "BTRIEVE STATUS IS ";STATUS   ! display status
          PRINT (0) "DATA LENGTH IS ";DATALEN     ! display datalen
          PRINT (0) "KEY IS ";KEY$;""             ! display key
          PRINT (0) "DATA IS ";DATA$;""           ! display data
          GOTO 4110

  4199    INPUT (0) ""
          GOTO 0000