C++ API Developer's Guide

899 Pages·2017·5.12 MB·English

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.
12/14/2017
Contents
1. Introduction ........................................................................................................ 1
1.1 Overview .............................................................................................................. 1
1.2 Layout of this Manual ........................................................................................... 2
2. Quick Tour .......................................................................................................... 3
2.1 Introductory Tutorial ............................................................................................. 4
Init 5
Define .................................................................................................................................. 6
Manage ............................................................................................................................... 8
Done .................................................................................................................................. 11
Additional Resources ........................................................................................................ 12
2.2 Relationships ..................................................................................................... 13
Init 15
Define ................................................................................................................................ 16
Manage ............................................................................................................................. 22
Done .................................................................................................................................. 28
Additional Resources ........................................................................................................ 29
2.3 Record/Row Locking .......................................................................................... 30
Init 32
Define ................................................................................................................................ 33
Manage ............................................................................................................................. 36
Done .................................................................................................................................. 40
Additional Resources ........................................................................................................ 41
2.4 Transaction Processing...................................................................................... 42
Init 44
Define ................................................................................................................................ 45
Manage ............................................................................................................................. 51
Done .................................................................................................................................. 58
Additional Resources ........................................................................................................ 59
3. Programmer's Reference ................................................................................. 60
3.1 Common functionality ........................................................................................ 61
Error Handling ................................................................................................................... 61
Transaction Processing .................................................................................................... 61
Session Wide Locking ....................................................................................................... 62
Default Date, Time and Float formats ............................................................................... 63
User Defined Tags ............................................................................................................ 64
3.2 Working with Sessions ....................................................................................... 65
All Rights Reserved iii www.faircom.com
Introduction

Creating a Session object ................................................................................................. 65
Creating a new session dictionary .................................................................................... 66
Session logon and logout .................................................................................................. 67
Session properties ............................................................................................................ 68
Managing Databases ........................................................................................................ 70
Working with Sessions without Dictionary Support ........................................................... 74
Attach and Detach Existing Sessions ............................................................................... 75
Session Dictionary ............................................................................................................ 76
3.3 Working with Databases .................................................................................... 77
Creating a Database object .............................................................................................. 77
Connecting to a database ................................................................................................. 77
Database properties .......................................................................................................... 78
Managing Tables ............................................................................................................... 79
Next Table ......................................................................................................................... 81
Database Dictionary .......................................................................................................... 84
3.4 Working with Tables ........................................................................................... 85
Creating a Table object ..................................................................................................... 86
Creating a new table ......................................................................................................... 87
Opening a table ................................................................................................................. 99
Altering a table ................................................................................................................ 101
Attach and Detach Open Tables ..................................................................................... 108
Table Properties .............................................................................................................. 109
3.5 Working with Records ...................................................................................... 115
Creating a record object .................................................................................................. 115
The default index ............................................................................................................. 117
Navigating records .......................................................................................................... 118
Finding records ............................................................................................................... 120
Record sets ..................................................................................................................... 123
Record Filters .................................................................................................................. 124
Record Batches ............................................................................................................... 144
Reading and writing field data to a record buffer ............................................................ 153
Clearing the record buffer ............................................................................................... 158
Adding new records ........................................................................................................ 158
Updating existing records ............................................................................................... 159
Deleting records .............................................................................................................. 160
Record properties ............................................................................................................ 161
Record Locking ............................................................................................................... 162
3.6 Data Types ...................................................................................................... 164
Scalar Types ................................................................................................................... 164
Date Types ...................................................................................................................... 164
Time Types ..................................................................................................................... 165
Date/Time (Timestamp) Types ....................................................................................... 166
Numeric Types ................................................................................................................ 167
All Rights Reserved iv www.faircom.com
Introduction

