0% found this document useful (0 votes)

581 views

PSQL BtrieveAPI Guide

Pervasive Software Inc. LICENSES THE SOFTWARE AND DOCUMENTATION PRODUCT TO YOU OR YOUR COMPANY SOLELY ON AN "AS IS" BASIS and in ACCORDANCE WITH the TERMS and CONDITIONS of the ACCOMPANYING LICENSE AGREEMENT.

Uploaded by

lenin jiv

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

581 views

PSQL BtrieveAPI Guide

Uploaded by

lenin jiv

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 210

Pervasive PSQL v9 Service Pack 2

Btrieve API Guide

Developing Applications Using the Btrieve API

Pervasive Software Inc. 12365 Riata Trace Parkway Building B Austin, TX 78727 USA

Telephone: 512 231 6000 or 800 287 4383 Fax: 512 231 6010 Email: [email protected] Web: http://www.pervasive.com

disclaimer

PERVASIVE SOFTWARE INC. LICENSES THE SOFTWARE AND DOCUMENTATION PRODUCT TO YOU OR YOUR COMPANY SOLELY ON AN AS IS BASIS AND SOLELY IN ACCORDANCE WITH THE TERMS AND CONDITIONS OF THE ACCOMPANYING LICENSE AGREEMENT. PERVASIVE SOFTWARE INC. MAKES NO OTHER WARRANTIES WHATSOEVER, EITHER EXPRESS OR IMPLIED, REGARDING THE SOFTWARE OR THE CONTENT OF THE DOCUMENTATION; PERVASIVE SOFTWARE INC. HEREBY EXPRESSLY STATES AND YOU OR YOUR COMPANY ACKNOWLEDGES THAT PERVASIVE SOFTWARE INC. DOES NOT MAKE ANY WARRANTIES, INCLUDING, FOR EXAMPLE, WITH RESPECT TO MERCHANTABILITY, TITLE, OR FITNESS FOR ANY PARTICULAR PURPOSE OR ARISING FROM COURSE OF DEALING OR USAGE OF TRADE, AMONG OTHERS. Btrieve, Client/Server in a Box, Pervasive, Pervasive Software, and the Pervasive Software logo are registered trademarks of Pervasive Software Inc.
Built on Pervasive Software, DataExchange, MicroKernel Database Engine, MicroKernel Database Architecture, Pervasive.SQL, Pervasive PSQL, Solution Network, Ultralight, and ZDBA are trademarks of Pervasive Software Inc. Microsoft, MS-DOS, Windows, Windows 95, Windows 98, Windows NT, Windows Millennium, Windows 2000, Windows XP, Win32, Win32s, and Visual Basic are registered trademarks of Microsoft Corporation. NetWare and Novell are registered trademarks of Novell, Inc. NetWare Loadable Module, NLM, Novell DOS, Transaction Tracking System, and TTS are trademarks of Novell, Inc. Sun, Sun Microsystems, Java, all trademarks and logos that contain Sun, Solaris, or Java, are trademarks or registered trademarks of Sun Microsystems. All other company and product names are the trademarks or registered trademarks of their respective companies. Copyright 2006 Pervasive Software Inc. All rights reserved. Reproduction, photocopying, or transmittal of this publication, or portions of this publication, is prohibited without the express prior written consent of the publisher. This product includes software developed by Powerdog Industries. Copyright 1994 Powerdog Industries. All rights reserved. This product includes software developed by KeyWorks Software. Copyright 2002 KeyWorks Software. All rights reserved. This product includes software developed by DUNDAS SOFTWARE. Copyright 1997-2000 DUNDAS SOFTWARE LTD., all rights reserved. This product includes software developed by the Apache Software Foundation (http://www.apache.org/). This product uses the free unixODBC Driver Manager as written by Peter Harvey ([email protected]), modified and extended by Nick Gorham ([email protected]), with local modifications from Pervasive Software. Pervasive Software will donate their code changes to the current maintainer of the unixODBC Driver Manager project, in accordance with the LGPL license agreement of this project. The unixODBC Driver Danager home page is located at www.unixodbc.org. For further information on this project, contact its current maintainer: Nick Gorham ([email protected]). A copy of the GNU Lesser General Public License (LGPL) is included on the distribution media for this product. You may also view the LGPL at www.fsf.org/licensing/licenses/lgpl.html.

trademarks

Btrieve API Guide May 2006

Contents
About This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Who Should Read This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Manual Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

xiii
xiv xv xvi

Introduction to Btrieve APIs . . . . . . . . . . . . . . . . . . . . . .

Btrieve API Functions . . . . . . . . . . . . . . . . . . . . . BTRV Function. . . . . . . . . . . . . . . . . . . . . . BTRVID Function . . . . . . . . . . . . . . . . . . . . BTRCALL Function . . . . . . . . . . . . . . . . . . . BTRCALL32 Function . . . . . . . . . . . . . . . . . . BTRCALLID Function. . . . . . . . . . . . . . . . . . BTRCALLID32 Function . . . . . . . . . . . . . . . . Obsolete Functions. . . . . . . . . . . . . . . . . . . . Btrieve API Function Parameters . . . . . . . . . . . . . . . Operation Code . . . . . . . . . . . . . . . . . . . . . Status Code . . . . . . . . . . . . . . . . . . . . . . . . Position Block . . . . . . . . . . . . . . . . . . . . . . Data Buffer . . . . . . . . . . . . . . . . . . . . . . . . Data Buffer Length . . . . . . . . . . . . . . . . . . . . Key Buffer. . . . . . . . . . . . . . . . . . . . . . . . . Key Number . . . . . . . . . . . . . . . . . . . . . . . Client ID . . . . . . . . . . . . . . . . . . . . . . . . . Key Length . . . . . . . . . . . . . . . . . . . . . . . . Summary of Btrieve API Operations . . . . . . . . . . . . . Session-Specific Operations . . . . . . . . . . . . . . . File-Specific Operations . . . . . . . . . . . . . . . . . Unsupported Operations . . . . . . . . . . . . . . . . Sequence of Events in Performing a Btrieve API Operation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1-1
1-2 1-2 1-2 1-3 1-3 1-3 1-3 1-3 1-5 1-5 1-6 1-7 1-7 1-8 1-8 1-10 1-10 1-11 1-12 1-12 1-13 1-16 1-18

Btrieve API Operations . . . . . . . . . . . . . . . . . . . . . . . .

Abort Transaction (21) . . . . . Parameters . . . . . . . . Prerequisites . . . . . . . Procedure . . . . . . . . . Result . . . . . . . . . . . Positioning . . . . . . . . Begin Transaction (19 or 1019) Parameters . . . . . . . . Prerequisites . . . . . . . Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-1
2-4 2-4 2-4 2-4 2-4 2-4 2-5 2-5 2-5 2-5

iii

Contents

Result . . . . . . . . . . Positioning. . . . . . . Clear Owner (30). . . . . . . Parameters . . . . . . . Prerequisites . . . . . . Procedure . . . . . . . Result . . . . . . . . . . Positioning. . . . . . . Close (1) . . . . . . . . . . . Parameters . . . . . . . Prerequisites . . . . . . Procedure . . . . . . . Result . . . . . . . . . . Positioning. . . . . . . Continuous Operation (42) . Parameters . . . . . . . Procedure . . . . . . . Details . . . . . . . . . Result . . . . . . . . . . Positioning. . . . . . . Create (14) . . . . . . . . . . Parameters . . . . . . . Prerequisites . . . . . . Procedure . . . . . . . Details . . . . . . . . . Result . . . . . . . . . . Positioning. . . . . . . Create Index (31). . . . . . . Parameters . . . . . . . Prerequisites . . . . . . Procedure . . . . . . . Details . . . . . . . . . Result . . . . . . . . . . Positioning. . . . . . . Delete (4) . . . . . . . . . . . Parameters . . . . . . . Prerequisites . . . . . . Procedure . . . . . . . Details . . . . . . . . . Result . . . . . . . . . . Positioning. . . . . . . Drop Index (32) . . . . . . . Parameters . . . . . . . Prerequisites . . . . . . Procedure . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-6 2-6 2-7 2-7 2-7 2-7 2-7 2-7 2-8 2-8 2-8 2-8 2-8 2-9 2-10 2-10 2-11 2-11 2-13 2-14 2-15 2-15 2-15 2-15 2-16 2-31 2-32 2-33 2-33 2-33 2-34 2-35 2-37 2-38 2-39 2-39 2-39 2-39 2-39 2-40 2-40 2-41 2-41 2-41 2-41

Contents

Details . . . . . . . Result . . . . . . . Positioning . . . . End Transaction (20) . . Parameters . . . . Prerequisites . . . Procedure . . . . . Result . . . . . . . Positioning . . . . Find Percentage (45) . . Parameters . . . . Prerequisites . . . Procedure . . . . . Details . . . . . . . Result . . . . . . . Positioning . . . . Get By Percentage (44) . Parameters . . . . Prerequisites . . . Procedure . . . . . Details . . . . . . . Result . . . . . . . Positioning . . . . Get Direct/Chunk (23) . Parameters . . . . Prerequisites . . . Procedure . . . . . Details . . . . . . . Result . . . . . . . Positioning . . . . Get Direct/Record (23) . Parameters . . . . Prerequisites . . . Procedure . . . . . Result . . . . . . . Positioning . . . . Get Directory (18) . . . Parameters . . . . Prerequisites . . . Procedure . . . . . Result . . . . . . . Positioning . . . . Get Equal (5) . . . . . . Parameters . . . . Prerequisites . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-41 2-42 2-42 2-43 2-43 2-43 2-43 2-43 2-43 2-44 2-44 2-44 2-44 2-45 2-46 2-47 2-48 2-48 2-48 2-48 2-49 2-50 2-51 2-52 2-52 2-52 2-53 2-53 2-59 2-60 2-61 2-61 2-61 2-62 2-62 2-62 2-64 2-64 2-64 2-64 2-64 2-64 2-65 2-65 2-65

Contents

Procedure . . . . . . . . Result . . . . . . . . . . . Positioning. . . . . . . . Get First (12) . . . . . . . . . . Parameters . . . . . . . . Prerequisites . . . . . . . Procedure . . . . . . . . Result . . . . . . . . . . . Positioning. . . . . . . . Get Greater (8) . . . . . . . . . Parameters . . . . . . . . Prerequisites . . . . . . . Procedure . . . . . . . . Result . . . . . . . . . . . Positioning. . . . . . . . Get Greater Than or Equal (9) Parameters . . . . . . . . Prerequisites . . . . . . . Procedure . . . . . . . . Result . . . . . . . . . . . Positioning. . . . . . . . Get Key (+50) . . . . . . . . . Parameters . . . . . . . . Prerequisites . . . . . . . Procedure . . . . . . . . Result . . . . . . . . . . . Positioning. . . . . . . . Get Last (13) . . . . . . . . . . Parameters . . . . . . . . Prerequisites . . . . . . . Procedure . . . . . . . . Result . . . . . . . . . . . Positioning. . . . . . . . Get Less Than (10) . . . . . . . Parameters . . . . . . . . Prerequisites . . . . . . . Procedure . . . . . . . . Result . . . . . . . . . . . Positioning. . . . . . . . Get Less Than or Equal (11). . Parameters . . . . . . . . Prerequisites . . . . . . . Procedure . . . . . . . . Result . . . . . . . . . . . Positioning. . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-65 2-66 2-66 2-67 2-67 2-67 2-67 2-67 2-68 2-69 2-69 2-69 2-69 2-70 2-70 2-71 2-71 2-71 2-71 2-72 2-72 2-73 2-73 2-73 2-73 2-74 2-74 2-75 2-75 2-75 2-75 2-75 2-76 2-77 2-77 2-77 2-77 2-78 2-78 2-79 2-79 2-79 2-79 2-80 2-80

Contents

Get Next (6) . . . . . . . . . Parameters . . . . . . Prerequisites . . . . . Procedure . . . . . . . Result . . . . . . . . . Positioning . . . . . . Get Next Extended (36) . . Parameters . . . . . . Prerequisites . . . . . Procedure . . . . . . . Details . . . . . . . . . Result . . . . . . . . . Positioning . . . . . . Get Position (22) . . . . . . Parameter . . . . . . . Prerequisites . . . . . Procedure . . . . . . . Result . . . . . . . . . Positioning . . . . . . Get Previous (7) . . . . . . . Parameters . . . . . . Prerequisites . . . . . Procedure . . . . . . . Result . . . . . . . . . Positioning . . . . . . Get Previous Extended (37) Parameters . . . . . . Prerequisites . . . . . Procedure . . . . . . . Details . . . . . . . . . Result . . . . . . . . . Positioning . . . . . . Insert (2) . . . . . . . . . . . Parameters . . . . . . Prerequisites . . . . . Procedure . . . . . . . Result . . . . . . . . . Positioning . . . . . . Insert Extended (40) . . . . Parameters . . . . . . Prerequisites . . . . . Procedure . . . . . . . Details . . . . . . . . . Result . . . . . . . . . Positioning . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-81 2-81 2-81 2-81 2-82 2-82 2-83 2-83 2-83 2-83 2-84 2-90 2-92 2-93 2-93 2-93 2-93 2-93 2-93 2-94 2-94 2-94 2-94 2-95 2-95 2-96 2-96 2-96 2-96 2-97 2-97 2-97 2-99 2-99 2-99 2-99 2-99 2-100 2-102 2-102 2-102 2-102 2-103 2-103 2-103

vii

Contents

Login/Logout (78) . . . . Parameters . . . . . Prerequisites . . . . Login Procedure . . Logout Procedure . Result . . . . . . . . Notes . . . . . . . . Positioning. . . . . Open (0) . . . . . . . . . Parameters . . . . . Prerequisites . . . . Procedure . . . . . Details . . . . . . . Result . . . . . . . . Positioning. . . . . Reset (28) . . . . . . . . . Parameters . . . . . Prerequisites . . . . Procedure . . . . . Result . . . . . . . . Positioning. . . . . Set Directory (17) . . . . Parameters . . . . . Prerequisites . . . . Procedure . . . . . Result . . . . . . . . Positioning. . . . . Set Owner (29) . . . . . . Parameters . . . . . Prerequisites . . . . Procedure . . . . . Details . . . . . . . Result . . . . . . . . Positioning. . . . . Stat (15) . . . . . . . . . . Parameters . . . . . Prerequisites . . . . Procedure . . . . . Details . . . . . . . Result . . . . . . . . Positioning. . . . . Stat Extended (65) . . . . Parameters . . . . . Prerequisites . . . . Procedure . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-106 2-106 2-106 2-106 2-106 2-106 2-107 2-107 2-108 2-108 2-108 2-108 2-109 2-111 2-112 2-113 2-113 2-113 2-113 2-113 2-113 2-114 2-114 2-114 2-114 2-114 2-114 2-115 2-115 2-115 2-115 2-116 2-116 2-116 2-117 2-117 2-117 2-117 2-117 2-121 2-122 2-123 2-123 2-123 2-123

viii

Contents

Subfunction 1: Extended File Information . . . . . . . . . . . . . . . . . . . . . . Subfunction 2: System Data Information . . . . . . . . . . . . . . . . . . . . . . . Subfunction 3: Duplicate Record Conflict Information . . . . . . . . . . . . . . . Subfunction 4: File Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . Subfunction 5: Gateway Information . . . . . . . . . . . . . . . . . . . . . . . . . Subfunction 6: Lock Owner Identification . . . . . . . . . . . . . . . . . . . . . . Result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step First (33) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Positioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step Last (34) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Positioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step Next (24) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Positioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step Next Extended (38) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Positioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step Previous (35). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Positioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step Previous Extended (39) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Positioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-124 2-125 2-126 2-127 2-129 2-130 2-133 2-134 2-134 2-134 2-134 2-134 2-135 2-136 2-136 2-136 2-136 2-136 2-137 2-138 2-138 2-138 2-138 2-138 2-139 2-140 2-140 2-140 2-140 2-141 2-141 2-142 2-144 2-144 2-144 2-144 2-144 2-145 2-146 2-146 2-146 2-146 2-147 2-147 2-147

Contents

Stop (25) . . . . . . Parameters . . Procedure . . Result . . . . . Positioning. . Unlock (27) . . . . . Parameters . . Prerequisites . Procedure . . Result . . . . . Positioning. . Update (3) . . . . . Parameters . . Prerequisites . Procedure . . Result . . . . . Positioning. . Update Chunk (53) Parameters . . Prerequisites . Procedure . . Details . . . . Result . . . . . Positioning. . Version (26) . . . . Parameters . . Prerequisites . Procedure . . Result . . . . . Positioning. .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-148 2-148 2-148 2-148 2-148 2-149 2-149 2-149 2-149 2-150 2-150 2-151 2-151 2-151 2-151 2-152 2-152 2-154 2-154 2-154 2-154 2-155 2-161 2-162 2-163 2-163 2-163 2-163 2-163 2-164

Quick Reference of Btrieve Operations. . . . . . . . . . . . . . . .

Table of Btrieve API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

A-1
A-1

Tables
1-1 1-2 1-3 1-4 1-5 1-6 1-7 2-1 2-2 2-3 2-4 2-5 2-6 2-7 2-8 2-9 2-10 2-11 2-12 2-13 2-14 2-15 2-16 2-17 2-18 2-19 2-20 2-21 2-22 2-23 2-24 2-25 2-26 2-27 2-28 2-29 2-30 2-31 2-32 2-33 Btrieve API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . Client ID Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . Session-Specific Operations . . . . . . . . . . . . . . . . . . . . . . . File Access and Information Operations . . . . . . . . . . . . . . . . Data Retrieval Operations . . . . . . . . . . . . . . . . . . . . . . . . Data Manipulation Operations . . . . . . . . . . . . . . . . . . . . . Unsupported Operations . . . . . . . . . . . . . . . . . . . . . . . . Data Buffer Structure for Create Operation . . . . . . . . . . . . . . File Flag Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Key Flag Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Extended Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . Data Buffer for Creating a User-Defined ACS . . . . . . . . . . . . . Data Buffer for Specifying an ISR ACS . . . . . . . . . . . . . . . . . Key Number Parameter for Create Operation . . . . . . . . . . . . . Create Operation Subfunctions . . . . . . . . . . . . . . . . . . . . . Create Subfunctions - Use of URI Parameters in Key Buffer . . . . . Create Subfunctions - Use of URI Parameters in Data Buffer . . . . Data Buffer Size Limitations by Environment . . . . . . . . . . . . . Data Buffer for Random Chunk Operations . . . . . . . . . . . . . . Data Buffer for Rectangle Chunks . . . . . . . . . . . . . . . . . . . Input Data Buffer Structure for Extended Get and Step Operations. Returned Data Buffer Structure for Extended Get and Step Ops. . . Data Buffer Structure for the Insert Extended Operation. . . . . . . Open Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Open Mode Combinations for Local Clients . . . . . . . . . . . . . Access and Encryption Codes . . . . . . . . . . . . . . . . . . . . . . Data Buffer Excluding File Version Information . . . . . . . . . . . Data Buffer Including File Version Information . . . . . . . . . . . Stat Extended (65) Sub-functions. . . . . . . . . . . . . . . . . . . . Extended Files Descriptor . . . . . . . . . . . . . . . . . . . . . . . . Extended Files Return Buffer . . . . . . . . . . . . . . . . . . . . . . System Data Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . System Data Return Buffer . . . . . . . . . . . . . . . . . . . . . . . Duplicate Record Conflict Descriptor . . . . . . . . . . . . . . . . . Duplicate Record Conflict Return Buffer . . . . . . . . . . . . . . . File Information Descriptor - Open File . . . . . . . . . . . . . . . . File Information Structure - Open File . . . . . . . . . . . . . . . . . File Information Flags . . . . . . . . . . . . . . . . . . . . . . . . . . Gateway Information Descriptor . . . . . . . . . . . . . . . . . . . . File Information Structure - Gateway Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 1-10 1-12 1-13 1-14 1-16 1-17 2-16 2-20 2-24 2-26 2-28 2-28 2-29 2-30 2-30 2-31 2-52 2-54 2-57 2-84 2-89 2-103 2-110 2-112 2-116 2-118 2-119 2-123 2-124 2-125 2-125 2-126 2-127 2-127 2-127 2-128 2-129 2-130 2-130

Tables

2-34 2-35 2-36 2-37 2-38 2-39 2-40

Lock Owner Information Descriptor . . Lock Owner Information Return Buffer Lock Owner Flags . . . . . . . . . . . . . Random Chunk Descriptor Structure . . Rectangle Chunk Descriptor Structure . Truncate Descriptor Structure . . . . . . Version Block . . . . . . . . . . . . . . .

. . . . . . .

. 2-131 . 2-131 . 2-132 . 2-156 . 2-158 . 2-160 . 2-164

xii

About This Manual

This manual contains information about the features and enhancements that are new in this release of Pervasive PSQL. This manual describes the new and changed behaviors of the product relative to the most recent previous release.

xiii

Who Should Read This Manual

This document is designed for any user who is familiar with Pervasive PSQL and wants to know what has changed in this release of the software. This manual does not provide comprehensive usage instructions for the software. Its purpose is to explain what is new and different in this particular release of the product. Pervasive Software Inc. would appreciate your comments and suggestions about this manual. As a user of our documentation, you are in a unique position to provide ideas that can have a direct impact on future releases of this and other manuals. If you have comments or suggestions for the product documentation, post your request at http://www.pervasive.com/devtalk.

xiv

Manual Organization
This manual begins with an overview of the new features, then provides links to chapters containing additional details where appropriate. JDBC Driver Guide is divided into the following sections:

Chapter 1Introduction to Btrieve APIs This chapter provides a brief overview of the Btrieve API functions and their parameters. This chapter also summarizes the Btrieve API operations.

Chapter 2Btrieve API Operations This chapter documents the Btrieve API operations.

Appendix AQuick Reference of Btrieve Operations This appendix summarizes the Btrieve API operations in order of operations.

This manual also contains an index.

Conventions
Unless otherwise noted, command syntax, code, and examples use the following conventions:
CASE Commands and reserved words typically appear in uppercase letters. Unless the manual states otherwise, you can enter these items using uppercase, lowercase, or both. For example, you can type MYPROG, myprog, or MYprog. Words appearing in bold include the following: menu names, dialog box names, commands, options, buttons, statements, etc. Monospaced font is reserved for words you enter, such as command syntax. Square brackets enclose optional information, as in [log_name]. If information is not enclosed in square brackets, it is required. A vertical bar indicates a choice of information to enter, as in [file_name | @file_name]. Angle brackets enclose multiple choices for a required item, as in /D=<5|6|7>. Words appearing in italics are variables that you must replace with appropriate values, as in file_name. An ellipsis following information indicates you can repeat the information more than one time, as in [parameter ...]. The symbol ::= means one item is defined in terms of another. For example, a::=b means the item a is defined in terms of b.

Bold

Monospaced font [ ]

< >

variable

...

::=

xvi

chapter

Introduction to Btrieve APIs

The Pervasive PSQL transactional interface is designed for highperformance data handling and improved programming productivity. The transactional interface operations allow your application to retrieve, insert, update, or delete records either by key value, or by sequential or random access methods. The Btrieve API provides compatibility with the following programming languages and development environments:

R Borland C/C++ R Borland Delphi R Micro Focus COBOL R Microsoft Visual Basic R Microsoft Visual C++ R Watcom C/C++
This chapter discusses the following topics:

Btrieve API Functions on page 1-2 Btrieve API Function Parameters on page 1-5 Summary of Btrieve API Operations on page 1-11 Sequence of Events in Performing a Btrieve API Operation on page 1-17

1-1

Introduction to Btrieve APIs

Btrieve API Functions

The Btrieve API is single-function in that most program actions are determined by an operation code parameter, rather than a function name. You should choose the API for your application based on whether you are most interested in cross-platform portability of code or the best possible performance on a particular platform. Your Btrieve application should never perform any standard I/O against a data file. Your application should perform all file I/O using a Btrieve API function. Following are the Btrieve API functions.
Table 1-1 Btrieve API Functions
Function BTRV BTRVID BTRCALL BTRCALLID BTRCALL32 BTRCALLID32 Windows NT, and Windows 9X/ME only For 32-bit OS/2 applications only Operating Systems All Description Use for complete code portability between operating systems. For most developers, this advantage offsets a very slight performance decrease. Use these functions to achieve a slight performance increase or backward compatibility with existing source code. Use these functions to achieve a slight performance increase or backward compatibility with existing source code.

To find the language-specific syntax required when calling a Btrieve API function, refer to the following section in Pervasive PSQL Programmer's Guide: Btrieve API Programming on page 11-1.

BTRV Function

BTRV allows an application to make calls to the transactional interface. All the language interface modules provided with the Programming Interfaces installation option support the BTRV function. In some cases, the BTRV function actually calls the BTRCALL function. However, BTRV is the preferred function because of the platform independence it provides. BTRVID allows an application to make a single transactional interface call that contains a clientID parameter, which the application can control. An application can use BTRVID to assign itself more than one client identity to the transactional interface and

BTRVID Function

1-2

Btrieve API Functions

to execute operations for one client without affecting the state of the other clients. For more information, refer to Client ID. In some cases, the BTRVID function actually calls another function. In 16-bit applications, it calls the BTRCALLID function. In 32-bit applications, it calls the BTRCALLID32 function (OS/2) or the BTRCALLID function (Windows NT/9X/ME). However, in both cases, BTRVID is the preferred function because of the platform independence it provides. In DOS applications, you must load the DOS Requester with the appropriate /T value. Set /T to equal the number of client IDs you use in the application. For more information about the DOS Requester, refer to Pervasives Getting Started With Pervasive PSQL manual.

BTRCALL Function

For Windows NT and Windows 9X/ME, the BTRCALL function is a 32-bit function. You should use the BTRV function instead of BTRCALL unless you cannot afford the slight performance decrease that occurs with BTRV. The BTRCALL32 function is the same as BTRCALL function, except that BTRCALL32 is a 32-bit function. Use the BTRCALLID function if you need client-level control and your application operates only in the Windows NT and Windows 9X/ME environments. This function is similar to the BTRVID function, except that it does not call an intermediate function. For Windows NT and Windows 9X/ME, BTRCALLID is a 32-bit function.

BTRCALL32 Function BTRCALLID Function

BTRCALLID32 Function Obsolete Functions

The BTRCALLID32 function is the same as the BTRCALLID function, except that the BTRCALLID32 is a 32-bit function. The following historical functions are supported to maintain compatibility with applications written for previous Btrieve API releases:

BTRCALLBACK BTRVINIT BTRVSTOP

1-3

Introduction to Btrieve APIs

RQSHELLINIT WBRQSHELLINIT WBTRVINIT WBTRVSTOP BRQSHELLINIT

While these functions are now obsolete, older applications that call these functions will still run with 6.15 and later MicroKernels.

1-4

Btrieve API Function Parameters

You must provide all parameters on every call; however, the transactional interface does not use every parameter on every operation. In some cases, the transactional interface ignores their value. In general, different parameters can be sent and returned for each operation. Chapter 2, Btrieve API Operations provides a detailed description of the parameters that are relevant for each Btrieve API operation.
Note C developers: Refer to BTITYPES.H for a description of the

platform-independent data types and pointers used in the C language interface. The parameters to the Btrieve API functions are as follows:

Operation Code Status Code (BASIC and COBOL only) Position Block Data Buffer Data Buffer Length Key Buffer Key Number Client ID (BTRVID and BTRCALLID functions only) Key Length (BTRCALL, BTRCALLID, BTRCALL32, and BTRCALLID32 functions only)

Operation Code The Operation Code parameter determines what action is

performed by the Btrieve API function. For example, the operation may read, write, delete, or update one or more records. Your application must specify a valid Operation Code on every Btrieve API call. The transactional interface never changes the Operation Code. The value of the variable you specify can be any one of the legal Btrieve API Operation Codes described in Chapter 2, Btrieve API Operations.

1-5

Introduction to Btrieve APIs

Note C developers: The variable you specify must be BTI_WORD

(an unsigned short integer), and is passed by value.

Status Code

The transactional interface returns status codes as signed integers. In most programming environments, the status code is the return value of the Btrieve API function call. However, some BASIC and COBOL language interfaces require a Status Code parameter. This parameter is a 2-byte integer containing a coded value that indicates whether any errors occurred during the operation. After a Btrieve API call, the application must always check the value of the status variable to determine if the call was successful. Pervasive PSQL components return status codes from calls to their APIs. When you write to these APIs, you should provide handling for three conditions:

API Success Anticipated API failure Unanticipated API failure

Following is a C code example that handles all three conditions.

status = BTRVID(B_VERSION, posBlock1, &versionBuffer, &dataLen, keyBuf1, keyNum, (BTI_BUFFER_PTR) &clientID); if (status == B_NO_ERROR) { /* continue normal operation */ status = BTRVID(...); } else if (status == B_RECORD_MANAGER_INACTIVE) { /* handle known error */ printf("Btrieve Get Version() returned B_RECORD_MANAGER_INACTIVE\n"); } else { /* unanticipated error */ printf("Btrieve Get Version() returned %d\n", status); } /* end if-else */

1-6

Btrieve API Function Parameters

By following this method of status code handling, you can help Pervasive Software ensure your applications future stability. Pervasive Software encourages and incorporates developer feedback in order to continuously improve our products. For example, in Pervasive PSQL 7, status code 20 was differentiated into several additional status codes based on customer feedback. Applications that handle status information as demonstrated here can accept such enhancements gracefully. (For more information about the differentiation of status codes, refer to Status Codes and Messages.)

Position Block

The Position Block parameter is the address of a 128-byte array that the transactional interface uses to store file I/O structures and the positioning information associated with an Open (0) operation. Each time your application opens a file, it must allocate a unique Position Block. The transactional interface initializes the Position Block when your application performs the Open operation, then references and updates it during file operations. Therefore, your application must specify the same Position Block on all subsequent Btrieve API operations for the file.
Note Do not write to the Position Block. Doing so could result

in a lost position error, other errors, or damage to the file. When you open more than one file at a time, the transactional interface uses the Position Block to determine which file a particular call is for. Similarly, when you open the same file more than once, the transactional interface uses a different Position Block for each separate Open operation. Likewise, the transactional interface uses a different Position Block for each separate client that opens the same file. Multiple clients cannot share position blocks.

Data Buffer

Your application transfers data to and from a file using the Data Buffer. The information passed to or from the transactional interface in the Data Buffer depends on which Btrieve API operation is being performed. Frequently, the Data Buffer contains one or more records that your application is transferring to or from a file. However, depending on the Btrieve API operation, the Data Buffer can contain other information, such as file or key specifications, transactional interface version information, and so on.

1-7

Introduction to Btrieve APIs

Be sure to allocate a large enough Data Buffer to accommodate the longest record in your file. If your Data Buffer Length parameter specifies a value larger than the allocated size of your Data Buffer, transactional interface modification operations may destroy data following the Data Buffer.

Data Buffer Length

For any operation that requires a Data Buffer, your application must pass a variable that indicates the size (in bytes) of the Data Buffer, which should be large enough to contain data that the operation returns.
Note BASIC developers: Your application must pass the Data

Buffer Length parameter ByRef as a Long integer. C, COBOL, and Pascal developers: Your application must pass the Data Buffer Length parameter as a pointer to a 2-byte unsigned integer. When you are inserting records into or updating a file with variablelength records, the Data Buffer Length should equal the record length specified when you first created the file, plus the number of characters included beyond the fixed-length portion. When you are retrieving variable-length records, the Data Buffer Length should be large enough to accommodate the longest record in the file. If a record is longer than 64 KB, you must use a chunk operation to operate on a portion of the record. The transactional interface uses the Data Buffer Length parameter to determine how much space is available in the Data Buffer. If you pass a Data Buffer Length that is longer than the Data Buffer you have allocated, you may cause the transactional interface to overwrite memory. The Data Buffer Length should always represent the size of the allocated Data Buffer.

Key Buffer

Your application must pass the Key Buffer parameter on every Btrieve API operation, even if that operation does not use a Key Buffer. Depending on the operation, your application may set the data in the Key Buffer, or the Btrieve API function may return it.

1-8

Btrieve API Function Parameters

Note BASIC developers: Your application must pass the Key

Buffer as a string. If the key value is an integer, your application should convert it to a string using the MKI$ statement before calling the Btrieve API function. If a key consists of two or more segments, you must concatenate them into a single string variable and pass the variable as the Key Buffer. The transactional interface returns an error if the string variable passed as the Key Buffer is shorter than the keys defined length. If your applications first call does not require initialization of the Key Buffer, assign the string variable the value SPACE$(x), where x represents the keys defined length. Until your application assigns some value in BASIC to the string variable, it has a length of 0. C developers: Your application must pass the Key Buffer as the address of a variable containing the key value. The file BTITYPES.H defines the Key Buffer as a VOID pointer (BTI_VOID_PTR). Your application can then define the Key Buffer type as needed. COBOL developers: Your application must pass the Key Buffer as a record variable. If the key consists of two or more segments, list them in the correct order as individual fields under an 01 level record. Then you can pass the entire record as the Key Buffer. Pascal developers: Your application must pass the Key Buffer as a variable containing a key value. If a key consists of two or more segments, use a record structure to define the individual fields in the key. In most environments, the transactional interface cannot determine the Key Buffer length when an application makes a Btrieve API call. Therefore, you must ensure that the buffer is at least as long as the key length you specified when you first created the key. Otherwise, Btrieve API operations may destroy data stored in memory following the Key Buffer. It is best to always have a 255-byte Key Buffer, because 255 is the maximum length for a key.

1-9

Introduction to Btrieve APIs

Key Number

The information passed in the Key Number parameter depends on which operation is being performed. Most often, the Key Number contains a value that indicates which of up to 119 key (access) paths to follow for a particular operation. However, other information can be sent or returned in the Key Number parameter, such as a value indicating in what mode a file is to be opened. For BTRV and BTRVID functions, the Key Number parameter is a 2byte integer. For BTRCALL, BTRCALLID, BTRCALL32, and BTRCALLID32 functions, the Key Number parameter is a 1-byte signed CHARACTER (BTI_CHAR). In all functions, the Key Number parameter has a value range of 0 through 118. A Btrieve API function never alters the Key Number parameter.

Client ID

The Client ID parameter is used only in the BTRVID and BTRCALLID functions. The Client ID parameter is the address of a 16-byte structure that allows the transactional interface to differentiate among the clients on a computer. Use the following structure for the Client ID.

Table 1-2 Client ID Structure

Element Length (bytes) 12 2 Description

Filler Service Agent ID

Initialize to 0. Identifies each instance of your application to the transactional interface. This is a 2-character ASCII value. The value of this identifier must be greater than or equal to the ASCII value AA (0x41 0x41). The transactional interface assumes special meaning for the following values: 0x4140 (@A) 0xFFFF 0x4952 (RI) 0x5244 (DR) 0x4553 (SE) 0x4353 (SC) 0x4344 (DC) 0x4544 (DE) 0x5544 (DU) Used internally. Used internally. Used internally. Used internally. Used to identify clients originated by Scalable SQL.

1-10

Btrieve API Function Parameters

Table 1-2 Client ID Structure continued

Element Length (bytes) Description

0x5257 (WR) Client Identifier 2

Used by Btrieve Requesters.

Establishes a clients identity within the current instance of your application. The transactional interface uses this unique identifier for concurrency and transaction-processing purposes.

Key Length

The Key Length parameter is used only in the BTRCALL, BTRCALLID, BTRCALL32, and BTRCALLID32 functions. When using these functions, you must pass the Key Length parameter as an unsigned char (BTI_BYTE), with a value of the allocated length of your Key Buffer. The maximum length you can specify is 255 (the maximum length of any key).

1-11

Introduction to Btrieve APIs

Summary of Btrieve API Operations

The Btrieve API provides over 40 operations that you can call from your application program. The following tables summarize these operations. Refer to Chapter 2, Btrieve API Operations, for complete descriptions of the Btrieve API operations. Refer to Appendix A, Quick Reference of Btrieve Operations, for a summary of Btrieve API operations ordered by operation code.

SessionSpecific Operations

The following operations allow you to set or retrieve the current directory, shut down a workstation transactional interface, retrieve the transactional interface version number, terminate a client connection with the server transactional interface, and begin, end, or abort a transaction. In applications that handle multiple clients, these operations are specific to the calling client.
Table 1-3 Session-Specific Operations
Operation Set Directory Get Directory Stop Code 17 18 25 Description Changes the current directory. Returns the current directory. Terminates the workstation transactional interface (not available for server-based transactional interface). Returns the version number of the transactional interface. Releases all resources held by a client. Marks the beginning of a set of logically related operations. Operation 19 begins an exclusive transaction. Operation 1019 begins a concurrent transaction. Marks the end of a set of logically related operations. Removes operations performed during an incomplete transaction.

Version

Reset Begin Transaction

28 19 1019

End Transaction

Abort Transaction

1-12

Summary of Btrieve API Operations

File-Specific Operations

The following operations deal with a specific file, and therefore use the position block parameter to identify the file on which to operate. The file-specific operations are of three types:

File access and information. These operations allow you to create a file, open and close a file, retrieve file statistics, set and clear the files owner name, start or stop continuous operation mode on a file, unlock a file, and create and drop indexes on a file.
Data retrieval. These operations allow you to retrieve a single

record or a set of records given specified criteria. The Btrieve API supports data retrieval either by logical location in an index path or by physical location. For more information, refer to Accessing Records in the Pervasive PSQL Programmer's Guide. In addition, you can apply biases to the operation codes to control file and record locking in multi-client situations. For more information, refer to Supporting Multiple Clients in the Pervasive PSQL Programmer's Guide.

Data manipulation. These operations allow you to insert, update, or delete data.

Table 1-4 File Access and Information Operations

Operation Open Close Create Stat Code 0 1 14 15 Description Makes a file available for access. Releases a file from availability. Creates a file with the specified characteristics. Returns file and index characteristics, and number of records. Returns file names and paths of an extended files components and reports whether a file is using a system-defined log key. Assigns an owner name to a file. Removes an owner name from a file. Places the specified file in or removes the file from continuous operation mode, for use in system backups.

Stat Extended

Set Owner Clear Owner Continuous Operation

29 30 42

1-13

Introduction to Btrieve APIs

Table 1-4 File Access and Information Operations continued

Operation Unlock Create Index Drop Index Code 27 31 32 Description Unlocks a record or records. Creates an index. Removes an index.

Table 1-5 Data Retrieval Operations

Operation Code Description

Index-Based (Logical) Data Retrieval Get Equal 5 Returns the first record in the specified index path whose key value matches the specified key value. Returns the record following the current record in the index path. Returns the record preceding the current record in the index path. Returns the first record in the specified index path whose key value is greater than the specified key value. Returns the first record in the specified index path whose key value is equal to or greater than the specified key value. Returns the first record in the specified index path whose key value is less than the specified key value. Returns the first record in the specified index path whose key value is equal to or less than the specified key value. Returns the first record in the specified index path. Returns the last record in the specified index path. Returns one or more records that follow the current record in the index path. Filtering conditions can be applied. Returns one or more records that precede the current record in the index path. Filtering conditions can be applied.

Get Next

Get Previous

Get Greater Than

Get Greater Than or Equal

Get Less Than

Get Less Than or Equal

Get First Get Last Get Next Extended

12 13 36

Get Previous Extended

1-14

Summary of Btrieve API Operations

Table 1-5 Data Retrieval Operations continued

Operation Get Key Code +50 Description Detects the presence of a key value in a file, without returning an actual record. Returns the record located approximately at a position derived from the specified percentage value. Returns a percentage figure based on the current records position in the file.

Get By Percentage

Find Percentage

Non-Index-Based (Physical) Retrieval Get Position Get Direct/Chunk 22 23 Returns the position of the current record. Returns data from the specified portions (chunks) of a record at a specified position. Returns the record at a specified position.

Get Direct/ Record Step Next

Returns the record from the physical location following the current record. Returns the record in the first physical location in the file. Returns the record in the last physical location in the file. Returns the record in the physical location preceding the current record. Returns one or more successive records from the location physically following the current record. Filtering conditions can be applied. Returns one or more preceding records from the location physically preceding the current record. Filtering conditions can be applied. Returns the record located approximately at a position derived from the specified percentage value. Returns a percentage figure based on the current records position in the file.

Step First

Step Last

Step Previous

Step Next Extended

Step Previous Extended

Get By Percentage

Find Percentage

1-15

Introduction to Btrieve APIs

Table 1-5 Data Retrieval Operations continued

Operation Code Description

Concurrency Control Biases (Add to the Appropriate Operation Code) Single-record wait read lock Single-record no-wait read lock +100 Locks only one record at a time. If the record is already locked, the client retries the operation. Locks only one record at a time. If the record is already locked, the transactional interface returns an error status code. Locks several records concurrently in the same file. If the record is already locked, the client retries the operation. Locks several records concurrently in the same file. If the record is already locked, the transactional interface returns an error status code. In a concurrent transaction, tells the transactional interface not to wait if the page to be changed has already been changed by another active concurrent transaction. This bias can be combined with any of the record locking read biases (+100, +200, +300, or +400).

+200

Multiple-record wait read lock

+300

Multiple-record no-wait read lock

+400

No-wait page write lock

+500

Table 1-6 Data Manipulation Operations

Operation Insert Update Delete Insert Extended Update Chunk Code 2 3 4 40 53 Description Inserts a new record into a file. Updates the current record. Removes the current record from the file. Inserts one or more records into a file. Updates specified portions (chunks) of the current record. This operation can also append data to a record or truncate a record.

Unsupported Operations

When looking at transactional interface traces or SDK header files, you may see operations that are not listed in the reference for Btrieve API operations. These are for the internal use of Pervasive PSQL and you should not use them in your applications. The following operations are not supported.

1-16

Summary of Btrieve API Operations

Table 1-7 Unsupported Operations

Operation B_MISC_DATA Code 41 Description Reserved for use by transactional interface Reserved for use by SQL engine Reserved for use by transactional interface

B_EXTEND

Begin Transaction (nested) via Btrieve

2019

1-17

Introduction to Btrieve APIs

Sequence of Events in Performing a Btrieve API Operation

To perform a Btrieve API operation, your application
must complete the following tasks:
1

Satisfy any prerequisites the operation requires. For example, before your application can perform any file I/O operations, it must make the file available by performing an Open operation (0) on that file. Initialize the parameters that the Btrieve API operation requires. The parameters are program variables or data structures that correspond in type and size to the particular values that the transactional interface expects for an operation. For future compatibility, initialize all parameters, whether or not they are used. For parameters of type INTEGER, set the value to binary 0. For character arrays, pass a pointer to a buffer. Initialize the first byte of the buffer to binary 0.

3 4

Call the appropriate Btrieve API function. (Refer to Btrieve API Functions on page 1-2.) Evaluate the results of the function call. Every Btrieve API operation returns a status code. Your application must check the status code and take the appropriate action. The operation also returns data or other information to the individual parameters based on the purpose of the operation.

1-18

chap-

Btrieve API Operations

This chapter describes the operations your application can perform using the Btrieve API. For each operation, this chapter presents the following information:

Name, code, and description of the operation. Parametersa table indicating which of the six parameter values the operation expects from and returns to your application. A Sent parameter is sent from the application to the operation; a Returned parameter is returned from the operation to the application when the operation is complete. Prerequisitesthe conditions your application must satisfy for the operation to be successful. Procedurethe steps for initializing the parameters that the operation requires. Detailsadditional information about the operation. Resultthe results of both a successful and an unsuccessful operation. Each operation returns a status code, informing your application of the outcome of the operation. Status Code 0 indicates the operation was successful. A nonzero status code usually indicates a failure. However, some nonzero status codes are informative and appear even when the associated operation is successfulfor example, Status Code 60 means the specified reject count has been reached. Positioningthe effect the operation has on the logical and/or physical currency of the records in a file.

This chapter includes the following Btrieve API operations, organized alphabetically:

Abort Transaction (21) on page 2-4 Begin Transaction (19 or 1019) on page 2-5 Clear Owner (30) on page 2-7 Close (1) on page 2-8 Continuous Operation (42) on page 2-10

2-1

Btrieve API Operations

Create (14) on page 2-14 Create Index (31) on page 2-32 Delete (4) on page 2-38 Drop Index (32) on page 2-40 End Transaction (20) on page 2-42 Find Percentage (45) on page 2-43 Get By Percentage (44) on page 2-47 Get Direct/Chunk (23) on page 2-51 Get Direct/Record (23) on page 2-60 Get Directory (18) on page 2-62 Get Equal (5) on page 2-63 Get First (12) on page 2-65 Get Greater (8) on page 2-67 Get Key (+50) on page 2-71 Get Last (13) on page 2-73 Get Less Than or Equal (11) on page 2-77 Get Next (6) on page 2-79 Get Next Extended (36) on page 2-81 Get Position (22) on page 2-90 Get Previous (7) on page 2-91 Get Previous Extended (37) on page 2-93 Insert (2) on page 2-95 Insert Extended (40) on page 2-98 Login/Logout (78) on page 2-102 Open (0) on page 2-104 Reset (28) on page 2-109 Set Directory (17) on page 2-110 Set Owner (29) on page 2-111 Stat (15) on page 2-113 Stat Extended (65) on page 2-118 Step First (33) on page 2-129 Step Last (34) on page 2-131 Step Next (24) on page 2-133 Step Next Extended (38) on page 2-135

2-2

Step Previous (35) on page 2-139 Step Previous Extended (39) on page 2-141 Stop (25) on page 2-143 Unlock (27) on page 2-144 Update (3) on page 2-146 Update Chunk (53) on page 2-149 Version (26) on page 2-158

2-3

Btrieve API Operations

Abort Transaction (21)

The Abort Transaction operation (B_AB ORT_TRAN) terminates the current transaction and removes the results of all operations performed since the beginning of the transaction. It also unlocks all files and records locked by the transaction.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returne d

Prerequisites Procedure Result

You must issue a successful Begin Transaction operation (19 or 1019) before you issue an Abort Transaction operation. Set the Operation Code to 21. The transactional interface ignores all other parameters on an Abort Transaction call. If the Abort Transaction operation is successful, the transactional interface returns Status Code 0. The results of all Insert, Update, and Delete operations issued since the beginning of the transaction are removed from the files. If the Abort Transaction operation is unsuccessful, the transactional interface returns one of the following status codes:
36 39 The application encountered a transaction error. A Begin Transaction operation must precede an End/Abort Transaction operation.

Positioning

The Abort Transaction operation has no effect on any file currency information.

2-4

Begin Transaction (19 or 1019)

The Begin Transaction operation (B_BEGIN_TRAN) defines the start of a transaction. Transactions are useful when you need to perform multiple Btrieve API operations as a single event. For example, use a transaction if your database would become logically inconsistent if some operations were successful, but at least one operation failed to complete successfully. By enclosing a set of operations between Begin and End Transaction operations, you can ensure that the transactional interface does not permanently complete any operations in the set unless you request the completion with an explicit End Transaction operation (20). Changes made within a transaction are not visible to other users until the End Transaction operation is successfully performed. The transactional interface prohibits certain operations during transactions because they have too great an effect on the file or on performance. These operations include Set Owner, Clear Owner, Create Index, and Drop Index.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites Procedure

Your application must end or abort any previous transaction before issuing a Begin Transaction operation. Set the Operation Code to 19 to begin an exclusive transaction, or 1019 to begin a concurrent transaction. The transactional interface ignores all parameters except the Operation Code on any Begin Transaction call. On any Begin Transaction operation, you can specify default lock biases:

+100Single wait record lock. +200Single no-wait record lock.

2-5

Btrieve API Operations

+300Multiple wait record lock. +400Multiple no-wait record lock.

On a Begin Concurrent Transaction operation, you can add +500 to the Operation Code (1519), which forces the transactional interface not to retry the Insert, Update, and Delete operations within a transaction. In addition, you can combine the +500 bias with a default lock bias. For example, using 1019 + 500 + 200 (1719) begins a concurrent transaction, suppresses retries for Insert, Update, and Delete operations, and specifies single no-wait read locks at the same time. For more information about transactions and locking, refer to the API Programmers Reference.

Result

If the Begin Transaction operation is successful, the transactional interface returns Status Code 0. If the Begin Transaction operation is unsuccessful, the transactional interface returns one of the following status codes:
36 37 The application encountered a transaction error. Another transaction is active.

Positioning

The Begin Transaction operation has no effect on any file currency information.

2-6

Clear Owner (30)

The Clear Owner operation (B_CLEAR_OWNER) removes an owner name that you have previously assigned to a file with the Set Owner operation. If the file was previously encrypted, the transactional interface decrypts the file during a Clear Owner operation.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites

The file must be open, and an owner name must have been specified. No transactions can be active. Set the Operation Code to 30. Pass the Position Block that identifies the file to clear.

Procedure

1 2

Result

After a Clear Owner operation, the transactional interface no longer requires the owner name to open or modify a file. If you encrypted the data in the file when you assigned the owner, the transactional interface decrypts the data during a Clear Owner operation. The more data that was encrypted, the longer the Clear Owner operation takes. If the Clear Owner operation is unsuccessful, the transactional interface returns one of the following status codes:
3 41 The file is not open. The transactional interface does not allow the attempted operation.

Positioning

The Clear Owner operation has no effect on any file currency information.

2-7

Btrieve API Operations

Close (1)
The Close operation (B_CLOSE) closes the file associated with a specified Position Block and releases any locks your application has executed for the file. Your application should always perform a Close operation when it has finished accessing a file. After a Close operation, your application cannot access the file again until it issues another Open operation (0) for that file. You can close a file even while inside a transaction. However, the Close operation does not end the transaction; you must explicitly end or abort the transaction. If you abort the transaction, changes made inside the transaction are aborted; if you end the transaction, changes are committed.
Note When you close a file inside a transaction, the transactional interface continues to keep an open handle on the file until the transaction is either aborted or ended so that updates to that file can be handled properly. The Position Block for the file is no longer available to your application, however.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites Procedure

The file must be open. Set the Operation Code to 1. Pass a valid Position Block for the file to close.

1 2

Result

If the Close operation is successful, the Position Block for the closed file is no longer valid.

2-8

Close (1)

If the Close operation fails, the file remains open and the transactional interface returns the following status code:
3 The file is not open.

Positioning

The Close operation destroys both the physical and the logical currency information of the file.

2-9

Btrieve API Operations

Continuous Operation (42)

The Continuous Operation operation (B_CONTINUOUS) allows you to perform system backups without closing active transactional interface files. Any changes you make while a file is being backed up are stored in a temporary file called a delta file. Except for changes written to the delta file, the system backup includes the contents of all files placed in continuous operation mode. The transactional interface automatically rolls the delta file changes into the backed up files when those files are taken out of continuous operation mode.
Note This operation is available only to applications running on

a local engine. A client application cannot use this operation for files that are located on a remote machine. This operation also allows you to safely copy a file while that file is still active. In a client/server set up, the client that begins Continuous Operation on a file must be the client that stops Continuous Operation on that file.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Note Values for the Data Buffer parameter and the Data Buffer

Length parameter are required only if the value of the Key Number parameter is 0 (which starts continuous operation mode) or 2 (which ends continuous operation mode). The following sections discuss these Key Number values. A Data Buffer Length of zero is required for a Key Number parameter of 1.

2-10

Continuous Operation (42)

Procedure

To start continuous operation mode, perform the

following steps:
1

Define a file or a set of files for backup, or add a file to the set of files currently defined for backup. a. Set the Operation Code to 42. b. Place the names of the files you want to place in continuous operation mode into the Data Buffer parameter. Include the full pathname, excluding only the server name. Separate the names with commas and terminate the list of names with a binary 0. The following example is for Windows NT servers:
f:\acct\march.mkd,f:\acct\april.mkd

The following example is for NetWare servers:

sys:\acct\march.mkd,sys:\acct\april.mkd

c. Place the length of the name (or names) in the Data Buffer Length parameter. This value must be equal to or greater than the actual length of the names (including binary zeros) in the Data Buffer itself. For example, the preceding names require a Data Buffer Length of 40 or greater. d. Set the Key Number parameter to 0.
2 3

Perform the backup. End continuous operation mode. a. Set the Operation Code to 42. b. Set the Key Number parameter to 1. To end continuous operation on one or more specific files, set the Key Number parameter to 2, and then place the filenames in the Data Buffer parameter as described in step 1b. Also, place the length of the name (or names) in the Data Buffer Length parameter as described in step 1c.

Details

When defining the set of files to be backed up, keep in mind the following information:

The transactional interface does not consider the absence of filenames in the Data Buffer to be an error. If it finds no filenames, the transactional interface takes no action on the Continuous Operation operation.

2-11

Btrieve API Operations

The presence of duplicate filenames in the Data Buffer does not affect how the Continuous Operation operation works. The MKDE places the specified file in continuous operation mode only once. No two files are allowed to share the same base file name and differ only in their extension. This restriction is because the name of the delta file uses the corresponding files base name with .^^^ for the extension. The transactional interface would attempt to write to the same delta file for both files, possibly causing data corruption or status 85. Also, no files will be placed into continuous operations when this condition occurs, even if these files are part of a larger list to be placed into continuous operations. An application can iteratively call the Continuous Operation operation to add more names to the list of files to be placed in continuous operation mode. However, this action can corrupt a backup when referential integrity (RI) constraints are placed on any of the files by the SRDE. Files related by referential integrity constraints should be passed in on a single continuous operations call. The transactional interface returns Status Code 88 if a file is specified that is already in continuous operation mode.

When writing a server-based application that calls the Continuous Operation operation, make sure you call btrvID, and use a valid client ID so you can begin and end continuous operation under the same client. The Btrieve API allows you to define multiple backup sets by specifying a different client ID for each backup set through the btrvID function. However, two sets cannot contain the same files. While the transactional interface rolls changes from the delta file into the data file, users can continue to update, insert, and read the transactional interface file just as they normally would. The transactional interface appends new pages to the delta file while rolling in changes, if an insert requires such an action. No changes are lost.
Note Never delete a delta file manually.

2-12

Continuous Operation (42)

If your application uses the btrv function, do not unload the application while any file is in continuous operation mode. If you do, you may be unable to remove the affected files from continuous operation mode. This is because the default client ID that the transactional interface originally assigned as the owner of the affected files may have been reassigned to another application. Because the transactional interface no longer knows the proper owner of the affected files, it is unable to remove those files from continuous operation mode. If the system crashes while in continuous operation mode or while the transactional interface is rolling the changes from a delta file into the file, then the transactional interface rolls all changes into the file when it is first opened after the system is rebooted.

Result

If the Continuous Operation operation is successful, the transactional interface returns Status Code 0, but it returns no values either in the Data Buffer or in the Data Buffer Length parameter. If the operation is unsuccessful, the transactional interface returns one of the following status codes:
11 12 41 51 88 91 The specified filename is invalid. The transactional interface cannot find the specified file. The transactional interface does not allow the attempted operation. The owner name is invalid. The application encountered an incompatible mode error. The application encountered a server error.

In addition to the preceding codes, your application can return standard I/O error codes such as Status Code 18. If the transactional interface returns a nonzero status code, the Continuous Operation operation returns in the Data Buffer the portion of the input string that generated the error. If no input string was used, the Data Buffer contains the file names that caused the error. The Data Buffer Length reflects the length of the output string in the Data Buffer. At this point, the Data Buffer Length contains the length of that filename.

2-13

Btrieve API Operations

Positioning

The Continuous Operation operation does not establish any currency on the file.

2-14

Create (14)

Create (14)
The Create operation (B_CREATE) lets you generate a new data file from within your application. The Create operation also has subfunctions that allow you to delete or rename a file (see Delete and Rename Subfunctions for the Create Operation on page 2-28).

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites Procedure

If you are creating an empty file over an existing file, ensure that the existing file is closed before executing the Create operation.
1 2

Set the Operation Code to 14. Specify the file specifications, key specifications, and any alternate collating sequences in the Data Buffer as described in Details. (All the values for the file specifications and key specifications you store in the Data Buffer must be in binary format.) Specify the Data Buffer Length. This is the length of the buffer that contains the Create specifications, not the length of the records in the file. Specify the pathname for the file in the Key Buffer. Be sure to terminate the pathname with a blank or binary zero. The pathname can be up to 80 characters long, including the volume name and the terminator. For more information about path names the transactional interface supports, refer to Getting Started With Pervasive PSQL.

Specify a value for the Key Number parameter, using one of the values in Table 2-7 on page 2-28.

2-15

Btrieve API Operations

Details

Table 2-1 illustrates the order in which the file and key specifications must be stored.
Table 2-1 Data Buffer Structure for Create Operation
Description Data Type1 Byte # Example Value2

File Specification Logical Fixed Record Length3 Short Int4 0, 1 Size of all fields combined. 512

Pervasive PSQL 6.x through 9.4 Pervasive PSQL 6.x and later Pervasive PSQL 6.x through 9.4 Pervasive PSQL 6.x and later Pervasive PSQL 6.x through 9.4 Page Size. Pervasive PSQL 6.x and later Pervasive PSQL 9.0 through 9.4x Pervasive PSQL 9.5 and later Short Int 2, 3

1,024

1,536

2,048

3,072 3,584 4,096

8,192

16,384

A minimum size of 4096 bytes works best for most files. When creating 9.5 file format files, if the logical page size specified is valid for the file format, the MicroKernel rounds the specified value to the next higher valid value if one exists. For all other values and file formats, the operation fails with status code 24. No rounding is done for the older file formats. Number of Keys (Indexes) Byte 4

2-16

Create (14)

Table 2-1 Data Buffer Structure for Create Operation continued

Description Data Type1 Byte # Example Value2

0x60 0x70 0x80 File Version Byte 5 0x90 0x95 0x00

Version 6.0 Version 7.0 Version 8.0 Version 9.0 Version 9.5 Use database engine default

Reserved. (Not used during a Create operation.) File Flags. Specifies the file attributes. The example file does not use any. Number of Extra Pointers. Sets the number of duplicate pointers to reserve for future key additions. Used if the file attributes specify Reserve Duplicate Pointers. Reserved. (Not used during a Create operation.) Preallocated Pages. Sets the number of pages to preallocate. Used if the file attributes specify Page Preallocation.

Reserve d Short Int

6- 9

10, 11

Byte

Reserve d Short Int

14, 15

Key Specification for Key 0 (Last Name) Key Position. Provides the position of the first byte of the key within the record. The first byte in the record is 1. Key Length. Specifies the length of the key, in bytes. Short Int 16, 17 1

Short Int

18, 19

2-17

Btrieve API Operations

Table 2-1 Data Buffer Structure for Create Operation continued

Description Data Type1 Short Int Byte # Example Value2

Key Flags. Specifies the key attributes.

20, 21

EXTTYPE_KEY + NOCASE_KEY + DUP + MOD 0 ZSTRING

Not Used for a Create. Extended Key Type. Used if the key flags specify Use Extended Key Type. Specifies one of the extended data types. Null Value (legacy nulls only). Used if the key flags specify Null Key (All Segments) or Null Key (Any Segment). Specifies an exclusion value for the key. See Null Value on page 4-17 for more conceptual information on legacy nulls and true nulls. Not Used for a Create. Manually Assigned Key Number. Used if the file attributes specify Key Number. Assigns a key number. ACS Number. Used if the key flags specify Use Default ACS, Use Numbered ACS in File, or Use Named ACS. Specifies the ACS number to use.

Byte Byte

22-25 26

Byte

Byte Byte

28, 29 30

0 0

Byte

Key Specification for Key 1 (Employee ID) Key Position. (Employee ID starts at first byte after Middle Initial.) Key Length. Key Flags. Not Used for a Create. Extended Key Type. Null Value. Short Int 32, 33 52

Short Int Short Int Byte Byte Byte

34, 35 36, 37 38-41 42 43

4 EXTTYPE_KEY + MOD 0 INTEGER 0

2-18

Create (14)

Table 2-1 Data Buffer Structure for Create Operation continued

Description Data Type1 Byte Byte Byte Byte # Example Value2

Not Used for a Create. Manually Assigned Key Number. ACS Number.
1Unless 2For 3

44, 45 46 47

0 0 0

specified otherwise, all data types are unsigned.

simplification, the non-numeric example values are for C applications.

For files with variable-length records, the logical record length refers only to the fixed-length portion of the record. Short Integers (Short Int) must be stored in the Little Endian byte order, which is the Low To High ordering of Intel-class computers.

Note You must allocate the not used and reserved areas of

the Data Buffer, even though the transactional interface does not use them for a Create operation. Initialize the reserved areas to zero to maintain compatibility with future releases.

File Specification Store the file specification in the first 16 bytes of the Data Buffer. The bytes are numbered beginning with 0. Store the information for the record length, page size, and number of indexes as integers.
Logical Record Length. (Offset 0x00) The logical record length is the number of bytes of fixed-length data in the file. (Do not include variable-length data in the logical record length.) Page Size. (Offset 0x02) Page size is determined by your file format version. See Choosing a Page Size on page 5-20 in Pervasive PSQL Programmer's Guide. Number of Indexes. (Offset 0x04) The number of indexes is the

number of keys (not key segments) you are defining for the file. To create a data-only file, set the number of indexes to 0.
File Version. (Offset 0x05) The transactional interface file version to

be created. In prior releases, the transactional interface used a two byte integer to receive the number of indexes on a create operation.

2-19

Btrieve API Operations

The high order byte of this integer was always zero because the maximum number of indexes is 119. This high-order byte has always been used in the Stat operation to return the file version and it can now be used to specify the file version in the Create operation without breaking any previous applications. The supported file versions for Create are 6.x, 7.x, 8.x, 9.x, 9.5 which are represented in the specified byte with hex values 0x50, 0x60, 0x70, 0x80, 0x90, 0x95, respectively.
Physical Page Size. (Offset 0xA). This field is ignored. File Flags. (Offset

0x0A) The bit settings in the File Flags word specify file attributes. Table 2-2 shows the binary, hexadecimal, and decimal representations of the file flag values.
Table 2-2 File Flag Values
Attribute Variable Length Records Constant VAR_RECS Binary 0000 0000 0000 0001 0000 0000 0000 0010 0000 0000 0000 0100 0000 0000 0000 1000 0000 0000 0001 0000 0000 0000 0010 0000 0000 0000 0100 0000 0000 0000 1000 0000 0000 0000 1100 0000 0000 0001 0000 0000 0000 0010 0000 0000 Hex 1 Decimal 1

Blank Truncation

BLANK_TRUNC

Page Preallocation

PRE_ALLOC

Data Compression

DATA_COMP

Key-Only File

KEY_ONLY

Balanced Index

BALANCED_KEYS

10% Free Space

FREE_10

20% Free Space

FREE_20

128

30% Free Space

FREE_30

192

Reserve Duplicate Pointers

DUP_PTRS

100

256

Include System Data1

INCLUDE_SYSTEM_DATA

200

512

2-20

Create (14)

Table 2-2 File Flag Values continued

Attribute Do Not Include System Data Constant NO_INCLUDE_SYSTEM_DATA Binary 0001 0010 0000 0000 0000 0100 0000 0000 0000 1000 0000 0000 Hex 1200 Decimal 4,608

Key Number

SPECIFY_KEY_NUMS

400

1,024

Use VATs

VATS_SUPPORT

800

2,048

1If

you do not explicitly specify whether to include system data in the file, the Btrieve API uses the current setting of the transactional interface configuration option Include System Data.

Avoid using incompatible flags; flags are incompatible if they use the same bit positions. Unused bits are reserved for future use. Set them to 0. To combine file attributes, add their respective File Flag values. For example, to specify a file that allows variable-length records and uses blank truncation, initialize the File Flags word to 3 (2 + 1). The transactional interface ignores the Blank Truncation and Free Space bits if the Variable Length Records bit is set to 0. If you set the Page Preallocation bit, use the last 2 bytes in the file specification block (allocation) to store an integer value that specifies the number of pages to preallocate to the file. If you set the Data Compression bit, the transactional interface ignores the Variable Length Records bit. If you set the Key-only File bit, the transactional interface ignores the System Data bits. The database engine automatically uses data compression on files that use system data and have a record length that exceeds the maximum length allowed. See Table 4-10 on page 4-41. Set the Duplicate Pointers bit if you anticipate adding an index sometime after creating a file, and if that index has many duplicate values. Setting this bit causes the transactional interface to reserve space in each record of the file for pointers that link the duplicate values. By reserving this space, you can possibly lower retrieval time and save disk space, especially if the keys are long and you anticipate that many records will have duplicate key values.

2-21

Btrieve API Operations

Note You can reserve duplicate pointer space only for indexes

that are added after file creation. Therefore, when reserving space for pointers to duplicate values, do not include space for the indexes created during this Create operation. Also, the transactional interface does not reserve duplicate pointer space for any key you specify as a repeating-duplicatable key. Set the Key Number bit if you need to assign a specific number to a key, and place the desired key number in the Manually Assigned Key Number element (offset 0x0E) of the Key Specification block. The transactional interface does not require consecutive key numbers; files can have gaps between key numbers. When a key is created, by default the transactional interface assigns the lowest available key number to that index (beginning with 0). However, some applications may require a key number different from the default assignment. Set the Use VATs bit if the file uses Variable-tail Allocation Tables. To use VATs, a file must use variable-length records.
Number of Duplicate Pointers to Reserve. (Offset 0x0C) You can specify

the number of duplicate pointers to reserve for each file. Use this element only if you specified the Reserve Duplicate Pointers file flag. For more information about duplicatable keys, refer to the following topic in Pervasive PSQL Programmer's Guide: Duplicatable Keys on page 5-33.
Allocation. (Offset 0x0E) You can specify the number of pages to

preallocate. Use this element only if you specified the Page Preallocation file flag. For more information about page preallocation, see the following topic in Pervasive PSQL Programmer's Guide: Page Preallocation on page 5-35. Key Specification Blocks Place the key specification blocks immediately after the file specification. Allocate a 16-byte key specification block for each key segment in the file. Store the information for the Key Position and the Key Length as integers.

2-22

Create (14)

The maximum number of key segments allowed depends on the files page size.
Page Size (bytes) Maximum Key Segments byFile Version 8.x and prior 512 1,024 1,536 2,048 2,560 3,072 3,584 4,096 8,192 16,384
1n/a 2

9.0 8 23 24 54 54 54 54 119 119 n/a1

9.5 rounded up2 97 rounded up2 97 rounded up2 rounded up2 rounded up2 204 420 420

8 23 24 54 54 54 54 119 n/a1 n/a1

stands for not applicable

rounded up means that the page size is rounded up to the next size supported by the file version. For example, 512 is rounded up to 1,024, 2,560 is rounded up to 4,096, and so forth.

See also the status codes 26: The number of keys specified is invalid on page 1-68 and 29: The key length is invalid on page 1-71, both in Status Codes and Messages.
Key Position. (Offset 0x00) The key position is the byte offset at which

the key or key segment begins. Positions are relative to 1; A key at the beginning of the record starts at position 1. There is no position 0.
Key Length. (Offset 0x02) The length of the key or key segment. The

maximum length of a key, including all key segments, is 255 bytes.

2-23

Btrieve API Operations

Key Flags. (Offset 0x04) The bit settings in the Key Flags word specify key attributes. Table 2-3 shows the binary, hexadecimal, and decimal representations of the Key Flags values. Table 2-3 Key Flag Values
Attribute Duplicates allowed (linked duplicates is default, or combine with REPEAT_DUPS_KEY for repeating duplicates) Modifiable Key Values Use Old Style BINARY Data Type Use Old Style STRING Data Type (bits 2 and 8 must be 0) Null Key (All Segments) Segmented Key Use Default ACS Use Numbered ACS in File Use Named ACS Descending Sort Order Repeating Duplicates (combine with attribute DUP) Use Extended Data Type Null Key (Any Segment) Case Insensitive Key NUL SEG ALT NUMBERED_ACS NAMED_ACS DESC_KEY REPEAT_DUPS_K EY EXTTYPE_KEY MANUAL_KEY NOCASE_KEY Constant DUP Binary 0000 0000 0000 0001 Hex 1 Decimal 1

MOD BIN

0000 0000 0000 0010 0000 0000 0000 0100 0000 0000 0000 0000

2 4 0

0000 0000 0000 1000 0000 0000 0001 0000 0000 0000 0010 0000 0000 0100 0010 0000 0000 1100 0010 0000 0000 0000 0100 0000 0000 0000 1000 0000

8 10 20 420 C20 40 80

8 16 32 1,056 3,104 64 128

0000 0001 0000 0000 0000 0010 0000 0000 0000 0100 0000 0000

100 200 400

256 512 1,024

Avoid using incompatible flags; flags are incompatible if they use the same bit positions. Unused bits are reserved for future use. Set them to 0. To combine key attributes, add their respective Key Flags values. For example, if the key is an extended type, part of a segmented key, and to be collated in descending order, initialize the Key Flags word to 336 (256 + 16 + 64).

2-24

Create (14)

The Segmented Key attribute indicates that the next key specification block in the Data Buffer refers to the next segment of the same key. Follow these rules for segmented keys:

All segments of the same key must have the same Duplicate Key Values, Repeating Duplicates, Modifiable Key Values, and Null Key values. (If you specify the legacy Null Key attribute, either All Segments or Any Segment, you can assign different null values for individual segments.) All segments of the same key must use the same ACS. Individual segments of the same key can have different Descending Sort Order and Extended Data Type values.

ACSs are applicable only to STRING, LSTRING, and ZSTRING keys. You cannot define a key that is both case-insensitive and uses an ACS. In a file in which a key has an ACS designated for some segments but not for others, the segments that designate an ACS are sorted by the specified ACS; the segments with no ACSs are sorted according to their respective types.

2-25

Btrieve API Operations

Extended Data Type. (Offset 0x0A) You specify the Extended Data Type in byte 10 of the Key Specification block as a binary value. Table 2-4 shows the codes for the extended data types. Table 2-4 Extended Data Types
Type CHAR INTEGER FLOAT DATE TIME DECIMAL MONEY LOGICAL NUMERIC BFLOAT LSTRING Code 0 1 2 3 4 5 6 7 8 9 10 Type ZSTRING UNSIGNED BINARY AUTOINCREMENT NUMERICSTS NUMERICSA CURRENCY TIMESTAMP WSTRING WZSTRING GUID NULL INDICATOR SEGMENT Code 11 14 15 17 18 19 20 25 26 27 255

Extended data type codes 12, 13, 16, and 21 through 24 are reserved for future use. You can define the STRING and UNSIGNED BINARY data types as either standard or extended types. This maintains compatibility with applications that were developed with earlier versions of Btrieve API, while allowing newer applications to use extended data types exclusively. Regarding the data type you assign to a key, transactional interface does not ensure that the records you input adhere to the data types defined for the keys. For example, you could define a TIMESTAMP key in a file, but store a character string there. Your Btrieve API application would work fine, but an ODBC application that tries to access the same data using the ODBC TIMESTAMP format might fail, because the byte format could be different and the algorithms used to generate the timestamp value could be different. For complete descriptions of the data types, refer to SQL Engine Reference.

2-26

Create (14)

Null Value. (Offset 0x0B) of the Key Specification block represents an

exclusion value for the key. If you have defined a key as a null key, you must supply a value for the transactional interface to recognize as the null value for each key segment. This is in reference to the legacy null and does not reflect true nulls. For a discussion of null support, see the following topic in Pervasive PSQL Programmer's Guide: Null Value on page 4-17.
Manually Assigned Key Number. (Offset 0x0E) The transactional

interface allows an application to assign specific key numbers when creating a file with indexes. To manually assign key numbers to each index for a file, specify each keys number as a binary value in byte 14 of the key specification block, and set the Key Number bit (0x400) in the File Flags word. Key numbers must be unique to the file and must be specified in ascending order, beginning with key 0. They must also be valid (less than the maximum number of keys for the files page size). The ability to manually assign key numbers complements to the ability to delete a key and not have the transactional interface renumber all keys that have a key number greater than the deleted key. For example, if an application drops an index and instructs the transactional interface not to renumber higher-numbered keys, and if a user then clones the affected file without assigning specific key numbers, the cloned file has different key numbers than the original.
ACS Number. (Offset 0x0F) For keys that use a specific ACS, offset

0x0F in the key specification block provides the ACS number by which to collate the key. The ACS number is based on its position in the Data Buffer. The first ACS following the last key specification block is ACS number 0. Following ACS 0 is ACS 1, which is followed by ACS 2, and so on. Alternate Collating Sequence Your application specifies ACSs one after the other immediately following the last key specification block in the Data Buffer.
User-Defined ACSs. To create an ACS that sorts string values

differently from the ASCII standard, your application must place 265

2-27

Btrieve API Operations

bytes directly into the Data Buffer, using the format displayed in Table 2-5 on page -27.
Table 2-5 Data Buffer for Creating a User-Defined ACS
Offset Length (Bytes) 1 8 Description

0 1

Signature byte. Specify 0xAC. A unique 8-byte name that identifies the ACS to the transactional interface. A 256-byte map. Each 1-byte position in the map corresponds to the code point having the same value as the positions offset in the map. The value of the byte at that position is the collating weight assigned to the code point. For example, to force code point 0x61 (a) to sort with the same weight as code point 0x41 (A), place the same values at offsets 0x61 and 0x41.

256

For examples of user-defined ACSs, refer to the following topic in Pervasive PSQL Programmer's Guide: Alternate Collating Sequences on page 4-28.
International Sort Rules (ISRs). To specify an ISR, your application must place 265 bytes directly into the Data Buffer, using the following format: Table 2-6 Data Buffer for Specifying an ISR ACS
Offset Length (Bytes) 1 16 Description

0 1

Signature byte. Specify 0xAE. A unique 16-byte name that identifies the ISR table to the transactional interface. Refer to the Pervasive PSQL Programmer's Guide for a list of ISR table names. Filler.

248

Data Buffer Length The Data Buffer Length must be long enough to include the file specifications, the key specifications, and any ACSs that have been defined. Do not specify the files record length in this parameter.

2-28

Create (14)

For example, to create a file that has two keys of one segment each and an ACS, the Data Buffer for the Create operation should be at least 313 bytes long, as follows:
File Spec 16 + + Key Spec 16 + + Key2 Spec 16+ + + ACS 265 = 313

Key Number The Create operations Key Number parameter is used to determine if the transactional interface warns you when a file of the same name already exists, and also to determine whether the transactional interface should use a local or remote engine when creating the file. Use Table 2-7 to determine which value you should use for the Key Number parameter.
Note The Create operation makes no distinction between

workstation, workgroup, and server engines when you specify that the local engine should create the file.

Table 2-7 Key Number Parameter for Create Operation

CREATE Operation No preference 0 -1 Force local engine to create file 6 7 Force remote engine to create file 99 100

Normal create (overwrite file if it already exists) Return Status 59 if file already exists

Delete and Rename Subfunctions for the Create Operation The Create operation has two additional subfunctions that you can use to delete or rename files. In releases prior to Pervasive.SQL v8.5, it was always possible to manipulate transactional interface files through the operating system, because the transactional interface depended on the rights and privileges given by the operating system to the Pervasive PSQL user.

2-29

Btrieve API Operations

Now, if you have a secure Pervasive PSQL database, these operating system access rights may have been removed in the process of securing the database from unauthorized access. This makes programmatically deleting or moving the files difficult since the rights required are not always available. The rename and delete subfunctions are implemented as Create operations with alternate key numbers. You do not need to provide a file specification as you do when creating a new data file. The following table shows how you set up the Create operation to use the rename or delete subfunctions.
Table 2-8 Create Operation Subfunctions
Function Key Number to Use -127 Description Place in Data Buffer Existing File Name Place in Key Buffer New File Name

Rename File

Rename an existing file in the data buffer to the name in the key buffer Delete a file

Delete File

-128

N/A

Existing File Name

These subfunctions have been modified to work with the security model in that they will accept a URI in place of a file name in the key buffer and data buffer, if needed, to indicate a transactional interface file to delete or rename. This allows you to provide security information with the operation. The security information is processed just like a normal Create or Open operation. The user must be authenticated and have DB_RIGHT_CREATE, DB_RIGHT_ALTER and DB_RIGHT_OPEN privileges for the existing files and for the directory where the new file will be located if applicable.
Table 2-9 Create Subfunctions - Use of URI Parameters in Key Buffer
Function URI parameter file= URI parameter dbfile= URI parameter table=

Rename Delete

2-30

Create (14)

Table 2-10 Create Subfunctions - Use of URI Parameters in Data Buffer

Function Rename Delete file= dbfile= table=

Not applicable

Notes on Rename and Delete Subfunctions

The previous functionality of the Create operation is intact. Follow the existing documentation on the Create operation if you want to create a new transactional interface data file. The RenameFile and DeleteFile subfunctions cannot be used on files that are bound to specific databases because they do not affect the contents of the miscellaneous page. If a file contains an Owner name, the owner name check is not performed by the new subfunctions. The owner name is still needed to view the contents of the files.

Result

If the Create operation is successful, the transactional interface either warns you of the existence of a file with the same name or creates the new file according to your specifications. The new file does not contain any records. The Create operation does not open the file. Your application must perform an Open operation before it can access the file. If the Create operation is unsuccessful, the transactional interface returns one of the following status codes:
2 11 18 22 24 25 26 27 The application encountered an I/O error. The specified file name is invalid. The disk is full. The data buffer length is too short. The page size or data buffer size is invalid. The application cannot create the specified file. The number of keys specified is invalid. The key position is invalid.

2-31

Btrieve API Operations

28 29 48 49 59 104 105 134 135

The record length is invalid. The key length is invalid. The alternate collating sequence definition is invalid. The extended data type is invalid. The specified file already exists. The transactional interface does not recognize the locale. The file cannot be created with Variable-tail Allocation Tables (VATs). The transactional interface cannot read the International Sorting Rule. The specified International Sort Rule table is corrupt or otherwise invalid.

Positioning

The Create operation establishes no currency on the file.

2-32

Create Index (31)

The Create Index operation (B_BUILD_INDEX) adds a key to an existing file.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites

The file must be open. The number of existing key segments in the file must be less than or equal to maximum number of key segments allowed minus the number of key segments to be added. The maximum number of key segments allowed depends on the files page size. The following table shows these values:
Page Size (bytes) Maximum Key Segments byFile Version 8.x and prior 512 1,024 1,536 2,048 2,560 3,072 3,584 4,096 8,192 8 23 24 54 54 54 54 119 n/a1 9.0 8 23 24 54 54 54 54 119 119 9.5 rounded up2 97 rounded up2 97 rounded up2 rounded up2 rounded up2 204 420

2-33

Btrieve API Operations

Page Size (bytes)

Maximum Key Segments byFile Version 8.x and prior 9.0 n/a1 9.5 420

16,384
1

n/a1

n/a stands for not applicable

2rounded

up means that the page size is rounded up to the next size supported by the file version. For example, 512 is rounded up to 1,024, 2,560 is rounded up to 4,096, and so forth.

See also the status codes 26: The number of keys specified is invalid on page 1-68 and 29: The key length is invalid on page 1-71, both in Status Codes and Messages.

Ensure that the key flags, position, and length of the new key are appropriate for the file to which you are adding the key. No transactions can be active. Set the Operation Code to 31. Pass the Position Block for the file to which to add the key. For each segment in the key, store a 16-byte key specification block in the Data Buffer. Use the same structure as defined in Table 2-1. Store the information for the key position and the key length as integers. If you are rebuilding the system-defined log key (also called system data), the Data Buffer must be at least 16 bytes long and initialized to zeroes. To define an ACS for the new key, perform one of the following steps:

Procedure

1 2 3

To use the default ACS, which is the first ACS already defined in the file, specify the Use Default ACS attribute in the Key Flags word. To define a new ACS, specify the Use Numbered ACS attribute in the Key Flags word and set the ACS Number field to zero (0). In addition, store the 265-byte ACS after the last key specification block in the Data Buffer.

2-34

Create Index (31)

To specify an existing ACS by name, specify the Use Named ACS attribute in the Key Flags word and set the ACS Number field to zero (0). In addition, store the name of the ACS at the beginning of the 265-byte block after the last key specification block in the Data Buffer. (The remainder of the ACS block after the name is ignored.) The name must be in one of the following formats:
Length (in Bytes) 1 8 1 16 Description

ACS Type

User-defined ACS ISR

Signature 0xAC ACS table name Signature 0xAE ISR table name

Set the Data Buffer Length parameter to the number of bytes in the Data Buffer. For a new key with no ACS (or one that uses the default ACS), use the following formula to determine the correct Data Buffer Length: 16 * (# of segments) If the new key specifies an ACS other than the default, use the following formula to determine the correct Data Buffer Length: 16 * (# of segments) + 265

To assign a specific Key Number to the key being created, add the desired key number to 0x80, and place the sum in the Key Number parameter. If you are rebuilding the system-defined log key (also called system data), specify 0xFD (that is, key number 125 plus 128).
Note Key numbers must be unique to the file. They must also be

valid. (The value of each key number must be less than the maximum number of key segments allowed for the files page size.)

Details

The transactional interface allows you to assign specific key numbers when creating a key. This capability complements the ability to delete

2-35

Btrieve API Operations

a key and not have the transactional interface renumber all keys that have a key number greater than that of the deleted key. If an application drops an index and instructs the transactional interface not to renumber higher-numbered keys, and a user then clones the affected file without assigning specific key numbers, the cloned file has different key numbers than the original. If you define an ACS in the Data Buffer, the transactional interface first checks for an existing ACS (using the name you specified) before adding it to the file. If the transactional interface finds an existing ACS with the name you specified, the transactional interface does not duplicate the ACS definition in the file, but does associate the ACS with the new key. If you specify the Use Named ACS attribute in the Key Flags word, the transactional interface uses the ACS name supplied in the Data Buffer to locate an ACS of the same name within the file, then assigns that ACS to the new key. If a file is opened by more than one transactional interface and a client initiates a Create Index process, remote clients can perform Get and Step operations on the same file while the transactional interface creates the key. If the key being created is not an AUTOINCREMENT key, the Get and Step operations of remote clients can have lock biases, and when the Create Index process is completed, you can update and delete the locked records without issuing additional read operations. This is possible because the transactional interface does not have to change the images of the records in order to create the key. However, if the key being created is an AUTOINCREMENT key, the transactional interface has to both build the index and change every record with a zero value in the appropriate field. Remote clients that perform Get or Step operations without a lock bias before or during the key creation can receive Status Code 80 when they execute an update or delete operation after the successful completion of the key creation. Also, the transactional interface returns Status Code 84 if a client attempts to create an AUTOINCREMENT key while another client has locked a record. Similarly, the transactional interface returns Status Code 85 if a client attempts to execute a Get or Step operation with a lock bias during index creation for an AUTOINCREMENT key by another client.

2-36

Create Index (31)

Result

The transactional interface immediately adds the new key to the file. The time required for this operation depends on the total number of records to be indexed, the size of the file, and the length of the new index. If the Create Index operation is successful, the number of the new key is either the number you specified or one of the following:

For files that have no gaps between key numbers, the key number is one higher than the previous highest key number. For files that have gaps between key numbers, the key number is the lowest missing key number.

You can use the new key to access your data as soon as the operation completes. If the Create Index operation is unsuccessful, the transactional interface drops whatever portion of the new index it has already built. The file pages allocated to the new index prior to the error are placed on a list of free space for the file and reused when you insert records or create another key. If the operation fails during the creation of an AUTOINCREMENT key, any values that have already been altered remain altered. The transactional interface can return the following status codes:
22 27 41 45 49 56 84 85 104 134 The data buffer length is too short. The key position is invalid. The transactional interface does not allow the attempted operation. The specified key flags are invalid. The extended data type is invalid. An index is incomplete. The record or page is locked. The file is locked. The transactional interface does not recognize the locale. The transactional interface cannot read the International Sorting Rule.

2-37

Btrieve API Operations

135 136

The specified International Sort Rule table is corrupt or otherwise invalid. The transactional interface cannot find the specified Alternate Collating Sequence in the file.

If processing is interrupted during the creation of a key, you can access the data in the file through the files other keys. However, the transactional interface returns a nonzero status code if you try to access data by the incomplete index. To correct this problem, drop the incomplete index with a Drop Index operation (32) and reissue the Create Index operation.

Positioning

The Create Index operation has no effect on any file currency information.

2-38

Delete (4)

Delete (4)
The Delete operation (B_DELETE) removes an existing record from a file. The space that the deleted record occupied is then available for inserting new records.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites

The file must be open. You have established physical or logical currency in the file. Operations that satisfy this requirement are: Get (except extended Gets or Get Key), Step (except extended Steps), Insert, and Update. Set the Operation Code to 4. Pass the Position Block of the file that contains the record to be deleted.

Procedure

1 2

Details

The Delete operation is not a valid operation if performed immediately after an extended Get or extended Step operation. When performing a Delete operation immediately following a Get operation, do not change the Key Number that the Get operation returns. If you do, the transactional interface deletes the record successfully; however, it returns Status Code 7 on the first Get operation performed after the deletion. The transactional interface does not allow Delete operations after a Get Key operation (+50). Before the transactional interface performs a Delete operation, it compares the current usage count of the data page it intends to modify with the usage count of the data page when the record was read. To obtain the usage count, the transactional interface must read the data page.

2-39

Btrieve API Operations

Because the Get Key operation does not read the data page, no usage count is available for comparison on the Delete. The Delete fails because the transactional interface cannot perform its passive concurrency conflict checking without the compare. When the Delete fails, the transactional interface returns Status Code 8.

Result

If the Delete operation is successful, the transactional interface removes the record from the file, releases the record lock (if one existed for the deleted record), and adjusts all key indexes to reflect the deletion. If the Delete operation is unsuccessful, the transactional interface returns one of the following status codes:
8 80 84 85 The current positioning is invalid. The transactional interface encountered a record-level conflict. The record or page is locked. The file is locked.

Delete operations never reduce file size. Empty Space created by deletion of records is re-used when records are added in the future. Recovering disk space can only be done by re-creating the file and inserting all the records into it.

Positioning

The Delete operation destroys the complete physical location information and the logical current record position but does not change the physical and logical positions of either the next record or the previous record.

2-40

Drop Index (32)

The Drop Index operation (B_DROP_INDEX) deletes a key from an existing file.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites

The file must be open. The key must exist in the file. No transactions can be active. Set the Operation Code to 32. Pass the Position Block of the file that contains the key to drop. Store the number of the key to drop in the Key Number parameter. To drop the system-defined log key (also called system data), specify 125.

Procedure

1 2 3

Details

If you drop the system-defined log key, you can rebuild it using the Create Index (31) operation. When you delete a key, the transactional interface automatically renumbers all higher-numbered keys, unless you specify otherwise. The transactional interface renumbers by decrementing the highernumbered keys by 1. For example, suppose you have a file with key numbers 1, 4, and 7. If you drop key 4, the transactional interface renumbers the keys as 1 and 6. If you do not want the transactional interface to automatically renumber keys, add a bias of 128 to the value you supply for the Key Number parameter. This allows you to leave gaps in the key numbering; consequently, you can drop a damaged index and then rebuild it without affecting the numbering of other keys in the file. You rebuild the index using the Create Index operation (31), which allows you to specify a key number.

2-41

Btrieve API Operations

However, if you delete a key and do not renumber higher-numbered keys and a user then clones the affected file without assigning specific key numbers, the cloned file has different key numbers than the original. (Users can clone files using the Btrieve Maintenance utility. Cloning is the process of creating a new, empty file with the same statistics as an existing file.)

Result

If the Drop Index operation is successful, the transactional interface places the pages that were allocated to that index on a list of free space for later use. Unless you specify otherwise, the transactional interface renumbers the higher-numbered keys. If the Drop Index operation is unsuccessful, the transactional interface returns one of the following status codes:
6 41 The key number parameter is invalid. The transactional interface does not allow the attempted operation.

If processing is interrupted while the transactional interface is dropping an index, you can access the data in the file by the files other keys. The transactional interface returns Status Code 56 if you try to access the file by an incomplete index. If processing is interrupted, reissue the Drop Index operation.

Positioning

The Drop Index operation has no effect on physical file currency information. However, dropping the key used to establish the last logical currency destroys the logical currency.

2-42

End Transaction (20)

The End Transaction operation (B_END_TRAN) completes a transaction and makes the appropriate changes to the data files. It also unlocks all files and records locked by the transaction.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites Procedure

Before issuing an End Transaction operation, your application must issue a successful Begin Transaction operation (19 or 1019). Set the Operation Code to 20. While the transactional interface ignores all other parameters on an End Transaction call, you should initialize them to 0 to ensure compatibility with future releases. If the End Transaction operation is successful, all the operations within the transaction are recorded in your file. Your application cannot abort a transaction after an End Transaction operation. If the End Transaction operation is unsuccessful, the transactional interface returns the following status code:
38 The transactional interface encountered a transaction control file I/O error.

Result

Positioning

The End Transaction operation has no effect on any file currency information.

2-43

Btrieve API Operations

Find Percentage (45)

The Find Percentage operation (B_GET_PERCENT) is one of two Btrieve API operations that window-oriented applications can use to implement scroll bars. The other is the Get By Percentage operation (44). Find Percentage finds the approximate position of a record either relative to a key path or as the records physical location within the file. The position is expressed as a percentage value. See the Result section for a definition of the range of percentage values.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Note When seeking the percentage relative to a key path, Find

Percentage does not require an input value for the Data Buffer parameter. When seeking the percentage as relative to a records physical location within the file, Find Percentage does not require an input value for the Key Buffer parameter.

Prerequisites

The file must be open. If you are seeking the percentage relative to a key path, the file cannot be a data-only file. When you are seeking the percentage by a records physical location in the file, you must provide the 4-byte physical location of the record in the Data Buffer parameter. You can retrieve this location with a Get Position operation (22). Set the Operation Code to 45. Pass the Position Block for the file.

Procedure

1 2

2-44

Find Percentage (45)

If you are seeking the percentage relative to the records physical location within the file, store the records physical address in the Data Buffer parameter. If you are seeking the percentage relative to the records key path and wish to specify a granularity for the search, set your Data Buffer parameter as specified in Granularity on page 2-45. Otherwise, you do not need to provide a value for the Data Buffer parameter. Set the Data Buffer Length to a minimum of 4 bytes. (This 4-byte minimum is a requirement of the transactional interfaces internal implementation). If specifying a granularity for the search, set the data buffer length to a minimum of 12 bytes. If you are seeking the percentage relative to a key path, set the Key Buffer parameter to the key value. Otherwise, you do not need to provide a value for the Key Buffer parameter. Set the Key Number parameter as follows: a. If you are seeking the percentage by a key path, set the Key Number parameter to the actual key number. b. If you are seeking the percentage by the records physical location, set the Key Number parameter to 1 (0xFF).

Details

The Find Percentage operation is provided specifically to support scroll bar implementation. Because many factors affect the accuracy of this operationthat is, whether the returned percentage value accurately reflects the position of the record or key valueyou should not rely on the accuracy of this operation for other purposes. To optimize the Find Percentage operation, the transactional interface assumes that a file has an even distribution of records among the data pages and keys among the index pages. However, distribution can be affected by the following situations:

The file is not index balanced, and a large number of records within the same range of keys has been deleted. A large number of records within the same range of physical addresses has been deleted. The file contains numerous duplicate key values, and the key is a linked-duplicatable key.

2-45

Btrieve API Operations

Granularity The granularity setting is optional and allows you to choose the factor by which the percentage is measured. In releases prior to Pervasive PSQL 9, this value was always 10,000. If you want to specify the granularity, follow these steps:

To specify a granularity in the Find Percentage

operation
1 2

Place ExPc in the second four bytes of the data buffer. Place the desired granularity in the third four bytes as a LoHi Intel integer. The granularity you choose can be any number from 1 to 0xFFFFFFFF. Ensure that your data buffer length is at least 12 bytes.

For example if you want to get the 100th record from a file that contains 365 records, you can use FindPercentage with 100 as the percentage, and 365 as the granularity.

Result

If the Find Percentage operation is successful, the transactional interface returns the relative position of the specified key value or record to the Data Buffer. This position is expressed as a percentage of the offset into the key path or file and is a value in the range of 0 (0 percent) through 10,000 (100.00 percent). Note this is not the physical or logical position. The percentage value is returned as a 2-byte integer in low-byte, high-byte order. For example:
Returned Value Hex 88h 13h Returned Value Dec 00 50 Percentage in Key Path or File 50%

The transactional interface also returns a Data Buffer Length of 4 if the operation is successful. If the Find Percentage operation is unsuccessful, the transactional interface returns one of the following status codes:
3 6 The file is not open. The key number parameter is invalid.

2-46

Find Percentage (45)

7 8 9 22 41 43 82

The key number has changed. The current positioning is invalid. The operation encountered the end-of-file. The data buffer parameter is too short. The transactional interface does not allow the attempted operation. The specified record address is invalid. The transactional interface lost positioning.

Positioning

The Find Percentage operation does not change any currency information.

2-47

Btrieve API Operations

Get By Percentage (44)

The Get By Percentage operation (B_SEEK_PERCENT) is one of two Btrieve API operations that can be used by window-oriented applications for implementing scroll bars. The other is the Find Percentage (45). Get By Percentage retrieves a record by that records relative position in the file, where the position is based on a percentage value you supply when you call the operation. You must also specify whether the position is relative to a specified key path or represents the records actual physical location in the file.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Note The Get By Percentage operation, when seeking the record by its physical location in the file, does not return any information in the Key Buffer parameter.

Prerequisites

The file must be open. If you are seeking the record relative to a key path, the file cannot be a data-only file. Set the Operation Code to 44. Optionally, you can include a lock bias:

Procedure

+100Single wait record lock. +200Single no-wait record lock. +300Multiple wait record lock. +400Multiple no-wait record lock.

For more information about locking, refer to the Pervasive PSQL Programmer's Guide.

2-48

Get By Percentage (44)

2 3

Pass the Position Block for the file. Store the percentage value as a 2-byte integer in the Data Buffer. See the Details section for the acceptable range of percentage values and related information. Set the Data Buffer Length to a value greater than or equal to the length of the largest possible record that could be returned. (The transactional interfaces internal implementation requires that you set the Data Buffer Length value to a minimum of 4 bytes). If specifying a granularity for the search, set the data buffer length to a minimum of 12 bytes. Set the Key Number parameter. a. If you are seeking the record by a key path, set the Key Number parameter to the actual key number. To use the system-defined log key (also called system data), specify 125. b. If you are seeking the record by the records physical position in the file, set the Key Number parameter to 1 (0xFF).

Details

If you are not specifying a granularity (see Granularity on page 249), the range of acceptable percentage values for the first two bytes of the Data Buffer parameter is from 0 (indicating the beginning of the key path or file) through 10,000 (the end of the key path or file). The value corresponds to a range of 0% to 100.00%, assuming two implied decimal places. If you want to find the record approximately 33.33% through the file, pass the value 3333 in the Data Buffer. Be sure to store the value as an integer (in low-byte, high-byte order). For example, to seek to the 50 percent point in the file, use a value of 5,000 (0x1388). After byte-swapping 0x1388, store 0x88 and 0x13 in the first two bytes of the Data Buffer parameter. If you are seeking the percentage relative to the records key path and wish to specify a granularity for the search, set your Data Buffer parameter as specified in Granularity on page 2-49. The Get By Percentage operation is provided specifically to support scroll bar implementation. Because many factors affect the accuracy of this operationthat is, whether the returned record is positioned at the actual percentage point you specify in the fileyou should not rely on the accuracy of this operation for other purposes.

2-49

Btrieve API Operations

To optimize the Get By Percentage operation, the transactional interface assumes that a file has an even distribution of records among the data pages and keys among the index pages. However, distribution can be affected by the following situations:

To specify a granularity in the Get By Percentage

operation
1 2

For example if you want to get the 100th record from a file that contains 365 records, you can use GetByPercentage with 100 as the percentage, and 365 as the granularity.

Result

If the Get By Percentage operation is successful, the transactional interface returns to the Data Buffer a record that is either from the designated position relative to the specified key path or from the physical position in the file. The transactional interface returns the length of the record in bytes into the Data Buffer Length parameter. If the operation seeks the record by a key path, the transactional interface returns the key value for the specified key path in the Key Buffer parameter. If the operation seeks the record by physical record order, the transactional interface does not return any information in the Key Buffer parameter.

2-50

Get By Percentage (44)

Note When Get By Percentage is seeking a record relative to a key path, and the key contains duplicate values, the transactional interface always returns the first record containing the duplicated value. This implementation detail can affect the accuracy of the operation.

If the Get By Percentage operation is unsuccessful, the transactional interface returns one of the following status codes:
3 6 7 8 9 22 41 43 82 The file is not open. The key number parameter is invalid. The key number has changed. The current positioning is invalid. The operation encountered the end-of-file. The data buffer parameter is too short. The transactional interface does not allow the attempted operation. The specified record address is invalid. The transactional interface lost positioning.

Positioning

If successful when seeking a record relative to a specified key path, the Get By Percentage operation establishes the new logical and physical currencies based respectively on the specified Key Number and the retrieved record. If successful when seeking a record based on the records physical location within the file, the Get By Percentage operation establishes the new physical currency based on the retrieved record. If the Get By Percentage operation is unsuccessful, the transactional interface changes no currency.

2-51

Btrieve API Operations

Get Direct/Chunk (23)

The Get Direct/Chunk operation (B_GET_DIRECT) can retrieve one or more portions, called chunks, of a record. This operation is especially useful on files containing records longer than 65,535 bytes. Such records are too long to be retrieved by the other Get and Step operations, due to restrictions on the length of the Data Buffer parameter. Your application specifies the record from which chunks are to be retrieved by supplying its physical address. The location of a chunk in a record is generally specified by its offset and length.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites

The file must be open. You must provide the 4-byte physical location of the record. You can retrieve this location with a Get Position operation (22). You must provide a large enough Data Buffer to contain all values that a Get Direct/Chunk operation returns. The Data Buffer must also be able to contain the entire chunk descriptor (all the chunk definitions) when the Get Direct/Chunk operation is performing an indirect chunk operation. The maximum size of the Data Buffer is limited as shown in Table 2-11.

Table 2-11 Data Buffer Size Limitations by Environment

Environment Maximum Data Buffer Size 64,512 bytes 55,512 bytes 57,000 bytes 65,153 bytes

Local calls to server or workstation engine Remote calls via DOS Requester (BREQNT) Remote calls via DOS Requester (BREQUEST) Remote calls via Win16, Win32, or OS/2 Requester

2-52

Get Direct/Chunk (23)

Procedure

Set the Operation Code to 23. Optionally, you can include a lock bias:

+100Single wait record lock. +200Single no-wait record lock. +300Multiple wait record lock. +400Multiple no-wait record lock.

For more information about locking, refer to the Pervasive PSQL Programmer's Guide.
2 3 4

Pass the Position Block for the file. Specify a Data Buffer, as described in Details. Specify the Data Buffer Length as either the length of the input structure (Table 2-12 or Table 2-13) or the number of bytes you requested for the transactional interface to retrieve, whichever is larger. Some options for the Get Direct/Chunk operation retrieve chunks to locations other than the Data Buffer. See the Details section for more information about calculating the Data Buffer Length.

Set the Key Number parameter to 2 (0xFE).

Details

Use one of the following chunk descriptors in the Data Buffer:

Random Chunk DescriptorTo retrieve a single chunk per operation, or to retrieve multiple chunks in a single operation when the chunks are spaced randomly throughout the record. Rectangle Chunk DescriptorTo retrieve multiple chunks in an operation, when each chunk is the same length and chunks are spaced equidistantly in the record.

Random Chunks

2-53

Btrieve API Operations

The following example shows a record with three randomly spaced chunks (areas containing [*]): chunk 0 (bytes 0x12 through 0x16), chunk 1 (bytes 0x2A through 0x31), and chunk 2 (bytes 0x41 through 0x4E).
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F

[*]

To fetch random chunks, you must create a structure in the Data Buffer, based on the following table.
Table 2-12 Data Buffer for Random Chunk Operations
Element Length (Bytes) 4 Description

Record Address

The 4-byte physical location of the record. You can retrieve this location with a Get Position operation (22).

Random Chunk Descriptor Subfunction 4 Type of chunk descriptor; one of the following:
0x80000000 (Direct random chunk descriptor)

Retrieves chunks directly into the Data Buffer. The first chunk is retrieved and stored at offset 0 in the Data Buffer, the second chunk immediately follows the first, and so on.
0x80000001 (Indirect random chunk descriptor)

Retrieves chunks into addresses specified by the Chunk Definitions. NumChunks 4 Number of chunks to retrieve. The value must be at least 1. Although no explicit maximum value exists, the chunk descriptor must fit in the Data Buffer, which is limited in size as described in Table 2-11.

2-54

Get Direct/Chunk (23)

Table 2-12 Data Buffer for Random Chunk Operations continued

Element Length (Bytes) 12 Description

Chunk Definition (Repeat for each chunk)

Each Chunk Definition is a 4-byte Chunk Offset, followed by a 4-byte Chunk Length, followed by a 4-byte User Data, described as follows:
Chunk OffsetIndicates where the chunk begins

as an offset in bytes from the beginning of the record. The minimum value is 0, and the maximum value is the offset of the last byte in the record.
Chunk LengthIndicates how many bytes are in

the chunk. The minimum value is 0, and the maximum value 65,535; however, the chunk descriptor must fit in the Data Buffer, which is limited in size as described in Table 2-11.
User Data(Used only for indirect descriptors.) A

32-bit pointer to the actual chunk data. The format you should use depends on your operating system.1 The transactional interface ignores this element for direct chunk descriptor subfunctions.
1For 16-bit applications, initialize User Data as a 16-bit offset and a 16-bit segment.

User Data cannot address memory beyond the end of its segment. When Chunk Length is added to the offset portion of User Data, the result must be within the segment that User Data defines. By default, the transactional interface does not check for violations of this rule and does not properly handle such violations.

The following table shows a sample Data Buffer for fetching direct random chunks.
Element Record Address Subfunction NumChunks Chunk 0 Chunk Offset Chunk Length User Data Chunk 1 18 5 N/A 4 4 4 Sample Value 0x00000628 0x80000000 3 Length (in Bytes) 4 4 4

2-55

Btrieve API Operations

Element Chunk Offset Chunk Length User Data Chunk 2 Chunk Offset Chunk Length User Data

Sample Value 42 8 N/A

Length (in Bytes) 4 4 4

65 14 N/A

4 4 4

Rectangle Chunk Descriptor Structure When chunks of the same length are spaced equidistantly throughout a record, you can describe all the chunks to retrieve with a rectangle chunk descriptor. For example, consider the following diagram, which represents offset 0x00 through 0x4F in a record:
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F

[*]

2-56

Get Direct/Chunk (23)

You can retrieve all three chunks using a single rectangle descriptor. To fetch rectangle chunks, you must create a structure in the Data Buffer based on the following table.
Table 2-13 Data Buffer for Rectangle Chunks
Element Length (Bytes) 4 Description

Record Address

The 4-byte physical location of the record. You can retrieve this location with a Get Position operation (22).

Rectangle Chunk Descriptor Subfunctio n 4 Type of chunk descriptor; one of the following:
0x80000002 (Direct rectangle chunk descriptor)

Retrieves chunks into addresses specified by the User Data and Application Distance Between Rows elements. Number of Rows 4 Number of chunks on which the rectangle chunk descriptor must operate. The minimum value is 1. No explicit maximum value exists. Offset from the beginning of the record of the first byte to retrieve. The minimum value is 0, and the maximum value is the offset of the last byte in the record. If the record is viewed as a rectangle, this element refers to the offset of the first byte in the first row to be retrieved. Number of bytes to retrieve in each chunk. The minimum value is 0, and the maximum value is 65,535; however, the chunk descriptor must fit in the Data Buffer, which is limited in size as described in Table 2-11. Number of bytes between the beginning of each chunk.

Offset

Bytes Per Row

Distance Between Rows User Data

(Used only with indirect descriptors.) A 32-bit pointer to the location into which the transactional interface stores bytes after retrieving them from each row. The format you should use depends on your operating system.1 The transactional interface ignores this element for direct rectangle descriptors; however, you must still allocate the element and initialize it to 0.

2-57

Btrieve API Operations

Table 2-13 Data Buffer for Rectangle Chunks continued

Element Length (Bytes) 4 Description

Application Distance Between Rows

(Used only with indirect rectangle descriptors.) Number of bytes between the beginning of each chunk in the rectangle, as the rectangle is stored in your applications memory, at the address specified by User Data. The transactional interface ignores this element for direct rectangle descriptors; however, you must still allocate the element and initialize it to 0.

1For

16-bit applications, express User Data as a 16-bit offset followed by a 16-bit segment.

When you use an indirect descriptor, be sure that the User Data pointer is initialized so that the chunks retrieved do not overwrite your chunk descriptor. The transactional interface uses the descriptor when copying the returned chunks to the locations that the User Data elements specify. In the event that you overwrite your chunk descriptor, the transactional interface returns Status Code 62. If the rectangle has the same number of bytes between rows when it is in memory as when it is stored as a record, set Application Distance Between Rows with the same value as Distance Between Rows. However, if the rectangle is arranged in your applications memory with either more or fewer bytes between rows, Application Distance Between Rows allows you to pass that information to the transactional interface. When you use an indirect rectangle descriptor, the transactional interface uses both the User Data and the Application Distance Between Rows elements to determine the locations in which to store the data after retrieving it. The transactional interface stores data from the first row in offset 0 of User Data. The transactional interface stores the second rows data to an address specified by User Data plus Application Distance Between Rows. The transactional interface stores the third rows data in the address specified by User Data plus (Application Distance Between Rows * 2), and so on.

2-58

Get Direct/Chunk (23)

The following table shows a sample Data Buffer for fetching a direct rectangle chunk.
Element Name Sample Value Length (in Bytes) 4 4 4 4 4 4 4 4

Record Address Subfunction Number of Rows Offset Bytes Per Row Distance Between Rows User Data Application Distance Between Rows

0x00000628 0x80000002 3 25 4 16 0 0

Next-in-Record Subfunction Bias If you add a bias of 0x40000000 to any of the subfunctions previously listed, the transactional interface calculates the subfunctions Offset element values based on your physical intrarecord currency (that is, your current physical location within the record). When you use the Next-in-Record subfunction, the transactional interface ignores the Offset element in the chunk descriptor.

Result

If the Get Direct/Chunk operation is successful and a direct chunk descriptor is used, the transactional interface returns the chunks one after another in the Data Buffer. If you used an indirect random chunk descriptor, the transactional interface returns the data to the locations that each chunks User Data element specifies. If you used an indirect rectangle descriptor, the transactional interface returns the data to locations it derives from the User Data and Application Distance Between Rows elements. The transactional interface also stores the total length of the chunks retrieved in the Data Buffer Length parameter. (The returned value reflects all bytes retrieved, whether they were retrieved and stored directly into the Data Buffer, or the indirect descriptor was used to retrieve and store the bytes elsewhere.) If the operation was partially successful, your application can use the value returned in the Data

2-59

Btrieve API Operations

Buffer Length parameter to determine which chunks could not be retrieved and how many bytes of the final chunk were retrieved. The Get Direct/Chunk operation is only partially successful if any chunk begins beyond the end of the record (resulting in the transactional interface returning Status Code 103), or if any chunks offset and length combine to exceed the length of the record. In the latter case, the transactional interface returns Status Code 0 but ceases processing subsequent chunks, if any, in the operation.
Note Only the Data Buffer Length parameter shows that not all

of the chunks were properly retrieved. For this reason, be sure that you always check the value returned in the Data Buffer Length parameter after a Get Direct/Chunk operation. The following status codes indicate a partially successful Get Direct/ Chunk operation. When the transactional interface returns one of these status codes, your application should check the Data Buffer Length parameters return value to see how much data the transactional interface actually returned.
22 54 103 The data buffer parameter is too short. The variable-length portion of the record is corrupt. The chunk offset is too big.

If the transactional interface returns any of the following status codes, it has returned no data.
43 58 62 97 106 The specified record address is invalid. The compression buffer length is too short. The descriptor is incorrect. The data buffer is too small. The transactional interface cannot perform a Get Next Chunk operation.

Positioning

The Get Direct/Chunk operation has no effect on logical currency. In terms of physical currency, Get Direct/Chunk makes the record from which chunks are retrieved the physical current record.

2-60

Get Direct/Record (23)

The Get Direct/Record operation (B_GET_DIRECT) retrieves a record using its physical location in the file instead of using one of the defined key paths. Use Get Direct/Record to accomplish the following:

Retrieve a record faster using its physical location instead of its key value. Use the Get Position operation (22) to retrieve the 4-byte location of a record, save the location, and use Get Direct/ Record to return directly to that location after performing other operations that affect currency. Use the 4-byte location to retrieve a record in a chain of duplicates without rereading all the records from the beginning of the chain. Change the current key path. A Get Position operation, followed by a Get Direct/Record operation with a different key number, establishes positioning for the current record in a different index path. A subsequent Get Next returns the next record in the file based on the new key path.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Note The Key Number parameter is not needed when

performing a Get Direct/Record operation on a data-only file.

Prerequisites

The file must be open. You must provide the 4-byte physical location of the record. You can retrieve this location with a Get Position operation (22), which returns the physical address of the current record.

2-61

Btrieve API Operations

Procedure

Set the Operation Code to 23. Optionally, you can include a lock bias:

+100Single wait record lock. +200Single no-wait record lock. +300Multiple wait record lock. +400Multiple no-wait record lock.

For more information about locking, refer to the Pervasive PSQL Programmer's Guide.
2 3 4 5

Pass the Position Block for the file. Store the 4-byte position of the requested record in the first 4 bytes of the Data Buffer. Set the Data Buffer Length to a value greater than or equal to the length of the record to retrieve. Set the Key Number to the key number of the path for which you want the transactional interface to establish logical currency. Specify 1 if you do not want the transactional interface to establish logical currency. To use the system-defined log key (also called system data), specify 125.

Result

If the Get Direct/Record operation is successful, the transactional interface returns the requested record in the Data Buffer, the length of the record in the Data Buffer Length parameter, and the key value for the specified key path in the Key Buffer. If the Get Direct/Record operation is unsuccessful and the transactional interface cannot return the requested record, the transactional interface returns one of the following status codes:
22 The data buffer parameter is too short. (Logical currency is still established.) The specified record address is invalid. (Logical currency is not established.) The specified key path is invalid. (Logical currency is not established.) The transactional interface lost positioning. (Logical currency is not established.)

44 82

Positioning

The Get Direct/Record operation erases any existing logical currency information and establishes the new logical currency according to

2-62

Get Direct/Record (23)

the Key Number specified. It has no effect on the physical currency information.

2-63

Btrieve API Operations

Get Directory (18)

The Get Directory operation (B_GET_DIR) returns the current directory for a specified logical disk drive.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites Procedure

Your application can issue a Get Directory operation at any time. The Key Buffer should be at least 65 characters long.
1 2

Set the Operation Code to 18. Store the logical disk drive number in the Key Number parameter. Specify the drive as 1 for A, 2 for B, and so on. To use the default drive, specify 0.

Result Positioning

The transactional interface returns the current directory, terminated by a binary 0, in the Key Buffer. The Get Directory operation has no effect on any file currency information.

2-64

Get Equal (5)

The Get Equal operation (B_GET_EQUAL) retrieves a record that has a key value equal to that specified in the Key Buffer. If the key allows duplicates, this operation retrieves the first record (chronologically) of a group with the same key values. You can use the Get Key (+50) bias to detect the presence of a value in a file. A Get Key operation is generally faster.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites

The file must be open. The file cannot be a data-only file. Set the Operation Code to 5. Optionally, you can include a lock bias:

Procedure

+100Single wait record lock. +200Single no-wait record lock. +300Multiple wait record lock. +400Multiple no-wait record lock.

For more information about locking, refer to the Pervasive PSQL Programmer's Guide.
2 3 4

Pass the Position Block for the file. Set the Data Buffer Length to a value greater than or equal to the length of the record to retrieve. Specify the desired key value in the Key Buffer. If the key consists of multiple segments, make sure you define the key buffer to represent all segments and fill in values for all segments. If you dont have search criteria for all segments, use the GetGreaterOrEqual operation instead.

2-65

Btrieve API Operations

Set the Key Number to the correct key path. To use the systemdefined log key (also called system data), specify 125.

Result

If the Get Equal operation is successful, the transactional interface returns the requested record in the Data Buffer and the length of the record in the Data Buffer Length parameter. If the Get Equal operation is unsuccessful, the transactional interface returns one of the following status codes:
3 4 6 22 The file is not open. The application cannot find the key value. The key number parameter is invalid. The data buffer parameter is too short.

This operation returns Status Code 4 if the key contains a non-zero value in a null indicator segment. You cannot use GetEqual to find records that are NULL, because by definition NULL is indeterminate, or not equal to anything. If you need to find NULL values, use GetFirst followed by GetNext.

Positioning

The Get Equal operation establishes the complete logical and physical currencies and makes the retrieved record the current one.

2-66

Get First (12)

The Get First operation (B_GET_FIRST) retrieves the logical first record based on the specified key. You can use the Get Key (+50) bias to detect the presence of a value in a file. A Get Key operation is generally faster.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites

The file must be open. The file cannot be a data-only file. Set the Operation Code to 12. Optionally, you can include a lock bias:

Procedure

+100Single wait record lock. +200Single no-wait record lock. +300Multiple wait record lock. +400Multiple no-wait record lock.

For more information about locking, refer to the Pervasive PSQL Programmer's Guide.
2 3 4

Pass the Position Block for the file. Set the Data Buffer Length to a value greater than or equal to the length of the record to retrieve. Indicate the Key Number for the key path. To use the systemdefined log key (also called system data), specify 125.

Result

If the Get First operation is successful, the transactional interface returns the requested record in the Data Buffer, stores the corresponding key value in the Key Buffer, and returns the length of the record in the Data Buffer Length parameter.

2-67

Btrieve API Operations

If the Get First operation is unsuccessful, the transactional interface returns one of the following status codes:
3 6 9 22 The file is not open. The key number parameter is invalid. The operation encountered the end-of-file. The data buffer parameter is too short.

Positioning

The Get First operation establishes the complete logical and physical currencies and makes the retrieved record the current one. The logical previous position points beyond the beginning of the file.

2-68

Get Greater (8)

The Get Greater operation (B_GET_GT) retrieves a record in which the field specified by the Key Number has the next greater value than the one in the Key Buffer. If the key allows duplicates, this operation retrieves the first record (chronologically) of the group with the same key values. You can use the Get Key (+50) bias to detect the presence of a value in a file. A Get Key operation is generally faster.
Note If you are using the Get Greater operation on descending

keys, the next greater value refers to a value lower than the one specified in the Key Buffer.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites

The file must be open. The file cannot be a data-only file. Set the Operation Code to 8. Optionally, you can include a lock bias:

Procedure

+100Single wait record lock. +200Single no-wait record lock. +300Multiple wait record lock. +400Multiple no-wait record lock.

For more information about locking, refer to the Pervasive PSQL Programmer's Guide.
2 3 4

Pass the Position Block for the file. Set the Data Buffer Length to a value greater than or equal to the length of the record you want to retrieve. Specify the desired key value in the Key Buffer parameter.

2-69

Btrieve API Operations

Set the Key Number parameter to correspond to the correct key path. To use the system-defined log key (also called system data), specify 125.

Result

If the Get Greater operation is successful, the transactional interface stores the record in the Data Buffer, the key value in the Key Buffer, and the length of the record in the Data Buffer Length parameter. If the Get Greater operation is unsuccessful, the transactional interface returns one of the following status codes:
3 6 22 The file is not open. The key number parameter is invalid. The data buffer parameter is too short.

Positioning

The Get Greater operation establishes the complete logical and physical currencies and makes the retrieved record the current one.

2-70

Get Greater Than or Equal (9)

The Get Greater Than or Equal operation (B_GET_GE) retrieves a record in which the value for the key specified by the Key Number is equal to or greater than the value you supply in the Key Buffer. The transactional interface first tries to satisfy the equal requirement. If the key allows duplicates, this operation retrieves the first record (chronologically) of the group with the same key values. You can use the Get Key (+50) bias to detect the presence of a value in a file. A Get Key operation is generally faster.
Note If you are using the Get Greater Than or Equal operation

on descending keys, the next greater value refers to a value lower than the one specified in the Key Buffer.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites

The file must be open. The file cannot be a data-only file. Set the Operation Code to 9. Optionally, you can include a lock bias:

Procedure

+100Single wait record lock. +200Single no-wait record lock. +300Multiple wait record lock. +400Multiple no-wait record lock.

For more information about locking, refer to the Pervasive PSQL Programmer's Guide.
2

Pass the Position Block for the file.

2-71

Btrieve API Operations

3 4 5

Set the Data Buffer Length to a value greater than or equal to the length of the record you want to retrieve. Specify the key value in the Key Buffer parameter. Set the Key Number parameter to correspond to the correct key path. To use the system-defined log key (also called system data), specify 125.

Result

If the Get Greater Than or Equal operation is successful, the transactional interface stores the record in the Data Buffer, the key value in the Key Buffer, and the length of the record in the Data Buffer Length parameter. If the Get Greater Than or Equal operation is unsuccessful, the transactional interface returns one of the following status codes:
3 6 22 The file is not open. The key number parameter is invalid. The data buffer parameter is too short.

Positioning

The Get Greater Than or Equal operation establishes the complete logical and physical currencies and makes the retrieved record the current one.

2-72

Get Key (+50)

The Get Key bias allows you to perform a Get operation without actually retrieving a data record. You can use Get Key to detect the presence of a value in a file. A Get Key operation is generally faster than its corresponding Get operation. You can use the Get Key operation with any of the following Get operations:

Get Equal (5) Get Next (6) Get Previous (7) Get Greater (8) Get Greater Than or Equal (9) Get Less Than (10) Get Less Than or Equal (11) Get First (12) Get Last (13)

Parameters

The parameters are the same as those for the corresponding Get operation, except that the transactional interface ignores the Data Buffer Length and does not return a record in the Data Buffer. The prerequisites for a Get Key operation are the same as those for the corresponding Get operation.
1 2

Prerequisites Procedure

Set the parameters as you would for the corresponding Get operation. You do not need to initialize the Data Buffer Length. Set the Operation Code to the Get operation you want to perform, plus 50. For example, to perform a Get Key (+50) with the Get Equal operation (5), set the Operation code to 55.

The transactional interface does not allow Delete or Update operations after a Get Key operation (+50). Before the transactional interface performs Update or Delete operations, it compares the current usage count of the data page it intends to modify with the usage count of the data page when the record was read. To obtain the usage count, the transactional interface must read the data page.

2-73

Btrieve API Operations

Because the Get Key operation does not read the data page, no usage count is available for comparison on the Update or Delete. The Update or Delete fails because the transactional interface cannot perform its passive concurrency conflict checking without the compare. When the Update or Delete fails, the transactional interface returns Status Code 8.

Result

If the transactional interface finds the requested key, it returns the key value in the Key Buffer and Status Code 0. Otherwise, the transactional interface returns a status code indicating why it cannot find the key value. The Get Key operation establishes the current positioning in a similar manner to the corresponding Get operation. However, when a Get Key operation involves a key that allows duplicates, the transactional interface ignores the duplicate instances of the current retrieved key value. After a Get Key operation, the logical previous position points to the record containing the previous lesser key value. The logical next position points to the record with the next greater key value. For example, assume you perform a Get Key/Get Equal operation (55) on a last name key that contains eight occurrences of Smith and a single Smythe. The logical next position does not point to the next Smith, but to Smythe. Because a Get Key operation does not positively identify any one record, the transactional interface does not allow an Update or Delete operation to follow a Get Key operation.

Positioning

2-74

Get Last (13)

The Get Last operation (B_GET_LAST) retrieves the logical last record based on the specified key. If duplicates exist for the last key value, the record returned is the last duplicate. You can use the Get Key (+50) bias to detect the presence of a value in a file. A Get Key operation is generally faster.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites

The file must be open. The file cannot be a data-only file. Set the Operation Code to 13. Optionally, you can include a lock bias:

Procedure

+100Single wait record lock. +200Single no-wait record lock. +300Multiple wait record lock. +400Multiple no-wait record lock.

For more information about locking, refer to the Pervasive PSQL Programmer's Guide.
2 3 4

Pass the Position Block for the file. Set the Data Buffer Length to a value greater than or equal to the length of the record you want to retrieve. Specify the Key Number for the key path. To use the systemdefined log key (also called system data), specify 125.

Result

If the Get Last operation is successful, the transactional interface returns the requested record in the Data Buffer, stores the corresponding key value in the Key Buffer, and returns the length of the record in the Data Buffer Length parameter.

2-75

Btrieve API Operations

If the Get Last operation is unsuccessful, the transactional interface returns one of the following status codes:
3 6 9 22 The file is not open. The key number parameter is invalid. The operation encountered the end-of-file. The data buffer parameter is too short.

Positioning

The Get Last operation establishes the complete logical and physical currencies and makes the retrieved record the current one. The logical next position points beyond the end of the file.

2-76

Get Less Than (10)

The Get Less Than operation (B_GET_LT) retrieves a record in which the value for the key specified by the Key Number has the previous lesser value than the value you supply in the Key Buffer. If the key allows duplicate values, this operation retrieves the last record (chronologically) of the group with the same key values. You can use the Get Key (+50) bias to detect the presence of a value in a file. A Get Key operation is generally faster.
Note If you are using the Get Less Than operation on descending keys, the next lesser value refers to a value higher than the one specified in the Key Buffer.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites

The file must be open. The file cannot be a data-only file. Set the Operation Code to 10. Optionally, you can include a lock bias:

Procedure

+100Single wait record lock. +200Single no-wait record lock. +300Multiple wait record lock. +400Multiple no-wait record lock.

For more information about locking, refer to the Pervasive PSQL Programmer's Guide.
2 3

Pass the Position Block for the file. Set the Data Buffer Length to a value greater than or equal to the length of the record you want to retrieve.

2-77

Btrieve API Operations

4 5

Specify the desired key value in the Key Buffer parameter. Set the Key Number parameter to the key path. To use the system-defined log key (also called system data), specify 125.

Result

If the Get Less Than operation is successful, the transactional interface returns the record in the Data Buffer, the key value for the record in the Key Buffer, and the length of the record in the Data Buffer Length parameter. If the Get Less Than operation is unsuccessful, the transactional interface returns one of the following status codes:
3 6 22 The file is not open. The key number parameter is invalid. The data buffer parameter is too short.

Positioning

The Get Less Than operation establishes the complete logical and physical currencies and makes the retrieved record the current one.

2-78

Get Less Than or Equal (11)

The Get Less Than or Equal operation (B_GET_LE) retrieves a record in which the value for the key specified by the Key Number has an equal or a previous lesser value than the value you supply in the Key Buffer. The transactional interface first tries to satisfy the equal requirement. If the key allows duplicate values, this operation retrieves the last record (chronologically) of the group with the same key values. You can use the Get Key (+50) bias to detect the presence of a value in a file. A Get Key operation is generally faster.
Note If you are using the Get Less Than or Equal operation on

descending keys, the next lesser value refers to a value higher than the one specified in the Key Buffer.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites

The file must be open. The file cannot be a data-only file. Set the Operation Code to 11. Optionally, you can include a lock bias:

Procedure

+100Single wait record lock. +200Single no-wait record lock. +300Multiple wait record lock. +400Multiple no-wait record lock.

For more information about locking, refer to the Pervasive PSQL Programmer's Guide.
2

Pass the Position Block for the file.

2-79

Btrieve API Operations

3 4 5

Set the Data Buffer Length to a value greater than or equal to the length of the record you want to retrieve. Specify the key value in the Key Buffer parameter. Set the Key Number parameter to the key path. To use the system-defined log key (also called system data), specify 125.

Result

If the Get Less Than or Equal operation is successful, the transactional interface returns the record in the Data Buffer, the key value for the record in the Key Buffer, and the length of the record in the Data Buffer Length parameter. If the Get Less Than or Equal operation is unsuccessful, the transactional interface returns one of the following status codes:
3 6 22 The file is not open. The key number parameter is invalid. The data buffer parameter is too short.

Positioning

The Get Less Than or Equal operation establishes the complete logical and physical currencies and makes the retrieved record the current one.

2-80

Get Next (6)

The Get Next operation (B_GET_NEXT) retrieves the record in the logical next position (based on the specified key). You can use the Get Next operation to retrieve records within a group of records that have duplicate key values. You can use the Get Key (+50) bias to detect the presence of a value in a file. A Get Key operation is generally faster.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites

The file must be open. The file cannot be a data-only file. Your application must have an established logical next position based on the specified key. Set the Operation Code to 6. Optionally, you can include a lock bias:

Procedure

+100Single wait record lock. +200Single no-wait record lock. +300Multiple wait record lock. +400Multiple no-wait record lock.

For more information about locking, refer to the Pervasive PSQL Programmer's Guide.
2 3 4

Pass the Position Block for the file. Set the Data Buffer Length to a value greater than or equal to the length of the record you want to retrieve. Specify the key value from the previous operation in the Key Buffer.

2-81

Btrieve API Operations

Pass the Key Buffer exactly as the transactional interface returned it on the previous call, because the transactional interface may need the information previously stored there to determine its current position in the file.
5

Set the Key Number parameter to the key path used on the previous call. You cannot change key paths using a Get Next operation.

Result

If the Get Next operation is successful, the transactional interface returns the record in the Data Buffer, the key value for the record in the Key Buffer, and the length of the record in the Data Buffer Length parameter. If the Get Next operation is unsuccessful, the transactional interface returns one of the following status codes:
3 6 7 8 9 22 82 The file is not open. The key number parameter is invalid. The key number has changed. The current positioning is invalid. The operation encountered the end-of-file. The data buffer parameter is too short. The transactional interface lost positioning.

The operation returns Status Code 9 if the logical next position points beyond the end of the file.

Positioning

The Get Next operation establishes the complete logical and physical currencies and makes the retrieved record the current one.

2-82

Get Next Extended (36)

The Get Next Extended operation (B_GET_NEXT_EXTENDED) examines one or more records, starting at the logical next position and proceeding toward the end of the file, based on the specified key. It checks to see if the examined record or records satisfy a filtering condition, and it retrieves the ones that do. The filtering condition is a logic expression and is not limited to key fields only. Get Next Extended can also extract specified portions from records and return only those portions to an application.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites

The file must be open. The file cannot be a data-only file. You must have an established logical next position based on the specified key. You can establish logical positioning by issing any non-extended Get operation, such as a Get Equal. Set the Operation Code to 36. Optionally, you can include a lock bias:

Procedure

+100Single wait record lock. +200Single no-wait record lock. +300Multiple wait record lock. +400Multiple no-wait record lock.

For more information about locking, refer to the Pervasive PSQL Programmer's Guide.
2

Pass the Position Block for the file.

2-83

Btrieve API Operations

Specify a large enough Data Buffer to accommodate either the input Data Buffer or the returned Data Buffer, whichever is larger. Initialize the Data Buffer according to the structure shown in Table 2-14. Specify the Data Buffer Length as either the length of the input structure (Table 2-14) or the length of the returned structure (Table 2-15), whichever is larger. Specify the key value from the previous operation in the Key Buffer. Pass the Key Buffer exactly as the transactional interface returned it on the previous call, because the transactional interface may need the information previously stored there to determine its current position in the file. Set the Key Number parameter to the key path used on the previous call. You cannot change key paths using a Get Next Extended operation.

Details

The following table shows the structure of the input data buffer.
Table 2-14 Input Data Buffer Structure for Extended Get and Step Operations
Element Length (Bytes) 2 2 Description

Header

Total length of the Data Buffer. One of two string constant values (fixed length, do not null-terminate): EGBegin with the record after the one at which you are positioned. UCBegin with the record at which you are positioned. For Step Next Extended operations, always set this value to EG.

2-84

Get Next Extended (36)

Table 2-14 Input Data Buffer Structure for Extended Get and Step Operations
continued Element Length (Bytes) 2 Description

Filter (Fixed Portion)

Maximum Reject Count, which is the number of records that the transactional interface can skip while searching for records that satisfy the filter condition. You can set the value from 0 to 65,535. (0 means the transactional interface uses the system-defined maximum reject count, which is 4,095.) Number of Terms in the logic expression of the filter condition. (0 means the transactional interface performs no filtering.) The only limit to the number of terms is the size of the data buffer. In Pervasive.SQL 2000i SP3 only, the limit for the number of terms is 119.

2-85

Btrieve API Operations

Table 2-14 Input Data Buffer Structure for Extended Get and Step Operations
continued Element Length (Bytes) 1 Description

Filter (Repeat this segment once for each term in the logic expression)

Data Type of the field. Use one of the codes shown in Table 2-4. Field Length. Field Offset (zero relative). Specifies a Comparison Code: 1Equal 2Greater than 3Less than 4Not equal 5Greater than or equal 6Less than or equal Add a +8 bias to compare strings using one of the files existing ACSs. Add a +32 bias to compare strings using the files default ACS, which is the first ACS defined in the file. If you use both a +8 bias and a +32 bias, the +32 bias is ignored. Add a +64 bias if the second operand is another field of the record, rather than a constant. Add a +128 bias to compare strings without case sensitivity.

2 2 1

Indicates an AND/OR logic expression: 0Identifies the last term 1Next term is connected with AND 2Next term is connected with OR When comparing two fields: a 2-byte, zero-relative offset to the second field. (The second field must be the same type and length.) or When comparing a field to a constant: the actual value of the constant. The length of the constant (n) must equal the length of the field. When specifying an ACS by name (bias +8), the ACS identifier using one of the name formats shown in Table 2-5.

2 or n

0, 5, 9, or 17

2-86

Get Next Extended (36)

Table 2-14 Input Data Buffer Structure for Extended Get and Step Operations
continued Element Length (Bytes) 2 Description

Descriptor (Fixed Portion)

Number of Records to retrieve. To retrieve only one record instead of a set of records, specify 1. Number of Fields to extract from each record. Field Length to extract. Field Offset (zero relative).

2 Descriptor (Repeat this segment for each extracted field) 2 2

The transactional interface interprets the AND and OR operators used in a filter with the extended Get and Step operations in strict left-to-right order. The transactional interface evaluates an expression in the filter and proceeds as follows:

If the expression is true when applied to the current record and the next operator is OR, the transactional interface accepts this record as meeting the filter condition. If the expression is true and the next operator is AND, the transactional interface continues to evaluate each expression until one of the following situations occurs: The transactional interface reaches an OR expression.

One of the expressions evaluates to false. The transactional interface reaches the end of the filter.

If the expression is false and the next operator is OR, the transactional interface continues and evaluates the next expression in the filter. If the expression is false and the next operator is AND, the transactional interface rejects the record.

The search for records stops if any one of the following conditions is met:

The transactional interface finds the requested number of records that satisfy the filter.

2-87

Btrieve API Operations

While the transactional interface searches for records to satisfy the filter condition, the number of records it examines exceeds the Maximum Reject Count you specify. The current key path is used as a filtering field and the transactional interface reaches a rejected record after which no records can satisfy the filtering condition in the rest of the file. The transactional interface reaches the end of the file.

Examples To get the next entire record that satisfies the filtering condition, set the filter portion as desired and set the descriptor fields as follows:
1 2 3 4

Set the Number of Records to 1. Set the Number of Fields to 1. Set the Field Length to the length of the entire record to retrieve. Set the Field Offset to 0.

To retrieve the next 12 records without using a filtering condition and extract 4 fields from each record, set the filter Number of Terms to 0 and set the descriptor fields as follows:
1 2 3

Set the Number of Records to 12. Set the Number of Fields to 4. Set the Field Length and Field Offset parameters for each of the 4 fields extracted.

Retrieving Fields from Records When retrieving one or more fields (portions) of records with an extended operation, you must ensure that the Data Buffer can accommodate the information that the operation returns.

2-88

Get Next Extended (36)

Table 2-15 on page -86 illustrates the structure of the Data Buffer that the transactional interface returns.
Table 2-15 Returned Data Buffer Structure for Extended Get and Step Ops
Element Length (Bytes) 2 Description

Number of Records

Number of records returned.

Repeating portion (one for each record retrieved) Length 0 Position 0 Record 0 . . . Length x 2 Length in bytes of the last record image (all fields combined). Physical currency (address) of the last record. Image of the last record (all fields combined). 2 4 n Length of the first record image (all fields combined). Physical currency (address) of the first record. Image of the first record (all fields combined).

Position x Record x

4 n

If all returned records (or fields of records) are fixed length, your application can easily calculate the location of data within the returned Data Buffer. However, your application may need to perform extra steps to extract the variable-length portion of records from the Data Buffer that an extended operation returns. The transactional interface does not pad any record image in the returned Data Buffer when returning the variable-length portion of a record. Consequently, if you allow room in the returned Data Buffer for the maximum number of bytes that the variable-length portion of a record could occupy, but the actual data returned is less than that maximum, the transactional interface starts the field description for the next returned field immediately following the data for the current field. For example, suppose your fixed-record length is 100 bytes, your variable-length portion is up to 300 bytes, and you want to return just the variable-length portion of 5 records. You would use the descriptor element of the input buffer to set a Field Length of 300

2-89

Btrieve API Operations

and a Field Offset of 100. For the returned buffer, you need 2 bytes for the Number of Records plus 306 bytes for each record (that is, 2 bytes for the length, 4 bytes for the address, and 300 bytes for the data), as shown in the following calculation:
2 + ((2 bytes + 4 bytes + 300 bytes) * 5) = 1532 bytes

However, suppose that the variable-length portion of the first record returned contains only 50 bytes of data. This means the 2-byte length for the second record returned is stored at offset 58 in the Data Buffer, immediately following the image of the first records field. In such a situation, your application must parse the length, position, and data from the Data Buffer that the transactional interface returns.

Result

If the Get Next Extended operation is successful, the transactional interface returns the following:

In the Data Buffer, one or more fields from one or more records. (See Table 2-15.) In the Data Buffer Length, the total number of bytes received. In the Key Buffer, the key value for the last data record received.

If the Get Next Extended operation is unsuccessful, the transactional interface returns one of the following status codes:
3 6 7 8 9 22 60 61 62 64 65 The file is not open. The key number parameter is invalid. The key number has changed. The current positioning is invalid. The operation encountered the end-of-file. The data buffer parameter is too short. The specified reject count has been reached. The work space is too small. The descriptor is incorrect. The filter limit has been reached. The field offset is incorrect.

2-90

Get Next Extended (36)

82 134 135

The transactional interface lost positioning. The transactional interface cannot read the International Sorting Rule. The specified International Sort Rule table is corrupt or otherwise invalid. The transactional interface cannot find the specified Alternate Collating Sequence in the file.

136

It is possible for the transactional interface to return a nonzero status code and also return valid data in the Data Buffer. In this case, the last record returned may be incomplete. If the Data Buffer Length parameter returned is greater than 0, check the Data Buffer for extracted data. If a field can only be partially filled because the data buffer is too short, then the transactional interface returns what it can of the record to and including the partial field. If the partial field is the last field to be extracted, then the transactional interface continues the operation. Otherwise, the transactional interface aborts the operation and returns a Status Code 22. For example, consider a Get Next Extended operation that retrieves 3 fields from 2 variable-length records. The first record is 55 bytes long and the second is 50 bytes long. The Data Buffer allows 50 bytes for return data. The 3 fields to be retrieved are defined as follows:

Field 1 begins at offset 2 and is 2 bytes long. Field 2 begins at offset 45 and is 10 bytes long. Field 3 begins at offset 6 and is 2 bytes long.

When the transactional interface performs the Get Next Extended operation, it returns the first record without any problem. However, when attempting to extract field 2s 10 bytes from the second record, the transactional interface finds that only 5 bytes are available (between offset 45 and the end of the record, at offset 49). At this point, the transactional interface does not pad the missing 5 bytes of field 2, and thus cannot extract field 3. Instead, the transactional interface returns Status Code 22 and places all of field 1 and the first 5 bytes of field 2 in the return Data Buffer. Depending on the fields and the operators used in the filtering condition, the transactional interface may be able to optimize your request. After reaching a certain rejected record, it returns Status

2-91

Btrieve API Operations

Code 64, indicating that no records can satisfy the filtering conditions in the rest of the file.

Positioning

The Get Next Extended operation establishes the complete logical and physical currencies. The last record examined becomes the current record. This record can be either a record that satisfies the filtering condition and is retrieved, or a record that does not satisfy the filtering condition and is rejected, but is still not past the optimization limit. For example, if the extended operation returns status 9, the current record is that last record in the file. If status 60 (reject count reached) is retuned, then the current record is the last record rejected. If status 64 (Filter Limit Reached) is returned, then the current record is the last record that satisfies the optimization criteria. Even thought the transactional interface had to look at the next record after this to determine that the optimization limit was exceeded, it sets the current record back to the previous record that did satisfy that criteria.
Note The transactional interface does not allow Delete or

Update operations after a Get Next Extended operation. Because the current record is the last record examined, there is no way to ensure that your application would delete or update the intended record.

2-92

Get Position (22)

The Get Position operation (B_GET_POSITION) returns the physical 4-byte position of the current record. Get Position fails if there is no established physical currency when you issue the operation. Once you determine a records position (address), you can use the Get Direct/Record operation (23) to retrieve that record directly by its physical location in the file. The transactional interface does not perform any disk I/O to process a Get Position request.

Parameter

Op Code

Pos Block

Data Buf

Data Buf Len

Key Buffer

Key Number

Sent Returned

Prerequisites

The file must be open. Your application must have established physical currency. Set the Operation Code to 22. Pass the Position Block for the file. Set the Data Buffer Length to at least 4 bytes. Set the Key Number to 0.

Procedure

1 2 3 4

Result

If the Get Position operation is successful, the transactional interface returns the position of the record in the Data Buffer. The position is a 4-byte binary value (most significant word first) that indicates the records offset (in bytes) into the file. The transactional interface also sets the Data Buffer Length to 4 bytes. If the Get Position operation is unsuccessful, the transactional interface returns one of the following status codes:
3 8 The file is not open. The current positioning is invalid.

Positioning

The Get Position operation has no effect on positioning.

2-93

Btrieve API Operations

Get Previous (7)

The Get Previous operation (B_GET_PREVIOUS) retrieves the record in the logical previous position based on a specified key. You can use the Get Previous operation to retrieve a record within a group of records that have duplicate key values. You can use the Get Key (+50) bias to detect the presence of a value in a file. A Get Key operation is generally faster.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites

The file must be open. The file cannot be a data-only file. Your application must have established a logical previous position based on the specified key. Set the Operation Code to 7. Optionally, you can include a lock bias:

Procedure

+100Single wait record lock. +200Single no-wait record lock. +300Multiple wait record lock. +400Multiple no-wait record lock.

For more information about locking, refer to the Pervasive PSQL Programmer's Guide.
2 3

Pass the Position Block for the file. Set the Data Buffer Length to a value greater than or equal to the length of the record you want to retrieve.

2-94

Get Previous (7)

Specify the key value from the previous operation in the Key Buffer. Pass the Key Buffer exactly as the transactional interface returned it on the previous call. The transactional interface may need the information previously stored in the Key Buffer to determine its current position in the file. Set the Key Number parameter to the key path used on the previous call. You cannot change key paths using a Get Previous operation.

Result

If the Get Previous operation is successful, the transactional interface updates the Key Buffer with the key value for the previous record, returns the previous record in the Data Buffer, and returns the length of the record in the Data Buffer Length parameter. If the Get Previous operation is unsuccessful, the transactional interface returns one of the following status codes:
3 6 7 8 9 22 82 The file is not open The key number parameter is invalid The key number has changed The current positioning is invalid The operation encountered the end-of-file The data buffer parameter is too short The transactional interface lost positioning

This operation returns Status Code 9 if the logical previous position points beyond the beginning of the file.

Positioning

The Get Previous operation establishes the complete logical and physical currencies and makes the retrieved record the current one.

2-95

Btrieve API Operations

Get Previous Extended (37)

The Get Previous Extended operation (B_GET_PREV_EXTENDED) examines one or more records, starting at the logical previous position and proceeding toward the beginning of the file, based on the specified key. It checks to see if the examined record or records satisfy a filtering condition, and it retrieves the ones that do. The filtering condition is a logic expression and is not limited to key fields only. Get Previous Extended can also extract specified portions of records and return only those portions to an application.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites

The file must be open. The file cannot be a data-only file. You must have an established logical previous position based on the specified key. Set the Operation Code to 37. Optionally, you can include a lock bias:

Procedure

+100Single wait record lock. +200Single no-wait record lock. +300Multiple wait record lock. +400Multiple no-wait record lock.

For more information about locking, refer to the Pervasive PSQL Programmer's Guide.
2

Pass the Position Block for the file.

2-96

Get Previous Extended (37)

Specify a large enough Data Buffer to accommodate either the input Data Buffer or the returned Data Buffer, whichever is larger. Initialize the Data Buffer according to the structure shown in Table 2-14. Specify the Data Buffer Length as either the length of the input structure (Table 2-14 on page -82) or the length of the returned structure (Table 2-15 on page -86), whichever is larger. The transactional interface sets up a buffer as a workspace for extended operations. You configure the size of this buffer using the Extended Operation Buffer Size option. The sum of the Data Buffer structure, plus the longest record to be retrieved, plus 355 bytes of requester overhead, cannot exceed the configured buffer size. (Requester overhead is not applicable in DOS workstation engines.)

Specify the key value from the previous operation in the Key Buffer. Pass the Key Buffer exactly as the transactional interface returned it on the previous call, because the transactional interface may need the information previously stored there to determine its current position in the file. Set the Key Number parameter to the key path used on the previous call. You cannot change key paths using a Get Previous Extended operation.

Details

This operation uses the same input and returned Data Buffers as the Get Next Extended operation. Refer to Details for more information. This operation returns the same results as the Get Next Extended operation. Refer to Result for more information. The Get Previous Extended operation establishes the complete logical and physical currencies. The last record examined becomes the current record. This record can be either a record that satisfies the filtering condition and is retrieved, or a record that does not satisfy the filtering condition and is rejected.

Result Positioning

2-97

Btrieve API Operations

Note The transactional interface does not allow Delete or

Update operations after a Get Previous Extended operation. Because the current record is the last record examined, there is no way to ensure that your application would delete or update the intended record.

2-98

Insert (2)

Insert (2)
The Insert operation (B_INSERT) inserts a record into a file. The transactional interface adjusts the B-trees for the keys to reflect the key values for the new record.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites

The file must be open. The record to be inserted must be the proper length, and the key values must conform to the keys defined for the file. Set the Operation Code to 2. Pass the Position Block for the file. In the Data Buffer, store the record to be inserted. Specify the Data Buffer Length. This value must be at least as long as the fixed-length portion of the record. Specify the Key Number that the transactional interface uses to establish positioning information (currency). To use the NCC option, specify 1 (0xFF) for the Key Number. To use the systemdefined log key (also called system data), specify 125.
Note When using the no-currency-change (NCC) option, the

Procedure

1 2 3 4 5

Insert operation does not update the value of the Key Buffer parameter; it does not return any information in that parameter.

Result

If the Insert operation is successful, the transactional interface places the new record in the file, updates the B-trees for the keys to reflect the new record, and returns the value of the specified key in the Key Buffer. If you insert a record that contains an AUTOINCREMENT key value initialized to binary 0, the transactional interface also

2-99

Btrieve API Operations

returns the inserted record in the Data Buffer, including the AUTOINCREMENT value assigned by the transactional interface. An NCC Insert operation does not change the value of the Key Buffer parameter. If the Insert operation is unsuccessful, the transactional interface returns one of the following status codes:
2 3 5 18 21 22 The application encountered an I/O error. The file is not open. The record has a key field containing a duplicate key value. The disk is full. The key buffer parameter is too short. The data buffer parameter is too short.

Positioning

An Insert operation that does not specify the NCC option establishes the complete logical and physical currencies and makes the inserted record the current one. The logical currency is based on the specified key. An NCC Insert operation establishes physical currency without affecting logical currency. This means that an application, having performed an NCC Insert operation, has the same logical position in the file as it had prior to the Insert operation. In such a situation, operations that follow an NCC Insertsuch as Get Next (6), Get Next Extended (36), Get Previous (7), and Get Previous Extended (37)return values based on the applications logical currency prior to the NCC Insert.
Note The transactional interface does not return any

information in the Key Buffer parameter as the result of an NCC Insert operation. Therefore, an application that must maintain the logical currency must not change the value of the Key Buffer following the NCC Insert operation. Otherwise, the next Get operation has unpredictable results. The transactional interface establishes the physical currency to a newly inserted record for both the standard Insert and the NCC Insert operations. Operations following an NCC Insert operation

2-100

Insert (2)

such as Step Next (24), Step Next Extended (38), Step Previous (35), Step Previous Extended (39), Update (3), Delete (4), and Get Position (22)operate based on the new physical currency.

2-101

Btrieve API Operations

Insert Extended (40)

The Insert Extended operation (B_EXT_INSERT) inserts one or more records into a file. The transactional interface adjusts the Btrees for the keys to reflect the key values for the new records.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Note When using the no-currency-change (NCC) option, the

Insert Extended operation does not update the value of the Key Buffer parameter; it does not return any information in that parameter.

Prerequisites

The file must be open. The records to be inserted must be the proper length, and the key values must conform to the keys defined for the file. Set the Operation Code to 40. Pass the Position Block for the file. Specify the Data Buffer according to the structure shown in Table 2-16. Specify the Data Buffer Length. This value must be exactly the size of the Data Buffer structure. Specify the Key Number that the transactional interface uses to establish currency. To use the NCC option, specify 1 (0xFF) for the Key Number. To use the system-defined log key (also called system data), specify 125.

Procedure

1 2 3 4 5

2-102

Insert Extended (40)

Details

The following table shows the data buffer structure.

Table 2-16 Data Buffer Structure for the Insert Extended Operation
Element Length (Bytes) 2 Description

Fixed portion

Number of records inserted.

Repeating portion (one for each record) 2 n Length of the record image. Record image.

Result

If the Insert Extended operation is successful, the transactional interface places the new records in the file, updates all the B-trees to reflect the new records that were inserted, and (except for NCC Insert Extended operation) returns in the Key Buffer the value of the specified key from the last record inserted. In addition, in the first word of the returned Data Buffer, the transactional interface places the number of records that were successfully inserted into the file. Following the first word of the Data Buffer, the transactional interface stores the addresses of the inserted records. If the operation is only partially successful and the transactional interface returns a nonzero status code, the first word of the Data Buffer equals the number of records that were successfully inserted. The record that caused the error is the number of records that were successfully inserted plus one. If the Insert Extended operation is unsuccessful, the transactional interface returns one of the following status codes:
2 3 5 18 21 22 The application encountered an I/O error. The file is not open. The record has a key field containing a duplicate key value. The disk is full. The key buffer parameter is too short. The data buffer parameter is too short.

Positioning

An Insert Extended operation that does not specify the NCC option establishes the complete logical and physical currencies and makes

2-103

Btrieve API Operations

the last inserted record the current one (unless the inserted records key value is null). The logical currency is based on the specified key. An NCC Insert Extended operation establishes physical currency without affecting logical currency. This means that an application, having performed an NCC Insert Extended operation, has the same logical position in the file as it had prior to the operation. In such a situation, operations that follow an NCC Insert Extended operationsuch as Get Next (6), Get Next Extended (36), Get Previous (7), and Get Previous Extended (37)return values based on the applications logical currency prior to the NCC Insert Extended operation.
Note The transactional interface does not return any

information in the Key Buffer parameter as the result of an NCC Insert Extended operation. Therefore, an application that must maintain the logical currency must not change the value of the Key Buffer following the NCC Insert Extended operation. Otherwise, the next Get operation has unpredictable results. The transactional interface establishes the physical currency to a newly inserted record for both the standard Insert Extended and the NCC Insert Extended operations. Therefore, operations following an NCC Insert Extended operationsuch as Step Next (24), Step Next Extended (38), Step Previous (35), Step Previous Extended (39), Update (3), Delete (4), and Get Position (22) operate based on the new physical currency. An NCC Insert Extended operation is useful when an application must save its logical position in the file prior to executing the Insert Extended operation in order to perform another operation based on the original logical currency, such as a Get Next operation (6). To achieve this effect without an NCC Insert Extended operation, your application would have to execute the following steps:
1

Get Position (22)Obtains the 4-byte physical address for the logical current record. The application saves this value and passes it back in Step 3. Insert Extended (40)Inserts the new records. This operation establishes new logical and physical currencies.

2-104

Insert Extended (40)

Get Direct/Record (23)Re-establishes logical and physical currencies as they were in Step 1.

The NCC Insert Extended operation has the same effect in terms of logical currency, but can have a different effect in terms of physical currency. For example, executing a Get Next (6) operation after either procedure produces the same result, but executing a Step Next (24) might return different records.

2-105

Btrieve API Operations

Login/Logout (78)
The Login/Logout operation (B_LOGIN/B_LOGOUT) allows a user to specify his/her user credentials and obtain authentication and authorization tokens from the database engine. This operation also allows the user to reset his/her login credentials so that they must be entered again to gain access to the database.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites Login Procedure

The database name and the user ID must be pre-defined. Set the Operation Code to 78. Set the key number to 0. Place the server name, database name, user ID, and password in the key buffer in the form of a database URI. (In Pervasive PSQL Programmer's Guide, see Database URIs on page 4-35.) Set the Operation Code to 78. Set the key number to 1. Place the server name, database name, user ID, and password in the key buffer in the form of a database URI. (In Pervasive PSQL Programmer's Guide, see Database URIs on page 4-35.)

1 2 3

Logout Procedure

1 2 3

Result

If the Login or Logout operation is successful, the database engine returns status 0; otherwise, one of the following status codes may be returned:
1 172 3103 Invalid operation Database name not found Unknown server

2-106

Notes

The combined length of the database URI must be less than 255 bytes. This is due to the maximum size of the key buffer. The Login operation has a performance cost. You should not code applications to login and logout on every file. Instead, login once to a database at the beginning of a session, then logout when the database work is complete.

Positioning

The Login/Logout operation has no effect on any file currency information.

2-107

Btrieve API Operations

Open (0)
The Open operation (B_OPEN) makes a file available for access. To access a file, your application must first perform an Open operation. The file does not have to reside in the current directory as long as you specify the full or relative pathname.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites

The file to be opened must exist on an accessible logical disk drive. A file handle must be available for the file. Set the Operation Code to 0. If the file has an owner, specify the owner name, terminated by a binary 0, in the Data Buffer parameter. Specify the length of the owner name, including the binary 0 in the Data Buffer Length parameter. Place the pathname of the file to open in the Key Buffer parameter. Terminate the pathname with a NULL (binary zero) depending on the setting for embedded spaces. The pathname can be up to 255 bytes. Any fully-qualified Unified Naming Convention (UNC) path name including the null terminator can be up to 255 bytes long. The transactional interface normally expands the file name to a fully-qualified UNC file name. For example, J:\Data\File.dat would be converted to \\Servername\ShareName\Data\File.dat. This expanded name must fit into 255 bytes including the NULL terminator.

Procedure

1 2 3

2-108

Open (0)

However, if the Btrieve Open request is sent to a local engine, the MIF will not replace the local drive letter with the computer name and share name. Even though you may get by with a longer path name if opened locally, remote clients may not be able to open the file. Support for file names with embedded spaces based is enabled by a client configuration option, "Embedded Spaces." By default, this configuration parameter is set to On, which means spaces are considered part of the path. When the setting is On, a NULL byte must delimit the file name. When the setting is Off, you cannot use filenames that contain embedded spaces (such as "C:\My Folder\my file.mkd"). See Advanced Operations Guide on page 13-4 (Long File Names and Embedded Spaces Support). For more information about path names transactional interface supports, refer to Getting Started With Pervasive PSQL.
4

In the Key Number parameter, specify one of the mode values listed in Table 2-17 on page 2-106.

Details

This section describes the open modes that are supported.

Caution The database engine cannot guarantee transaction atomicity, transaction durability, or archival log safety for any client during use of Accelerated mode by any client. The reason for this restriction is that in the event a restore from log is needed, the log may not contain adequate information to complete the restore, because it is only a partial record of operations on a data file. For example, if a system failure occurs while the same file is being accessed by a client performing inserts using Accelerated mode and a client performing updates using Normal mode, it is possible for the transaction log to contain updates to records that do not yet exist in the data files, because the Accelerated insert operation in memory was never flushed to disk, while the transactional update operation was written to the transaction log. An attempt to roll forward an archival log containing this combination of operations will fail.

2-109

Btrieve API Operations

When you open a file, you can instruct the transactional interface through the open mode to use either a local or remote engine. You specify the open mode in the Key Number parameter.
Note The Open operation makes no distinction between

workstation, workgroup, and server engines when you specify that the local engine should open the file.

Table 2-17 Open Modes

Description No preference 0 1 Force local engine 6 7 Force remote engine 99 100

Normal Accelerated To improve performance on specific files, you can open a file in Accelerated mode. (The 6.x transactional interface accepted Accelerated mode opens, but interpreted them as Normal opens.) When you open a file in Accelerated mode, the transactional interface does not perform transaction logging on the file. See the caution above. NetWare developers: Opening a file in Accelerated mode cancels the effect of flagging a file as transactional. (On other platforms, the transactional interface ignores the files NetWare TTS flag.) Read-Only When you open a file in Read-Only mode, you can only read the file; you cannot perform updates. This mode allows you to open a file with corrupt data that the transactional interface cannot automatically recover. If the data in the files indexes has been corrupted, you can retrieve the records by opening the file in Read-Only mode and then using the Step Next (24) operation. Verify This mode is ignored. If you specify this mode, the transactional interface opens the file in Normal mode. In previous versions of the transactional interface, Verify mode verified that the data written to disk was correct. Exclusive Exclusive mode gives an application exclusive access to a file. No other application can open that file until the application that has exclusive access to the file closes it.

101

N/A

103

2-110

Open (0)

The transactional interface allows a maximum of 250 open files, but you might be unable to open that many files due to limitations on system resources. A file is opened only once by the transactional interface. (The transactional interface recognizes and handles the situation in which more than one client at a time opens a file, or a single client has more than one Position Block in the file.) When you open an extended file, the transactional interface uses a single handle, and opens the base file and all extension files.
Note When the NetWare server transactional interface opens an

extended file, it enforces NetWare security on the base file, but not on the extension files. In the rare event that a user has NetWare rights to a base file, but not the extension files, NetWare security can be violated. For workstation engines, NetWare does enforce security; therefore, such a user would not have access to the extension files.

Result

If the Open operation is successful, the transactional interface assigns a file handle to the file, reserves the Position Block passed on the Open call for the newly opened file, and makes the file available for access. If the Open operation is unsuccessful, the transactional interface returns one of the following status codes:
2 11 12 20 46 84 85 86 The application encountered an I/O error. The specified filename is invalid. The transactional interface cannot find the specified file. The transactional interface or Btrieve Requester is inactive. Access to the requested file is denied. The record or page is locked. The file is locked. The file table is full.

2-111

Btrieve API Operations

87 88

The handle table is full. The application encountered an incompatible mode error.

The following tables show the possible combinations for open modes involving local clients. Table 2-18 shows open modes involving local clients.
Table 2-18 Open Mode Combinations for Local Clients
Open Mode for Local Client 1 Normal Open Mode for Local Client 2 Normal Read-Only Exclusive Accelerated Read-Only Normal Read-Only Exclusive Accelerated Exclusive Normal Read-Only Exclusive Accelerated Accelerated Normal Read-Only Exclusive Accelerated Result

Successful Successful Status Code 88 Successful Successful Successful Status Code 88 Successful Status Code 88 Status Code 88 Status Code 88 Status Code 88 Successful Successful Status Code 88 Successful

Positioning

An Open operation does not establish any positioning except that the physical next record becomes the first physical record of the file.

2-112

Reset (28)

Reset (28)
The Reset operation (B_RESET) releases all resources held by a client. This operation aborts any transactions the client has pending, releases all locks, and closes all open files for the client.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites

Your application can issue a Reset operation at any time after the transactional interface or Requester is loaded, as long as the client issuing the Reset call has established a connection with the transactional interfacefor example, by opening a file or by requesting the status of a file using a Pervasive PSQL utility.
1 2

Procedure

Set the Operation Code to 28. Set the Key Number and Key Buffer to 0.

Result

If the Reset operation is successful, the transactional interface performs the following actions for the specified client, window, or session:
1 2 3

Aborts any active transactions. Releases all locks held. Closes all open files.

If the Reset operation is unsuccessful, the transactional interface returns a nonzero status code.

Positioning

The Reset operation destroys all currencies because it closes any open files.

2-113

Btrieve API Operations

Set Directory (17)

The Set Directory operation (B_SET_DIR) sets the current directory to a specified pathname.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites Procedure

The target logical disk drive and directory must be accessible.

1 2

Set the Operation Code to 17. Store the logical disk drive and directory path, terminated by a binary 0, in the Key Buffer. If you omit the drive name, the transactional interface uses the default drive. If you do not specify the complete path for the directory, the transactional interface appends the directory path specified in the Key Buffer to the current directory. For more information about path names Pervasive PSQL supports, refer to Getting Started With Pervasive PSQL.

Result

If the Set Directory operation is successful, the transactional interface makes the directory specified in the Key Buffer the current directory. If the Set Directory operation is unsuccessful, the transactional interface leaves the current directory unchanged and returns a nonzero status code.

Positioning

The Set Directory operation has no effect on positioning.

2-114

Set Owner (29)

The Set Owner operation (B_SET_OWNER) assigns an owner name to a file, so that users who do not provide the name cannot access or modify the file. If an owner name has been set for a file, users or applications must specify the owner name each time they open the file. You can specify that an owner name be required for any access or just for update privileges. When you assign an owner name, you can also direct the transactional interface to encrypt the files data on the disk. If you specify data encryption, the transactional interface encrypts all the data during the Set Owner operation. Therefore, the longer the file, the longer Set Owner takes to complete.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites

The file must be open. No transactions can be active. The file cannot already have an owner name. Set the Operation Code to 29. Pass the Position Block that identifies the file to protect. Store the owner name in both the Data Buffer and the Key Buffer. The transactional interface requires that the name be in both buffers to avoid accidentally specifying an incorrect value. The owner name can be up to eight characters long and must end with a binary 0. The owner name cannot consist of all spaces (0x20). Specify the length of the owner name, including the binary 0, in the Data Buffer Length parameter. Set the Key Number to an integer that specifies the type of access restrictions and encryption for the file. (See Table 2-19.)

Procedure

1 2 3

4 5

2-115

Btrieve API Operations

Details

Once you specify an owner name, it remains in effect until you issue a Clear Owner operation. The following table lists the access restriction codes you can specify for the Key Number.
Table 2-19 Access and Encryption Codes
Code 0 1 2 3 Description Requires an owner name for any access mode (no data encryption). Permits read-only access without an owner name (no data encryption). Requires an owner name for any access mode (with data encryption). Permits read-only access without an owner name (with data encryption).

Result

If the Set Owner operation is successful, the transactional interface prevents future operations from accessing or modifying the file unless those operations specify the correct owner name. The only exception is if read-only access is allowed without an owner name. In addition, if the Set Owner operation is successful, the transactional interface encrypts the data in the file (if encryption is specified). Encryption occurs immediately; the transactional interface has control until the entire file is encrypted, and the larger the file, the longer the encryption process takes. Reading data from an encrypted file is slower than reading data from an unencrypted file. The transactional interface decrypts a page when it loads the page from the disk, then encrypts the page when it writes to the disk again. If you have a small cache or use a relatively large amount of modification operations, the transactional interface must execute the encryption routine more frequently. If the Set Owner operation is unsuccessful, the transactional interface returns one of the following status codes:
41 50 51 The transactional interface does not allow the attempted operation. The file owner is already set. The owner name is invalid.

Positioning

The Set Owner operation has no effect on positioning.

2-116

Stat (15)

Stat (15)
The Stat operation (B_STAT) retrieves the defined characteristics of a file and statistics about the files contents, such as the number of records in the file, the number of unique key values stored for each index in the file, and the number of unused pages in the file.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites Procedure

The file must be open.

1 2 3 4

Set the Operation Code to 15. Pass the Position Block for the file. Indicate a Data Buffer to hold the statistics defined for the file. Specify the Data Buffer Length, which must be long enough to hold the file statistics. (For more information, see Table 2-20 and Table 2-21.) Specify a Key Buffer that is at least 255 characters long. Set the Key Number as follows:

5 6

Specify 0 to exclude file version and unused duplicate pointers information. Parse the returned Data Buffer as shown in Table 2-20. Specify 1 (0xFF) to include file version and unused duplicate pointers information. Parse the returned Data Buffer as shown in Table 2-21.

Details

The transactional interface returns information about all keys in the file, including those added since file creation. The key information includes any applicable ACS definitions. You must account for this

2-117

Btrieve API Operations

extra information in the Data Buffer. Specifically, do not use the same Data Buffer here that you used for the Create (0) operation. Because the transactional interface allows up to 119 keys and multiple ACSs in a file, the longest possible Data Buffer is 33,455 bytes (that is, 16 + (11 * 16) + (119 * 265)). However, you probably do not need such a large data buffer. In fact, you may prefer to specify a smaller Data Buffer if you want only certain information. For example, you could set the Data Buffer Length to 1920 bytes (that is, 16 + (16 * 119)). In effect, such a setting returns all key information but not necessarily all the ACSs. If your application does not need information about the ACSs, you might prefer this method. If you specify a value of 0 in the Key Number parameter, the transactional interface returns Stat information as shown in the following table.
Table 2-20 Data Buffer Excluding File Version Information
Element Description Length (Bytes) 2 2 2 4 2 2 2 2

File Specification

Record Length Page Size Number of Indexes Number of Records File Flags Reserved Word Unused Pages

Key Specification (repeated for each segment)

Key Position

Key Length Key Flags Number of Unique Key Values Extended Data Type Key Specification (repeated for each segment) continued Null Value

2 2 4 1 1

Reserved

2-118

Stat (15)

Table 2-20 Data Buffer Excluding File Version Information continued

Element Description Length (Bytes) 1 1 265 ...

Key Number ACS Number ACS Number 0 ... ACS ...

ACS Number x

ACS

265

If you specify a value of 1 in the Key Number parameter, the transactional interface returns Stat information as shown in the following table.
Table 2-21 Data Buffer Including File Version Information
Element Description Length (Bytes) 2 2 1 1 4 2 1

File Specification

Record Length Page Size Number of Indexes File Version Number Number of Records File Flags Number of Unused Duplicate Pointers Reserved Byte Unused Pages

1 2 2

Key Specifications (repeated for each key segment)

Key Position

Key Length

2-119

Btrieve API Operations

Table 2-21 Data Buffer Including File Version Information continued

Element Description Length (Bytes) 2 4 1 1 2 1 1

Key Flags Number of Unique Key Values Extended Data Type Null Value Reserved Key Number (last member of Key Specification, end of repeated elements) ACS Number 0 ... ACS Number x ACS Number

ACS ... ACS

265 ... 265

File Specifications The File Specification fields in the returned Data Buffer are the same as those described for Create (14), with the following exceptions:

In the File Specification area: If the Data Buffer includes file version information, the Number of Indexes is 1 byte long and is followed by a 1-byte File Version Number. Do not translate the File Version Number value to decimal. A value of 0x70 indicates that the file is a 7.0 file; a value of 0x60 indicates that the file is 6.x, and so on. When creating a file, the transactional interface assigns a version number according to the attributes defined for the file. The Number of Records is a 4-byte value representing the number of records in the file.

2-120

Stat (15)

In the File Flags word, Bits 9 and 12 have the following meaning:
File was created with system data. (This does not necessarily mean that the system-defined log key is currently in use; it may have been dropped.) File was created without system data.

Bit 9 = 1 and Bit 12 = 0

Bit 9 = 1 and Bit 12 = 1

Stat does not indicate whether system data was included by default or explicitly.

If the Data Buffer includes file version information, a 1-byte Number of Unused Duplicate Pointers follows the File Flags field and indicates how many unused duplicate pointers remain in the file. The reserved areas are allocated even though the transactional interface ignores them on a Stat operation.

Key Specifications The Key Specification fields in the returned Data Buffer are the same as those described in Table 2-3 on page -22, except that a 4-byte Number of Unique Key Values follows the Key Flags field and indicates the number of records that have a unique, non-duplicated value for the specified key. ACSs The ACS definitions in the returned Data Buffer are the same as those described for Create (14).

Result

If the Stat operation is successful, the transactional interface returns the file and key characteristics to the Data Buffer and the length of the Data Buffer in the Data Buffer Length. If the file is an extended file, the transactional interface returns the filename of the first extension file in the Key Buffer. If the filename of the first extension file is longer than 63 bytes, the transactional interface truncates the filename. If the file is not an extended file, the transactional interface initializes the first byte of the Key Buffer to 0. (You can use the Stat Extended operation to retrieve statistics regarding extended files.)

2-121

Btrieve API Operations

If the Stat operation is unsuccessful, the transactional interface returns one of the following status codes:
3 22 The file is not open. The data buffer parameter is too short.

Positioning

The Stat operation has no effect on positioning.

2-122

Stat Extended (65)

The Stat Extended operation (B_EXTENDED_STAT) has several subfunctions that allow an application to gather information about an open file.
Table 2-22 Stat Extended (65) Sub-functions
Sub-function ID 1 2 3 4 5 6 Description Listing of extension file names System Data information for the file Duplicate conflict record and key identification File information Gateway identification Lock owner identification

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites Procedure

The file must be open.

1 2 3

Set the Operation Code to 65. Pass the Position Block for the given file. Store the extended stat structure in the Data Buffer. See the subsections below for more information about the extended stat structure required for each subfunction. Specify the Data Buffer Length. Set the Key Number to 0.

4 5

2-123

Btrieve API Operations

Subfunction 1: Extended File Information

For the file specified by the input Position Block, this subfunction returns information about the extension files associated with the specified data file. Returned information includes number of extension files that exist, number returned by the function, and file names for the returned files. Input Data Buffer Structure To receive information about extension files, you must create an extended files descriptor in the Data Buffer, as follows.
Table 2-23 Extended Files Descriptor
Element Length (Bytes) 4 Description

Signature

Type of extended stat call. Specify the following 4 bytes to indicate an Extended Stat Call: 0x45, 0x78, 0x53, 0x74. These are equivalent to ASCII ExSt or to the value 0x74537845 on Intel-types, LoHi and Little-Endian hardware. Type of extended stat call. Specify 0x00000001. File naming convention. Specify 0x00000000. Maximum number of filenames to return. You can set this value higher than the number of extension files composing the extended file. (An extended file can contain up to 32 extension files.) Sequence number of the first filename to return. Specify 0 to begin with the base file, 1 to begin with the first extension file, and so on. If you specify a number higher than the number of extension files, the transactional interface returns Status Code 0 and no filenames. Allow enough additional room for the return data. If you receive Status Code 22, re-try the operation with a larger data buffer size.

Subfunction Namespace Max Files

4 4 4

First File Sequence

Buffer space

Output Data Buffer Structure For the extended files subfunction, the transactional interface updates the value of the Data Buffer Length parameter and returns

2-124

Stat Extended (65)

an extended files structure in the Data Buffer, as illustrated in Table 2-24 on page 2-120.
Table 2-24 Extended Files Return Buffer
Element Length (Bytes) 4 Description

Number of Files

Number of operating system files that comprise the extended file. Number of extension files returned.

Number of Extensions

Filename Portion (Repeated for each filename returned) Length of Filename Filename 4 n Length of the extension filename. Extension filename.

Subfunction 2: System Data Information

For the file specified by the input Position Block, this subfunction returns information about whether there is a system key defined on a file, and whether the file can be logged (transaction durable). Input Data Buffer Structure To receive information about a files use of system data, you must create a system data descriptor in the Data Buffer, as follows.
Table 2-25 System Data Descriptor
Element Length (Bytes) 4 Description

Signature

Unique identifier for an extended stat call. Specify ExSt. See Table 2-23. Type of extended stat call. Specify 0x00000002.

Subfunction

2-125

Btrieve API Operations

Output Data Buffer Structure For the system data subfunction, the transactional interface returns a system data structure in the Data Buffer, as follows.
Table 2-26 System Data Return Buffer
Element Length (Bytes) 1 Description

Has System Data

Indicates whether the files records contain a systemdefined log key (also called system data). 1 = Yes and 0 = No. Indicates whether the system-defined log key is currently being used, as opposed to being dropped. 1 = Yes and 0 = No (dropped). Indicates whether the file has a unique key that can be used to implement transaction durability. This key can be either a user-defined unique key or a systemdefined log key. 1 = Yes and 0 = No. Key number that the transactional interface is currently using as the transaction log key. If the system-defined log key is being used as the transaction log key, this value is 125. Size of the system-defined log key, which is 8.

Has Log Key

Is Loggable

Log Key Number

Size of System Data System Data Version

Major version in byte 7, minor version in byte 8 (0x0007).

Subfunction 3: Duplicate Record Conflict Information

For the file specified by the input Position Block, this subfunction returns information about the extension files associated with the specified data file. Returned information includes the record address and key number that caused a Status Code 5 (Duplicate Key) on a previous failed insert or update operation. Input Data Buffer Structure To receive information about the record address and key number that caused the most recent Status Code 5 (Duplicate Key), you must

2-126

Stat Extended (65)

create a duplicate record information descriptor in the Data Buffer, as follows.

Table 2-27 Duplicate Record Conflict Descriptor
Element Length (Bytes) 4 Description

Signature

Unique identifier for an extended stat call. Specify ExSt. See Table 2-23. Type of extended stat call. Specify 0x00000003.

Subfunction

Output Data Buffer Structure For the system data subfunction, the transactional interface returns a system data structure in the Data Buffer, as follows.
Table 2-28 Duplicate Record Conflict Return Buffer
Element Length (Bytes) 4 Description

Duplicate Record Address Key Number

Physical address of record containing the duplicate key value. Key number of the key containing the duplicate value.

Subfunction 4: For the file specified by the input Position Block, this subfunction File Information returns information about the extension files associated with the
specified data file. Returned information includes: the internal file ID used by the transactional interface to identify the file, the number of file handles currently open, the timestamp of the last time the file was opened, and a variety of flags indicating file properties. Input Data Buffer Structure To receive information about an open file, you must create a file information descriptor in the Data Buffer, as follows.
Table 2-29 File Information Descriptor - Open File
Element Length (Bytes) 4 Description

Signature

Unique identifier for an extended stat call. Specify ExSt. See Table 2-23.

2-127

Btrieve API Operations

Table 2-29 File Information Descriptor - Open File

Element Length (Bytes) 4 12 Description

Subfunction Buffer space

Type of extended stat call. Specify 0x00000004. Additional bytes needed for returned information. See Output Data Buffer Structure For the file information subfunction, the transactional interface returns a file information structure in the Data Buffer, as follows. for details.

Output Data Buffer Structure For the file information subfunction, the transactional interface returns a file information structure in the Data Buffer, as follows.
Table 2-30 File Information Structure - Open File
Element Length (Bytes) 4 Description

FileID

A unique number which the transactional interface uses to identify the file. The current number of handles that the transactional interface has open on this file. The system time when the file was last opened by the transactional interface. This number gets incremented at each checkpoint or System Transaction. It is also the usage count placed in the FCR. The number returned here is the usage count of the file as it is represented in the transactional interface cache. When a checkpoint starts, this number gets incremented. A four-byte bitmap in which various values may be set. See the table below for descriptions of the possible values. More flags may be added in the future.

NumberOfHandles

OpenTimeStamp

FileUsageCount

Flags

2-128

Stat Extended (65)

The permitted values for the Flags field are described in the tables below.
Table 2-31 File Information Flags
Value 0x00000001 Name Explicit Locks Description There are explicit locks currently on the file. There is at least one client transaction currently open on the file. The file was opened by the transactional interface as ReadOnly. This may be a CD-ROM drive or a read-only directory. The file is currently in continuous operations. The file has referential integrity constraints on it. The file has a Read/Write Owner name assigned to it. The owner name is required to read from or write to the file. The file has an owner name that is required only to write to the file. Reads can be done without an owner name. The file has a Reads-OK Owner name assigned to it and the handle was opened with the wrong owner name. The file has the encryption flag on the owner name. This flag means that every page in the file is encrypted and cannot be read using a text editor.

0x00000002

Client Transactions Read Only

0x00000004

0x00000008

Continuous Operations Referential Integrity Owner Read/ Write

0x00000010

0x00000020

0x00000040

Owner Reads OK

0x00000080

Opened with Wrong Owner

0x00000100

Owner Encryption

Subfunction 5: Gateway Information

For the file specified by the input Position Block, this subfunction returns information about the Gateway engine that has control of the file. Input Data Buffer Structure To receive information about the Gateway engine that is responsible

2-129

Btrieve API Operations

for the specified file, you must create a gateway information descriptor in the Data Buffer, as follows.
Table 2-32 Gateway Information Descriptor
Element Length (Bytes) 4 Description

Signature

Unique identifier for an extended stat call. Specify ExSt. See Table 2-23. Type of extended stat call. Specify 0x00000005. Additional bytes needed for returned information. See Output Data Buffer Structure For the gateway information subfunction, the transactional interface modifies the Data Buffer Length parameter and returns a file information structure in the Data Buffer, as follows. for details.

Subfunction Buffer space

4 at least 80

Output Data Buffer Structure For the gateway information subfunction, the transactional interface modifies the Data Buffer Length parameter and returns a file information structure in the Data Buffer, as follows.
Table 2-33 File Information Structure - Gateway Information
Element Length (Bytes) 4 Description

Major Version

The major version of the engine, such as version 7 or 8. The minor version of the engine, such as 05 or 82. The patch level of the engine, such as 1, 2, or 3. The operating system platform the engine is running on. A null-terminated string indicating the name of the machine where the database engine is running. The Data Buffer Length returned by the Btrieve API call contains the actual length of the data returned, including the server name and the null terminator.

Minor Version Patch Level Platform

4 4 4

Server Name

Subfunction 6: Lock Owner Identification 2-130

For the file specified by the input Position Block, this subfunction returns information about the cause of the most recent Status Code 84 or 85 that occurred when accessing the file.

Stat Extended (65)

Input Data Buffer Structure To receive information about the cause of a Status Code 84 or 85, you must create a lock owner information descriptor in the Data Buffer, as follows.
Table 2-34 Lock Owner Information Descriptor
Element Length (Bytes) 4 Description

Signature

Unique identifier for an extended stat call. Specify ExSt. See Table 2-23. Type of extended stat call. Specify 0x00000006. Additional bytes needed for returned information. See Result for details.

Subfunction Buffer space

4 at least 96

Output Data Buffer Structure For the lock owner information subfunction, the transactional interface modifies the Data Buffer Length parameter and returns a file information structure in the Data Buffer, as follows.
Table 2-35 Lock Owner Information Return Buffer
Element Length (Bytes) 16 4 Description

Client ID Flags

The 16-byte client ID of the blocking client. A four-byte bitmap containing flags indicating the type of conflict that occurred. See the table below for a description of each flag value. Number of milliseconds in which the blocking client has been in a transaction. This can be helpful in determining whether to retry the operation. If the conflict occurred on a key page, this element indicates which key is involved. Tracking this information can be useful in designing a database with fewer potential conflicts. If this number is non-zero, then the blocking client is currently in a transaction. Since some page and record locks are held until the transaction completes, this information might be useful in determining if the operation should be retried.

Time In Transaction

Key Number

Transaction Level

2-131

Btrieve API Operations

Table 2-35 Lock Owner Information Return Buffer

Element Length (Bytes) 8 Description

Reserved

Reserved for future use. If there is some information about the blocking client which you think may be useful, please contact Pervasive Software. This is a null-terminated string which is the same identifying name that is displayed in Monitor for each client. Use at least 64 bytes since that is the current maximum display name length. The Data Buffer Length returned by the Btrieve API call contains the actual length of the data returned, including the display name and the null terminator.

Display Name

If there is no record in the transactional interface of a previous blocking client, then the output data buffer length is set to zero. The permitted values for the Flags field are described in the table below.
Table 2-36 Lock Owner Flags
Value 0x00000001 0x00000002 0x00000010 0x00000020 0x00000040 0x00000100 Name Implicit Lock Explicit Lock File Lock Page Lock Record Lock Data Page Description The blocking client is using an implicit lock. The blocking client is using an explicit lock. The blocking client is using a file lock. The blocking client is using a page lock. The blocking client is using a record lock. If the conflict was a Page Lock, this flag indicates the conflict occurred on a data page. If the conflict was a Page Lock, this flag indicates the conflict occurred on a key page. If the conflict was a Page Lock, this flag indicates the conflict occurred on a variable page.

0x00000200

Key Page

0x00000400

Variable Page

2-132

Stat Extended (65)

Table 2-36 Lock Owner Flags

Value 0x00000800 Name Same Process Description If this flag is set, then the first 12 bytes of the blocking client ID are the same as the first 12 bytes of the client that got blocked, that is, the client that is issuing the Stat Extended call. In this case, it means that the two blocking clients came from the same process on the same computer. If you have a single threaded application making Btrieve API calls, then retrying this operation will not help. You need to complete or abort the work that is blocking. Indicates that the blocking client is using the 500 bias. Indicates that the blocking client made a change to a page that caused that client to keep the full page lock until its transaction completes. This situation can occur on implicit key page locks when a change causes key entries to move to another page. For explicit record locks, this flag indicates that the blocking client is using either lock bias 200 or 400. For explicit record locks, this flag indicates that the blocking client is using either lock bias 300 or 400.

0x00001000

Write No Wait Write Hold

0x00002000

0x00004000

Read No Wait Read Multiple

0x00008000

Result

If the Stat Extended operation is unsuccessful, the transactional interface returns one of the following status codes:
3 06 22 62 The file is not open. The key number parameter is invalid. The data buffer parameter is too short. The descriptor is incorrect.

2-133

Btrieve API Operations

Step First (33)

The Step First operation (B_STEP_FIRST) retrieves the first physical record of the file. The transactional interface does not use a key path to retrieve the record.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites Procedure

The file must be open.

Set the Operation Code to 33. Optionally, you can include a lock bias:

+100Single wait record lock. +200Single no-wait record lock. +300Multiple wait record lock. +400Multiple no-wait record lock.

For more information about locking, refer to the Pervasive PSQL Programmer's Guide.
2 3

Pass the Position Block for the file. Set the Data Buffer Length to a value greater than or equal to the length of the record to retrieve.

Result

If the Step First operation is successful, the transactional interface returns the files first physical record in the Data Buffer and sets the Data Buffer Length parameter to the number of bytes returned. If the Step First operation is unsuccessful, the transactional interface returns one of the following status codes:
3 The file is not open.

2-134

Step First (33)

9 22

The operation encountered the end-of-file. The data buffer parameter is too short.

Positioning

The Step First operation destroys logical currency. Step First sets the physical currency using the retrieved record as the physical current record. The previous physical position points beyond the beginning of the file.

2-135

Btrieve API Operations

Step Last (34)

The Step Last operation (B_STEP_LAST) retrieves the last physical record of the file. The transactional interface does not use a key path to retrieve the record.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites Procedure

The file must be open.

Set the Operation Code to 34. Optionally, you can include a lock bias:

+100Single wait record lock. +200Single no-wait record lock. +300Multiple wait record lock. +400Multiple no-wait record lock.

For more information about locking, refer to the Pervasive PSQL Programmer's Guide.
2 3

Pass the Position Block for the file. Set the Data Buffer Length to a value greater than or equal to the length of the record to retrieve.

Result

If the Step Last operation is successful, the transactional interface returns the files last physical record in the Data Buffer and sets the Data Buffer Length parameter to the number of bytes returned. If the Step Last operation is unsuccessful, the transactional interface may return one of the following status codes:
3 The file is not open.

2-136

Step Last (34)

9 22

The operation encountered the end-of-file. (when the file is empty) The data buffer parameter is too short.

Positioning

The Step Last operation destroys logical currency. Step Last sets the physical currency using the retrieved record as the current physical record. The next physical position points beyond the end of the file.

2-137

Btrieve API Operations

Step Next (24)

The Step Next operation (B_STEP_NEXT) retrieves the record to which the next physical position points. The transactional interface does not use a key path to retrieve the record. A Step Next operation issued immediately after any Get or Step operation returns the record physically following the record retrieved by the previous operation.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites Procedure

The file must be open.

Set the Operation Code to 24. Optionally, you can include a lock bias:

+100Single wait record lock. +200Single no-wait record lock. +300Multiple wait record lock. +400Multiple no-wait record lock.

For more information about locking, refer to the Pervasive PSQL Programmer's Guide.
2 3

Pass the Position Block for the file. Set the Data Buffer Length to a value greater than or equal to the length of the record to retrieve.

Result

If the Step Next operation is successful, the transactional interface returns the files next physical record in the Data Buffer and sets the Data Buffer Length parameter to the number of bytes returned.

2-138

Step Next (24)

If the Step Next operation is unsuccessful, the transactional interface returns one of the following status codes:
3 9 22 The file is not open. The operation encountered the end-of-file. The data buffer parameter is too short.

Positioning

The Step Next operation does not establish logical currency. Step Next sets the physical currency using the retrieved record as the physical current record. If a Step Next operation is issued immediately following a Delete operation (4), Step Next returns the record that was established as the next physical record by the operation preceding the Delete. If a Step Next operation is issued immediately after an Open operation (0), Step Next returns the first record in the file.

2-139

Btrieve API Operations

Step Next Extended (38)

The Step Next Extended operation (B_STEP_NEXT_EXT) examines one or more records, starting at the next physical position and proceeding toward the end of the file. It checks to see if the examined record or records satisfy a filtering condition, and it retrieves the ones that do. The filtering condition is a logic expression and is not limited to key fields only. Step Next Extended can also extract specified fields from existing records and return a new set of records that contain only the extracted fields.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites

The file must be open. You must have established a next physical position. (For example, a Step Next Extended operation cannot follow a Delete operation.) Set the Operation Code to 38. Optionally, you can include a lock bias:

Procedure

+100Single wait record lock. +200Single no-wait record lock. +300Multiple wait record lock. +400Multiple no-wait record lock.

For more information about locking, refer to the Pervasive PSQL Programmer's Guide.
2

Pass the Position Block for the file.

2-140

Step Next Extended (38)

Specify a Data Buffer large enough to accommodate either the input data buffer or the returned data buffer, whichever is larger. Initialize the Data Buffer according to the structure shown in Table 2-14 on page -82. Specify the Data Buffer Length from the preceding step. The transactional interface sets up a buffer as a workspace for extended operations. You configure the size of this buffer using the Extended Operation Buffer Size option. The sum of the Data Buffer structure, plus the longest record to be retrieved, plus 355 bytes of requester overhead, cannot exceed the configured buffer size. (Requester overhead is not applicable in DOS workstation engines.)

Details

The Step Next Extended operation shares the same Details as the Get Next Extended operation. Refer to Details for more information. If the Step Next Extended operation is successful, the transactional interface returns one or more fields from one or more records to the Data Buffer (as shown in Table 2-15). The transactional interface also sets the Data Buffer Length parameter to the number of bytes it returned to the Data Buffer. If the Step Next Extended operation is unsuccessful, the transactional interface returns one of the following status codes:
3 9 22 60 61 62 64 65 82 134 The file is not open. The operation encountered the end-of-file. The data buffer parameter is too short. The specified reject count has been reached. The work space is too small. The descriptor is incorrect. The filter limit has been reached. The field offset is incorrect. The transactional interface lost positioning. The transactional interface cannot read the International Sorting Rule.

Result

2-141

Btrieve API Operations

135

The specified International Sort Rule table is corrupt or otherwise invalid. The transactional interface cannot find the specified Alternate Collating Sequence in the file.

136

It is possible for the transactional interface to return a nonzero status code and also return valid data in the Data Buffer. In this case, the last record returned may be incomplete. If the Data Buffer Length parameter returned is greater than 0, check the Data Buffer for extracted data. If a field can only be partially filled because the record is too short, then the transactional interface returns what it can of the record to and including the partial field. If the partial field is the last field to be extracted, then the transactional interface continues the operation. Otherwise, the transactional interface aborts the operation and returns a Status Code 22. For example, consider a Step Next Extended operation that retrieves three fields from two variable-length records. The first record is 55 bytes long, and the second is 50 bytes. The fields to be retrieved are defined as follows:

Field 1 begins at offset 2 and is 2 bytes long. Field 2 begins at offset 45 and is 10 bytes long. Field 3 begins at offset 6 and is 2 bytes long.

When the transactional interface performs the Step Next Extended operation, it returns the first record without any problem. However, when attempting to extract 10 bytes from field 2 of the second record, the transactional interface finds that only 5 bytes are available (between offset 45 and the end of the record, at offset 49). At this point, the transactional interface does not pad the missing 5 bytes of field 2, and thus cannot extract field 3. Instead, the transactional interface returns Status Code 22 and places all of field 1 and first 5 bytes of field 2 in the return Data Buffer.

Positioning

The Step Next Extended operation does not establish any logical currency, but the last record examined (not necessarily retrieved) becomes the current physical record. This record can be either a record that satisfies the filtering condition and is retrieved, or a record that does not satisfy the filtering condition and is rejected.

2-142

Step Next Extended (38)

Note The transactional interface does not allow Delete or

Update operations after a Step Next Extended operation. Because the current record is the last record examined, there is no way to ensure that your application would delete or update the intended record.

2-143

Btrieve API Operations

Step Previous (35)

The Step Previous operation (B_STEP_PREVIOUS) retrieves the record to which the previous physical position points. The transactional interface does not use an index path to retrieve a record for a Step Previous operation. A Step Previous operation performed immediately after any Get or Step operation returns the record physically preceding the record that the previous operation retrieves.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites

The file must be open. You must have an established previous physical position. (For example, a Step Previous cannot follow a Delete operation.) Set the Operation Code to 35. Optionally, you can include a lock bias:

Procedure

+100Single wait record lock. +200Single no-wait record lock. +300Multiple wait record lock. +400Multiple no-wait record lock.

For more information about locking, refer to the Pervasive PSQL Programmer's Guide.
2 3

Pass the Position Block for the file. Set the Data Buffer Length to a value greater than or equal to the length of the record to retrieve.

Result

If the operation is successful, the transactional interface returns the previous physical record in the Data Buffer and sets the Data Buffer Length parameter to the number of bytes returned.

2-144

Step Previous (35)

If the operation is unsuccessful, the transactional interface returns one of the following status codes:
3 9 22 The file is not open. The operation encountered the end-of-file. (at the beginning of the file) The data buffer parameter is too short.

Positioning

The Step Previous operation does not establish logical currency. Step Previous sets the physical currency using the retrieved record as the physical current record.

2-145

Btrieve API Operations

Step Previous Extended (39)

The Step Previous Extended operation (B_STEP_PREVIOUS_EXT) examines one or more records, starting at the previous physical position and proceeding toward the beginning of the file. It checks to see if the examined record or records satisfy a filtering condition, and it retrieves the ones that do. The filtering condition is a logic expression and is not limited to key fields only. Step Previous Extended can also extract specified fields from existing records and return a new set of records that contain only the extracted fields.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites

The file must be open. You must have established a previous physical position. (For example, a Step Previous Extended operation cannot follow a Delete operation.) Set the Operation Code to 39. Optionally, you can include a lock bias:

Procedure

+100Single wait record lock. +200Single no-wait record lock. +300Multiple wait record lock. +400Multiple no-wait record lock.

For more information about locking, refer to the Pervasive PSQL Programmer's Guide.
2

Pass the Position Block for the file.

2-146

Step Previous Extended (39)

Specify a Data Buffer large enough to accommodate either the input data buffer or the returned data buffer. Initialize the Data Buffer according to the structure shown in Table 2-14 on page -82. Specify the Data Buffer Length from the preceding step. The transactional interface sets up a buffer as a workspace for extended operations. You configure the size of this buffer using the Extended Operation Buffer Size option. The sum of the Data Buffer structure, plus the longest record to be retrieved, plus 355 bytes of requester overhead, cannot exceed the configured buffer size. (Requester overhead is not applicable in DOS workstation engines.)

Details

This operation uses the same input and returned Data Buffers as the Get Next Extended operation. Refer to Details for more information. This operation returns the same results as the Step Next Extended operation. Refer to Result for more information. The Step Previous Extended operation does not establish logical currency, but the last record examined (not necessarily retrieved) becomes the current physical record. This record can be either a record that satisfies the filtering condition and is retrieved, or a record that does not satisfy the filtering condition and is rejected.
Note The transactional interface does not allow Delete or

Result Positioning

Update operations after a Step Previous Extended operation. Because the current record is the last record examined, there is no way to ensure that your application would delete or update the intended record.

2-147

Btrieve API Operations

Stop (25)
The Stop operation (B_STOP) performs a number of termination routines for the client, such as releasing all locks and closing all open files associated with that client.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Procedure Result

Set the Operation Code to 25. If the Stop operation is successful, the transactional interface performs the following actions:
1 2 3 4

Aborts any active transactions. Releases all locks held by the client. Closes all files open for the client. If no other clients (other applications registered with the transactional interface) exist and depending on the transactional interface configuration, the transactional interface may terminate itself and free a number of resources.

If the Stop operation is unsuccessful, the transactional interface returns a nonzero status code. The most common nonzero Status Code is 20 (Record Manager Inactive). This status occurs because the transactional interface or the Requester is not loaded.

Positioning

The Stop operation destroys all currencies because it closes any open files.

2-148

Unlock (27)

Unlock (27)
The Unlock operation (B_UNLOCK) unlocks one or more records that have been locked explicitly (that is, the records were locked using a lock bias of +100, +200, +300, or +400). The Unlock operation releases locks held by the specified position block; therefore, if you have the same file opened more than once, you must issue an Unlock for each position block before the record is completely unlocked. Similarly, each client that holds a lock on records in the file must issue an Unlock before the record is completely unlocked.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites Procedure

You must have at least one record lock.

To unlock a single-record lock, follow these steps:

1 2 3

Set the Operation Code to 27. Pass the Position Block for the file that contains the locked record. Set the Key Number to a non-negative value. first retrieve the 4-byte position of the record to unlock by issuing a Get Position operation (22) for that record. Then, issue the Unlock operation as follows:

To unlock a record locked by a multiple-record lock,

1 2 3

Set the Operation Code to 27. Pass the Position Block for the file that contains the locked record. Store (in the Data Buffer) the 4-byte position that the transactional interface returns.

2-149

Btrieve API Operations

4 5

Set the Data Buffer Length to 4. Set the Key Number parameter to 1. these steps:

To unlock all the multiple record locks on a file, follow

1 2 3

Set the Operation Code to 27. Pass the Position Block for the file that contains the multiple locks. Set the Key Number parameter to 2.

Result

If the Unlock operation is successful, the transactional interface releases all the locks that the operation specified. If the Unlock operation is unsuccessful, the transactional interface returns a nonzero status codemost likely, Status Code 81.

Positioning

The Unlock operation has no effect on positioning.

2-150

Update (3)

Update (3)
The Update operation (B_UPDATE) changes the information in an existing record.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Note When using the no-currency-change (NCC) option, the

Update operation does not update the value of the Key Buffer parameter; it does not return any information in that parameter.

Prerequisites

The file must be open. You must have established physical currency in the file. (Although an Extended Get, Extended Step, or Get Key operation establishes the required position, these operations cannot be followed by an Update.) Set the Operation Code to 3. Pass the Position Block for the file containing the record. Store the updated data record in the Data Buffer. Set the Data Buffer Length to the length of the updated record. Set the Key Number used for retrieving the record. To use the NCC option, specify 1 (0xFF) for the Key Number. To use the system-defined log key (also called system data), specify 125. When performing a non-NCC Update operation immediately following a Get operation, pass the Key Number exactly as the transactional interface returned it on the Get operation; otherwise, the transactional interface updates the record successfully but returns Status Code 7 on the first Get operation performed after the update.

Procedure

1 2 3 4 5

2-151

Btrieve API Operations

Result

If the Update operation is successful, the transactional interface updates the record stored in the file with the new value in the Data Buffer, adjusts the indexes to reflect any change in the key values, and returns the value of the specified key in the Key Buffer. An NCC Update operation does not update the value of the Key Buffer parameter. If the application holds a single-record lock on the record to be updated, the transactional interface releases the lock. However, a multiple-record lock is never released by an Update operation. If the Update operation is unsuccessful, the transactional interface returns one of the following status codes:
5 8 10 22 80 The record has a key field containing a duplicate key value. The current positioning is invalid. The key field is not modifiable. The data buffer parameter is too short. The transactional interface encountered a record-level conflict.

Positioning

The Update operation and the NCC Update operation do not affect physical currency. An Update operation that does not use the NCC option can affect logical currency if the value of the updated key repositions the record in the index. For example, suppose an INTEGER keys logical current record has a value of 1. For that same key, the logical next record has a value of 2. If you update 1 to 4, you no longer have the same logical next record. In this example, after the Update operation, the logical next record has a value that is greater than 4. An NCC Update operation does not affect logical currency. This means that an application, having performed an NCC Update operation, has the same logical position in the file as it had prior to the Update operation. In such a situation, operations that follow an NCC Updatesuch as Get Next (6), Get Next Extended (36), Get Previous (7), and Get Previous Extended (37)return values based on the applications logical currency prior to the NCC Update.

2-152

Update (3)

Note The transactional interface does not return any

information in the Key Buffer parameter as the result of an NCC Update operation. Therefore, an application that must maintain the logical currency must not change the value of the Key Buffer following the NCC Update operation. Otherwise, the next Get operation has unpredictable results.

2-153

Btrieve API Operations

Update Chunk (53)

The Update Chunk operation (B_CHUNK_UPDATE) can change the information in one or more portions of a record (each portion being a chunk). It can also append information to an existing record (thereby lengthening the record), or truncate an existing record at a specified offset.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites

The file must be open. You must have an established current physical or logical record in the file.
Note Although an extended operation or a Get Key operation

(+50) establishes the required position, you cannot issue an Update Chunk operation immediately after these operations, because they do not return a single record.

Procedure

Set the Operation Code to 53. Optionally, you can include a lock bias:

+100Single wait record lock. +200Single no-wait record lock. +300Multiple wait record lock. +400Multiple no-wait record lock.

For more information about locking, refer to the Pervasive PSQL Programmer's Guide.
2 3

Pass the Position Block for the file containing the record. Specify a Data Buffer, as described in Details.

2-154

Update Chunk (53)

Set the Data Buffer Length to a value greater than or equal to the number of bytes your application has placed in the Data Buffer. See the Details section for more information about calculating the Data Buffer Length. Set the Key Number used for retrieving the record in the Key Number parameter. To use the system-defined log key (also called system data), specify 125.

Details

Use one of the following chunk descriptors in the Data Buffer:

Random Chunk DescriptorTo update a single chunk per operation, or to update more than one chunk in a single operation when the chunks are spaced randomly throughout the record. Rectangle Chunk DescriptorTo update many chunks in an operation, when each chunk is the same length and chunks are spaced equidistantly in the record. Truncate Chunk DescriptorTo truncate a record at a specified offset.

Random Chunk Descriptor Structure The following example shows a record with three randomly spaced chunks (areas containing [*]): chunk 0 (bytes 0x12 through 0x16), chunk 1 (bytes 0x2A through 0x31), and chunk 2 (bytes 0x41 through 0x4E).
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F

[*]

2-155

Btrieve API Operations

To define a random chunk descriptor, your application must create a structure in the Data Buffer, based on the following table.
Table 2-37 Random Chunk Descriptor Structure
Element Length (Bytes) 4 Description

Subfunction

Type of chunk descriptor; one of the following:

0x80000000 (Direct random chunk descriptor)

Updates chunks stored directly in the Data Buffer. The data for updating the first chunk is stored in the Data Buffer immediately after the last chunk definition (Chunk n), the data for the second chunk immediately follows the first, and so on.
0x80000001 (Indirect random chunk descriptor)

Updates chunks from data at addresses specified by the Chunk Definitions. NumChunks 4 Number of chunks to be updated. The value must be at least 1. Although no explicit maximum value exists, the chunk definitions must fit in the Data Buffer, which is limited in size as described in Table 2-11. Each Chunk Definition is a 4-byte Chunk Offset, followed by a 4-byte Chunk Length, followed by a 4byte User Data, described as follows:
Chunk OffsetIndicates where the chunk begins

Chunk Definition (Repeat for each chunk)

as an offset in bytes from the beginning of the record. The minimum value is 0, and the maximum value is the offset of the last byte in the record, plus 1.
Chunk LengthIndicates how many bytes are in

the chunk. The minimum value is 0, and the maximum value 65,535; however, the chunk definitions must fit in the Data Buffer, which is limited in size as described in Table 2-11.
User Data(Used only for indirect descriptors.) A

2-156

Update Chunk (53)

The following table shows a sample direct random chunk descriptor structure.
Element Subfunction NumChunks Chunk 0 Chunk Offset Chunk Length User Data Chunk 1 Chunk Offset Chunk Length User Data Chunk 2 Chunk Offset Chunk Length User Data Data for Chunk 0 Data for Chunk 1 Data for Chunk 2 0x41 0x0E N/A N/A N/A N/A 4 4 4 5 8 14 0x2A 0x08 N/A 4 4 4 0x12 0x05 N/A 4 4 4 Sample Value 0x8000000 3 Length (in Bytes) 4 4

Rectangle Chunk Descriptor Structure When chunks of the same length are spaced equidistantly throughout a record, you can describe all the chunks to update with a rectangle chunk descriptor. For example, consider the following diagram, which represents offset 0x00 through 0x4F in a record:
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F

[*]

2-157

Btrieve API Operations

20 21 22 23 24 25 26 27 28 [*] [*] [*] [*] 2D 2E 2F

[*]

The record contains three chunks (areas containing [*]): chunk 0 (bytes 0x19 through 0x1C), chunk 1 (bytes 0x29 through 0x2C), and chunk 2 (bytes 0x39 through 0x3C). Each chunk is four bytes long, and a total of 16 (0x10) bytes, calculated from the beginning of each chunk, separates the chunks from one another. You can update all three chunks using a single rectangle descriptor. To update rectangle chunks, you must create a structure in the Data Buffer based on Table 2-38 on page 2-153.
Table 2-38 Rectangle Chunk Descriptor Structure
Element Length (Bytes) 4 Description

Subfunction

Type of chunk descriptor; one of the following:

0x80000002 (Direct rectangle chunk descriptor)

Updates chunks from data at addresses specified by the Chunk Definitions. Number of Rows 4 Number of chunks on which the rectangle chunk descriptor must operate. The minimum value is 1. No explicit maximum value exists. Offset from the beginning of the record of the first byte to update. The minimum value is 0, and the maximum value is the offset of the last byte in the record, plus 1. If the record is viewed as a rectangle, this element refers to the offset of the first byte in the first row to be retrieved. Number of bytes in each chunk to be updated. The minimum value is 0, and the maximum value is 65,535; however, the chunk definitions must fit in the Data Buffer, which is limited in size as described in Table 2-11.

Offset

Bytes Per Row

2-158

Update Chunk (53)

Table 2-38 Rectangle Chunk Descriptor Structure

Element Length (Bytes) 4 Description

Distance Between Rows User Data

Number of bytes between the beginning of each chunk.

(Used only with indirect descriptors.) A 32-bit pointer to the actual chunk data. The format you should use depends on your operating system.1 The transactional interface ignores this element for direct rectangle descriptors; however, you must still allocate the element and initialize it to 0. (Used only with indirect rectangle descriptors.) Number of bytes between the beginning of chunks in the rectangle, as the rectangle is stored in your applications memory, at the address specified by User Data. The transactional interface ignores this element for direct rectangle descriptors; however, you must still allocate the element and initialize it to 0.

Application Distance Between Rows

1For

16-bit applications, express User Data as a 16-bit offset followed by a 16-bit segment.

If the rectangle has the same number of bytes between rows when it is in memory as when it is stored as a record, set Application Distance Between Rows with the same value as Distance Between Rows. However, if the rectangle is arranged in your applications memory with either more or fewer bytes between rows, Application Distance Between Rows allows you to pass that information to the transactional interface. When you use an indirect rectangle descriptor, the transactional interface uses both the User Data and the Application Distance Between Rows elements to determine the locations from which to read the data for the update. The transactional interface reads data for the first row from offset 0 of User Data. The transactional interface reads the second rows data from an address specified by User Data plus Application Distance Between Rows. The transactional interface reads the third rows data from the address specified by User Data plus (Application Distance Between Rows * 2), and so on.

2-159

Btrieve API Operations

The following table shows a sample direct rectangle chunk descriptor structure.
Element Name Sample Value Length (in Bytes) 4 4 4 4 4 4 4 4 4 4

Subfunction Number of Rows Offset Bytes Per Row Distance Between Rows User Data Application Distance Between Rows Data (Row 0) Data (Row 1) Data (Row 2)

0x80000002 3 0x19 0x04 0x10 0 0 N/A N/A N/A

Truncate Descriptor Structure The truncate descriptor allows you to truncate a record at a specified offset. To use this type of chunk descriptor, you must create a structure in the Data Buffer, based on the following table:
Table 2-39 Truncate Descriptor Structure
Element Length (in Bytes) 4 4 Description

Subfunction ChunkOffset

Type of chunk descriptor. Specify 0x80000004. Byte offset into the record where truncation begins. That byte and every byte following it is eliminated. The minimum value is 4. The maximum value is the offset of the final byte in the record.

2-160

Update Chunk (53)

Next-in-Record subfunction, the transactional interface ignores the Offset element in the chunk descriptor. If you use this bias in combination with a random chunk descriptor and it updates more than one chunk in a single operation, the transactional interface calculates the offset for all chunks (except the first) by adding the previous chunks length to the previous chunks offset. In other words, the next-in-record bias applies to all chunks in the operation. Append Subfunction Bias If you add a bias of 0x20000000 to the random chunk descriptors subfunction or to the rectangle chunk descriptors subfunction, the transactional interface calculates the subfunctions Offset element value to be one byte beyond the end of the record.
Note Do not use this bias with the Next-in-Record bias or the

Truncate subfunction. If you use this bias in combination with a random chunk descriptor and it updates more than one chunk in a single operation, the transactional interface calculates the offset for all chunks (except the first chunk) based on the records length after the transactional interface appends the previous chunk.

Result

If the Update Chunk operation is successful, the transactional interface updates the portions of the record identified as chunks in the chunk descriptor portion of the Data Buffer. The new data for updating the chunks is contained either in the chunk descriptor itself (for direct chunk descriptor subfunctions) or in the memory address specified by the 32-bit pointer in each chunks User Data element (for indirect chunk descriptor subfunctions). After the Update Chunk operation completes, the transactional interface adjusts the key indexes to reflect any change in the key values, and, if necessary, updates the Key Buffer parameter. In addition, if the application holds a single-record lock on the record to be updated, the transactional interface releases the lock. However, a multiple-record lock is never released by an Update Chunk operation.

2-161

Btrieve API Operations

If the Update Chunk operation is unsuccessful, the transactional interface returns one of the following status codes:
5 8 10 22 58 62 80 97 103 106 The record has a key field containing a duplicate key value. The current positioning is invalid. The key field is not modifiable. The data buffer parameter is too short. The compression buffer length is too short. The descriptor is incorrect. The transactional interface encountered a record-level conflict. The data buffer is too small. The chunk offset is too big. The transactional interface cannot perform a Get Next Chunk operation.

Positioning

The Update Chunk operation does not change the physical currency or the current logical record.
Note When you perform an Update Chunk operation following

a Get operation, do not pass to the Update Chunk operation a Key Number that differs from the one specified in the preceding Get operation. If you do, the positioning established by the transactional interface is unpredictable.

2-162

Version (26)

Version (26)
For client applications, the Version operation (B_VERSION) returns the local transactional interface version and the Requester version, if applicable. If a client application opens a file on a server or specifies a server file path name in the Key Buffer, the Version operation also returns the transactional interface version on that server. For serverbased applications, the Version operation returns the server-based transactional interface version and revision numbers.

Parameters
Op Code Pos Block Data Buf Data Buf Len Key Buffer Key Number

Sent Returned

Prerequisites Procedure

Either the transactional interface or the Requester must be loaded before you can issue a Version operation.
1 2 3

Set the Operation Code to 26. Set the Data Buffer Length to at least 15. (For more information, see Table 2-40.) To retrieve the version number of a server-based transactional interface, you must specify either a valid Position Block for an opened file on that server or a valid pathname in the Key Buffer.

Result

If you have both a workstation transactional interface and client Requester configured for access and the Version operation is successful, the operation returns the version information for the workstation transactional interface, the client Requester, and the server-based transactional interface. Specify a 15-byte Data Buffer and Data Buffer Length. If both the client Requester and the workstation transactional interface are loaded and you specify only a 5-byte Data Buffer and Data Buffer Length, the operation returns only the client Requesters version information.

2-163

Btrieve API Operations

If you specify only a 10-byte Data Buffer and Data Buffer Length, the operation returns the client Requester and the local workstation engine. If you specify a 15-byte Data Buffer and Data Buffer Length, the operation returns the client Requester, the local workstation engine, and the server engine (if applicable). In the Data Buffer, the Version operation returns a 5-byte Version Block for each transactional interface or Requester, according to the format shown in Table 2-40. The fifth byte of each block identifies each transactional interface or Requester.
Table 2-40 Version Block
Element Length (Bytes) 2 2 1 Description

Version Number Revision Number Requester or Engine Type

Pervasive PSQL version number. Pervasive PSQL revision number. Type of engine or requester; one of the following:
9 (0x39) for 32-bit Windows workstation/

workgroup engine or Linux server using Workgroup authentication mode

D (0x44) for DOS workstation N (0x4E) for client Requester S (0x53) for NetWare server T (0x54) for 32-bit Windows server engine U (0x55) for Linux server using PAM or

BTPASSWD authentication

For example, if you are running Pervasive.SQL v8.10 for Windows, the Version operation returns the following hexadecimal values in the Data Buffer:
08 00 0A 00 54

After converting these values to decimal, the version number is 8 and the revision number is 10. If the Version operation is unsuccessful, the transactional interface returns a nonzero status code.

Positioning

The Version operation has no effect on positioning.

2-164

Quick Reference of Btrieve Operations

Appen-

This appendix provides a summary of Btrieve API operations in numerical order by operation code

Table of Btrieve API Operations

.
Table A-1
Operation Open Close Insert Update Delete

Quick Reference of Btrieve API Operations

Code 0 1 2 3 4 Constant B_OPEN B_CLOSE B_INSERT B_UPDATE B_DELETE Description Makes a file available for access. Releases a file from availability. Inserts a new record into a file. Updates the current record. Removes the current record from the file. Returns the record whose key value matches the specified key value. Returns the record following the current record in the index path. Returns the record preceding the current record in the index path. Returns the record whose key value is greater than the specified key value. Returns the record whose key value is equal to or greater than the specified key value. Returns the record whose key value is less than the specified key value.

Get Equal

B_GET_EQUAL

Get Next

B_GET_NEXT

Get Previous

B_GET_PREVIOUS

Get Greater Than

B_GET_GT

Get Greater Than or Equal

B_GET_GE

Get Less Than

B_GET_LT

A-1

Quick Reference of Btrieve Operations

Table A-1
Operation

Quick Reference of Btrieve API Operations continued

Code 11 Constant B_GET_LE Description Returns the record whose key value is equal to or less than the specified key value. Returns the first record in the specified index path. Returns the last record in the specified index path. Creates a file with the specified characteristics. Returns file and index characteristics, and number of records. Divides a data file over two logical disk drives. This operation is not supported in Btrieve 6.0 and later. Changes the current directory. Returns the current directory. Marks the beginning of a set of logically related operations. Operation 19 begins an exclusive transaction. Operation 1019 begins a concurrent transaction. Marks the end of a set of logically related operations. Removes operations performed during an incomplete transaction.

Get Less Than or Equal

Get First

B_GET_FIRST

Get Last

B_GET_LAST

Create

B_CREATE

Stat

B_STAT

Extend

B_EXTEND

Set Directory Get Directory Begin Transaction

17 18 19 1019

B_SET_DIR B_GET_DIR B_BEGIN_TRAN

End Transaction

B_END_TRAN

Abort Transaction

B_ABORT_TRAN

A-2

Table A-1
Operation Get Position

Quick Reference of Btrieve API Operations continued

Code 22 Constant B_GET_POSITION Description Returns the position of the current record. Returns data from the specified portions (chunks) of a record at a specified position. Returns the record at a specified position. Returns the record from the physical location following the current record. Terminates the workstation transactional interface (not available for server-based transactional interfaces). Returns the version number of the transactional interface. Unlocks a record or records. Releases all resources held by a client. Assigns an owner name to a file. Removes an owner name from a file. Creates an index. Removes an index. Returns the record in the first physical location in the file. Returns the record in the last physical location in the file. Returns the record in the physical location preceding the current record. Returns one or more records that follow the current record in the index path. Filtering conditions can be applied. Returns one or more records that precede the current record in the index path. Filtering conditions can be applied.

Get Direct/Chunk

B_GET_DIRECT

Get Direct/Record

B_GET_DIRECT

Step Next

B_STEP_NEXT

Stop

B_STOP

Version

B_VERSION

Unlock Reset Set Owner Clear Owner Create Index Drop Index Step First

27 28 29 30 31 32 33

B_UNLOCK B_RESET B_SET_OWNER B_CLEAR_OWNER B_BUILD_INDEX B_DROP_INDEX B_STEP_FIRST

Step Last

B_STEP_LAST

Step Previous

B_STEP_PREVIOUS

Get Next Extended

B_GET_NEXT_EXTENDED

Get Previous Extended

B_GET_PREV_EXTENDED

A-3

Quick Reference of Btrieve Operations

Table A-1
Operation

Quick Reference of Btrieve API Operations continued

Code 38 Constant B_STEP_NEXT_EXT Description Returns one or more successive records from the location physically following the current record. Filtering conditions can be applied. Returns one or more preceding records from the location physically preceding the current record. Filtering conditions can be applied. Inserts one or more records into a file. Places the specified file in or removes the file from continuous operation mode, for use in system backups. This operation is available only to applications running on a local engine. Returns the record located approximately at a position derived from the specified percentage value. Returns a percentage figure based on the current records position in the file. Detects the presence of a key value in a file, without returning an actual record. Updates specified portions (chunks) of the current record. This operation can also append data to a record or truncate a record. Returns filenames and paths of an extended files components and reports whether a file is using a system-defined log key.

Step Next Extended

Step Previous Extended

B_STEP_PREVIOUS_EXT

Insert Extended Continuous Operation

40 42

B_EXT_INSERT B_CONTINUOUS

Get By Percentage

B_SEEK_PERCENT

Find Percentage

B_GET_PERCENT

Get Key

+50

KEY_BIAS

Update Chunk

B_CHUNK_UPDATE

Stat Extended

B_EXTENDED_STAT

A-4

Table A-1
Operation

Quick Reference of Btrieve API Operations continued

Code +100 Constant S_WAIT_LOCK Description Locks only one record at a time. If the record is already locked, the transactional interface retries the operation. Locks only one record at a time. If the record is already locked, the transactional interface returns an error status code. Locks several records concurrently in the same file. If the record is already locked, the transactional interface retries the operation. Locks several records concurrently in the same file. If the record is already locked, the transactional interface returns an error status code. In a concurrent transaction, tells the transactional interface not to wait if the page to be changed has already been changed by another active concurrent transaction. This bias can be combined with any of the record locking biases (+100, +200, +300, or +400).

Single-record wait lock

Single-record no-wait lock

+200

S_NOWAIT_LOCK

Multiple-record wait lock

+300

M_WAIT_LOCK

Multiple-record no-wait lock

+400

M_NOWAIT_LOCK

No-wait page lock

+500

NOWRITE_WAIT

A-5

Quick Reference of Btrieve Operations

A-6

Index
A
Abort Transaction operation 2-4 Accelerated file open mode 2-109, 2-110 ACS. See Alternate collating sequence. Adding index to an existing file 2-33 ALT constant 2-24 Alternate collating sequence Create operation and 2-25 creating keys that use 2-24 flag in Stat operation for 2-121 ISR 2-28 user-defined 2-27 AND and OR operations in filters 2-86 Ascending sort order 2-24 Attributes file 2-20 key 2-24 B_GET_LE 2-79 B_GET_LT 2-77 B_GET_NEXT 2-81 B_GET_NEXT_EXTENDED 2-83 B_GET_PERCENT 2-44 B_GET_POSITION 2-93 B_GET_PREV_EXTENDED 2-96 B_GET_PREVIOUS 2-94 B_INSERT 2-99 B_LOGIN 2-106 B_MISC_DATA 1-17 B_OPEN 2-108 B_RESET 2-113 B_SEEK_PERCENT 2-48 B_SET_DIR 2-114 B_SET_OWNER 2-115 B_STAT 2-117 B_STEP_FIRST 2-134 B_STEP_LAST 2-136 B_STEP_NEXT 2-138 B_STEP_NEXT_EXT 2-140 B_STEP_PREVIOUS 2-144 B_STEP_PREVIOUS_EXT 2-146 B_STOP 2-148 B_UNLOCK 2-149 B_UPDATE 2-151 B_VERSION 2-163 Balanced indexes 2-20 BALANCED_KEYS constant 2-20 Begin Transaction operation 2-5 BIN constant 2-24 Blank truncation 2-20 BLANK_TRUNC constant 2-20 BRQSHELLINIT function 1-3 BTRCALL function 1-3 BTRCALL32 function 1-3 BTRCALLBACK function 1-3 BTRCALLID function 1-3 BTRCALLID32 function 1-3 Btrieve function parameters 1-5 functions 1-2

B
B_ABORT_TRAN 2-4 B_BEGIN_TRAN 2-5 B_BUILD_INDEX 2-33 B_CHUNK_UPDATE 2-154 B_CLEAR_OWNER 2-7 B_CLOSE 2-8 B_CONTINUOUS 2-10 B_CREATE 2-15 B_DELETE 2-39 B_DROP_INDEX 2-41 B_END_TRAN 2-43 B_EXT_INSERT 2-102 B_EXTEND 1-17 B_EXTENDED_STAT 2-123 B_GET_DIR 2-64 B_GET_DIRECT 2-52, 2-61 B_GET_EQUAL 2-65 B_GET_FIRST 2-67 B_GET_GE 2-71 B_GET_GT 2-69 B_GET_LAST 2-75

Index 1

operations, using 2-1 unsupported features 1-16 BTRV function 1-2 BTRVID function 1-2 BTRVINIT function 1-3 BTRVSTOP function 1-3

C
Case-insensitive keys 2-24, 2-25 Chunk descriptors Get Direct/Chunk operation and 2-53 Update Chunk operation and 2-155 Clear Owner operation 2-7 Client transaction determining if open on file 2-129 ClientID parameter 1-10 Close operation 2-8 Compression, data 2-20 Continuous Operation operation 2-10 Continuous Operations and referential integrity 2-12 Continuous operations determining if file is in 2-129 Create Index operation 2-33 Create operation alternate collating sequence in 2-25 data buffer 2-28 description of 2-15 file specifications in 2-19 specifying file version 2-19

setting the current 2-114 Drop Index operation 2-41 DUP constant 2-24 DUP_PTRS constant 2-20 Duplicate keys 2-24 Duplicate pointers, reserved 2-20 Duplicate record conflict determining source of 2-127

E
embedded spaces 2-108 Encryption determining if file has 2-129 End Transaction operation 2-43 Exclusive file open mode 2-110 Explicit locks determining if on file 2-129 Extend operation (obsolete) A-2 Extended data types 2-24 Extended key types 2-26 Extension files names of, determining 2-124 number of, determining 2-124 EXTTYPE_KEY constant 2-24

F
File client transaction, determining if open 2-129 continuous operations, determining if file is in 2129 current number of handles, determining 2-128 determining if encrypted 2-129 determining transaction durability 2-125 explicit locks, determining if set 2-129 gateway engine determining name of 2-130 determining platform of 2-130 determining version of 2-130 owner name determining if opened with wrong 2-129 owner name, determining if set 2-129 read-only, determining if 2-129 referential integrity, determining if set 2-129 time last opened, determining 2-128 usage count, determining 2-128 File access operations 1-13

D
Data Buffer Length parameter 1-8 Data Buffer parameter 1-7 Data compression 2-20 Data encryption 2-115 Data manipulation operations 1-13 Data retrieval operations 1-13 DATA_COMP constant 2-20 Data-only files, creating 2-19 Delete operation 2-39 Deleting an index 2-41 DESC_KEY constant 2-24 Descending sort order 2-24 Directory returning the current 2-64

2 Index

File flags (attributes) 2-20 File information operations 1-13 File Open mode 2-109, 2-110, 2-112 File open modes 2-110 File specification block 2-19 File version specifying during Create operation 2-19 Files closing 2-8 creating 2-15 extension, see Extension files opening 2-108 statistics 2-117 File-specific operations 1-13 Filters for extended operations 2-85 Find Percentage operation 2-44 Flags file 2-20, 2-121 key 2-24 Free space threshold 2-20 FREE_10 constant 2-20 FREE_20 constant 2-20 FREE_30 constant 2-20 Functions Btrieve 1-2

Get Previous Extended operation 2-96 Get Previous operation 2-94 GetEqual NULL key segments and 2-66

H
Handles determining current number on file 2-128

I
Include system data 2-20 INCLUDE_SYSTEM_DATA constant 2-20 Indexes balanced 2-20 creating 2-33 dropping 2-41 rebuilding 2-41 Insert Extended operation 2-102 Insert operation 2-99 International Sort Rules 2-28

K
Key Buffer parameter 1-8 Key flags (attributes) 2-24 Key Length parameter 1-11 Key Number parameter 1-10 Key numbers, assigning 2-21, 2-27 Key specification blocks 2-22 Key values, finding specific 2-73 KEY_ONLY constant 2-20 Key-only files creating 2-20

G
Gateway engine determining name of 2-130 determining platform of 2-130 determining version of 2-130 Get By Percentage operation 2-48 Get Direct/Chunk operation 2-52 Get Direct/Record operation 2-61 Get Directory operation 2-64 Get Equal operation 2-65 Get First operation 2-67 Get Greater operation 2-69 Get Greater Than or Equal operation 2-71 Get Key operation 2-73 Get Last operation 2-75 Get Less Than operation 2-77 Get Less Than or Equal operation 2-79 Get Next Extended operation 2-83 Get Next operation 2-81 Get Position operation 2-93

L
Linked duplicate keys 2-24 Lock determining bias of 2-133 determining client ID of 2-131 determining duration of 2-131 determining if from transaction 2-131 determining if implicit or explicit 2-132 determining location of conflict 2-132 determining name of client 2-132 determining owner of 2-131

Index 3

determining source of on key page 2-131 determining whether page, record, or file 2-132 getting information about 2-131 Lock biases 1-16 Locks explicit determining if set 2-129

setting 2-115

P
Page preallocation 2-20 Pointers, reserved duplicate 2-20 Position Block parameter 1-7 PRE_ALLOC constant 2-20

M
Manipulation operations 1-13 MANUAL_KEY constant 2-24 MOD constant 2-24 Modifiable keys 2-24 Modification operations 1-13 Multiple record locks 2-149

R
Random chunk descriptors 2-53, 2-155 Read-only determining if file opened as 2-129 Read-only file open mode 2-110 Rebuilding a damaged index 2-41 Record, duplicate conflict determining source of 2-127 Records deleting 2-39 inserting 2-99 inserting multiple 2-102 updating 2-151 Rectangle chunk descriptors 2-56, 2-157 Referential integrity and continuous operations 2-12 determining if set on file 2-129 REPEAT_DUPS_KEY constant 2-24 Repeating duplicate keys 2-24 Requesters version, retrieving 2-163 Reserved duplicate pointers 2-20 Reset operation 2-113 Resources, releasing 2-113 Retrieval operations 1-13 records equal to the index path 2-65 first in physical location 2-134 first in the index path 2-67 Get By Percentage operation 2-48 Get Direct/Record operation and 2-61 getting one or more chunks of a record 2-52 greater than or equal to the index path 2-71 greater than the index path 2-69 last in physical location 2-136 last in the index path 2-75 less than or equal to the index path 2-79 less than the index path 2-77

N
NAMED_ACS constant 2-24 Next-in-record subfunction bias 2-59, 2-160 NO_INCLUDE_SYSTEM_DATA constant 2-21 NOCASE_KEY constant 2-24 No-currency-change Insert Extended operation and 2-102 Insert operation and 2-99 Update operation and 2-151 Normal file open mode 2-110 NUL constant 2-24 NULL key segments GetEqual and 2-66 Null keys 2-24 NUMBERED_ACS constant 2-24

O
Obsolete functions 1-3 Open modes 2-110 operation 2-108 Open mode 2-109, 2-110, 2-112 Operation Code parameter 1-5 Operations, using in applications 2-1 Owner name clearing 2-7 determining if file opened with wrong 2-129 determining if set on file 2-129 Owner names

4 Index

next in physical location 2-138, 2-140 next in the index path 2-81, 2-83 previous in physical location 2-144, 2-146 previous in the index path 2-94, 2-96 using established physical location 2-93 RQSHELLINIT function 1-3

Transaction durability determining for file 2-125 Truncate chunk descriptors 2-160

U
Undocumented features 1-16 Unlock operation 2-149 Unsupported features 1-16 Update Chunk operation 2-154 Update operation 2-151 Usage count of file, determining 2-128 Use VATs 2-21 User-defined ACSs 2-27

S
Scroll bars 2-48 SEG constant 2-24 Segmented keys 2-24 Server engine version, retrieving 2-163 Session-specific operations 1-12 Set Directory operation 2-114 Set Owner operation 2-115 Single record locks 2-149 Sort order keys 2-24 SPECIFY_KEY_NUMS constant 2-21 Standard data types 2-24 Stat Extended operation 2-123 Stat operation 2-117 Status Code causes of status code 5 2-127 causes of status code 85 2-131 determining cause of 86 2-131 parameter 1-6 Step operations Step First operation 2-134 Step Last operation 2-136 Step Next Extended operation 2-140 Step Next operation 2-138 Step Previous Extended operation 2-146 Step Previous operation 2-144 Stop operation 2-148 System data 2-20 determining if file has system log key 2-125

V
VAR_RECS constant 2-20 Variable-length records and Extended operations 2-89 flag 2-20 Variable-tail Allocation Tables (VATs) 2-21 VATS_SUPPORT constant 2-21 Verify file open mode 2-110 Version specifying during Create operation 2-19 Version operation 2-163

W
WBRQSHELLINIT function 1-3 WBTRVINIT function 1-3 WBTRVSTOP function 1-3 Workstation engine version, retrieving 2-163 Wrong owner name determining if file opened with 2-129

T
Transaction aborting 2-4 beginning 2-5 client, determining if open 2-129 ending 2-43 log key determining key number 2-125

Index 5

6 Index

Etland - : Harold. Charles Van Engen
No ratings yet
Etland - : Harold. Charles Van Engen
1,078 pages
Dev Guide
100% (3)
Dev Guide
195 pages
Progress Programming Handbook
No ratings yet
Progress Programming Handbook
1,024 pages
Bridge Inisght
No ratings yet
Bridge Inisght
227 pages
Web Designer: TSX ETG 3000 Product Range User Manual
No ratings yet
Web Designer: TSX ETG 3000 Product Range User Manual
310 pages
Metastock Developer Kit
100% (1)
Metastock Developer Kit
152 pages
Audio, Video, and Media in the Ministry
From Everand
Audio, Video, and Media in the Ministry
Clarence Floyd Richmond
No ratings yet
ProCash NDC V2000 ProConsult NDC V2000 UserGuide en
No ratings yet
ProCash NDC V2000 ProConsult NDC V2000 UserGuide en
420 pages
Fa Batch
100% (1)
Fa Batch
190 pages
Asynchronous Apex API
No ratings yet
Asynchronous Apex API
118 pages
MSDK 9.1 Read - DISK PDF
No ratings yet
MSDK 9.1 Read - DISK PDF
152 pages
UMData Acq
No ratings yet
UMData Acq
196 pages
TcSE Release 10.1 API Reference PDF
No ratings yet
TcSE Release 10.1 API Reference PDF
212 pages
Bulk API Developer Guide: Version 44.0, Winter '19
No ratings yet
Bulk API Developer Guide: Version 44.0, Winter '19
119 pages
Parameter Guide
No ratings yet
Parameter Guide
584 pages
Control M PDF
No ratings yet
Control M PDF
608 pages
528226-001M Instant ID Developer's Guide
No ratings yet
528226-001M Instant ID Developer's Guide
48 pages
Guide BRF+ PDF
60% (5)
Guide BRF+ PDF
274 pages
Progress Client Deployment Guide
No ratings yet
Progress Client Deployment Guide
206 pages
Verifone Integration Package 37
No ratings yet
Verifone Integration Package 37
413 pages
Mfgpro Manager Functions
No ratings yet
Mfgpro Manager Functions
214 pages
Gray Hat Hacking the Ethical Hacker's
From Everand
Gray Hat Hacking the Ethical Hacker's
Çağatay Şanlı
5/5 (1)
Guia Oficial Matisse Java
No ratings yet
Guia Oficial Matisse Java
65 pages
Query Reference Manual
100% (1)
Query Reference Manual
35 pages
F001681E
No ratings yet
F001681E
224 pages
victoryextract_users1
No ratings yet
victoryextract_users1
147 pages
Software Patterns Made Easy
From Everand
Software Patterns Made Easy
Justice Nanhou
No ratings yet
OpenScape Business V1, Accounting Manager, User Guide, Issue 1 PDF
No ratings yet
OpenScape Business V1, Accounting Manager, User Guide, Issue 1 PDF
29 pages
SQL Engine Reference
No ratings yet
SQL Engine Reference
608 pages
CONTROL-M Parameter Guide
No ratings yet
CONTROL-M Parameter Guide
584 pages
SAP Predictive Service User Guide
No ratings yet
SAP Predictive Service User Guide
174 pages
PC 81 TransformationGuide
No ratings yet
PC 81 TransformationGuide
552 pages
Firebird IB ApiGuide
No ratings yet
Firebird IB ApiGuide
442 pages
Fileaid Batch Reference
No ratings yet
Fileaid Batch Reference
176 pages
Rexx
No ratings yet
Rexx
572 pages
ROSCOE - B001673e - Programs and Utilities Guide
No ratings yet
ROSCOE - B001673e - Programs and Utilities Guide
326 pages
Manual Informix 10
No ratings yet
Manual Informix 10
193 pages
Tib Iprocess Server Objects Java Programmers Guide
No ratings yet
Tib Iprocess Server Objects Java Programmers Guide
333 pages
Api Rest
No ratings yet
Api Rest
363 pages
Database Link User Guide
No ratings yet
Database Link User Guide
122 pages
Control M Userguide
No ratings yet
Control M Userguide
190 pages
Xpedref (Expediter Manual)
No ratings yet
Xpedref (Expediter Manual)
228 pages
Xpediter/Tso and Xpediter/Ims Reference Manual: Release 7.2
No ratings yet
Xpediter/Tso and Xpediter/Ims Reference Manual: Release 7.2
228 pages
System API Programming
100% (1)
System API Programming
505 pages
Firmware Specification: Edition November 2018 EPOS4 Positioning Controllers Firmware Specification Maxon Motor Control
No ratings yet
Firmware Specification: Edition November 2018 EPOS4 Positioning Controllers Firmware Specification Maxon Motor Control
278 pages
CONTROL-M Job Parameter and Variable Reference Guide 20091008
No ratings yet
CONTROL-M Job Parameter and Variable Reference Guide 20091008
542 pages
SysAdmin AG v2015EE
No ratings yet
SysAdmin AG v2015EE
310 pages
Programmers Manual
No ratings yet
Programmers Manual
157 pages
Api Rest
No ratings yet
Api Rest
354 pages
Api Rest
100% (1)
Api Rest
346 pages
Networkadvisor 1401 Rest API
No ratings yet
Networkadvisor 1401 Rest API
200 pages
Procash/Ndc V3.0/00 Proconsult/Ndc V3.0/00: User Guide
No ratings yet
Procash/Ndc V3.0/00 Proconsult/Ndc V3.0/00: User Guide
438 pages
RV Cobol
No ratings yet
RV Cobol
386 pages
AMBA Transactors User and Reference Guide: Product Version 5.4 May 2005
No ratings yet
AMBA Transactors User and Reference Guide: Product Version 5.4 May 2005
170 pages
Certification Study Guide Series IBM Tivoli Application Dependency Discovery Manager V7.1 Sg247764
No ratings yet
Certification Study Guide Series IBM Tivoli Application Dependency Discovery Manager V7.1 Sg247764
224 pages
0511 Proghand PDF
No ratings yet
0511 Proghand PDF
1,024 pages
Progress
No ratings yet
Progress
1,024 pages
01 Why Latin A Dead Language - Editorial
No ratings yet
01 Why Latin A Dead Language - Editorial
1 page
Ramya Resume
No ratings yet
Ramya Resume
4 pages
THE Project Gutenberg Bible, King James, Book 20: Proverbs
No ratings yet
THE Project Gutenberg Bible, King James, Book 20: Proverbs
62 pages
De Thi Hoc Ki 2 Lop 10 Mon Tieng Anh Co File Nghe Nam Hoc 2018 2019 So 1
No ratings yet
De Thi Hoc Ki 2 Lop 10 Mon Tieng Anh Co File Nghe Nam Hoc 2018 2019 So 1
8 pages
Rubric On Acting
100% (2)
Rubric On Acting
2 pages
CELTA Pre Interview Task 1
No ratings yet
CELTA Pre Interview Task 1
6 pages
DAY 3 Passage and Questions
100% (1)
DAY 3 Passage and Questions
4 pages
B2 Practice Tests: Test Preparation Answer Key
No ratings yet
B2 Practice Tests: Test Preparation Answer Key
7 pages
Modes of Learning
No ratings yet
Modes of Learning
5 pages
The Rattrap
No ratings yet
The Rattrap
3 pages
DLL FBS W2
No ratings yet
DLL FBS W2
2 pages
CHAPTER II AYU AZ Rev
No ratings yet
CHAPTER II AYU AZ Rev
10 pages
Gambar Colony Counter
No ratings yet
Gambar Colony Counter
9 pages
Chapter 6 Assembly Language-PPandMS-1617
No ratings yet
Chapter 6 Assembly Language-PPandMS-1617
14 pages
Full download (Ebook) Lessons on Islamic Morals by Mohammad Ali Shomali ISBN 9781904934257, 1904934250 pdf docx
100% (3)
Full download (Ebook) Lessons on Islamic Morals by Mohammad Ali Shomali ISBN 9781904934257, 1904934250 pdf docx
67 pages
Functions and Liraries Introduction Guide So Machine)
No ratings yet
Functions and Liraries Introduction Guide So Machine)
42 pages
Review - The New Marxist Criticism
No ratings yet
Review - The New Marxist Criticism
10 pages
Weekly Home Learning Plan For Grade 3
No ratings yet
Weekly Home Learning Plan For Grade 3
2 pages
Adjective Clauses - Part 2
No ratings yet
Adjective Clauses - Part 2
16 pages
The Joy of Signing A Dictionary of American Signs Lottiel. Riekehof 2024 Scribd Download
100% (1)
The Joy of Signing A Dictionary of American Signs Lottiel. Riekehof 2024 Scribd Download
65 pages
Integrity
No ratings yet
Integrity
28 pages
Emma 5 Ybsdyyxtvgdsrtbrtvvsdfgbfsyn 5 U 68 M 7 K 9 Mtnhrgteftgdyujhtgrfgdhyfugjhtgrhyu
No ratings yet
Emma 5 Ybsdyyxtvgdsrtbrtvvsdfgbfsyn 5 U 68 M 7 K 9 Mtnhrgteftgdyujhtgrfgdhyfugjhtgrhyu
3 pages
IS-H FHIR Configuration Guide en
No ratings yet
IS-H FHIR Configuration Guide en
26 pages
TOS - 21st Century Literature from the Philippines and the World
No ratings yet
TOS - 21st Century Literature from the Philippines and the World
2 pages
Word Study
100% (6)
Word Study
80 pages
RH - G2B - U6 - L5 - Saving - An - Island - Sherry - 200117175421
No ratings yet
RH - G2B - U6 - L5 - Saving - An - Island - Sherry - 200117175421
28 pages
Ward J S M-The Master Masons Handbook
100% (3)
Ward J S M-The Master Masons Handbook
33 pages
Java Lab Manual
No ratings yet
Java Lab Manual
66 pages
SQL Joins-Anran Xing and Michelle Tin
No ratings yet
SQL Joins-Anran Xing and Michelle Tin
26 pages