Index Sequential and Fulltext Retrieval Developer Toolkit / Programming Interfaces / Fabs Plus Compatible Entry Points

FATS - Fast Access Tree System
	Table of Contents
		Programming Interfaces
			Fabs Plus Compatible Entry Points

Fabs Plus Compatible Entry Points

FABSMB (Basic Compiler)
FBSVBDOS (Visual Basic)
FBSPAS (MS Pascal)
FBPAS1 (MS Pascal)
FBSFOR (MS Fortran)
FBSCOB (MS Cobol)
GFSEG (ALL)
GFSEG1 (ALL)
KEYADR (ALL)

To the compatibility with the file administration FABS Plus all programming interfaces of this software were reproduced.

If you operate already longer time with FABS Plus you don´t have to read the following pages for the functionality of the specified interfaces is the same as with FABS. You just need to change obj-/dll files to use FATS in existing projects, for example in the MS-DOS environment you only have to replace the FABSP.OBJ module with the FATS.obj module.

By using the following described interfaces you have to consider the fact that FABS plus operates only with record numbers of 1-65535. Because FATS does not know a limitation in the number of data records, the Get Record # High (X) command must be consulted for the completion of the record number, if the FABS Plus compatible interfaces are used.

FABSMB (MS Basic Compiler)

At this entry point, which is normally used by the Microsoft Basic compiler, 4 pointers on the variables CMND$, ERRORCODE%, RECNO% and KEYADR% are transferred to FATS. All pointers are NEAR pointers (non-segmented) and refer to the data segment register (DS).

The command string (CMND$) possesses a header record which contains specification concerning the length and the address of the basic string:

2 bytes Length of string
2 bytes Offset of string to the data segment (DS)

Before returning to BASIC FATS removes the four pointers (8 bytes) of the stack and writes the return values into the appropriate variables. The returned address of the key value (KEYADR) refers to the FATS segment and can be completed with the call of GFSEG.

A typical function call from BASIC could look as follows:

CALL FABSMB(CMND$, ERRORCODE %, RECNO%, KEYADR%)

FBSVBDOS (MS Visual Basic for DOS)

At this entry point, which is normally used by the Microsoft Visual Basic compiler, 4 pointers on the variables CMND$, ERRORCODE%, RECNO% and KEYADR% are transferred to FATS. All pointers are NEAR pointers (non-segmented) and refer to the data segment register (DS).

In Visual Basic for DOS the strings are not as in past versions of BASIC in one data segment but are distributed on different data segments (heaps). Thus the structure of the string header record changed in relation to Microsoft Basic:

The string header record has the following structure:

2 bytes Offset of string (in respective string-heap)
2 bytes Offset of the segment address of heap

A typical function call from Visual Basic could look as follows:

CALL FBSVBDOS(CMND$, ERRORCODE%, RECNO%, KEYADR%)

FBSPAS (MS Pascal)

At this entry point, which is normally used by the Microsoft Pascal compiler, 2 pointers on the variables CMND and ERRORCODE are transferred to FATS. All pointers are FAR pointers (segmented).

The first byte of the command string (CMND) defines the length of the pascal string:

1 Byte Length of string (0 - 255)
? Bytes String content

Before returning to pascal FATS removes the two pointers (8 bytes) of the stack and writes the return values into the appropriate variables. The record number is transferred via the AX register.

A typical function call from pascal could look as follows:

RECNO := FBSPAS(CMND^, ERRORCODE);

FBPAS1 (MS Pascal)

Upon entry at FBPAS1, an integer and 3 pointers on the variables CMND, ERRORCODE and KEYADR are transferred to FATS. All pointers are FAR pointers (segmented). The leading integer is used by MS Pascal when passing LSTRING´s and is ignored by FATS.

The first byte of the command string (CMND) defines the length of the pascal string:

1 Byte Length of string (0 - 255)
? Bytes String content

