C API Developer's Guide - FairCom Corporation

904 Pages·2016·5.38 MB·English

c-treeDB
C API Developer's Guide
c-treeDB
C API Developer's Guide
Copyright Notice

Copyright © 1992-2017 FairCom Corporation. All rights reserved. No part of this publication may be stored in a retrieval
system, or transmitted in any form or by any means, electronic, mechanical, photocopying, recording or otherwise without
the prior written permission of FairCom Corporation. Printed in the United States of America.

Information in this document is subject to change without notice.

Trademarks
c-treeACE, c-treeRTG, c-treeAMS, c-tree Plus, c-tree, r-tree, FairCom and FairCom’s circular disc logo are trademarks of
FairCom, registered in the United States and other countries.
The following are third-party trademarks: AMD and AMD Opteron are trademarks of Advanced Micro Devices, Inc.
Macintosh, Mac, Mac OS, and Xcode are trademarks of Apple Inc., registered in the U.S. and other countries.
Embarcadero, the Embarcadero Technologies logos and all other Embarcadero Technologies product or service names
are trademarks, service marks, and/or registered trademarks of Embarcadero Technologies, Inc. and are protected by the
laws of the United States and other countries. Business Objects and the Business Objects logo, BusinessObjects, Crystal
Reports, Crystal Decisions, Web Intelligence, Xcelsius, and other Business Objects products and services mentioned
herein as well as their respective logos are trademarks or registered trademarks of Business Objects Software Ltd.
Business Objects is an SAP company. HP and HP-UX are registered trademarks of the Hewlett-Packard Company. AIX,
IBM, POWER6, POWER7, and pSeries are trademarks or registered trademarks of International Business Machines
Corporation in the United States, other countries, or both. Intel, Intel Core, Itanium, Pentium and Xeon are trademarks or
registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. Microsoft, the .NET
logo, the Windows logo, Access, Excel, SQL Server, Visual Basic, Visual C++, Visual C#, Visual Studio, Windows,
Windows Server, and Windows Vista are either registered trademarks or trademarks of Microsoft Corporation in the
United States and/or other countries. Novell and SUSE are registered trademarks of Novell, Inc. in the United States and
other countries. Oracle and Java are registered trademarks of Oracle and/or its affiliates. QNX and Neutrino are
registered trademarks of QNX Software Systems Ltd. in certain jurisdictions. CentOS, Red Hat, and the Shadow Man logo
are registered trademarks of Red Hat, Inc. in the United States and other countries, used with permission. UNIX and
UnixWare are registered trademarks of The Open Group in the United States and other countries. Linux is a trademark of
Linus Torvalds in the United States, other countries, or both. Python and PyCon are trademarks or registered trademarks
of the Python Software Foundation. OpenServer is a trademark or registered trademark of Xinuos, Inc. in the U.S.A. and
other countries. Unicode and the Unicode Logo are registered trademarks of Unicode, Inc. in the United States and other
countries.
Btrieve is a registered trademark of Actian Corporation.
ACUCOBOL-GT, MICRO FOCUS, RM/COBOL, and Visual COBOL are trademarks or registered trademarks of Micro
Focus (IP) Limited or its subsidiaries in the United Kingdom, United States and other countries.
isCOBOL and Veryant are trademarks or registered trademarks of Veryant in the United States and other countries.
All other trademarks, trade names, company names, product names, and registered trademarks are the property of their
respective holders.

Portions Copyright © 1991-2016 Unicode, Inc. All rights reserved.
Portions Copyright © 1998-2016 The OpenSSL Project. All rights reserved. This product includes software developed by
the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/).
Portions Copyright © 1995-1998 Eric Young ([email protected]). All rights reserved. This product includes cryptographic
software written by Eric Young ([email protected]). This product includes software written by Tim Hudson
([email protected]).
Portions © 1987-2017 Dharma Systems, Inc. All rights reserved. This software or web site utilizes or contains material
that is © 1994-2007 DUNDAS DATA VISUALIZATION, INC. and its licensors, all rights reserved.
Portions Copyright © 1995-2013 Jean-loup Gailly and Mark Adler.
4/28/2017
Contents
1. Introduction ......................................................................................................... 1
1.1 Layout of this Manual ............................................................................................ 2
2. Quick Tour ........................................................................................................... 3
2.1 Introductory Tutorial .............................................................................................. 4
Init 5
Define .................................................................................................................................. 6
Manage ............................................................................................................................... 8
Done .................................................................................................................................. 12
Additional Resources ........................................................................................................ 13
2.2 Relationships ....................................................................................................... 14
Init 16
Define ................................................................................................................................ 17
Manage ............................................................................................................................. 23
Done .................................................................................................................................. 31
Additional Resources ........................................................................................................ 32
2.3 Record/Row Locking ........................................................................................... 33
Init 35
Define ................................................................................................................................ 36
Manage ............................................................................................................................. 39
Done .................................................................................................................................. 44
Additional Resources ........................................................................................................ 45
2.4 Transaction Processing ....................................................................................... 46
Init 47
Define ................................................................................................................................ 48
Manage ............................................................................................................................. 54
Done .................................................................................................................................. 62
Additional Resources ........................................................................................................ 63
3. Programmer's Reference .................................................................................. 64
3.1 Working with Sessions ........................................................................................ 66
Allocating a Session Handle ............................................................................................. 66
Creating a new session dictionary .................................................................................... 67
Session logon and logout .................................................................................................. 68
Session properties ............................................................................................................ 69
Managing Databases ........................................................................................................ 70
Session wide functions ..................................................................................................... 74
Working with Sessions without Dictionary Support ........................................................... 77
All Rights Reserved iv www.faircom.com
Introduction

