Developer Reference > Getting Started > Programmer's Guide > Language Interfaces Modules
Language Interfaces Modules
This section covers language interface source modules provided in the Zen SDK installation option.
We provide the source code for each language interface. You can find additional information in the source modules themselves.
Visit the Actian website for online resources for developers, including articles and sample code for the various language interfaces.
Continue reading for information on specific interface modules:
• C/C++
• Delphi
• Pascal
Interface Modules Overview
If your programming language does not have an interface, check if your compiler supports mixed language calls. If so, you may be able to use the C interface. The following table lists the language interface source modules for Btrieve.
Language
Compiler
Source Module
C/C++
• Most C/C++ compilers, including Embarcadero, Microsoft, and WATCOM.
This interface provides multiple platform support.
• Embarcadero C++ Builder
• BlobHdr.h (for Extended DOS platforms using Embarcadero or Phar Lap only)
• BtiTypes.h (platform-independent data types)
• BtrApi.h (Btrieve function prototypes)
• BtrApi.c (MicroKernel Engine code for all platforms)
• BtrConst.h (common Btrieve constants)
• BtrSamp.c (sample program)
• Btrvexid.h (entry point declarations)
• CBBtrv.cpp
• CBBtrv.mak
• CBBMain.cpp
• CBBMain.dfm
• CBBMain.h
Delphi
• Embarcadero Delphi 1
• Embarcadero Delphi 3 and above
• BtrConst.pas (common Btrieve constants)
• Btr32.dpr
• Btr32.dof
• BtrSam32.dfm
• BtrSam32.pas (sample program)
• BtrApi32.pas
• BtrConst.pas (common Btrieve constants)
Pascal
• Borland Turbo Pascal 5 – 6
• Borland Pascal 7 for DOS
• Extended DOS Pascal for Turbo Pascal 7
• Borland Turbo Pascal 1.5
• Borland Pascal 7 for Windows
• BtrApid.pas
• BtrSampd.pas (sample program)
• BtrConst.pas (common Btrieve constants)
• BlobHdr.pas
• BtrApiw.pas
• BtrSampw.pas (sample program)
Visual Basic
• Microsoft Visual Basic for Windows NT and Windows 9X
• BtSamp32.vbp
• BtrSam32.bas (sample program)
• BtrFrm32.frm
The following table provides a comparison of some common data types used in data buffers for Btrieve operations, such as Create and Stat.
Assembly
C
COBOL
Delphi
Pascal
Visual Basic
quadword
long long1
—
—
—
—
doubleword
long1
PIC 9(4)
longint1
longint1
Long integer
word
short int1
PIC 9(2)
smallint1
integer1
Integer
byte
char
PIC X
char
char
String
byte
unsigned char
PIC X
byte
byte
Byte
1The value of integers depends on the environment in which you develop. In 32-bit environments, integers are the same as long integers. In 16-bit environments, integers are the same as short, or small, integers.
Programming Notes
Calling a Btrieve function always returns an INTEGER value that corresponds to a status code. After a Btrieve call, your application should always check the value of this status code. A status code 0 indicates a successful operation. Your application must be able to recognize and resolve a nonzero status.
Although you must provide all parameters on every call, the MicroKernel does not use every parameter for every operation. See the Btrieve API Guide for a more detailed description of the parameters that are relevant for each operation.
C/C++
This section provides C/C++ module information for the Btrieve API.
The C/C++ interface facilitates writing platform-independent applications. This interface supports development on DOS, Windows, Linux, and macOS. These modules also are documented under BTITYPES.H.
Interface Modules
This topic describes in detail the modules that comprise the C language interface.
BTRAPI.C
The file BTRAPI.C is the actual implementation of the C application interface. It provides support for all applications that call BTRV and BTRVID. When making a Btrieve call with either of these functions, compile BTRAPI.C and link its object with the other modules in your application.
The BTRAPI.C file contains #include directives that instruct your compiler to include BTRAPI.H, BTRCONST.H, BLOBHDR.H, and BTITYPES.H. By including these files, BTRAPI.C takes advantage of the data types that provide the platform independence associated with the interface.
BTRAPI.H
The file BTRAPI.H contains the prototypes of the Btrieve functions. The prototype definitions use the platform-independent data types defined in the file BTITYPES.H. BTRAPI.H provides support for all applications calling the BTRV and BTRVID functions.
BTRVEXID.H
This file contains the declarations of the Btrieve entry point functions for BTRVEX and BTRVEXID.
BTRCONST.H
The file BTRCONST.H contains useful constants specific to Btrieve. These constants can help you standardize references to Btrieve operation codes, status codes, file specification flags, key specification flags, and many more items.
You can use the C application interface without taking advantage of BTRCONST.H, however, including the file may simplify your programming effort.
BTITYPES.H
The file BTITYPES.H defines the platform-independent data types. By using the data types in BTITYPES.H on your Btrieve function calls, your application ports among operating systems.
BTITYPES.H also describes the switches you must use to indicate the operating system on which your application runs. The following table lists these operating system switches.
Operating System
Application Type
Switch
DOS
16-bit
32-bit with Tenberry Extender and BStub.exe
32-bit with Phar Lap 6
32-bit with Embarcadero PowerPack
BTI_DOS
BTI_DOS_32R
BTI_DOS_32P
BTI_DOS_32B
Linux
32-bit
BTI_LINUX
Linux
64-bit
BTI_LINUX_64
macOS
64-bit
BTI_MACOSX_64
Win32
32-bit Windows
BTI_WIN_32
Win64
64-bit Windows
BTI_WIN_64
BTRSAMP.C
The source file BTRSAMP.C is a sample Btrieve program that you can compile, link, and run on any of the operating systems listed under BTITYPES.H.
Programming Requirements
If you use the C application interface to make your application platform independent, you must use the data types described in BTITYPES.H. To see how these data types are used, see the file BTRSAMP.C.
Note:  You must also specify a directive that identifies the operating system on which the program executes. The available values for the directive are listed in the header file BTITYPES.H. Specify the directive using the appropriate command line option for your compiler.
Delphi
The Btrieve Delphi modules are documented under BTITYPES.H.
DOS (Btrieve)
This section explains how a DOS application can use the Btrieve API.
Interface Modules
The following modules comprise the language interface for DOS applications using the Btrieve API.
BTRAPI.C
The file BTRAPI.C is the implementation of the C application interface. This file also contains the DOS interface:
#if defined( BTI_DOS )
BTI_API BTRVID(
BTI_WORD operation,
BTI_VOID_PTR posBlock,
BTI_VOID_PTR dataBuffer,
BTI_WORD_PTR dataLength,
BTI_VOID_PTR keyBuffer,
BTI_SINT keyNumber,
BTI_BUFFER_PTR clientID )
BTRAPI.C provides support for all applications that call BTRV and BTRVID. When making a Btrieve call with either of these functions, compile BTRAPI.C and link its object with the other modules in your application.
The BTRAPI.C file contains #include directives that instruct your compiler to include BTRAPI.H, BTRCONST.H, BLOBHDR.H, and BTITYPES.H. By including these files, BTRAPI.C takes advantage of the data types that provide the platform independence associated with the interface.
BTRAPI.H
The file BTRAPI.H contains the prototypes of the Btrieve functions. The prototype definitions use the platform-independent data types defined in the file BTITYPES.H. BTRAPI.H provides support for all applications calling the BTRV and BTRVID functions.
BTRCONST.H
The file BTRCONST.H contains useful constants specific to Btrieve. These constants can help you standardize references to Btrieve operation codes, status codes, file specification flags, key specification flags, and many more items.
You can use the C application interface without taking advantage of BTRCONST.H, however, including the file may simplify your programming effort.
BTITYPES.H
The file BTITYPES.H defines the platform-independent data types. By using the data types in BTITYPES.H on your Btrieve function calls, your application ports among operating systems.
BTITYPES.H also describes the switches you must use to indicate the DOS operating system on which your application runs. The following table lists these switches.
Operating System
Application Type
Switch
DOS
16-bit
32-bit with Tenberry Extender and BStub.exe1
32-bit with Phar Lap 6
32-bit with Embarcadero PowerPack
BTI_DOS
BTI_DOS_32R
BTI_DOS_32P
BTI_DOS_32B
Pascal
The Btrieve API source modules for Pascal are described in the following topics.
Source Modules
The Pascal interface is comprised of the following source modules:
• BTRAPID.PAS – Btrieve functions interface unit for DOS.
• BTRCONST.PAS – Common Btrieve constants unit.
• BTRSAMPD.PAS – Sample Btrieve program for DOS.
BBTRAPID.PAS
BTRAPID.PAS contains the source code implementation of the Pascal application interface for DOS. This file provides support for applications calling Btrieve functions.
In order for Turbo Pascal to properly compile and link the MicroKernel Engine with the other modules in your application, you can compile BTRAPID.PAS to create a Turbo Pascal unit which you then list in the uses clause of your application source code.
BTRCONST.PAS
The file BTRCONST.PAS contains useful constants specific to Btrieve. These constants can help you standardize references to Btrieve operation codes, status codes, file specification flags, key specification flags, and many more items.
To use BTRCONST.PAS, you can compile it to create a Turbo Pascal unit which you then list in the uses clause of your application source code.
You can use the Pascal application interface without taking advantage of BTRCONST.PAS; however, using the file may simplify your programming effort.
BTRSAMPD.PAS
The source file BTRSAMPD.PAS is a sample Btrieve program that you can compile, link, and run.
Note:  If your application uses Pascal record structures that contain variant strings, consider that odd-length elements in a Pascal record may require an extra byte of storage (even if the record is not packed). This is an important consideration when you define the record length for the Create (14) operation. See your Pascal reference manual for more information on record types.
Visual Basic
This section describes the Visual Basic source modules for the Btrieve API.
Visual Basic, when compiling a 32-bit application, aligns members of a UDT (user-defined data type) on 8-, 16-, or 32-bit boundaries, depending on the size of that particular member. Unlike structures, database rows are packed, meaning there is no unused space between fields. Because there is no way to turn alignment off, there must be some method to pack and unpack structures so that Visual Basic applications can access a database. The Zen Btrieve Alignment DLL, PALN32.DLL, is designed to handle this alignment issue.
In the case of Visual Basic, this language aligns elements at various multiples of bits. The following table provides various data types and shows how Visual Basic handles them:
Visual Basic Type
Type Constant
Typical Size (in bytes)
Boundary
Byte
FLD_BYTE
Any
1 byte (none)
String
FLD_STRING
Any
1 byte (none)
Boolean
FLD_LOGICAL
2
2 bytes
Integer
FLD_INTEGER
2
2 bytes
Currency
FLD_MONEY
4
4 bytes
Long
FLD_INTEGER
4
4 bytes
Single
FLD_IEEE
4
4 bytes
Double
FLD_IEEE
8
4 bytes
Programs access Btrieve calls in Visual Basic by calling the BTRCALL function. Access to this function is accomplished by including the BTRAPI.BAS module in your project. The rest of the functions required reside in PALN32.DLL.
To include PALN32.DLL in your project
• Select Project > References and select the Zen Btrieve Alignment Library module. If it is not shown, add it to the list first by selecting the browse button and locating the file.
The following table includes each function and the specific module it requires.
Function
Purpose
Location
Parameters
Returns
BTRCALL
To perform Btrieve operations
BTRAPI.BAS
• OP As Integer
The Btrieve operation number as listed in the Btrieve API Guide.
• Pb$ As String
Stores the position block in a string used to retrieve or store records or to pass structures to Btrieve.
• Db As Any
Data buffer. This parameter is used to retrieve or store records or to pass structures to Btrieve.
• DL As Long
Length of data buffer.
• Kb As Any
Key buffer.
• Kl As Integer
Length of key buffer.
• Kn As Integer
Key number.
Integer
The Btrieve status code returned by the operation. See Status Codes and Messages for more information about a specific code.
RowToStruct
Converts a row of bytes into a Visual Base UDT.
PALN32.DLL
• row (1 to n) As Byte
Input array to retrieve packed data.
• fld (1 to n) As FieldMap
A FieldMap array used to determine data types of individual fields.
• udt As Any
The UDT to store the data.
• udtSize As Long
The size of the UDT. Generate this value using LenB( ).
Integer
0 if okay. Otherwise an error occurred.
SetFieldMap
Sets the members of a FieldMap element.
PALN32.DLL
• map As FieldMap
An element of a FieldMap array.
• dataType As Integer
The field type, passes on the following constants:
- FLD_STRING
- FLD_INTEGER
- FLD_IEEE
- FLD_MONEY
- FLD_LOGICAL
- FLD_BYTE
- FLD_UNICODE1
• size As Long
Size of the field, in bytes, as stored in the database.
Nothing
SetFieldMap
FromDDF
Sets all the members of an array of the FieldMap type.
PALN32.DLL
• path As String
A full path name to the data source.
• table As String
Name of the table.
• userName As String
Reserved, pass a null string (e.g. " ").
• passwd As String
Reserved, pass a null string (e.g. " ").
• map (1 to n) As FieldMap
The destination FieldMap array to fill. It must contain the exact number of elements as the number of fields in the record.
• unicode As Integer
0 if strings are stored in record as ASCII. Otherwise, they are stored as Unicode.
Integer
0 if okay. Otherwise, an error occurred.
StructToRow
Converts a Visual Basic UDT to a row of bytes
PALN32.DLL
• row (1 to n) As Byte
Output array to store packed data.
• fld (1 to n) As FieldMap
A FieldMap array used to determine data types of individual fields.
• udt As Any
The UDT from which to retrieve data.
• udtSize As Long
The size of the UDT. Generate this value using LenB( ).
Integer
0 if okay. Otherwise, an error occurred.
1The field type FLD_UNICODE is used to specify a field of Visual Basic Type 'String' that is to be stored in UNICODE both within the database row (packed structure) as well as within the UDT (user-defined data type). If the field type FLD_STRING is used, it will be converted into the default ANSI code page character set of the system in the database row, although UNICODE will be used in the UDT (user-defined data type). In short, if you wish to store the string field in UNICODE in your database, choose field type FLD_UNICODE. If you wish to store the string field in the database in the default ANSI code page character set of the system, choose FLD_STRING.
Last modified date: 10/31/2023