Lesson 2: Btrieve API Tutorials with Visual Basic

Including PALN32.DLL in a Visual Basic Project

Select References from the Project menu.

Check the Pervasive Btrieve Alignment Library module. If it is not displayed, add it to the list by using the browse feature. It is installed into the same folder as your Visual Basic sample application for Btrieve API (default location of C:\PVSW\SDK\Intf\vb).

Copy BTR32VB.BAS from \PVSW\SDK2000\INTF\VB into your project directory, and add it to your project.

Initializing Global Structures

The Pervasive Btrieve Alignment library (PALN32.DLL) is provided in the Pervasive Software Developer's Kit. This library is used for packing aligned structures and unpacking database rows.

Before a database can be accessed, there first must exist the required data structures needed to manipulate data. We need to store these items:

Packed data in database format.

Unpacked data in Visual Basic's UDT format.

Field information needed for packing and unpacking.

Create structures needed to store a packed database row.

Const CustRowSize = 193 
Type CustRowType 
    buf(1 To CustRowSize) As Byte 
End Type 
Dim CustRow As CustRowType

Create structure for holding data.

Public Type CustRecType   
    custid As Long 
    lastname As String * 24 
    firstname As String * 24 
    address1 As String * 36 
    address2 As String * 36 
    city As String * 24 
    state As String * 2 
    zip As String * 10 
    homephone As String * 12 
    workphone As String * 12 
    status As Long 
    member As Byte 
    expiration As Long 
End Type

Create structure for holding file structure.

Global CustFldMap(1 To 13) As FieldMap

Load the file structure into memory.

' Initialize Customer field map. 
' If there exists a DDF file: 
SetFieldMapFromDDF DdfPath$, "Customers", "", "", _ 
					CustFldMap, False

Otherwise:

SetField CustFldMap(1), FLD_INTEGER, 4   'CustID 
SetField CustFldMap(2), FLD_STRING, 24   'LastName 
SetField CustFldMap(3), FLD_STRING, 24   'FirstName 
SetField CustFldMap(4), FLD_STRING, 36   'Address1 
SetField CustFldMap(5), FLD_STRING, 36   'Address2 
SetField CustFldMap(6), FLD_STRING, 24   'City 
SetField CustFldMap(7), FLD_STRING, 2    'State 
SetField CustFldMap(8), FLD_STRING, 10   'Zip 
SetField CustFldMap(9), FLD_STRING, 12   'HomePhone 
SetField CustFldMap(10), FLD_STRING, 12  'WorkPhone 
SetField CustFldMap(11), FLD_INTEGER, 4  'Status 
SetField CustFldMap(12), FLD_BYTE, 1     'Member 
SetField CustFldMap(13), FLD_INTEGER, 4  'Expiration

Performing Basic File Operations

Opening a File

To perform this operation, you need this information: Position Block, file name, and owner. For the Position Block, we need to allocate memory for it by creating a variable and setting it equal to 128 characters. The file name goes into the key buffer followed by a null character, and the owner is stored in the data buffer also with a null character. The DataSize and KeySize parameters of BTRCALL must be set to the length of the names including the null character at the ends of each.

Create a Position Block variable.

' Prepare to open Customer table. 
CustPosBlk$ = Space$(128)         ' Allocate 128 
characters.

Set the Key Buffer to your table name and Owner to the owner's name.

' Set the owner name to an empty string. 
TblFile$ = DdfPath & "\" & "customer.mkd" + Chr$(0) 
Owner$ = "" + Chr$(0)

Call BTRCALL with the Open operation.

' Open Customer table. 
status% = BTRCALL(BOPEN, CustPosBlk$, Owner$, _ 
		Len(Owner$), ByVal TblFile$, Len(TblFile$), _ 
		KeyNum%)

Verify status returned is correct.

' Verify status returned. 
If status% <> 0 Then 
	MsgBox "Error opening Customer table.  Btrieve " & _ 
		"returned status: " & status% 
End If

Closing a File

Closing files is a simple task. All that is needed is to call the BCLOSE operation and pass the Position Block. The status returned then can be used to determine success or failure.

Call the Close operation with the position block.

status% = BTRCALL(BCLOSE, CustPosBlk$, 0, 0, 0, 0, 0)

Verify status returned.

If status% Then 
	MsgBox "Error closing Customer table.  " & _ 
				"Btrieve returned status: " & status% 
End If

Creating a File

To create a file, you need to create a structure that contains the necessary information required to build a new Btrieve file. The StructToRow function is not needed, as the structure is not subject to alignment problems.

Include the necessary structures and constants.

Type BtrFileSpec 
	Length As Integer 
	PageSize As Integer 
	NumIndexes As Integer 
	Reserved As Long 
	FileFlags As Integer 
	NumDupPtr As Byte 
	NotUsed As Byte 
	Allocation As Integer 
End Type 
' Constants used for specifying file flags: 
Global Const VAR_RECS = &h1 
Global Const BLANK_TRUNC = &h2 
Global Const PRE_ALLOC = &h4 
Global Const DATA_COMP = &h8 
Global Const KEY_ONLY = &h10 
Global Const BALANCED_KEYS = &h20 
Global Const FREE_10 = &h40 
Global Const FREE_20 = &h80 
Global Const FREE_30 = &hC0 
Global Const DUP_PTRS = &h100 
Global Const INCLUDE_SYSTEM_DATA = &h200 
Global Const NO_INCLUDE_SYSTEM_DATA = &h1200 
Global Const SPECIFY_KEY_NUMS = &h400 
Global Const VATS_SUPPORT = &h800

Create and fill the File Specification structure.

Dim NewFileSpec As BtrFileSpec

' Create a file that contain records with the length of 100.

With NewFileSpec 
	.Length = 100 
	.PageSize = 4096 
	.NumIndexes = 0 
	.Reserved = 0 
	.FileFlags = 0 
	.NumDupPtr = 0 
	.NotUsed = 0 
	.Allocation = 0 
End With

Specify a file name.

FileName$ = "Example.btr" + Chr$(0)

Call Btrieve Create function.

' Call the Btrieve command to create a file:

status% = BTRCALL(BCREATE, 0, NewFileSpec, 16, _ 
				FileName$, Len(FileName$), -1)

Verify Status.

' Verify status returned: 
If status% <> 0 Then 
	MsgBox "An error occurred creating the file.  Btrieve 
" & _ 
			"returned status: " & status% 
End If

Modifying Data

Inserting Records

A row may be inserted by calling BINSERT with the row to be inserted in the Data Buffer.

Convert structure to a packed row.

StructToRow custrow.buf, CustFldMap, custrec, 
LenB(keyrec)

Call Btrieve Insert function.

status% = BTRCALL(BINSERT, CustPosBlk$, custrow, _ 
			LenB(custrow), 0, 0, -1)

Verify status.

If status% <> 0 Then 
MsgBox "Error on Insert: " & status% 
End If

Updating Records

In order to update a row, a Get or Step operation must occur to establish currency. Once that is done successfully, the programmer may modify that row.

Convert structure to a packed row.

StructToRow custrow.buf, CustFldMap, custrec, 
LenB(keyrec)

Call Btrieve Update function.

status% = BTRCALL(BUPDATE, CustPosBlk$, custrow, _ 
	LenB(custrow), ByVal KeyBuffer$, KeyBufLen%, 0)

Verify status.

If status% <> 0 Then 
MsgBox "Error on Update: " & status% 
End If