Attach and Detach Existing Sessions ............................................................................... 78
Session Dictionary ............................................................................................................ 79
3.2 Working with Databases ...................................................................................... 80
Allocating a Database handle ........................................................................................... 80
Connecting to a database ................................................................................................. 80
Database properties .......................................................................................................... 81
Managing Tables ............................................................................................................... 82
Database Dictionary .......................................................................................................... 87
3.3 Working with Tables ............................................................................................ 89
Allocating a table handle ................................................................................................... 90
Creating a new table ......................................................................................................... 91
Opening a table ............................................................................................................... 102
Altering a table ................................................................................................................ 104
Attach and Detach Open Tables ..................................................................................... 110
Table Properties .............................................................................................................. 111
3.4 Working with Records ....................................................................................... 115
Allocating a record handle .............................................................................................. 115
User managed record buffers ......................................................................................... 116
The default index ............................................................................................................. 117
Navigating records .......................................................................................................... 118
Finding records ............................................................................................................... 120
Record Sets .................................................................................................................... 121
Record Filters .................................................................................................................. 122
Record Batches ............................................................................................................... 139
Reading and writing field data to a record buffer ............................................................ 148
Operators ........................................................................................................................ 153
Clearing the record buffer ............................................................................................... 154
Adding new records ........................................................................................................ 154
Updating existing records ............................................................................................... 155
Deleting records .............................................................................................................. 156
Record properties ............................................................................................................ 156
Record Locking ............................................................................................................... 157
3.5 Data Types ........................................................................................................ 159
Scalar Types ................................................................................................................... 159
Date Types ...................................................................................................................... 159
Time Types ..................................................................................................................... 161
Date/Time (Timestamp) Types ....................................................................................... 162
Numeric Types ................................................................................................................ 162
3.6 Data Integrity ..................................................................................................... 168
Locking ............................................................................................................................ 168
Transactions .................................................................................................................... 171
3.7 Working with Resources .................................................................................... 174
All Rights Reserved v www.faircom.com
Introduction

Types of Resources ........................................................................................................ 174
c-treeDB C API - Working with Resources ..................................................................... 175
3.8 Working with Callbacks ..................................................................................... 184
Callback Function Type .................................................................................................. 184
Callback Return Codes ................................................................................................... 185
Callback Handle Parameters .......................................................................................... 185
Callback Types ................................................................................................................ 186
Working with Callbacks ................................................................................................... 205
3.9 Working with Unicode ........................................................................................ 207
Unicode UTF-16 .............................................................................................................. 207
Unicode UTF-8 ................................................................................................................ 207
c-treeDB C API UTF-8 Compliance ................................................................................ 208
Activating c-treeDB Unicode support .............................................................................. 209
ICU - International Components for Unicode .................................................................. 209
Unicode Support ............................................................................................................. 209
Extended Key Segment Definition .................................................................................. 217
3.10 Working with Multi-Record Virtual Tables .......................................................... 221
c-treeDB Virtual Tables ................................................................................................... 222
c-treeACE MRTTable API ............................................................................................... 224
Multi-Record Table Tutorial ............................................................................................. 238
3.11 Working with Multiple Files (FILESET) .............................................................. 255
Dynamic partition member support ................................................................................. 255
3.12 Compatibility with other c-tree API Technologies .............................................. 259
Compatibility with c-treeACE ISAM and Low-level Data Files ........................................ 259
Compatibility with c-treeACE SQL .................................................................................. 259
3.13 c-treeDB, ISAM, and Low-Level Integration ...................................................... 261
Overview ......................................................................................................................... 261
Switching c-tree instances .............................................................................................. 261
Switching ISAM contexts ................................................................................................ 262
Obtaining table data and file number .............................................................................. 263
Obtaining data file number .............................................................................................. 263
Obtaining index file number ............................................................................................ 264
4. c-treeDB C API Function Reference .............................................................. 265
4.1 c-treeDB Definitions .......................................................................................... 266
Field Types ...................................................................................................................... 266
Find Modes ..................................................................................................................... 268
Index Key Types ............................................................................................................. 269
Record Lock Modes ........................................................................................................ 269
Session Wide Lock Modes .............................................................................................. 269
Segment Modes .............................................................................................................. 270
Table Create Modes........................................................................................................ 272
All Rights Reserved vi www.faircom.com
Introduction

Table Open Modes .......................................................................................................... 273
Table Permissions ........................................................................................................... 274
4.2 c-treeDB C API Summary ................................................................................. 276
Initialization ..................................................................................................................... 276
Transaction Processing .................................................................................................. 276
Data Definition ................................................................................................................. 276
Data Manipulation ........................................................................................................... 277
Data Types ...................................................................................................................... 277
Data Structures ............................................................................................................... 278
Utility ............................................................................................................................... 281
4.3 Function Descriptions ........................................................................................ 281
A. c-treeACE Error Code Reference ................................................................... 852
B. c-treeDB Error and Return Values ................................................................. 885
5. Index ................................................................................................................. 890

All Rights Reserved vii www.faircom.com
FairCom Typographical Conventions
Before you begin using this guide, be sure to review the relevant terms and typographical
conventions used in the documentation.
The following formatted items identify special information.

Formatting convention Type of Information
Bold Used to emphasize a point or for variable expressions such
as parameters
CAPITALS Names of keys on the keyboard. For example, SHIFT,
CTRL, or ALT+F4
FairCom Terminology FairCom technology term
FunctionName() c-treeACE Function name
Parameter c-treeACE Function Parameter
Code Example Code example or Command line usage
utility c-treeACE executable or utility
filename c-treeACE file or path name
CONFIGURATION KEYWORD c-treeACE Configuration Keyword
CTREE_ERR c-treeACE Error Code
All Rights Reserved ix www.faircom.com