3.7 Data Integrity ................................................................................................... 171
Transactions .................................................................................................................... 171
Locking ............................................................................................................................ 173
3.8 Working with Resources .................................................................................. 176
Types of Resources ........................................................................................................ 176
c-treeDB C++ API - Working with Resources ................................................................. 177
3.9 Working with Callbacks .................................................................................... 185
Callback Function Type .................................................................................................. 185
Callback Return Codes ................................................................................................... 186
Callback Handle Parameters .......................................................................................... 186
Callback Types ................................................................................................................ 187
Working with Callbacks ................................................................................................... 206
3.10 Working with Unicode ...................................................................................... 208
c-treeDB Support for Unicode ......................................................................................... 208
Unicode UTF-16 .............................................................................................................. 208
Unicode UTF-8 ................................................................................................................ 209
c-treeDB C++ API UTF-8 Compliance ............................................................................ 209
Activating c-treeDB Unicode support .............................................................................. 210
ICU - International Components for Unicode .................................................................. 210
Unicode Support ............................................................................................................. 210
Extended Key Segment Definition .................................................................................. 217
3.11 Compatibility with other c-tree API Technologies ............................................. 221
Compatibility with c-treeACE ISAM and Low-level Data Files ........................................ 221
Compatibility with c-treeACE SQL .................................................................................. 221
3.12 c-treeDB, ISAM, and Low-Level Integration ..................................................... 223
Overview ......................................................................................................................... 223
Switching c-tree instances .............................................................................................. 223
Switching ISAM contexts ................................................................................................ 224
Obtaining table data and file number .............................................................................. 225
Obtaining data file number .............................................................................................. 225
Obtaining index file number ............................................................................................ 226
4. c-treeDB C++ API Class Reference ............................................................... 227
4.1 c-treeDB Definitions ......................................................................................... 228
Field Types ...................................................................................................................... 228
Find Modes ..................................................................................................................... 230
Index Key Types ............................................................................................................. 231
Record Lock Modes ........................................................................................................ 231
Session Wide Lock Modes .............................................................................................. 231
Segment Modes .............................................................................................................. 232
Table Create Modes........................................................................................................ 234
Table Open Modes.......................................................................................................... 235
All Rights Reserved v www.faircom.com
Introduction

Table Permissions ........................................................................................................... 236
4.2 CTBase Class .................................................................................................. 238
class CTBase .................................................................................................................. 238
CTBase Public Members ................................................................................................ 238
CTBase Methods ............................................................................................................ 239
4.3 CTBigint Class ................................................................................................. 282
class CTBigint ................................................................................................................. 282
CTBigint Operators ......................................................................................................... 282
CTBigint Methods ............................................................................................................ 285
4.4 CTBlob Class ................................................................................................... 296
class CTBlob ................................................................................................................... 296
CTBlob Operators ........................................................................................................... 296
CTBlob Methods ............................................................................................................. 299
4.5 CTCurrency Class ............................................................................................ 309
class CTCurrency ............................................................................................................ 309
CTCurrency Operators .................................................................................................... 309
CTCurrency Methods ...................................................................................................... 312
4.6 CTDatabase Class ........................................................................................... 326
class CTDatabase ........................................................................................................... 326
CTDatabase Methods ..................................................................................................... 327
4.7 CTDate Class .................................................................................................. 351
class CTDate ................................................................................................................... 351
CTDate Operators ........................................................................................................... 351
CTDate Methods ............................................................................................................. 354
4.8 CTDateTime Class ........................................................................................... 369
class CTDateTime ........................................................................................................... 369
CTDateTime Operators ................................................................................................... 369
CTDateTime Methods ..................................................................................................... 372
4.9 CTException Class .......................................................................................... 393
class CTException .......................................................................................................... 393
CTException Methods ..................................................................................................... 394
4.10 CTField Class .................................................................................................. 401
class CTField .................................................................................................................. 401
CTField Operators ........................................................................................................... 401
CTField Methods ............................................................................................................. 403
4.11 CTIndex Class ................................................................................................. 430
class CTIndex ................................................................................................................. 430
CTIndex Operators.......................................................................................................... 430
CTIndex Methods ............................................................................................................ 432
4.12 CTMoney Class ............................................................................................... 462
class CTMoney ............................................................................................................... 462
All Rights Reserved vi www.faircom.com
Introduction

CTMoney Operators........................................................................................................ 462
CTMoney Methods .......................................................................................................... 465
4.13 CTNumber Class ............................................................................................. 475
class CTNumber ............................................................................................................. 475
CTNumber Operators...................................................................................................... 475
CTNumber Methods ........................................................................................................ 478
4.14 CTRecord Class............................................................................................... 494
class CTRecord ............................................................................................................... 494
CTRecord Methods ......................................................................................................... 495
4.15 CTResource Class ........................................................................................... 609
class CTResource ........................................................................................................... 609
CTResource Methods ..................................................................................................... 610
4.16 CTSegment Class ............................................................................................ 631
class CTSegment ............................................................................................................ 631
CTSegment Operators .................................................................................................... 631
CTSegment Methods ...................................................................................................... 633
4.17 CTSession Class ............................................................................................. 648
class CTSession ............................................................................................................. 648
CTSession Methods ........................................................................................................ 649
4.18 CTString Class ................................................................................................. 692
class CTString ................................................................................................................. 692
CTString Operators ......................................................................................................... 692
CTString Methods ........................................................................................................... 696
4.19 CTTable Class ................................................................................................. 727
class CTTable ................................................................................................................. 727
CTTable Methods ............................................................................................................ 728
4.20 CTTime Class .................................................................................................. 817
class CTTime .................................................................................................................. 817
CTTime Operators .......................................................................................................... 817
CTTime Methods ............................................................................................................. 820
A. c-treeACE Error Code Reference .................................................................. 847
B. c-treeDB Error and Return Values ................................................................ 880
5. Index ............................................................................................................... 885

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