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