Before returning to pascal FATS removes the 3 pointers (12 bytes) of the stack and writes the return values into the appropriate variables. The record number is transferred via the AX register. The returned address of the key value (KEYADR) refers to the FATS segment and can be completed with the call of GFSEG1.

A typical function call from pascal could look as follows:

RECNO := FBSPAS(CMND^, ERRORCODE, KEYADR);

FBSFOR (MS Fortran)

At this entry point, which is normally used by the Microsoft Fortran compiler, 3 pointers on the variables CMND, ERRORCODE and KEYADR are transferred to FATS. All pointers are FAR pointers (segmented).

The command string must be terminated with an up-arrow (^), so that FATS can determine the length, e.g. "S\1\1\ABC^".

Before returning to pascal FATS removes the 3 pointers (12 bytes) of the stack and writes the return values into the appropriate variables. The returned address of the key value (KEYADR) refers to the FATS segment and can be completed with the call of GFSEG1.

A typical function call from fortran could look as follows:

RECNO = FBSFOR(CMND, ERRORCODE, KEYADR)

FBSCOB (MS Cobol)

At this entry point, which is normally used by the Microsoft Cobol compiler, 4 pointers on the variables CMND, ERRORCODE, RECNO and KEYADR are transferred to FATS. All pointers are NEAR pointers (non-segmented) and refer to the data segment register (DS).

The command string must be terminated with an up-arrow (^), so that FATS can determine the length, e.g. "S\1\1\ABC^".

Before returning to COBOL FATS removes the four pointers (8 bytes) of the stack and writes the return values into the appropriate variables. The returned address of the key value (KEYADR) refers to the FATS segment and can be completed with the call of GFSEG.

A typical function call from COBOL could look as follows:

CALL 'FBSCOB' USING CMND, ERRORCODE, RECNO, KEYADR

GFSEG (segment address of FATS)

Strings are stored in a variety of formats depending on the used programmin language. For a toolkit like FATS that supports a variety of programming languages there is a problem of interchanging string variables with the application.

The above described entry points return a NEAR pointer to the key value of a previous search command over the KEYADR variable. This pointer refers to the FATS data segment which you can determine by calling one of the functions GFSEG or GFSEG1.

Upon entry to GFSEG, one pointer (non-segmented) must have been pushed on the stack. The FATS segment is placed in the specified address relative to the application´s data segment. Before returning to the application FATS removes this pointer (2 bytes) of the stack.

Following an example for BASIC:

XADRKEY = KEYADR%
IF XADRKEY < 0 THEN XADRKEY = XADRKEY + 65536
CALL GFSEG(FATSSEG%)
FATSSEG = FATSSEG%
IF FATSSEG < 0 THEN FATSSEG = FATSSEG + 65536
FATSKEY$ = ""
FOR C = XADRKEY TO XADRKEY + KEYLEN% - 1
DEF SEG = FATSSEG
TMPCHAR = PEEK (C)
DEF SEG
IF TMPCHAR = 0 THEN EXIT FOR
FATSKEY$ = FATSKEY$ + CHR$(TMPCHAR)
NEXT C

GFSEG1

This function is identical to the previous one (GFSEG) except that the FATS data segment is returned via the AX register. This function is most useful for programming languages like Pascal, Cobol and C.

Following an example for MS-Pascal:

FATSSEG : WORD;
XADRKEY : ads of String(100);
FATSKEY : LString(100);
FUNCTION GFSEG1 : WORD; EXTERN;
FATSSEG := GFSEG1;
XADRKEY.S := FATSSEG;
XADRKEY.R := KEYADR;
MOVESL (XADRKEY, ads FATSKEY [1], KEYLEN);
FATSKEY.LEN := KEYLEN;

KEYADR

This variable contains the address of the last found key value. This is a FAR pointer that is stored in the FATS data segment and only available in the PC-DOS/MS-DOS version of FATS.

2 bytes	Length of string
2 bytes	Offset of string to the data segment (DS)

2 bytes	Offset of string (in respective string-heap)
2 bytes	Offset of the segment address of heap