C++ API Developer's Guide

899 Pages·2016·4.76 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 ([e-mail]). All rights reserved. This product includes cryptographic
software written by Eric Young ([e-mail]). This product includes software written by Tim Hudson
([e-mail]).
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/27/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 iv 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 ............................................................................................................... 143
Reading and writing field data to a record buffer ............................................................ 153
Clearing the record buffer ............................................................................................... 157
Adding new records ........................................................................................................ 158
Updating existing records ............................................................................................... 159
Deleting records .............................................................................................................. 160
Record properties ............................................................................................................ 160
Record Locking ............................................................................................................... 161
3.6 Data Types ........................................................................................................ 163
Scalar Types ................................................................................................................... 163
Date Types ...................................................................................................................... 163
Time Types ..................................................................................................................... 164
Date/Time (Timestamp) Types ....................................................................................... 165
Numeric Types ................................................................................................................ 166
All Rights Reserved v www.faircom.com
Introduction

3.7 Data Integrity ..................................................................................................... 170
Transactions .................................................................................................................... 170
Locking ............................................................................................................................ 172
3.8 Working with Resources .................................................................................... 175
Types of Resources ........................................................................................................ 175
c-treeDB C++ API - Working with Resources ................................................................. 176
3.9 Working with Callbacks ..................................................................................... 184
Callback Function Type .................................................................................................. 184
Callback Return Codes ................................................................................................... 185
Callback Handle Parameters .......................................................................................... 185
Callback Types ................................................................................................................ 186
Working with Callbacks ................................................................................................... 205
3.10 Working with Unicode ........................................................................................ 207
c-treeDB Support for Unicode ......................................................................................... 207
Unicode UTF-16 .............................................................................................................. 207
Unicode UTF-8 ................................................................................................................ 208
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 .................................................................................. 216
3.11 Compatibility with other c-tree API Technologies .............................................. 220
Compatibility with c-treeACE ISAM and Low-level Data Files ........................................ 220
Compatibility with c-treeACE SQL .................................................................................. 220
3.12 c-treeDB, ISAM, and Low-Level Integration ...................................................... 222
Overview ......................................................................................................................... 222
Switching c-tree instances .............................................................................................. 222
Switching ISAM contexts ................................................................................................ 223
Obtaining table data and file number .............................................................................. 224
Obtaining data file number .............................................................................................. 224
Obtaining index file number ............................................................................................ 225
4. c-treeDB C++ API Class Reference ................................................................ 226
4.1 c-treeDB Definitions .......................................................................................... 227
Field Types ...................................................................................................................... 227
Find Modes ..................................................................................................................... 229
Index Key Types ............................................................................................................. 230
Record Lock Modes ........................................................................................................ 230
Session Wide Lock Modes .............................................................................................. 230
Segment Modes .............................................................................................................. 231
Table Create Modes........................................................................................................ 233
Table Open Modes .......................................................................................................... 234
All Rights Reserved vi www.faircom.com
Introduction

Table Permissions ........................................................................................................... 235
4.2 CTBase Class ................................................................................................... 237
class CTBase .................................................................................................................. 237
CTBase Public Members ................................................................................................ 237
CTBase Methods ............................................................................................................ 238
4.3 CTBigint Class ................................................................................................... 281
class CTBigint ................................................................................................................. 281
CTBigint Operators ......................................................................................................... 281
CTBigint Methods ............................................................................................................ 284
4.4 CTBlob Class .................................................................................................... 295
class CTBlob ................................................................................................................... 295
CTBlob Operators ........................................................................................................... 295
CTBlob Methods ............................................................................................................. 298
4.5 CTCurrency Class ............................................................................................. 308
class CTCurrency ............................................................................................................ 308
CTCurrency Operators .................................................................................................... 308
CTCurrency Methods ...................................................................................................... 311
4.6 CTDatabase Class ............................................................................................ 325
class CTDatabase ........................................................................................................... 325
CTDatabase Methods ..................................................................................................... 326
4.7 CTDate Class .................................................................................................... 350
class CTDate ................................................................................................................... 350
CTDate Operators ........................................................................................................... 350
CTDate Methods ............................................................................................................. 353
4.8 CTDateTime Class ............................................................................................ 368
class CTDateTime ........................................................................................................... 368
CTDateTime Operators ................................................................................................... 368
CTDateTime Methods ..................................................................................................... 371
4.9 CTException Class ............................................................................................ 392
class CTException .......................................................................................................... 392
CTException Methods ..................................................................................................... 393
4.10 CTField Class .................................................................................................... 400
class CTField .................................................................................................................. 400
CTField Operators ........................................................................................................... 400
CTField Methods ............................................................................................................. 402
4.11 CTIndex Class ................................................................................................... 429
class CTIndex ................................................................................................................. 429
CTIndex Operators .......................................................................................................... 429
CTIndex Methods ............................................................................................................ 431
4.12 CTMoney Class ................................................................................................. 461
class CTMoney ............................................................................................................... 461
All Rights Reserved vii www.faircom.com
Introduction

CTMoney Operators........................................................................................................ 461
CTMoney Methods .......................................................................................................... 464
4.13 CTNumber Class ............................................................................................... 474
class CTNumber ............................................................................................................. 474
CTNumber Operators...................................................................................................... 474
CTNumber Methods ........................................................................................................ 477
4.14 CTRecord Class ................................................................................................ 493
class CTRecord ............................................................................................................... 493
CTRecord Methods ......................................................................................................... 494
4.15 CTResource Class ............................................................................................ 608
class CTResource ........................................................................................................... 608
CTResource Methods ..................................................................................................... 609
4.16 CTSegment Class ............................................................................................. 630
class CTSegment ............................................................................................................ 630
CTSegment Operators .................................................................................................... 630
CTSegment Methods ...................................................................................................... 632
4.17 CTSession Class ............................................................................................... 647
class CTSession ............................................................................................................. 647
CTSession Methods ........................................................................................................ 648
4.18 CTString Class .................................................................................................. 691
class CTString ................................................................................................................. 691
CTString Operators ......................................................................................................... 691
CTString Methods ........................................................................................................... 695
4.19 CTTable Class ................................................................................................... 726
class CTTable ................................................................................................................. 726
CTTable Methods ............................................................................................................ 727
4.20 CTTime Class .................................................................................................... 816
class CTTime .................................................................................................................. 816
CTTime Operators .......................................................................................................... 816
CTTime Methods ............................................................................................................. 819
A. c-treeACE Error Code Reference ................................................................... 846
B. c-treeDB Error and Return Values ................................................................. 879
5. Index ................................................................................................................. 885

All Rights Reserved viii 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 x www.faircom.com