c-tree Plus ® Developer's Guide Developer's Guide Red Hat, Inc. in the United States and other countries, used with permission. SCO and SCO Open Server, are trademarks or regist trademarks of The SCO Group, Inc. in the U.S.A. and other countries. SGI and IRIX are registered trademarks of Silicon Graphic s, Inc., in the United States and/or other countries worldwide. Sun, Sun Microsystems, the Sun Logo, Solaris, SunOS, JDBC, Java and all Java-ba sed trademarks are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. 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. All other trademarks, trade names, company names, product names, and registered trademarks are the pr operty of thei respective holders. FairCom welcomes your comments on this document and the software it describes. Send comments to: Documentation Comments FairCom Corporation 6300 W. Sugar Creek Drive Columbia, MO 65203 Portions © 1987-2008 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. 6/26/2008 www.faircom.com All Rights Reserved Introduc tion................................................................................................................... ...........................................1 Sections of this manual........................................................................................................ .........................1 Notes on this Guide............................................................................................................ ..........................2 Notes on the samples........................................................................................................... ........................2 Kylix Note..................................................................................................................... .................................2 Quick Tour..................................................................................................................... ...........................................3 VCL for CBuilder............................................................................................................... ............................3 Introductory Tutorial.......................................................................................................... ............................3 Relationships.................................................................................................................. .............................12 Record/Row Locking............................................................................................................. ......................25 Transaction Processing......................................................................................................... .....................33 VCL for Delphi................................................................................................................. ............................45 Introductory Tutorial.......................................................................................................... ..........................45 Relationships.................................................................................................................. .............................52 Record/Row Locking............................................................................................................. ......................65 Transaction Processing......................................................................................................... .....................73 Programmer's Reference......................................................................................................... .............................85 Modifying Compone nt Properties................................................................................................. ..............85 Using the Object Inspector..................................................................................................... .....................85 Using code..................................................................................................................... .............................86 Error handling................................................................................................................. .............................86 Using the Session Component.................................................................................................... ...............87 Creating a new session......................................................................................................... ......................87 Log On to c-tree............................................................................................................... ...........................88 AutoCreate Property............................................................................................................ .......................89 Using the Database Component................................................................................................... ..............89 Creating a New Database........................................................................................................ ...................90 AutoCreate Property............................................................................................................ .......................91 Connecting to a Database....................................................................................................... ...................91 Dropping a Database from the Session........................................................................................... ...........92 Deleting a Database............................................................................................................ .......................93 Adding an Exis ting Database.................................................................................................... ..................93 Using the Tabl e Component...................................................................................................... .................94 Creating a Table............................................................................................................... ..........................95 Creating a Table Under Transaction Control..................................................................................... .......104 Opening a table................................................................................................................ .........................105 Closing a Table................................................................................................................ .........................106 Altering an ex isting table..................................................................................................... ......................107 Adding an Existing Ta ble to a Database......................................................................................... ..........109 Dropping a Table from a Database............................................................................................... ............110 Deleting a Table............................................................................................................... .........................111 Working with Records........................................................................................................... ....................112 Deleting a Record.............................................................................................................. .......................114 Filters........................................................................................................................ ................................116 Selecting Records.............................................................................................................. .......................119 Using TCtTable with VCL Data Controls.......................................................................................... ........121 Working without the Visual Components.......................................................................................... ........122 Data Integrity................................................................................................................. ............................123 Transactions................................................................................................................... ...........................123 Table of Contents FairCom Corporation iv Copyright 2008 FairCom Corporation Locking........................................................................................................................ ..............................124 c-treeVCL- Working with Resources.............................................................................................. ...........125 Constructing resource objects.................................................................................................. ................126 Adding New Resources........................................................................................................... .................126 Deleting Resources............................................................................................................. ......................127 Updating existi ng resources.................................................................................................... ..................128 Reading resources.............................................................................................................. ......................129 Getting and setting resource properties........................................................................................ ............131 Resource Locks................................................................................................................. .......................131 Compatib ility.................................................................................................................. ............................132 Compatibility with c-tree Plus IS AM and Low-level Data Files.................................................................13 Compatibility with c-treeSQL................................................................................................... ..................133 Migrating c-tree Plus files.................................................................................................... ......................134 ference............................................................................................................ .............................135 Class Hierarchy................................................................................................................ .........................136 c-treeVCL/CLX Definitions...................................................................................................... ..................137 Data Types..................................................................................................................... ...........................137 Date Types..................................................................................................................... ...........................137 Time Types..................................................................................................................... ..........................137 Find Modes..................................................................................................................... ..........................138 Index Key Types................................................................................................................ .......................138 Record Lock Modes.............................................................................................................. ....................138 Session Wide Lock Modes........................................................................................................ ................139 Segment Modes.................................................................................................................. ......................140 Table Create Modes............................................................................................................. ....................141 Table Open Modes............................................................................................................... ....................142 Table Permissions.............................................................................................................. ......................144 TCtComponent Component......................................................................................................... .............145 Public pr operties.............................................................................................................. .........................145 c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Public Pr operties.............................................................................................................. .........................173 Appendix B. www.faircom.com All Rights Reserved vi 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 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-tree Function name. Parameter c-tree Function Parameter. Code Examples Code example or Command line usage. c-tree executable or utility. filename c-tree file or path name. CONFIGURATION KEYWORDS c-treeACE Configuration Keyword. c-tree Error Code. www.faircom.com All Rights Reserved Chapter 1 Introduction The c-tree Plus® Data Access Components, referred to here as c-treeVCL/CLX, allow users of Borland® Delphi™, C++Builder™, and Kylix™ to use VCL™ or CLX™ data controls to access data stored on c-tree Servers or in c-tree Plus files. With the release of Borland Delphi 3.0, developers were no longer limited to accessing data through the Borland Database Engine (BDE) or through ODBC to use the data controls or quick report components. New data-aware components made way for easier development of database applications using Borland IDEs. Deriving from c-treeVCL components are intended for V7.11 and later, and will not work with servers prior to that version. 1.1 Sections of this manual Chapter 2 - Quick Tour: This chapter will introduce you to the use of c-treeVCL/CLX using a hands-on approach. The tutorials include a sample project for developing a simple database application in Borland C++Builder or in Borland Delphi using c-treeVCL/CLX. The full source is included with explanations of each part. The Borland project files are included. Chapter 1 Introduction FairCom Corporation Copyright 2008 FairCom Corporation Chapter 3 - Programmer's Reference: This chapter provides step-by-step instructions for integration of these components into applications. The Programmer's Reference also includes an overview on using c-treeVCL/CLX, with descriptions of the Session, Database, and Table components for Borland C++Builder, Delphi, and Kylix. Other miscellaneous information is also included. Chapter 4 - Component Reference: This chapter describes the properties, methods and events of each c-treeVCL/CLX components. Advanced information such as data types, table create modes, key types, and error codes is also included. 1.2 Notes on this Guide Throughout this document, the definition “c-treeVCL/CLX” is used to indicate the c-tree Plus implementation of the components under Windows or Linux, even though the VCL is a Windows specific library, and CLX a cross-platform (Windows and Linux at the present time) library. Under Windows, the component to be installed is always the Windows version, even if the user intends to work with the CLX library. The Linux version only uses the CLX components (there is no VCL under Linux), and should be installed under Linux only. The c-tree Plus source code is the same for both implementations. 1.3 Notes on the samples The samples presented in this document can be used to test and run initial applications with c-treeVCL/CLX. It is important to notice that for all code excerpts, some or all of the three c-treeVCL/CLX components should have been inserted into the form to initialize them. It is possible, and in some circumstances it is more general, to work with the declaration of the objects. Each sample represents a very simple piece of code that runs in the sequence presented, and does not represent a good practice for general programming. For instance, if some of the code is run twice in the sequence, an error will be shown. The reason for this is explained in the specific sessions. 1.4 Kylix Note The Kylix product represents a Linux implementation of the Borland RAD tools using Object Pascal and C++. Up to Kylix 2, there was only an Object Pascal implementation. With the release of Kylix 3, Borland introduced a version of its C++Builder tool in the Linux world. With this, Kylix 3 became a Linux Development Platform with two possible environments, “Delphi for Linux” and “C++Builder for Linux”, as defined by Borland. The samples in this guide use the new nomenclature from Borland, Delphi and C++Builder, and do not make any reference to Kylix. Whenever the sample requires some specific modification to be run under Linux, this is done in the code using “#ifdef” (C) or “$IFDEF” (pascal). In general, the difference is restricted to the path. For more information on the c-treeVCL/CLX Kylix installation and usage, see the readme.txt file included with the c-treeCLX distribution. www.faircom.com All Rights Reserved Chapter 2 This section introduces c-treeVCL/CLX using a hands-on approach. The tutorial includes a sample project for developing a simple database application in Borland C++Builder or in Borland Delphi using c-treeVCL/CLX. The full source is included with explanations of each part. The Borland project files are included. 2.1 VCL for CBuilder Introductory Tutorial ..\sdk\ctree.vcl.cbuilder\tutorials\Tutorial1.cpp This tutorial will take you through the basic use of the c-treeACE CodeGear VCL ISAM Component Framework - CBuilder. Like all other examples in the c-tree tutorial series, this tutorial simplifies the creation and use of a database into four simple steps: Initialize(), Define(), Manage(), and You’re Done() ! Tutorial #1: Introductory - Simple Single Table We wanted to keep this program as simple as possible. This program does the following: Initialize() - Connects to the c-treeACE Database Engine. Define() - Defines and creates a "customer master" (custmast) table/file. Manage() - Adds a few rows/records; Reads the rows/records back from the database; displays the column/field content; and then deletes the rows/records. Done() - Disconnects from c-treeACE Database Engine. Note our simple mainline: We suggest opening the source code with your own editor. Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation Continue now to review these four steps. c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Init First we need to open a connection to a database by providing the c-treeACE Database Engine with a user name, password and the database name. Below is the code for Initialize() Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation Define The Define() step is where specific data definitions are established by your application and/or process. This involves defining columns/fields and creating the tables/files with optional indices. Below is the code for Define() c-treeVCL Developer's Guide www.faircom.com All Rights Reserved { hTable-UpdateCreateMode(hTable-CreateMode & ~CTCREATE_TRNLOG); } } catch (ECtError &E) { Application-ShowException(&E); } } Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation Manage The manage step provides data management functionality for your application and/or process. Below is the code for Manage() c-treeVCL Developer's Guide www.faircom.com All Rights Reserved } } void TForm1::Display_Records() { Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Additional Resources We encourage you to explore the additional resources listed here: Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation Relationships ..\sdk\ctree.vcl.cbuilder\tutorials\Tutorial2.cpp Now we will build some table/file relationships using the c-treeACE CodeGear VCL ISAM Component Framework - CBuilder. This tutorial will advance the concepts introduced in the first tutorial by expanding the number of tables. We will define key columns/fields and create specific indices for each table to form a relational model database. Like all other examples in the c-tree tutorial series, this tutorial simplifies the creation and use of a database into four simple steps: Initialize(), Define(), Manage(), and You’re Done() ! Tutorial #2: Relational Model and Indexing Here we add a bit more complexity, introducing multiple tables, with related indices in order to form a simple "relational" database simulating an Order Entry system. Here is an overview of what will be created: Initialize() - Connects to the c-treeACE Database Engine. Define() - Defines and creates the "custmast", "custordr", "ordritem" and the "itemmast" tables/files with related indices. Manage() - Adds some related rows/records to all tables/files. Then queries the database. Done() - Disconnects from c-treeACE Database Engine. Note our simple mainline: We suggest opening the source code with your own editor. c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Continue now to review these four steps. Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation Init First we need to open a connection to a database by providing the c-treeACE Database Engine with a user name, password and the database name. Below is the code for Initialize() c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Define The Define() step is where specific data definitions are established by your application and/or process. This involves defining columns/fields and creating the tables/files with optional indices. Below is the code for Define() Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation Application-ShowException(&E); } } else Check_Table_Mode(TabOrderList); } void TForm1::Create_OrderItem_Table() { boolean do_create = false; { // try to open the table TabOrderItem-Table = "ORDERITEMS"; TabOrderItem-Active = true; } catch (...) { // table may not exist, try creating it do_create = true; } { try { // add fields to table TabOrderItem-AddField("oi_ordernum", CT_STRING, 7); TabOrderItem-AddField("oi_seqnumber", CT_INT2, 2); TabOrderItem-AddField("oi_quantity", CT_INT2, 2); TabOrderItem-AddField("oi_itemnum", CT_STRING, 6); TabOrderItem-AddIndex("orderitem", CTINDEX_FIXED, false, false); TabOrderItem-AddSegment("orderitem", "oi_ordernum", CTSEG_SCHSEG); TabOrderItem-AddSegment("orderitem", "oi_seqnumber", CTSEG_SCHSEG); c-treeVCL Developer's Guide www.faircom.com All Rights Reserved if (do_create) { try { // add fields to table TabItemMast-AddField("im_weight", CT_INT4, 4); TabItemMast-AddField("im_price", CT_MONEY, 4); TabItemMast-AddField("im_itemnum", CT_STRING, 6); TabItemMast-AddField("im_desc", CT_STRING, 48); TabItemMast-AddIndex("itemnum", CTINDEX_FIXED, false, false); TabItemMast-AddSegment("itemnum", "im_itemnum", CTSEG_SCHSEG); Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation // This scenario arises out of the fact that this table was created in tutorial 1 without c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Manage The manage step provides data management functionality for your application and/or process. Below is the code for Manage() Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation msg = "Customer number " + custnum + " not found"; Application-MessageBox(msg.c_str(), "Record not found"); c-treeVCL Developer's Guide www.faircom.com All Rights Reserved } } void TForm1::Add_OrderItem_Records() { int counter; { Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation Additional Resources We encourage you to explore the additional resources listed here: c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Record/Row Locking ..\sdk\ctree.vcl.cbuilder\tutorials\Tutorial3.cpp Now we will explore row/record locks using the c-treeACE CodeGear VCL ISAM Component Framework - CBuilder. The functionality for this tutorial focuses on inserting/adding rows/records, then updating a single row/record in the customer master table under locking control. The application will pause after a LOCK is placed on a row/record. Another instance of this application should then be launched, which will block, waiting on the lock held by the first instance. Pressing the Enter-10;&#x.3nt;r-1;退 key will enable the first instance to proceed. This will result in removing the lock thereby allowing the second instance to continue execution. Launching two processes provides a visual demonstration of the effects of locking and a basis for experimentation on your own. Like all other examples in the c-tree tutorial series, this tutorial simplifies the creation and use of a database into four simple steps: Initialize(), Define(), Manage(), and you’re Done() ! Tutorial #3: Locking Here we demonstrate the enforcement of data integrity by introducing record/row "locking". Initialize() - Connects to the c-treeACE Database Engine. Define() - Defines and creates a "customer master" (custmast) table/file. Manage() - Adds a few rows/records; Reads the rows/records back from the database; displays the column/field content. Then demonstrates an update operation under locking control, and a scenario that shows a locking conflict. Done() - Disconnects from c-treeACE Database Engine. Note our simple mainline: We suggest opening the source code with your own editor. Continue now to review these four steps. Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation Init First we need to open a connection to a database by providing the c-treeACE Database Engine with a user name, password and the database name. Below is the code for Initialize() c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Define The Define() step is where specific data definitions are established by your application and/or process. This involves defining columns/fields and creating the tables/files with optional indices. Below is the code for Define() Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation } else { c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Manage The manage step provides data management functionality for your application and/or process. Below is the code for Manage() Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation { while (ATable-ActiveRecord-First()) { c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation Additional Resources We encourage you to explore the additional resources listed here: c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Transaction Processing ..\sdk\ctree.vcl.cbuilder\tutorials\Tutorial4.cpp Now we will discuss transaction processing as it relates to the c-treeACE CodeGear VCL ISAM Component Framework - CBuilder. Transaction processing provides a safe method by which multiple database operations spread across separate tables/files are guaranteed to be atomic. By atomic, we mean that, within a transaction, either all of the operations succeed or none of the operations succeed. This "either all or none" atomicity insures that the integrity of the data in related tables/files is secure. Like all other examples in the c-tree tutorial series, this tutorial simplifies the creation and use of a database into four simple steps: Initialize(), Define(), Manage(), and You’re Done() ! Tutorial #4: Transaction Processing Here we demonstrate transaction control. Initialize() - Connects to the c-treeACE Database Engine. Define() - Defines and creates our four tables/files. Manage() - Adds rows/records to multiple tables/files under transaction control. Done() - Disconnects from c-treeACE Database Engine. Note our simple mainline: We suggest opening the source code with your own editor. Continue now to review these four steps. Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation Init First we need to open a connection to a database by providing the c-treeACE Database Engine with a user name, password and the database name. Below is the code for Initialize() c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Define The Define() step is where specific data definitions are established by your application and/or process. This involves defining columns/fields and creating the tables/files with optional indices. Below is the code for Define() Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation { Application-ShowException(&E); } } else Check_Table_Mode(TabOrderList); } void TForm1::Create_OrderItem_Table() { boolean do_create = false; { // try to open the table TabOrderItem-Table = "ORDERITEMS"; TabOrderItem-Active = true; } catch (...) { // table may not exist, try creating it do_create = true; if (do_create) { try { // add fields to table TabOrderItem-AddField("oi_ordernum", CT_STRING, 7); TabOrderItem-AddField("oi_seqnumber", CT_INT2, 2); TabOrderItem-AddField("oi_quantity", CT_INT2, 2); TabOrderItem-AddField("oi_itemnum", CT_STRING, 6); TabOrderItem-AddIndex("orderitem", CTINDEX_FIXED, false, false); TabOrderItem-AddSegment("orderitem", "oi_ordernum", CTSEG_SCHSEG); TabOrderItem-AddSegment("orderitem", "oi_seqnumber", CTSEG_SCHSEG); TabOrderItem-CreateMode = CTCREATE_TRNLOG; c-treeVCL Developer's Guide www.faircom.com All Rights Reserved do_create = true; } if (do_create) { try { // add fields to table TabItemMast-AddField("im_weight", CT_INT4, 4); TabItemMast-AddField("im_price", CT_MONEY, 4); TabItemMast-AddField("im_itemnum", CT_STRING, 6); TabItemMast-AddField("im_desc", CT_STRING, 48); TabItemMast-AddIndex("itemnum", CTINDEX_FIXED, false, false); TabItemMast-AddSegment("itemnum", "im_itemnum", CTSEG_SCHSEG); TabItemMast-CreateMode = CTCREATE_TRNLOG; Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation TabCustMast-Table = "CUSTMAST"; TabCustMast-Active = true; } catch (ECtError& E) { Application-ShowException(&E); } } else { c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Manage The manage step provides data management functionality for your application and/or process. Below is the code for Manage() Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation { c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation Additional Resources We encourage you to explore the additional resources listed here: c-treeVCL Developer's Guide www.faircom.com All Rights Reserved 2.2 VCL for Delphi Introductory Tutorial ..\sdk\ctree.vcl.delphi\tutorials\Tutorial1.pas This tutorial will take you through the basic use of the c-treeACE CodeGear VCL ISAM Component Framework - Delphi. Like all other examples in the c-tree tutorial series, this tutorial simplifies the creation and use of a database into four simple steps: Initialize(), Define(), Manage(), and You’re Done() ! Tutorial #1: Introductory - Simple Single Table We wanted to keep this program as simple as possible. This program does the following: Initialize() - Connects to the c-treeACE Database Engine. Define() - Defines and creates a "customer master" (custmast) table/file. Manage() - Adds a few rows/records; Reads the rows/records back from the database; displays the column/field content; and then deletes the rows/records. Done() - Disconnects from c-treeACE Database Engine. Note our simple mainline: We suggest opening the source code with your own editor. Continue now to review these four steps. Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation Init First we need to open a connection to a database by providing the c-treeACE Database Engine with a user name, password and the database name. Below is the code for Initialize() c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Define The Define() step is where specific data definitions are established by your application and/or process. This involves defining columns/fields and creating the tables/files with optional indices. Below is the code for Define() Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation end; c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Manage The manage step provides data management functionality for your application and/or process. Below is the code for Manage() Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Additional Resources We encourage you to explore the additional resources listed here: Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation Relationships ..\sdk\ctree.vcl.delphi\tutorials\Tutorial2.pas Now we will build some table/file relationships using the c-treeACE CodeGear VCL ISAM Component Framework - Delphi. This tutorial will advance the concepts introduced in the first tutorial by expanding the number of tables. We will define key columns/fields and create specific indices for each table to form a relational model database. Like all other examples in the c-tree tutorial series, this tutorial simplifies the creation and use of a database into four simple steps: Initialize(), Define(), Manage(), and You’re Done() ! Tutorial #2: Relational Model and Indexing Here we add a bit more complexity, introducing multiple tables, with related indices in order to form a simple "relational" database simulating an Order Entry system. Here is an overview of what will be created: Initialize() - Connects to the c-treeACE Database Engine. Define() - Defines and creates the "custmast", "custordr", "ordritem" and the "itemmast" tables/files with related indices. Manage() - Adds some related rows/records to all tables/files. Then queries the database. Done() - Disconnects from c-treeACE Database Engine. Note our simple mainline: We suggest opening the source code with your own editor. c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Continue now to review these four steps. Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation Init First we need to open a connection to a database by providing the c-treeACE Database Engine with a user name, password and the database name. Below is the code for Initialize() c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Define The Define() step is where specific data definitions are established by your application and/or process. This involves defining columns/fields and creating the tables/files with optional indices. Below is the code for Define() Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation end; var do_create : boolean; begin do_create := false; try // try to open the table TabOrderItem.Table := 'ORDERITEMS'; TabOrderItem.Active := true; except // table may not exist, try creating it do_create := true; end; if do_create then begin try // add fields to table TabOrderItem.AddField('oi_ordernum', CT_STRING, 7); TabOrderItem.AddField('oi_seqnumber', CT_INT2, 2); TabOrderItem.AddField('oi_itemnum', CT_STRING, 6); TabOrderItem.AddIndex('orderitem', CTINDEX_FIXED, false, false); TabOrderItem.AddSegment('orderitem', 'oi_ordernum', CTSEG_SCHSEG); TabOrderItem.AddSegment('orderitem', 'oi_seqnumber', CTSEG_SCHSEG); c-treeVCL Developer's Guide www.faircom.com All Rights Reserved TabItemMast.AddIndex('itemnum', CTINDEX_FIXED, false, false); TabItemMast.AddSegment('itemnum', 'im_itemnum', CTSEG_SCHSEG); Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation begin c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Manage The manage step provides data management functionality for your application and/or process. Below is the code for Manage() Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation Application.MessageBox(PChar(msg), 'Record not found'); exit; end; c-treeVCL Developer's Guide www.faircom.com All Rights Reserved counter : integer; begin try Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation TabCustMast.ActiveRecord.Write; end; except on E : ECtError do Application.ShowException(E); end; end; c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation Additional Resources We encourage you to explore the additional resources listed here: c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Record/Row Locking ..\sdk\ctree.vcl.delphi\tutorials\Tutorial3.pas Now we will explore row/record locks using the c-treeACE CodeGear VCL ISAM Component Framework - Delphi. The functionality for this tutorial focuses on inserting/adding rows/records, then updating a single row/record in the customer master table under locking control. The application will pause after a LOCK is placed on a row/record. Another instance of this application should then be launched, which will block, waiting on the lock held by the first instance. Pressing the Enter-10;&#x.3nt;r-1;退 key will enable the first instance to proceed. This will result in removing the lock thereby allowing the second instance to continue execution. Launching two processes provides a visual demonstration of the effects of locking and a basis for experimentation on your own. Like all other examples in the c-tree tutorial series, this tutorial simplifies the creation and use of a database into four simple steps: Initialize(), Define(), Manage(), and you’re Done() ! Tutorial #3: Locking Here we demonstrate the enforcement of data integrity by introducing record/row "locking". Initialize() - Connects to the c-treeACE Database Engine. Define() - Defines and creates a "customer master" (custmast) table/file. Manage() - Adds a few rows/records; Reads the rows/records back from the database; displays the column/field content. Then demonstrates an update operation under locking control, and a scenario that shows a locking conflict. Done() - Disconnects from c-treeACE Database Engine. Note our simple mainline: We suggest opening the source code with your own editor. Continue now to review these four steps. Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation Init First we need to open a connection to a database by providing the c-treeACE Database Engine with a user name, password and the database name. Below is the code for Initialize() c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Define The Define() step is where specific data definitions are established by your application and/or process. This involves defining columns/fields and creating the tables/files with optional indices. Below is the code for Define() Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation // This scenario arises out of the fact that this table was created in tutorial 1 without c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Manage The manage step provides data management functionality for your application and/or process. Below is the code for Manage() Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation end; end; var str : string; begin try str := '1003'; TabCustMast.Lock(CTLOCK_WRITE_BLOCK); TabCustMast.ActiveRecord.Clear; c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation Additional Resources We encourage you to explore the additional resources listed here: c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Transaction Processing ..\sdk\ctree.vcl.delphi\tutorials\Tutorial4.pas Now we will discuss transaction processing as it relates to the c-treeACE CodeGear VCL ISAM Component Framework - Delphi. Transaction processing provides a safe method by which multiple database operations spread across separate tables/files are guaranteed to be atomic. By atomic, we mean that, within a transaction, either all of the operations succeed or none of the operations succeed. This "either all or none" atomicity insures that the integrity of the data in related tables/files is secure. Like all other examples in the c-tree tutorial series, this tutorial simplifies the creation and use of a database into four simple steps: Initialize(), Define(), Manage(), and You’re Done() ! Tutorial #4: Transaction Processing Here we demonstrate transaction control. Initialize() - Connects to the c-treeACE Database Engine. Define() - Defines and creates our four tables/files. Manage() - Adds rows/records to multiple tables/files under transaction control. Done() - Disconnects from c-treeACE Database Engine. Note our simple mainline: We suggest opening the source code with your own editor. Continue now to review these four steps. Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation Init First we need to open a connection to a database by providing the c-treeACE Database Engine with a user name, password and the database name. Below is the code for Initialize() c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Define The Define() step is where specific data definitions are established by your application and/or process. This involves defining columns/fields and creating the tables/files with optional indices. Below is the code for Define() Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation Check_Table_Mode(TabOrderList); end; end; var do_create : boolean; begin do_create := false; try // try to open the table TabOrderItem.Table := 'ORDERITEMS'; TabOrderItem.Active := true; except // table may not exist, try creating it do_create := true; end; if do_create then begin try // add fields to table TabOrderItem.AddField('oi_ordernum', CT_STRING, 7); TabOrderItem.AddField('oi_seqnumber', CT_INT2, 2); TabOrderItem.AddField('oi_itemnum', CT_STRING, 6); TabOrderItem.AddIndex('orderitem', CTINDEX_FIXED, false, false); TabOrderItem.AddSegment('orderitem', 'oi_ordernum', CTSEG_SCHSEG); TabOrderItem.AddSegment('orderitem', 'oi_seqnumber', CTSEG_SCHSEG); TabOrderItem.CreateMode := CTCREATE_TRNLOG; c-treeVCL Developer's Guide www.faircom.com All Rights Reserved TabItemMast.AddIndex('itemnum', CTINDEX_FIXED, false, false); TabItemMast.AddSegment('itemnum', 'im_itemnum', CTSEG_SCHSEG); TabItemMast.CreateMode := CTCREATE_TRNLOG; Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation // This scenario arises out of the fact that this table was created in tutorial 1 without c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Manage The manage step provides data management functionality for your application and/or process. Below is the code for Manage() Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation c-treeVCL Developer's Guide www.faircom.com All Rights Reserved begin // clear the record buffer TabCustMast.ActiveRecord.Clear; Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation StringGrid1.RowCount := StringGrid1.RowCount + 1; counter := counter + 1; bOrderItem := TabOrderItem.ActiveRecord.Next; end; bOrderList := TabOrderList.ActiveRecord.Next; end; except on E : ECtError do Application.ShowException(E); end; end; c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Chapter 2 Quick Tour FairCom Corporation Copyright 2008 FairCom Corporation Additional Resources We encourage you to explore the additional resources listed here: www.faircom.com All Rights Reserved Chapter 3 Programmer's Reference This chapter provides step-by-step instructions for integration of the c-treeVCL/CLX components into applications. session Chapter 3 Programmer's Reference FairCom Corporation Copyright 2008 FairCom Corporation Using code To make changes while an application is running (in response to an event, for example), it is necessary to write actual code that modifies a property. Choose the Events tab in the Object Inspector to see all of the events associated with a component. Double-click those events to enter the event-handling code for each. Examples on how to code property changes are in ensuing sections of the User Guide. 3.2 Error handling All of the c-tree Plus Data Access components indicate error conditions by raising an exception of type ECtError ECtError is a class derived from the Borland Exception Handling class, thus all normal VCL exception handling routines will work when handling ECtError exceptions. It is generally best to have a user-defined function, perhaps named ShowException() , that is called when an exception is caught to display the error message and number. "Component Reference" has more information on ECtError This particular sample shows the setting of some important properties to c-tree Plus. The three initial properties set are the server name, user name and user password. They are required for a client/server application and are ignored for a stand-alone application. The fourth property, Directory, indicates the directory where the session dictionary (in this sample) will be created. Other Session properties are described in the component reference chapter. Delphi Example C++ Example c-treeVCL Developer's Guide www.faircom.com All Rights Reserved 3.3 Using the Session Component Creating a new session The c-treeVCL/CLX interface requires a session to perform any data structure initialization or manipulation. All database information is stored inside the session dictionary, ctdbdict.fsd , which is located by default either in the server directory (client/server application) or in the application directory (stand-alone application). A session dictionary must exist to initialize c-treeVCL/CLX, and the user must logon to a session to operate on a database. If the user tries to create a session dictionary and one already exists in the desired directory, an error or exception will occur. The same session dictionary (as well as the database dictionaries) may be used in both standalone and client/server environments, although it is not a good practice to use both at the same time, since no files should be opened by the server and a stand-alone application at the same time. To create a new session dictionary at design time, take the following steps: 1. Drop a TCtSession component on the form. Chapter 3 Programmer's Reference FairCom Corporation Copyright 2008 FairCom Corporation C++ Example Log On to c-tree Before any c-tree Plus database or table operations can be performed by an application, it is necessary to log on to a c-tree session. To log on to a c-tree session at design time, execute the following steps: 1. Drop a TCtSession component on the form. to learn how to create a session dictionary. To log on to a c-tree session at run time, execute the following steps, after the TCtSession component has been dropped on the form: c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Delphi Example C++ Example In the examples discussed above, the default value for some properties like Bufs, Dbufs, Fils, Sect, Tag, and UserProf were not modified. The default value for these properties is enough for most applications, though the advanced user may fine-tune an application using custom values. See the discussion for each of these properties in "Component Reference" . This chapter has more information TCtSession and the related methods, properties and events. AutoCreate Property When the TCtSession AutoCreate property is set to true, a session dictionary is automatically created during a session logon. The session dictionary is created only if the session logon fails due to the non-existence of a session dictionary. In this case the session dictionary is created and the session logon is retried. 3.4 Using the Database Component A database may be considered a collection of tables. It is possible to have multiple databases in one session. To operate on the tables using c-treeVCL/CLX, a connection with a database is required. Before connecting with a specific database, it must be created. Chapter 3 Programmer's Reference FairCom Corporation Copyright 2008 FairCom Corporation Notice that c-treeDB allows the operation on tables without a database or session dictionary. This is not implemented in c-treeVCL/CLX at the present time. Creating a New Database Use the following procedure to create a new database at design time: 1. Log on to a c-tree Plus session (refer to “Log On to c-tree” 2. Drop a TCtDatabase component on a form. c-treeVCL Developer's Guide www.faircom.com All Rights Reserved AutoCreate Property When the TCtDatabase AutoCreate property is set to true, a database dictionary is automatically created during a database connect. The database dictionary is created only if the database connect fails because no database dictionary exists. In this case the database dictionary is created and the database connect operation is retried. Connecting to a Database It is necessary to connect to a database before creating a c-tree Plus table and/or manipulating data stored in a c-tree Plus table. To connect to a database at design time, execute the following steps: 1. Log on to a c-tree Plus session (refer to “Log On to c-tree” 2. Drop a TCtDatabase component on a form. Chapter 3 Programmer's Reference FairCom Corporation Copyright 2008 FairCom Corporation C++ Example Once again, it is important to disconnect from the database before closing the application. If, for any reason, the user logs off from the session, the database is automatically disconnected. To disconnect a database, either set its Active property to False or call the Disconnect method. It is also possible to disconnect from all active databases at once using the TCtSession DisconnectAll() method. Dropping a Database from the Session A database that is dropped from the session is eliminated from the session dictionary (the user is no longer able to connect to it), but it is kept on disk. It is possible to add back a dropped database to a session. Use the following procedure to drop a database from a session at run time: 1. Log on to a c-tree Plus session (refer to “Log On to c-tree” 2. Drop a TCtDatabase component on a form. c-treeVCL Developer's Guide www.faircom.com All Rights Reserved CtDatabase1-Database = "MyData"; CtDatabase1-Session = CtSession1; CtDatabase1-DropDatabase(); } catch (ECtError& E) { Application-ShowException(&E); } } 2. Drop a TCtDatabase component on a form. Chapter 3 Programmer's Reference FairCom Corporation Copyright 2008 FairCom Corporation 2. Drop a TCtDatabase component on a form. c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Creating a Table Creating a new table may be one of the most crucial operations performed by a database developer or administrator. The c-treeDB API offers a powerful, yet easy to use, mechanism for creating tables.Creating a table The create table process does not leave the table open after the table is created. The user must explicitly open the table to be able to add data records and query any of the table properties. The create table process involves the following steps: 1. Create a new TCtTable component 2. Add, insert or delete fields CT_BOOL CT_BOOL CTBOOL One byte Boolean CT_TINYINT CT_CHAR CTSIGNED Signed one byte integer. CT_UTINYINT CT_CHARU CTUNSIGNED Unsigned one byte integer. CT_SMALLINT CTSIGNED Signed two-byte integer. CT_USMALLINT CTUNSIGNED Unsigned two-byte integer. Chapter 3 Programmer's Reference FairCom Corporation Copyright 2008 FairCom Corporation Field Type c-tree Plus Field Type Equivalent Data Type Implementation CT_INTEGER CTSIGNED Signed four-byte integer. CT_UINTEGER CTUNSIGNED Unsigned four-byte integer. CT_MONEY CT_MONEY CTMONEY CT_DATE CT_DATE CT_TIME CT_TIME CTTIME CT_FLOAT CT_SFLOAT CTFLOAT Four-byte floating point. CT_DOUBLE CTFLOAT Eight-byte floating point. CT_TIMESTAMP CT_TIMES CT_EFLOAT CT_EFLOAT CTFLOAT Extended precision floating point (not supported as a key segment). CT_BINARY CT_ARRAY pTEXT, pUTEXT Arbitrary fixed length data. Fixed length binary data CT_CHARS pTEXT Fixed length delimited data. Fixed length string data CT_FPSTRING CT_FPSTRING pTEXT Fixed length data with 1-byte length count CT_F2STRING CT_F2STRING pTEXT Fixed length data with 2-byte length count CT_F4STRING CT_F4STRING pTEXT Fixed length data with 4-byte length count CT_BIGINT CT_BIGINT Eight-byte signed integer CT_NUMBER CT_NUMBER CTNUMBER Scaled BCD number CT_CURRENCY CT_CURRENCY CTCURRENCY CT_PSTRING CT_PSTRING pTEXT Varying length field data with 1-byte length count. CT_VARBINARY CT_2STRING pTEXT Varying length field data with 2-byte length count. Variable length binary data of up to 65535 bytes. CT_LVB CT_4STRING pTEXT Varying length field data with 4-byte length count. Variable length binary data of up to 4294967295 bytes. CT_VARCHAR or CT_LVC pTEXT Varying length field delimited data. Variable length string data. c-treeVCL Developer's Guide www.faircom.com All Rights Reserved BOOL TINYINT SMALLINT USMALLINT INTEGER UINTEGER MONEY TIME FLOAT DOUBLE TIMESTAMP EFLOAT BINARY CHARS FPSTRING BIGINT NUMBER CURRENCY PSTRING VARBINARY LVB VARCHAR/LVC Fixed or variable length records Chapter 3 Programmer's Reference FairCom Corporation Copyright 2008 FairCom Corporation variable length field is encountered. The variable length fields are listed below, with the matching c-tree Plus data type in parentheses: Any type of field can be placed anywhere in the record buffer and also be used as an index segment. c-treeVCL/CLX makes full use of this feature by providing the user with an advanced dynamic record buffer management. Hidden fields There are three special fields that are automatically included by c-treeVCL/CLX into the table record definition. c-treeSQL makes extensive use of the null flag and rowid fields: record size than the original record, thus the RECBYT index cannot be used as a unique record identifier. By default, c-treeVCL/CLX creates the three hidden fields. Tables created with c-tree Plus will not include these fields by default. c-treeDB does not require the fields to operate, but they allow more advanced capabilities. When creating a new table, users may disable the inclusion of the hidden fields by using the create modes CTCREATE_NONULFLD CTCREATE_NODELFLD CTCREATE_NOROWID The default table layout is presented below. Note: The first field added by the user is always field 0. $DELFLD$ $NULFLD$ $ROWID$ user fi eld 0 user field 1 ... user field n c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Adding or deleting indices Indices and index segments are key-based search tools that make record seeking faster and more efficient. An index is a mapping table that contains keys describing certain records and pointers to those records. An index segment describes the table field from which the keys are used. Indices are added to the table definition in the order they are declared. The c-treeVCL/CLX table components also includes a set of functions that will allow an index to be deleted from the table index definition. AddIndex() adds a new index at the end of the table index definition. For each index added to the table, one or more index segments define which field combination forms a particular index. AddSegment() adds segments to an index. The valid c-treeDB/c-treeVCL index types are: Index Type CTINDEX_FIXED FIXED_INDEX Fixed length key CTINDEX_LEADING LEADING_INDEX Fixed length keys that are likely to have leading character duplication among the key values CTINDEX_PADDING PADDING_INDEX Variable length keys for which not much leading character duplication is expected. CTINDEX_LEADPAD LEADPAD_INDEX Variable length keys for which much leading character duplication is expected. CTINDEX_ERROR ERROR_INDEX Index type error. Chapter 3 Programmer's Reference FairCom Corporation Copyright 2008 FairCom Corporation CTSEG_SCHSEG SCHSEG_SEG Absolute field number CTSEG_USCHSEG USCHSEG Absolute field number - uppercase CTSEG_VSCHSEG VSCHSEG Absolute field number - pad strings CTSEG_UVSCHSEG UVSCHSEG Absolute field number - pad strings upper CTSEG_SCHSRL SCHSRL Absolute field number - auto increment CTSEG_DESCENDING DESCENDING Descending segment mode CTSEG_ALTSEG ALTSEG Alternative collating sequence CTSEG_ENDSEG ENDSEG END segment mode The other segment modes are kept for compatibility with existing c-tree Plus applications. Advanced c-treeDB functions like ctdbAlterTable() may not work properly if the segment mode is not one of the preferred segment modes. You may specify these segment modes with ctdbAddSegmentEx() , which expects an absolute record CTSEG_REGSEG REGSEG CTSEG_INTSEG INTSEG CTSEG_UREGSEG UREGSEG CTSEG_SRLSEG SRLSEG CTSEG_VARSEG VARSEG Relative field number CTSEG_UVARSEG UVARSEG Relative field number - uppercase CTSEG_SGNSEG SGNSEG CTSEG_FLTSEG FLTSEG CTSEG_DECSEG DECSEG CTSEG_BCDSEG BCDSEG CTSEG_DESCENDING DESCENDING Descending segment mode CTSEG_ALTSEG ALTSEG Alternative collating sequence c-treeVCL Developer's Guide www.faircom.com All Rights Reserved When a table is created with rowid support, a ROWID index is automatically created for the table. The operation of the ROWID index is transparent to the c-treeDB user. c-treeDB will automatically update the index entries. The ROWID index will not appear in the list of indexes for a table. The user cannot below for more information on the table properties. Table Create Modes c-treeDB Table Create Mode CTCREATE_NORMAL NORMAL_CREATE 0 Normal table creation. Use this mode when no other create mode apply. Chapter 3 Programmer's Reference FairCom Corporation Copyright 2008 FairCom Corporation c-treeDB Table Create Mode CTCREATE_PREIMG PREIMG_CREATE 1 This mode implements transaction processing for a table but does not support automatic file recovery. Files with CTCREATE_PREIMG mode do not take any space in the system transaction logs. CTCREATE_TRNLOG TRNLOG_CREATE CTCREATE_CHECKL CHECKLOCK_CREA 8 Tables created with this mode requires a record lock before a record can be updated. If a lock is not obtained, the error code DADV_ERR VRLEN_CREATE CTCREATE_NORECB NORECBYT_CREAT Create the table without the RECBYT index. CTCREATE_NOROWI NOROWID_CREATE Create the table without the ROWID index. CTCREATE_CHECKR CHECKREAD_CREA 128 Tables create with this mode requires a record lock as records are read. Obtain at least a read lock on a record before it can be read, otherwise the function will CTCREATE_HUGEFIL HUGEFILE_CREATE 256 Create the table with huge file support. With this mode on, tables will support 8 CTCREATE_NODELFL NODELFLD_CREAT 512 This mode indicate that the create is to be created without the $DELFLD$ support. c-treeVCL Developer's Guide www.faircom.com All Rights Reserved c-treeDB Table Create Mode CTCREATE_NONULFL NONULFLD_CREAT 1024 This mode indicate that the table is to be created without the support. Creating the Table After all fields and indices have been defined and the table properties set, it is time to create the table by calling the Chapter 3 Programmer's Reference FairCom Corporation Copyright 2008 FairCom Corporation Creating a Table Under Transaction Control You can add an extra level of data integrity when creating a new table by placing the code to create a table inside a transaction. If the transaction is aborted, the table entry in the database dictionary file is removed, and the table data and index files are deleted from disk. When a table is created inside a transaction, and until the transaction is committed or aborted, the newly created table must be opened with CTOPEN_EXCLUSIVE mode, otherwise the table open operation will fail. After the transaction is committed the table can be opened in non-exclusive mode. The code fragment below creates a new table under transaction control. Again no error checking code is included in the example: Delphi Example c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Opening a table A table must be opened before any data operations within it can take place. Use TCtTable Active property or Open() method to open a table. After opening the table, usual operations like add, update, Records” . Before opening a table, set the appropriate table open mode: Open Mode CTOPEN_NORMAL NORMAL_OPEN Use this mode if no other open modes apply. CTOPEN_DATAONLY DATAONLY_OPEN Open only the data table. Used to rebuild a table that may or may not be missing indices. CTOPEN_EXCLUSIVE EXCLUSIVE_OPEN This mode opens the table as exclusive. If this mode is used, only one user can open a table. If an application already has the file open in any mode, no other application can open the table as CTOPEN_EXCLUSIVE Once an application opens a table as CTOPEN_EXCLUSIVE application can open it. Reads and writes are cached for index files opened with this file mode since there are no integrity issues with only one process in the file. CTOPEN_PERMANENT PERMANENT_OPEN Many operating systems and/or C compiler run-time libraries limit the number of files that can be opened at one time. A permanent file open causes the file to be opened and stay open until the program executes a file close. A non-permanent file open causes the table data and index files to be opened, but allows them to be transparently closed and reopened to allow other data and index files to be used. When it is necessary for a data and index file to be temporarily closed, c-tree Plus selects the least recently used file. This file remains closed until it is used, at which time it will be automatically reopened. This strategy causes c-tree Plus to use all available file descriptors. Chapter 3 Programmer's Reference FairCom Corporation Copyright 2008 FairCom Corporation Open Mode CTOPEN_CORRUPT CORRUPT_OPEN This mode opens tables with corrupted indexes or in certain cases, tables with corrupted data. With c-treeDB this mode is usually used in conjunction with ctdbAlterTable() mode to perform a rebuild if the indexes became corrupted: open table with CTOPEN_CORRUPT mode, then call ctdbAlterTable() with CTDB_ALTER_INDEX mode to force the rebuild of all indices of the table. You can also specify ctdbAlterTable() mode CTDB_ALTER_INDEX CTDB_ALTER_PURGEDUP ) to purge any duplicate records that may cause the index rebuild to fail. If a table table becames corrupt, the table may be open with CTOPEN_CORRUPT mode and then ctdbAlterTable() with CTDB_ALL_FULL is invoked to try to recover the table. CTOPEN_CHECKLOCK CHECKLOCK_OPEN Tables opened with this mode requires a record lock before a record can be updated. If a lock is not obtained, the error code DADV_ERR CTOPEN_CHECKREAD CHECKREAD_OPEN Tables opened with this mode requires a record lock as records are read. Obtain at least a read lock on a record before it can be CTOPEN_READONLY READONLY_OPEN Opens the table in READONLY mode and does not allow any modifications to the table structure or data records. c-treeVCL Developer's Guide www.faircom.com All Rights Reserved C++ Example Altering an existing table The c-treeVCL/CLX alter table method was designed and implemented to allow the modification of table, field and index properties after a table was created, and possibly already populated with data. The usual steps to perform an alter table are: Chapter 3 Programmer's Reference FairCom Corporation Copyright 2008 FairCom Corporation Most changes relating to indices will trigger the AlterTable() method to perform only an index rebuild. If only one index is affected, ctdbAlterTable() will only rebuild the affected index. If changes affect more than one index, ctdbAlterTable() may rebuild all indices. After a successful alter table, all records associated with the altered table will automatically re-initialize to reflect any new table field and index definitions. Alter the table AlterTable() scans the table, field, index, and segment structures to decide which changes need to be made and how to do it. At the very least, it may only update the DODA . If more than one index changed, or more than one index was added or deleted, then it may be necessary to rebuild all indices of the CTDB_ALTER_NORMAL 0 Check for table changes before altering the table and perform only the changes required. CTDB_ALTER_INDEX 1 Force rebuild of all indexes, regardless of table changes. CTDB_ALTER_FULL 2 Force full table rebuild, regardless of table changes. Adding an index to a table If you need to add one or more indices to an existing table, perform the following steps: Add the index by calling AddIndex() . Repeat this step for each new index. Add, insert or delete index segments by calling AddSegment() InsertSegment() or DeleteSegment() methods. Repeat this step for each segment of the index. Call AlterTable() to add the new index Deleting an index from a table c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Forcing a Table Rebuild There may be situations where you may need to force a full table rebuild. Please remember that in a full table rebuild a temporary table is created based on the properties of the original table, all records are read from the original table and written into the temporary table. All indices are also rebuilt. Once all data records have been moved, the original table is deleted and the temporary table is renamed with the name of the original table. To force a table rebuild call AlterTable() with CTDB_ALTER_FULL 2. Connect to a database (please refer to “Connecting to a database” 3. Drop a TCtTable component on a form. Chapter 3 Programmer's Reference FairCom Corporation Copyright 2008 FairCom Corporation 7. Call the AddTable() method. The code excerpts below represent a table being added to a database at run time. There is no way to add a table at design time. Delphi Example C++ Example Dropping a Table from a Database A table that is dropped from the database is eliminated from the database dictionary (the user is no longer able to retrieve its information from the database), but it is kept on the disk. It is possible to add back a dropped table to a database. Use the following procedure to drop a table from a database: 1. Log on to a c-tree Plus session (please refer to “Log On to c-tree” 2. Connect to a database (please refer to “Connecting to a database” 3. Drop a TCtTable component on a form. c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Delphi Example C++ Example 2. Connect to a database (please refer to “Connecting to a database” 3. Drop a TCtTable component on a form. Chapter 3 Programmer's Reference FairCom Corporation Copyright 2008 FairCom Corporation C++ Example 2. Connect to the database (please refer to “Connecting to a database” 3. Open the table ( refer to “Opening a table” and “Closing a table” 4. Call the c-treeVCL Developer's Guide www.faircom.com All Rights Reserved C++ Example To update a record (instead of adding a new one), retrieve the record to be updated using one of the search functions discussed in Selecting Records, then call the 2. Connect to the database (please refer to “Connecting to a database” 3. Open the table ( refer to “Opening a table” and “Closing a table” 4. Locate the first record using First() 5. Update the fields that have changed. 6. Call Post() to update the current record. Note that the first record is being retrieved without checking which index is used. The searching methods will be discussed in the topic “Selecting Records”. In the current topic, the update is the central point of interest. The following excerpts implement this sequence at run time. Note that just one of the fields, Age, has been changed from some value to 44. Delphi Example C++ Example Chapter 3 Programmer's Reference FairCom Corporation Copyright 2008 FairCom Corporation try { CtTable1-Table = "MyTable"; CtTable1-Database = CtDatabase1; CtTable1-Active = true; CtTable1-First; CtTable1-FieldByName("Age")-AsInteger=44; CtTable1-Post; } catch (ECtError& E) { Application-ShowException(&E); } } 2. Connect to the database (please refer to “Connecting to a database” 3. Open the table ( refer to “Opening a table” and “Closing a table” 4. Locate the first record using First() 5. Delete the record using Delete() Note that the first record is retrieved without checking which index is used. The searching methods will c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Use the following procedure to add new data to a c-tree Plus table using the c-treeDB methodology: 1. Log on to a c-tree Plus session (please refer to “Log On to c-tree” 2. Connect to the database (please refer to “Connecting to a database” 3. Open the table ( refer to “Opening a table” and “Closing a table” 4. Create a record buffer. 5. Clear the record buffer with a call to Clear() Chapter 3 Programmer's Reference FairCom Corporation Copyright 2008 FairCom Corporation c-treeVCL/CLX allows the user to define filters on the record. When a filter is set, all records retrieved from the table will be filtered against the given expression, and just those records that match the filter criteria will be returned. A filter is activated by setting the table Filter property with a string containing the filter expression and setting the table Filtered property to true. Only the user who sets the filter will have its records filtered. The filter is turned off when the table is closed, or when the Filtered property is set to false. Just one filter may be active per table per user at once, so if a new filter is set, the old filter will be overridden. When used in the client/server model, this feature has the potential to increase the performance since just the records matching the criteria will be returned, reducing the network traffic. Constants The expression parser uses the constants below internally as a 32-bit signed or unsigned integer: Character constants: any valid char enclosed in single quotes, e.g., ‘a’ Signed Integer constants: values from - 2,147,438,647 to 2,147,438,647 Unsigned Integer constants: values from 0 to 4,294,967,295 Hexadecimal constants: values from 0x00000000 to 0xffffffff. Any combination of lowercase or upper \a or \A ASCII 7 bell \b or \B ASCII 8 backspace \f or \F ASCII 12 Form Feed \n or \N ASCII 10 Linefeed \t or \T ASCII 9 tab \v or \V ASCII 11 vertical tab \\ \any Any character not listed above c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Variables A filter expression variable is actually the name of the fields defined for the table. There is a limit of 128 characters for the name of variables and the names are case sensitive. When a user specifies a variable name, the filter parser searches the table definition for a field of that name. The parser uses the type of the field and converts it to the types used internally by the expression evaluator. The conversion of field types is as follows: Field Type Data Type Field Type Data Type CT_BOOL CT_SFLOAT double CT_CHAR CT_DFLOAT double CT_CHARU unsigned char* CT_FPSTRING char* unsigned CT_F2STRING char* CT_F4STRING char* unsigned char* CT_DATE unsigned CT_PSTRING char* CT_TIME unsigned CT_2STRING char* CT_MONEY CT_4STRING char* Please note that “int” is a LONG , “unsigned” is a ULONG and “char*” is a pTEXT Filter expression syntax Filters provide a powerful expression parser/analyzer to provide automatic record filtering so that complex expressions can be defined and evaluated at run time. Filter expression syntax closely follows the C syntax for expressions, including order of precedence. An expression interpreted by the conditional expression parser should compile without errors with a standard C compiler. Like C, you cannot compare strings directly like LastNam e ‘S’. However, the expression parser has a number of built-in functions that allow the comparison of strings. Example: Parentheses Use parentheses exactly like they are used in C expressions. There are no limits on the number of parentheses you may use in an expression, as long as each open parenthesis has a closing parenthesis. Parentheses are also used to enclose the arguments of built-in functions. Predefined Functions The conditional expression parser has a number of built-in functions to make the use of expressions easier. The built-in functions closely follow the C library functions: Function Explanation int atoi( char* String ) convert string to integer Chapter 3 Programmer's Reference FairCom Corporation Copyright 2008 FairCom Corporation Function Explanation int atol( char* String ) convert string to long double atof( char* String ) convert string to double int strcmp( char* s, char* t ) compare two strings int stricmp( char* s, char* t ) compare strings without regard to case int strncmp( char* s, char* t, int len) compare characters of two strings int strnicmp( char* s, char *t, int len ) compare characters of two strings without regard to case int memcmp(char* s, char *d, int len) compare bytes of two memory locations Type Casting The filter expression parser allows you to use explicit type casts in expressions. This is very useful if you are comparing fields of different types and want to control the result of an expression. For example, suppose “Salary” is a CT_MONEY field and “Average” is a CT_DFLOAT field; type casts can be used as illustrated in the following expression: (Salary - (int)Average) 500 The following type casts may be used in conditional expressions: (int) or (long): Convert the result of expression to integer (32 bit). (unsigned [int | long]): Convert the result of expression to unsigned integer (32 bit). (double): Convert the result of expression to double. You cannot type cast a string expression. Automatic Type Promotion When mixing different types in an expression without explicit type casting, the conditional expression parser automatically promotes the types using the following rule: signed and unsigned integers: promoted to unsigned integer signed integer and double: promoted to double unsigned integer and double: promoted to double In the great majority of cases, mixing strings with numeric values returns a parsing error. c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Operators The following operators are allowed in conditional expressions: Mathematical operators + Adds two operands - Subtracts two operands or negates an operand (e.g., -5) * Multiplication / Division % Modulus Relational operators == Equal to != Not equal to Less than = Less or equal to Greater than = Greater than or equal to Logical operators && And || Or ! Not Binary operators & And | Or ~ Not ^ Xor Selecting Records c-treeVCL/CLX has multiple ways to search records. Being a , in the TCtRecord class. Of particular interest are the search methods First() Next() Prev() Last() Find() 2. Connect to the database (refer to “Connecting to a database” Chapter 3 Programmer's Reference FairCom Corporation Copyright 2008 FairCom Corporation 3. Open the table (refer to "Opening a table” and “Closing a table” 4. Create a record buffer. 5. Select the default index to be used in the search. 6. Locate the first record using First() 7. Start up a loop. 8. Follow to the next record. Delphi Example c-treeVCL Developer's Guide www.faircom.com All Rights Reserved ROWID - this unique index represents the ordering of the table by input order. To set this index as the default, the DefaultIndex property should be set to CTDB_ROWID_IDXNO DBNavigator Data-aware navigation buttons that move a table's current record pointer forward or backward. The navigator can also place a tabl e in Insert, Edit, or Browse state, post new or modified records, and retrieve updated data to refresh the display. DBText Data-aware label that displays a field value in the current record. DBEdit Data-aware edit box that displays or edits a field in the current record. DBMemo Data-aware memo box that displays or edits BLOB text in the current record. DBImage Data-aware image box that displays, cuts, or pastes bitmapped BLOB images to and from the current record. DBListBox Data-aware list box that displays a scrolling list of values from a column in a table. DBComboBox Data-aware combo box that displays or edits a scrolling list of values from a column in a table. DBCheckBox Data-aware check box that displays or edits a Boolean data field from the current record. Chapter 3 Programmer's Reference FairCom Corporation Copyright 2008 FairCom Corporation DBLookupListBox Data-aware list box that derives its list of display items from a Lookup field defined DBLookupComboBox Data-aware combo box that derives it s drop-down list of display items from either a 3.6 Working without the Visual Components c-treeVCL Developer's Guide www.faircom.com All Rights Reserved 3.7 Data Integrity Transactions There are two major aspects to transaction processing, atomicity and automatic recovery. These are related yet different aspects of transaction processing, and not all products supply both. c-treeDB provides a set of functions and file modes that cover both aspects of transaction processing. Atomicity Often, when updating a table, you perform several functions in a group. For instance, when creating an invoice, you update several tables: the account balance in the customer file, the invoice file, an invoice Chapter 3 Programmer's Reference FairCom Corporation Copyright 2008 FairCom Corporation Record locks are held on updated records for the duration of the transaction, so you don't want to make the transaction group too large or it will consume the system resources. On the other hand, you may not want to make the transaction group too small or the effect of grouping actions is lost. Terminating a transaction c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Session Wide Lock Modes Lock Modes CTLOCK_FREE FREE_LOCK Free all locks. Free the data record lock. CTLOCK_READ READ_LOCK Non-blocking read locks. If the lock cannot be acquired an error is returned. CTLOCK_READ_BLOCK READ_BLOCK_LOCK Blocking read lock. The thread will block until the lock can be acquired. CTLOCK_WRITE WRITE_LOCK Non-blocking write lock. If the lock cannot be acquired an error is returned. CTLOCK_WRITE_BLOC WRITE_BLOCK_LOCK Blocking write lock. The thread will block until the lock can be acquired. CTLOCK_SUSPEND SUSPEND_LOCK Temporarily suspend locking. CTLOCK_RESTORE _READ RESTORE_READ_LOC To be used after a call to Lock with the CTLOCK_SUSPEND mode. This lock mode restores the lock mode as CTLOCK_RESTORE _READ_BLOCK RESTORE_READ _BLOCK_LOCK To be used after a call to Lock with the CTLOCK_SUSPEND mode. This lock mode restores the lock mode as READ_BLOCK CTLOCK_RESTORE _WRITE RESTORE_WRITE_LO To be used after a call to Lock with the CTLOCK_SUSPEND mode. This lock mode restores the lock mode as WRITE CTLOCK_RESTORE _WRITE_BLOCK RESTORE_WRITE _BLOCK_LOCK To be used after a call to Lock with the CTLOCK_SUSPEND mode. This lock mode restores the lock mode as WRITE_BLOCK CTLOCK_RESTORE _PREVIOUS To be used after a call to Lock with the CTLOCK_SUSPEND mode. This lock mode restores the same lock mode valid before suspending the lock. Chapter 3 Programmer's Reference FairCom Corporation Copyright 2008 FairCom Corporation 1. Instantiate a TCtResource object using one of the TCtResource constructors. c-treeVCL Developer's Guide www.faircom.com All Rights Reserved 1. Instantiate a TCtResource object by calling one of the TCtResource constructors. You should pass at least the resource type and number. The resource name is optional. If you use a TCtResource constructor that does not take the resource type and number, you need to set the TCtResource.TypeID and TCtResource.Number properties before you add a new resource. 2. Call the TCtResource.Add() method to add the new resource passing the resource data and the length of the data. 3. Once the TCtResource object is no longer needed, destroy the object to release any system resources. To add a new resource you must call the following TCtResource method: is any collection of data that you wish to store as a Resource. It can be a character string, a structure, or any variable type. size indicates the number of bytes occupied by data Chapter 3 Programmer's Reference FairCom Corporation Copyright 2008 FairCom Corporation Example c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Reading resources There are four different ways of reading resources from a table: read all table resources, read all resources starting past a resource type and number, read an specific resource by specifying resource type and number, and read a resource by specifying its name. Read all resource starting with the first resource by calling method TCtResource.First() method and then read the remaining resources by calling TCtResource.Next() . To read the first resource in a table, call the following method: TCtResource.First() method retrieve the first resource stored in a table. Parameter lock is used to indicate if the resource should be locked, if it is found. TCTResource.First() return true if the resource Chapter 3 Programmer's Reference FairCom Corporation Copyright 2008 FairCom Corporation Read a specific resource by providing exact resource type and number by calling TCtResource.Find() Locate and retrieve a resource in a table based on type and number. TypeID is a value of the resource type and number is the value of the resource number to be located. lock is used to indicate if the resource should be locked, if it is found. TCtResource.Find() return true if the resource is found or false if this particular resource was not found. If an error occurs, TCtResource.Find() throws an ECtError exception. Example Read a resource by providing its name by calling TCtResource.Find() TCtResource.Find() locates and retrieves a resource by name. c-tree Plus can not guarantee unique resource names. is the resource name being located and lock indicates if the resource should locked, if it is found. TCtResource.Find() returns true if the resource is located or false if no resource is located. If errors are detected a ECtError exception object is thrown. Example c-treeVCL Developer's Guide www.faircom.com All Rights Reserved end; hRes.Free; end; TypeID LongWord Get or set the resource type. Number LongWord Get or set the resource number. Resource String Get or set the resource name. Locked Boolean Indicate if resource is locked. Read-only. DataLength Integer Get the number of bytes in resource data. Read-only. Pointer Get a pointer to the resource data. Read-only. The example below show how to use the TCtResource properties. Example Chapter 3 Programmer's Reference FairCom Corporation Copyright 2008 FairCom Corporation c-treeVCL resource handling code will automatically unlock resources were necessary, but resources can be manually unlocked by the user. Use the following property to check if a resource is locked or not: TCtResource.Locked() returns true if the resource is locked, otherwise it returns false. The following method should be used to unlock resources whose locks are no longer necessary: TCtResource.Unlock() releases a lock placed on a resource by one of the following read resource functions: TCtResource.First() TCtResource.Next() TCtResource.Find() Example 3.9 Compatibility Compatibility with c-tree Plus ISAM and Low-level Data Files The basic requirement for c-tree Plus ISAM and low-level data and index files to work with c-treeDB is that the data file must have describing the fields and an describing the data and index structures. The resource must have an entry for every field that forms a data record. The c-treeDB interface was designed to work best with ISEG structures with schema segments, that is, each index segment is a field declared in a DODA entry. c-treeDB works with index segments defined in ISEG c-treeVCL Developer's Guide www.faircom.com All Rights Reserved c-treeDB was designed from the outset to be as compatible as possible with existing c-tree ISAM and low-level data, however, there are situations where c-treeDB may not be able to handle very specific data type arrangements used by c-tree Plus users in their custom applications. Compatibility with c-treeSQL Tables created with c-treeDB are 100% compatible with c-treeSQL, even when tables are created without RECBYT or ROWID indices. Tables created with c-treeDB but without transaction processing flags will not be able to participate in SQL transactions or transaction isolation levels. BIT CT_BOOL TINYINT CT_TINYINT SMALLINT CT_SMALLINT INTEGER CT_INTEGER FLOAT CT_FLOAT DOUBLE CT_DOUBLE CT_UINTEGER CHAR CT_CHARS VARCHAR CT_VARCHAR LVARCHAR CT_LVARCHAR BINARY CT_BINARY VARBINARY CT_VARBINARY LVARBINARY CT_LVARBIN DATE CT_DATE TIME CT_TIME TIMESTAMP CT_TIMESTAMP BIGINT CT_BIGINT MONEY CT_CURRENCY NUMBER, NUMERIC, DECIMAL CT_NUMBER Chapter 3 Programmer's Reference FairCom Corporation Copyright 2008 FairCom Corporation Migrating c-tree Plus files This topic is only relevant to current or new c-tree Plus ISAM and Low-level developers migrating to c-treeVCL/CLX, c-treeDB, and c-treeSQL. If a developer is using just the new interface technology without using the ISAM or Low-level interfaces, this section may be disregarded. The basic requirements for a set of c-tree Plus ISAM and Low-level data and index files to work with c-treeVCL/CLX is: The data file must have a DODA resource describing the record fields. The data file must have an resource describing the data and index file structure. The c-treeVCL/CLX interface works best with schema-based segments, where each index segment is a field declared in a entry. c-treeVCL/CLX works with index segments based on absolute record www.faircom.com All Rights Reserved Chapter 4 Component Reference The c-tree Plus Data Access Components, c-treeVCL, are composed of six components TCtSession TCtDatabase TCtTable TCtField TCtIndex TCtSegment , although only the first three of the six components are found in the component palette. Keep in mind that the c-treeVCL components are intended for c-tree Server V7.11 and later, and will not work with servers prior to V7.11. Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation 4.1 Class Hierarchy TObject TCtIndex TCtSegment TCtdbBase TCtdbDbase TCtdbSession TCtDatabase c-treeVCL Developer's Guide www.faircom.com All Rights Reserved 4.2 c-treeVCL/CLX Definitions This chapter collects tables of information for developers, including data types, field types, find modes, key types, lock modes, segment modes, table create modes, table open modes, table permissions, and error and return values. Data Types Symbolic Constant Explanation CTBOOL One byte Boolean CTSIGNED Signed numeric CTUNSIGNED Unsigned numeric CTFLOAT Float value Character string Simple date value CTTIME Time value CTMONEY Currency value A buffer of bytes Date Types Symbolic Constant Explanation CTDATE_MDCY Date is mm/dd/ccyy CTDATE_MDY Date is mm/dd/yy CTDATE_DMCY Date is dd/mm/ccyy CTDATE_DMY Date is dd/mm/yy CTDATE_CYMD Date is ccyymmdd CTDATE_YMD Date is yymmdd Time Types Symbolic Constant Explanation CTTIME_HMSP Time is hh:mm:ss am|pm CTTIME_HMP Time is hh:mm am|pm CTTIME_HMS Time is hh:mm:ss (24 hour) Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation Symbolic Constant Explanation CTTIME_HM Time is hh:mm (24 hour) CTTIME_MIL Time is hhmm (military) Find Modes Use the following find modes with the record find methods: Find mode EQ CTFIND_LT LT CTFIND_LE GE Note: The Find Mode CTFIND_EQ compose the index and the index cannot allow duplicates. Index Key Types Index Type CTINDEX_FIXED FIXED_INDEX Fixed length key CTINDEX_LEADING LEADING_INDEX Fixed length keys that are likely to have leading character duplication among the key values CTINDEX_PADDING PADDING_INDEX Variable length keys for which not much leading character duplication is expected. CTINDEX_LEADPAD LEADPAD_INDEX Variable length keys for which much leading character duplication is expected. CTINDEX_ERROR ERROR_INDEX Index type error. Record Lock Modes c-treeDB Record Lock Modes CTLOCK_FREE FREE_LOCK Free the data record lock c-treeVCL Developer's Guide www.faircom.com All Rights Reserved c-treeDB Record Lock Modes CTLOCK_READ READ_LOCK Non-blocking read locks CTLOCK_READ_BLOCK READ_BLOCK_LOCK Blocking read locks CTLOCK_WRITE WRITE_LOCK Non-blocking write locks CTLOCK_WRITE_BLOC WRITE_BLOCK_LOCK Blocking write locks Session Wide Lock Modes Lock Modes CTLOCK_FREE FREE_LOCK Free all locks. Free the data record lock. CTLOCK_READ READ_LOCK Non-blocking read locks. If the lock cannot be acquired an error is returned. CTLOCK_READ_BLOCK READ_BLOCK_LOCK Blocking read lock. The thread will block until the lock can be acquired. CTLOCK_WRITE WRITE_LOCK Non-blocking write lock. If the lock cannot be acquired an error is returned. CTLOCK_WRITE_BLOC WRITE_BLOCK_LOCK Blocking write lock. The thread will block until the lock can be acquired. CTLOCK_SUSPEND SUSPEND_LOCK Temporarily suspend locking. CTLOCK_RESTORE _READ RESTORE_READ_LOC To be used after a call to Lock with the CTLOCK_SUSPEND mode. This lock mode restores the lock mode as CTLOCK_RESTORE _READ_BLOCK RESTORE_READ _BLOCK_LOCK To be used after a call to Lock with the CTLOCK_SUSPEND mode. This lock mode restores the lock mode as READ_BLOCK CTLOCK_RESTORE _WRITE RESTORE_WRITE_LO To be used after a call to Lock with the CTLOCK_SUSPEND mode. This lock mode restores the lock mode as WRITE CTLOCK_RESTORE _WRITE_BLOCK RESTORE_WRITE _BLOCK_LOCK To be used after a call to Lock with the CTLOCK_SUSPEND mode. This lock mode restores the lock mode as WRITE_BLOCK Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation Lock Modes CTLOCK_RESTORE _PREVIOUS To be used after a call to Lock with the CTLOCK_SUSPEND mode. This lock mode restores the same lock mode valid before suspending the lock. CTSEG_SCHSEG SCHSEG_SEG Absolute field number CTSEG_USCHSEG USCHSEG Absolute field number - uppercase CTSEG_VSCHSEG VSCHSEG Absolute field number - pad strings CTSEG_UVSCHSEG UVSCHSEG Absolute field number - pad strings upper CTSEG_SCHSRL SCHSRL Absolute field number - auto increment CTSEG_DESCENDING DESCENDING Descending segment mode CTSEG_ALTSEG ALTSEG Alternative collating sequence CTSEG_ENDSEG ENDSEG END segment mode The other segment modes are kept for compatibility with existing c-tree Plus applications. Advanced c-treeDB functions like ctdbAlterTable() may not work properly if the segment mode is not one of the preferred segment modes. You may specify these segment modes with ctdbAddSegmentEx() , which expects an absolute record c-treeVCL Developer's Guide www.faircom.com All Rights Reserved CTSEG_REGSEG REGSEG CTSEG_INTSEG INTSEG CTSEG_UREGSEG UREGSEG CTSEG_SRLSEG SRLSEG CTSEG_VARSEG VARSEG Relative field number CTSEG_UVARSEG UVARSEG Relative field number - uppercase CTSEG_SGNSEG SGNSEG CTSEG_FLTSEG FLTSEG CTSEG_DECSEG DECSEG CTSEG_BCDSEG BCDSEG CTSEG_DESCENDING DESCENDING Descending segment mode CTSEG_ALTSEG ALTSEG Alternative collating sequence CTCREATE_NORMAL NORMAL_CREATE 0 Normal table creation. Use this mode when no other create mode apply. CTCREATE_PREIMG PREIMG_CREATE 1 This mode implements transaction processing for a table but does not support automatic file recovery. Files with CTCREATE_PREIMG mode do not take any space in the system transaction logs. CTCREATE_TRNLOG TRNLOG_CREATE Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation c-treeDB Table Create Mode CTCREATE_CHECKL CHECKLOCK_CREA 8 Tables created with this mode requires a record lock before a record can be updated. If a lock is not obtained, the error code DADV_ERR VRLEN_CREATE CTCREATE_NORECB NORECBYT_CREAT Create the table without the RECBYT index. CTCREATE_NOROWI NOROWID_CREATE Create the table without the ROWID index. CTCREATE_CHECKR CHECKREAD_CREA 128 Tables create with this mode requires a record lock as records are read. Obtain at least a read lock on a record before it can be read, otherwise the function will CTCREATE_HUGEFIL HUGEFILE_CREATE 256 Create the table with huge file support. With this mode on, tables will support 8 CTCREATE_NODELFL NODELFLD_CREAT 512 This mode indicate that the create is to be created without the $DELFLD$ support. CTCREATE_NONULFL NONULFLD_CREAT 1024 This mode indicate that the table is to be created without the support. Table Open Modes Open Mode CTOPEN_NORMAL NORMAL_OPEN Use this mode if no other open modes apply. CTOPEN_DATAONLY DATAONLY_OPEN Open only the data table. Used to rebuild a table that may or may not be missing indices. c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Open Mode CTOPEN_EXCLUSIVE EXCLUSIVE_OPEN This mode opens the table as exclusive. If this mode is used, only one user can open a table. If an application already has the file open in any mode, no other application can open the table as CTOPEN_EXCLUSIVE Once an application opens a table as CTOPEN_EXCLUSIVE application can open it. Reads and writes are cached for index files opened with this file mode since there are no integrity issues with only one process in the file. CTOPEN_PERMANENT PERMANENT_OPEN Many operating systems and/or C compiler run-time libraries limit the number of files that can be opened at one time. A permanent file open causes the file to be opened and stay open until the program executes a file close. A non-permanent file open causes the table data and index files to be opened, but allows them to be transparently closed and reopened to allow other data and index files to be used. When it is necessary for a data and index file to be temporarily closed, c-tree Plus selects the least recently used file. This file remains closed until it is used, at which time it will be automatically reopened. This strategy causes c-tree Plus to use all available file descriptors. CTOPEN_CORRUPT CORRUPT_OPEN This mode opens tables with corrupted indexes or in certain cases, tables with corrupted data. With c-treeDB this mode is usually used in conjunction with ctdbAlterTable() mode to perform a rebuild if the indexes became corrupted: open table with CTOPEN_CORRUPT mode, then call ctdbAlterTable() with CTDB_ALTER_INDEX mode to force the rebuild of all indices of the table. You can also specify ctdbAlterTable() mode CTDB_ALTER_INDEX CTDB_ALTER_PURGEDUP ) to purge any duplicate records that may cause the index rebuild to fail. If a table table becames corrupt, the table may be open with CTOPEN_CORRUPT mode and then ctdbAlterTable() with CTDB_ALL_FULL is invoked to try to recover the table. CTOPEN_CHECKLOCK CHECKLOCK_OPEN Tables opened with this mode requires a record lock before a record can be updated. If a lock is not obtained, the error code DADV_ERR Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation Open Mode CTOPEN_CHECKREAD CHECKREAD_OPEN Tables opened with this mode requires a record lock as records are read. Obtain at least a read lock on a record before it can be CTOPEN_READONLY READONLY_OPEN Opens the table in READONLY mode and does not allow any modifications to the table structure or data records. Table Permissions c-tree DB Permission Constant OPF_READ O_READ owner read permission OPF_WRITE O_WRITE owner write/update permission OPF_DEF O_DEF owner file definition permission OPF_DELETE O_DELETE owner file deletion permission OPF_ALL O_ALL owner granted all permissions OPF_NOPASS O_NOPASS owner grants read only without password group access denied GPF_READ G_READ group read permission GPF_WRITE G_WRITE group write/update permission GPF_DEF G_DEF group file definition permission GPF_DELETE G_DELETE GPF_NOPASS G_NOPASS group read only access without password WPF_NONE W_NONE world access denied WPF_READ W_READ world read permission WPF_WRITE W_WRITE world write/update permission WPF_DEF W_DEF world file definition permission WPF_DELETE W_DELETE WPF_NOPASS W_NOPASS world read only access without password c-treeVCL Developer's Guide www.faircom.com All Rights Reserved 4.3 TCtComponent Component The equivalent of the Borland TComponent. The session and database components are derived from this component. Public properties Error property Error() : CTDBRET; This property indicates which error occurred with the component. Handle property Handle() : CTHANDLE; The c-tree Plus handle for the component. LockMode property LockMode() : TCtLockMode; This read-only property indicates the lock mode for the session wide lock. UserTag property UserTag() : Pointer; Indicates the user tag. A user tag is a user defined tag that can be used for storing an additional integer value or it can be typecast to any 32-bit value such as a reference or a pointer. Methods Create constructor Create( AOwner : TComponent The constructor for the TCtComponent component. Destroy destructor Destroy() The destructor for the TCtComponent component. Do not call Destroy directly. The object has to be destroyed with the inherited ( TObject Free() method. AbortTransaction procedure AbortTransaction() Abort the current transaction. BeginTransaction procedure BeginTransation() Start a new transaction. Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation ClearError procedure ClearError() Clear the error code. CommitTransaction procedure CommitTransaction() Commit the current transaction. GetLockMode function GetLockMode() TCtLockMode At the moment Lock is called, no file or record is locked. Instead, a flag is set internally to indicate that all new record reads will lock the records, with the given lock mode. A READ lock on a record allows an unlimited number of READ locks on that record, but prevents WRITE locks. A WRITE lock prevents any other locks on that record. Call Unlock or Lock with mode set to CTLOCK_FREE , to free all session locks. Notice that, if called inside a transaction, this free operation will result in the suspension of the locks, and not in their release. The locks will only be rele ased when the transaction is finished with a call to CommitTransaction() or AbortTransaction() . If the locks are sus pended, it means that new records read won't be locked. To restore the suspended locks, use Lock with one of the READ or WRITE lock modes (or the RESTORE options). If, for any special reason, the unused locks from a particular table must be released inside a transaction, the TCtTable procedure UnlockTable() may be used. Unused locks are records that where locked but not updated/deleted/added. Mixing LockRecord() and Lock may result in DLOK_ERR (42) returns when an automatic lock is attempted on a manually locked record, or vice versa. (42) simply means a lock could not be obtained. In the example above, a locked record can't be re-locked. RestoreSavePoint procedure RestoreSavePoint( ASavePoint : TCtSavePoint c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Restore a transaction save point, given by ASavePoint. If ASavePoint is 0, the last save point is returned. If -1, the previous and so on. Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation 4.4 TCtSession Component The equivalent of BDE the TSession component; it encapsulates the properties and methods of the c-tree Plus session layer. TCtSession is a derivation of TComponent with the following added properties and methods: Published properties Active property Active() : Boolean; Boolean property that indicates if a session is active or not. A session can be activated by calling the method or by setting this property to True. A session can be deactivated by calling the method or by setting this property to False. AutoCreate property AutoCreate() : Boolean; Boolean property that, when set to True, automatically creates the session dictionary if it doesn't yet exist. Notice that the session dictionary will be created when the component tries to Log on to the session (Active property set to true). The session dictionary will use all default session properties, unless any of them is modified using the OnCreate event. The Directory and other Published properties may be set before the session creation in order to modify its behavior. property Bufs() : Integer; The number of index file buffers. This is an optional property and the default value is sufficient for most applications. The default value for Bufs() is 10, and it should be enough for most c-treeVCL/CLX applications. For more information on Bufs() , refer to the c-tree Plus documentation. property DBufs() : Integer; The number of data file buffers. This is an optional property and the default value is sufficient for most applications. The default value for DBufs() is 10, and it should be enough for most c-treeVCL/CLX applications. For more information on DBufs,() refer to the c-tree Plus documentation. Directory property Directory() : String; Indicates the location of the session dictionary file. This property should be set to blank when connecting to a c-tree Server. property : Integer; An initial block of file structures. This is an optional property and the default value is sufficient for most applications. The default value for is 32, and it should be enough for most c-treeVCL/CLX applications. For more information on Fils() , refer to the c-tree Plus documentation. c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Password property Password() : String; The user password. This property should be set before activating the session. Sect property Sect() : Integer; The number of node sectors. This is an optional property and the default value is sufficient for most applications. The default value for Sect() is 32, and it should be enough for most c-treeVCL/CLX applications. For more information on Sect() , refer to the c-tree Plus documentation. Server property Server() : String; The server name. This property should be set before activating the session. SessionType property SessionType() : TCtSessionType; The session type being allocated or created. There are three types of sessions: CTSESSION_CTDB (default value), CTSESSION_CTREE CTSESSION_SQL CTSESSION_CTDB requires the session and database dictionaries to operate on tables. CTSESSION_CTREE does not require the dictionaries, but the user must specify the table directory directly. When using CTSESSION_SQL , any database created inside the session will also create the c-treeSQL system tables, and all tables created and opened using this session type will update the system tables. With this, these tables will be ready to be used with c-treeSQL. This is a read and write property. It should be set before logging on to or creating the session. It shows the appropriate setting after logging on. property User() : String; The user name. This property should be set before activating the session. Userprof property Userprof() : Integer; The user profile mask. This is an optional property and the default value is sufficient for most applications. The default value for Userprof() is 513, and it should be enough for most c-treeVCL/CLX applications. Please refer to c-tree Plus documentation for more information on user profile masks. Public properties Databases property Databases() : TStringList; List of the database names associated with the session. This is a read-only property and the list of names becomes populated after a session is activated. DatabaseCount property DatabaseCount() : Integer; Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation The number of databases in a session. Methods Create constructor Create( AOwner : TComponent The constructor for the TCtSession component. Destroy destructor Destroy() The destructor for the TCtSession component. Do not call Destroy directly. The object has to be destroyed with the inherited ( TObject Free() method. CreateSession procedure CreateSession() Create a session dictionary. The session dictionary will be located in the server directory with the server or in the application directory for a non-server application. To choose a different directory, indicate it in the Directory property before calling CreateSession() DisconnectAll procedure DisconnectAll() Disconnect all databases from the session. procedure Logon to a session. In order to logon to a session, a session dictionary must exist. By default, the session dictionary is located is the server directory, or the application directory for non-server applications. Set the Directory property to store the session dictionary in a different directory. procedure Logout from a session. Events OnActive property OnActive() : TActiveEvent; This event is called after a session logon or a session logout is executed successfully. This event has a c-treeVCL Developer's Guide www.faircom.com All Rights Reserved This event is called when the Active Property from the Component is set to True if the session dictionary does not exist and the AutoCreate() Property is set to True. It allows the user to modify the session properties before the session dictionary is created. property : TNotifyEvent; This event is called before the session logon is executed. This allows the user to manipulate the session properties such as Server, User and Password. property : TNotifyEvent; This event is called before the session logout is executed. Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation 4.5 TCtDatabase Component The equivalent of the BDE TDatabase component. TCtDatabase encapsulates the property and methods of the c-tree Plus database layer. TCtDatabase is a derivation of TComponent with the following added properties and methods: Published properties Active property Active() : Boolean; Indicates if a database is connected to a session. A database can be activated by calling the method Connect() or by setting this property to True. A database can be deactivated by calling the method Disconnect() or by setting this property to False. AutoCreate Property AutoCreate() : Boolean; Boolean property that, when set to True, automatically creates the database dictionary if it doesn't yet exist. Notice that the database dictionary will be created when the component tries to Connect to the Database (Active property set to true). The database dictionary will use all default database properties, unless any of them is modified using the OnCreate() event. The Directory and other Published properties may be set before the database creation in order to modify its behavior. Database property Database() : String; c-treeVCL Developer's Guide www.faircom.com All Rights Reserved List of tables that belong to the database. This is a read only property and the list only becomes populated after a database connection is established. Methods Create constructor Create( AOwner : TComponent The TCtDatabase component constructor. Destroy destructor Destroy() The TCtDatabase component destructor. Do not call Destroy directly. The object must be destroyed with the inherited ( TObject Free() method. AddDatabase procedure AddDatabase() Add an existing database to the session. The Database, Directory and Session properties must be set before this method is called. CloseAll procedure CloseAll() Close all open tables associated with this database. Connect procedure Connect() Connect the database to a session. The Database and Session properties must be set before calling this method. CreateDatabase procedure CreateDatabase() Create a new database for this session. The Database, Directory and Session properties must be set before calling this method. DeleteDatabase procedure Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation Drop a database from a session. This method only removes the database entry in the session c-treeVCL Developer's Guide www.faircom.com All Rights Reserved 4.6 TCtDataSet Component Database property Database() : TComponent; Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation hSession property hSession() : CTHANDLE; . for valid values for the permission masks. Position property Position() c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Destroy destructor Destroy() The destructor for the Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation 4.7 TCtTable Component This component is the equivalent of the BDE TTable component. TCtTable encapsulates the property and methods of the c-tree Plus table and record layers. TCtTable is a descendant of Database property Database() : TComponent; c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Filter is used to specify a dataset filter. When filtering is applied to a dataset, only those records that . for valid values for the permission masks. Table property Table() : String; Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation Public properties Error property Error() : CTDBRET; This property indicates the error occurred with the component. FieldCount property FieldCount() : Integer; Number of fields. Fields property Fields( Index : Integer : TCtField; List of table fields. IndexCount property IndexCount() : Integer; Number of indexes. Indexes property Indexes( Index : Integer : TCtIndex; List of table indexes. LockMode property LockMode() : TCtLockMode; This read-only property indicates the lock mode for the session wide lock. Recbyt property Recbyt() : Boolean; This read-only property indicates if the table has a recbyt index. RECBYT index is an index based on c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Methods Create constructor Create( AOwner : TComponent The constructor for the TCtTable component. Destroy destructor Destroy() The destructor for the TCtTable component. Do not call Destroy directly. The object has to be destroyed with the inherited ( TObject Free() method. AbortTransaction procedure AbortTransaction() Abort the current transaction. AddField function AddField( FieldName : String; FieldType : CTDBTYPE; FieldLength : Integer : TCtField; Add a new field to a table. The field is added to the end of the table. Available field types are described “c-treeVCL/CLX Definitions” AddIndex function AddIndex( IndexName : String; KeyType : CTDBKEY; AllowDuplicates : Boolean; NulFlag : Boolean : TCtIndex; Add a new index to the table. AddSegment function AddSegment( IndexName : String; Field : String; Mode : CTSEG_MODE : TCtSegment; function AddSegment( Index : Integer; Field : String; Mode : CTSEG_MODE : TCtSegment; Add index segment. An index is composed by one or more segments. Available segment modes are described in “TCtTable Component” AddTable procedure AddTable() Add an existing table to the database. AlterTable procedure AlterTable() procedure AlterTable( Action : Integer Commit table field, index, or index segment changes. This function should only be used to modify an existing table. If the overloaded procedure with the parameter Action is used, Action may have three values: CTDB_ALTER_NORMAL (= 0), to check for changes before altering; CTDB_ALTER_INDEX (= 1), to force rebuild of all indexes; Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation CTDB_ALTER_FULL (= 3), to force full table rebuild. c-treeVCL Developer's Guide www.faircom.com All Rights Reserved DropTable procedure DropTable() Drop a table from a database. Only the entry for the table in the database dictionary is removed. The Integer : TCtField; Insert a new field into a table. Inserted fields may be placed anywhere in the table. InsertSegment function InsertSegment( IndexName : String; BeforeSegment : Integer; Field : String; Mode : CTSEG_MODE : TCtSegment; function InsertSegment( Index : Integer; BeforeSegment : Integer; Field : String; Mode : CTSEG_MODE : TCtSegment; Insert a new segment into a table. IsLockActive function IsLockActive() : Boolean; Verify the lock state, returning true if session wide locks are enabled. IsTransActive function IsTransActive() : Boolean; Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation Verify the transaction state, if active or not. A transaction is activated by a call to BeginTransaction() and deactivated with a call to CommitTransaction or AbortTransaction() Lock procedure Lock( LockMode : CTLOCK_MODE Enable session lock. After a call to Lock, every record visited by Find() First() Last() Next() Prev() Seek() will be locked. The valid lock modes are given in “c-treeVCL/CLX Definitions” At the moment Lock is called, no file or record is locked. Instead, a flag is set internally to indicate that all new record reads will lock the records, with the given lock mode. A READ lock on a record allows an unlimited number of READ locks on that record, but prevents WRITE locks. A WRITE lock prevents any other locks on that record. Call Unlock or Lock with mode set to CTLOCK_FREE , to free all session locks. Notice that, if called inside a transaction, this free operation will result in the suspension of the locks, and not in their release. The locks will only be rele ased when the transaction is finished with a call to CommitTransaction() or AbortTransaction() . If the locks are sus pended, it means that new records read won't be locked. To restore the suspended locks, use Lock with one of the READ or WRITE lock modes (or the RESTORE options). If, for any special reason, the unused locks from a particular table must be released inside a transaction, the TCtTable procedure UnlockTable() may be used. Unused locks are records that where locked but not updated/deleted/added. Mixing LockRecord() and Lock may result in DLOK_ERR (42) returns when an automatic lock is attempted on a manually locked record, or vice versa. (42) simply means a lock could not be obtained. In the example above, a locked record can't be re-locked. Notification procedure Notification( AComponent : TComponent; Operation: TOperation Overload the default notification event handler. c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Notice that, if called inside a transaction, this free operation will result in the suspension of the locks, and not in their release. The locks will only be released when the transaction is finished with a call to CommitTransaction() or AbortTransaction() . If the locks are suspended, it means that new records read won't be locked. To restore the suspended locks, use Lock() with one of the READ or WRITE lock modes (or the RESTORE options). If, for any special reason, the unused locks from a particular table must be released inside a transaction, the TCtTable procedure UnlockTable() may be used. Unused TCtSession Lock function, or a record lock obtained with the TCtRecord LockRecord() function. If UnlockTable() is used inside a transaction, the lock mode is changed to CTLOCK_SUSPEND , and new locks aren't acquired until a new call to Lock or to LockRecord() restore the locks. All unused locks from this particular table are released. Unused locks are records that where locked but not Definitions” Events AfterCancel property AfterCancel() Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation Write an c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Write a BeforeClose() event to take specific action before an application closes a dataset. Calling Close or setting the Active property to False results in a call to the BeforeClose() event handler. BeforeDelete property BeforeDelete() Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation Handles exceptions that occur when an attempt to delete a record fails. When c-treeVCL Developer's Guide www.faircom.com All Rights Reserved 4.8 TCtBlobStream Class TCtBlobStream is a descendant of Borland TBlobStream class and it is used to implement support for TDataSeb blob fields. The following properties and methods were implemented: Methods Create constructor Create() The constructor for the TCtBlobStream component. Destroy destructor Destroy() The destructor for the TCtBlobStream component. Do not call Destroy directly. The object has to be destroyed with the inherited ( TObject Free() method. Read procedure Read( var Buffer; Count : Longint : Longint; This is an abstract method responsible for reading from the stream. It is useful when the number of bytes to read from the stream is not necessarily fixed. It attempts to read up to Count bytes into buffer and returns the number of bytes actually read. Seek procedure Seek( Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation 4.9 TCtObject Class The equivalent of the Borland TObject. The record class is derived from this object. Public properties Error property Error() : CTDBRET; This property indicates the error occurred with the component. Handle property Handle() : CTHANDLE; The c-tree Plus handle for the object. LockMode property LockMode() : TCtLockMode; This read-only property indicates the lock mode for the session wide lock. UserTag property UserTag() : Pointer; Indicates the user tag, a user defined tag that stores an integer value or can be typecast to any 32-bit value, such as a reference or a pointer. Methods Create constructor Create( AOwner : TComponent The constructor for the TCtObject object. Destroy destructor Destroy() The destructor for the TCtObject object. Do not call Destroy directly. The object has to be destroyed with the inherited ( TObject Free() method. AbortTransaction procedure AbortTransaction() Abort the current transaction. BeginTransaction procedure BeginTransation() Start a new transaction. c-treeVCL Developer's Guide www.faircom.com All Rights Reserved ClearError procedure ClearError() Clear the error code. Commit Transaction procedure CommitTransaction() Commit the current transaction. GetLockMode function GetLockMode() : TCtLockMode; IsLockActive function IsLockActive() : Boolean; Verify the lock state, returning true if session wide locks are enabled. IsTransActive function IsTransActive() : Boolean; Verify the transaction state. A transaction is activated by a call to BeginTransaction() , and deactivated with a call to CommitTransaction() or AbortTransaction() Lock procedure Lock( LockMode : CTLOCK_MODE Enable session lock. After a call to Lock, every record visited by Find() First() Last() Next() Prev() Seek() will be locked. The valid lock modes are given in “c-treeVCL/CLX Definitions” At the moment Lock is called, no file or record is locked. Instead, a flag is set internally to indicate that all new record reads will lock the records, with the given lock mode. A READ lock on a record allows an unlimited number of READ locks on that record, but prevents WRITE locks. A WRITE lock prevents any other locks on that record. Call Unlock or Lock with mode set to CTLOCK_FREE , to free all session locks. Notice that, if called inside a transaction, this free operation will result in the suspension of the locks, and not in their release. The locks will only be rele ased when the transaction is finished with a call to CommitTransaction() or AbortTransaction() . If the locks are sus pended, it means that new records read won't be locked. To restore the suspended locks, use Lock with one of the READ or WRITE lock modes (or the RESTORE options). If, for any special reason, the unused locks from a particular table must be released inside a transaction, the TCtTable procedure UnlockTable() may be used. Unused locks are records that where locked but not updated/deleted/added. Mixing LockRecord() Lock() may result in (42) returns when an automatic lock is attempted on a manually locked record, or vice versa. DLOK_ERR (42) simply means a lock could not be obtained. In the example above, a locked record can't be re-locked. RestoreSavePoint procedure RestoreSavePoint( ASavePoint : TCtSavePoint Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation Restore a transaction save point, given by ASavePoint . If ASavePoint is 0, the last save point is If called inside a transaction, this free operation suspends locks. The locks will only be released when the transaction is finished with a call to CommitTransaction() or AbortTransaction() . If the locks are suspended, it means that new records read won't be locked. To restore the suspended locks, use Lock with one of the READ or WRITE lock modes (or the RESTORE options). If, for any special reason, the unused locks from a particular table must be released inside a transaction, the TCtTable procedure UnlockTable() may be used. Unused locks are records that where locked but c-treeVCL Developer's Guide www.faircom.com All Rights Reserved 4.10 TCtRecord Class This class encapsulates the c-tree Plus record management functions. TCtRecord is a descendant of TObject and the following properties were implemented: Public Properties Active property Active() : Boolean; Read the contents of this property to check if the record buffer has been cleared by a call to the Clear() method. If True, this property indicates that the record buffer represents data read from disk; if False, the record has been cleared. Set this property to False to clear the record buffer (this is equivalent to invoking the method Clear, but the data fields are not modified or cleared). DefaultIndex property DefaultIndex() : Integer; Use this property to read or to change the current default index. Index numbers range from zero to TCtTable.IndexCount-1; Edited property Edited() : Boolean; Use this property to check if a record buffer was modified by one of the SetFieldAs() Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation Methods Create constructor Create() The constructor for the TCtRecord component. Destroy destructor Destroy() The destructor for the TCtRecord component. Do not call Destroy directly. The object has to be destroyed with the inherited ( TObject Free() method. Allocate procedure Allocate( AOwner : TObject Allocate a new record buffer. AOwner must be a TCtTable object. procedure Clear() Clear and initialize the record buffer. c-treeVCL Developer's Guide www.faircom.com All Rights Reserved function FindMode : CTFIND_MODE : Boolean; Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation GetFieldAsFloat function GetFieldAsFloat( FieldNumber : Integer : double; c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Next function Next() : Boolean; Locate the next record in a table. Next returns TRUE if the record is found, FALSE otherwise. NumberOfKeyEntries NumberOfKeyEntries (IndexNumber : Integer) : Integer; NumberOfKeyEntries (IndexName : String) : Integer; Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation Update the field data as an Int64 value. The record manager will automatically perform the necessary data type conversion. c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Update the field data as a TTime value. The record manager will automatically perform the necessary data type conversion. SetFieldAsUnsigned procedure SetFieldAsUnsigned( FieldNumber : Integer; Value : LongWord Update the field data as an unsigned integer value. The record manager will automatically perform the necessary data type conversion. UnlockRecord procedure UnlockRecord() Release the lock for the current record only. Write procedure Write() Update an existing record or add a new record. Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation 4.11 TCtField Class This class encapsulates the c-tree Plus field layer. TCtField is a descendant of TObject and the following properties were implemented: Public Properties DataType property DataType() : CTDBTYPE; This property specifies the field data type. The valid values are described in “c-treeVCL/CLX Definitions” Field property Field() : String; This property specifies the field name. It may be used to read or write the field name. Handle property Handle() : CTHANDLE read FHandle; This read-only property may be used to retrieve the c-treeDB field handle. This allows components to make direct calls to c-treeDB functions and procedures. Length property Length() : Integer; This property indicates the field length. property Number() : Integer; This read only property specifies the field number. Precision property Precision() : Integer; This property specifies the field precision. The field precision represents the number of total digits in a BCD number. Scale property Scale() : Integer; This property specifies the field scale. The field scale is the number of decimal digits in the field. Methods Create constructor Create( AOwner : TObject; Handle : CTHANDLE c-treeVCL Developer's Guide www.faircom.com All Rights Reserved The constructor for the TCtField class. Destroy destructor Destroy() The destructor for the TCtField class. Do not call Destroy directly. The object has to be destroyed with the inherited ( TObject Free() method. Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation 4.12 TCtIndex Class This class encapsulates the c-tree Plus index layer. TCtIndex is a descendant of TObject and the following methods and properties were implemented: Public Properties Duplicates property Duplicates() : Boolean; This property indicates if the index accepts duplicate keys. If Duplicates is set to True, the index accepts duplicate key values. EmptyChar property EmptyChar() : Integer; This property indicates the decimal equivalent of the ASCII table value for the empty char. For instance, an ASCII space is specified a value of 32, and NULL byte is specified as 0. IndexName property IndexName() : String; This property indicates the index name. It can only be modified if the index is not active. KeyLength property KeyLength() Integer; This property is the length of the key for the index as returned by ctdbGetIndexKeyLength() KeyType property KeyType() : CTDBKEY; This property specifies the key type. The valid values are given in “c-treeVCL/CLX Definitions” property NullFlag() : Boolean; This property indicates if the index does accept a null value. property Number() : Integer; This read only property indicates the index number. SegmentCount property SegmentCount() : Integer; This read only property indicates the number of segments that compose the index. Segments property Segments( Index : Integer) : TCtSegment; c-treeVCL Developer's Guide www.faircom.com All Rights Reserved This property is an array containing all segments that compose the index. It is a read-only property, and it may be used as Segments( to retrieve the first segment composing the index and so on. Temporary property Temporary() : Boolean; This property indicates if the index is temporary or permanent. Methods Create constructor Create( AOwner : TObject; Handle : CTHANDLE The constructor for the TCtIndex class. Destroy destructor Destroy() The destructor for the TCtIndex class. Do not call Destroy directly. The object has to be destroyed with the inherited ( TObject Free() method. AddSegment function AddSegment( Field : String; Mode : CTSEG_MODE : TCtSegment; Add a segment to an index. A segment is always added after all current segments. DeleteSegment procedure DeleteSegment( SegmentNumber : Integer Delete a segment from an index. GetSegment function GetSegment( SegmentNumber : Integer : TCtSegment; Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation 4.13 TCtSegment Class This class encapsulates the c-tree Plus segment layer. TCtSegment is a descendant of TObject and the following properties were implemented: Public Properties Field property Field() : TCtField; This read only property indicates the segment field object. FieldName property FieldName() : String; This read only property indicates the name of the segment field. FieldNumber property FieldNumber() : Integer; This read only property indicates the number of the segment field. Mode property Mode() : CTSEG_MODE; This property indicates the segment mode. The valid segment modes are given in “c-treeVCL/CLX Definitions” Methods Create constructor Create( AOwner : TObject; Handle : CTHANDLE The constructor for the TCtSegment class. Destroy destructor Destroy() The destructor for the TCtSegment class. Do not call Destroy directly. The object has to be destroyed with the inherited ( TObject Free() method. c-treeVCL Developer's Guide www.faircom.com All Rights Reserved 4.14 TCtResource Class The TCtResource class, derived from TObject , implements the resource handling for c-treeVCL. Public properties Property Description TypeID property TypeID : LongWord ; Number property Number : LongWord; Resource property Resource : string; Locked property Locked : boolean; This read-only property indicates if a resource is locked or not. A value of true indicate that the resource is locked, while false indicate that the resource is not locked. A DataLength property DataLength : integer; This read-only property indicate the number of bytes contained by the resource data property. property Data : pointer; This read-only property retrieve a pointer to the resource data. The resource data is any collection of data that you wish to store as a resource. It can be a character string, a structure, or any variable type. If the pointer is different than nil, property DataLength contains the number of bytes necessary to store the resource data. Methods Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation Create constructor TCtResource.Create(hTable : TObject); Construct a CTResource object with the resource type and number set to zero and the resource name set to NULL. constructor TCtResource.Create(hTable : TObject; TypeID : LongWord; number : LongWord); Construct a CTResource object passing the resource type and number. The resource name is set to NULL. constructor TCtResource.Create(hTable : TObject; TypeID : LongWord; number : LongWord; name : string); Construct a CTResource object passing the resource type and number, as well as the resource name. procedure Add(data : pointer; size : integer); Add a new resource to the table. Delete Update procedure Update(data : pointer; size : integer); Update the resource data of an existing resource. The resource TypeID and number passed to the resource object constructor must match the resource being updated. First function First(lock : boolean) : boolean; Locate and read the first resource of a table. lock, if true, indicate that the resource Next function Next(lock : boolean) : boolean; Locate and read the next resource of a table. lock, if true, indicate that the resource Find function Find(TypeID : LongWord; number : LongWord; lock : boolean) : boolean; Locate and read a resource that exactly match the TypeID and number. lock, if true, Unlock procedure Unlock; Release the resource lock acquired by a call to First, Next or Find. c-treeVCL Developer's Guide www.faircom.com All Rights Reserved 4.15 ECtError Class This class encapsulates the Borland Exception Handling class. The TCtError class inherits from the EDatabaseError class. The same methods and properties from the Borland Exception class were implemented. There is one extra property and one extra method described below. This change allows for applications to catch exceptions that are specific to c-treeVCL by using ECtError, or more general database exceptions by using the EDatabaseError class. Public Properties Error property Error() : CTDBRET; Error stores the error number returned by any c-treeVCL function. The available c-treeVCL errors are described in "c-tree Plus Error and Return Values" and "c-treeDB Error and Return Values" Methods Create constructor Create(const Msg : string); The constructor for the Exception handling class. Destroy destructor Destroy() The destructor for the Exception handling class. Do not call Destroy directly. The object has to be destroyed with the inherited (TObject) Free() method. GetError function GetError() www.faircom.com All Rights Reserved Appendix A. c-tree Plus Error Code Reference Please note that several of these “error” codes are not really errors, but rather indicators of an unsuccessful operation. For example, KDUP_ERR (2) occurs if you attempt to add an existing entry to an index that does not support duplicate key values. This is not an error, but a situation to which your application program must be prepared to react. Value Symbolic Constant Explanation 0 NO_ERROR Successful operation. KDUP_ERR Key value already exists in index. KMAT_ERR KDEL_ERR KBLD_ERR Cannot call BJMP_ERR ctree() function jump table error. TUSR_ERR Terminate user. This is a sysiocod value when FNOP_ERR was caused by conflicting open requests (Server). FDEV_COD This is a sysiocod value when FNOP_ERR DCRAT_ERR KCRAT_ERR were caused by device access error SPAC_ERR InitCTree() SPRM_ERR Bad parameter(s): either 3, idxs 0, sect 1, or 0. FNOP_ERR Could not open file. Either file does not exist, filnam points to incorrect file name, or file is locked by another process. Check sysiocod system-level error. For ISAM functions, check isam_fil for the specific file number. FUNK_ERR OpenIFile() cannot determine type of file. Version 3.3 files must be rebuilt before using . Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation Value Symbolic Constant Explanation FCRP_ERR File appears corrupt at open. This occurs if a file is updated; and the disk FCMP_ERR Data file has been compacted, but not rebuilt. Rebuild data file, but do not force rebuild. KCRAT_ERR Could not create index file. Either no space is available on disk or filnam points to improper name. DCRAT_ERR Could not create data file. Either no space is available on disk or points to improper name. KOPN_ERR Tried to create existing index file. DOPN_ERR Tried to create existing data file. KMIN_ERR Key length too large for node size. There must be room for at least 3 key values per node. The node size is given by sect * 128 where sect is 3rd DREC_ERR Cannot create data file with record length smaller than 5. FNUM_ERR filno out of range: 0 = fils , where is 2nd parameter. This error may occur if c-tree Plus has not been initialized. KMEM_ERR Illegal index member number. FCLS_ERR Could not close file. Usually indicates that memory is clobbered. KLNK_ERR Bad link in deleted node list. Rebuild file. FACS_ERR File number ( keyno filno ) is not in use. Data record position before 1st actual data record ZDRN_ERR AddKey() called with recbyt = 0. ZREC_ERR Data file routine called with recbyt LEOF_ERR recbyt exceeds logical end of file. If recbyt is correct, then data file header record may be incorrect. If so, rebuild data file. DELFLG_ERR DDRN_ERR DNUL_ERR recptr is NULL. PRDS_ERR Could not find correct predecessor node. Should not show up in a single user system. Indicates that an index insertion was interrupted before SEEK_ERR lseek() failed in function ctio() ctclib.c ). Possible causes are: out of disk space, corrupted record position in file, or corrupted file descriptor. READ_ERR Read failed in function ctio() ctclib.c ). Possible cause: corrupted data record position in file. c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Value Symbolic Constant Explanation WRITE_ERR Write failed in function ctio() . See 35 above. VRTO_ERR Could not convert a virtually opened file to an actually opened file. This might occur if your application uses up some file descriptors after a virtual file has been automatically closed. You can protect against this by lowering the MAXVFIL FULL_ERR The 4-byte data record position (or node position) address space has been exhausted. KSIZ_ERR sect * 128 (where sect is 3rd InitCTree() parameter) was larger when index was created. Buffers are too small for nodes. UDLK_ERR Could not unlock data record. If dummy lock file is in use, be sure it has a file mode of 3. Could not obtain data record lock. In a DOS system, be sure that the FVER_ERR OSRL_ERR Data file serial number overflow. KLEN_ERR Index key length exceeds MAXLEN FUSE_ERR File number is already in use FINT_ERR c-tree Plus has not been initialized FMOD_ERR A function has been called for the wrong type of file: e.g., a variable-length function is called for a fixed-length data file. FSAV_ERR Could not write file directory updates to disk during file extension. LNOD_ERR Could not lock index file node. UNOD_ERR Could not unlock index file node. If a dummy lock file is in use, be sure it has a file mode of 3. KTYP_ERR Variable-length and/or floating point keys disabled in ctoptn.h FTYP_ERR The file’s file mode is inconsistent with the compile time options selected in ctoptn.h REDF_ERR Attempt to write a read only file. DLTF_ERR DLTP_ERR DADV_ERR Proper lock is not held ( ctCHECKLOCK READ LoadKey() called with incorrect key number. You cannot continue. LoadKey() called with key out of order. You may skip this key and continue. KFRC_ERR Percent out of range. Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation Value Symbolic Constant Explanation CTNL_ERR NULL file control block detected during I/O. LERR_ERR File must be opened exclusively. RSER_ERR Start file/log file serial number error. RLEN_ERR Checkpoint past end of log file. RMEM_ERR Not enough memory during transaction processing. RCHK_ERR Log file entry failed to find checkpoint. RENF_ERR Could not rename file. LALC_ERR Could not allocate memory for control list. BNOD_ERR Node does not belong to index. TEXS_ERR Transaction already pending. TNON_ERR No active transaction. TSHD_ERR No space for shadow buffer. TLOG_ERR ctLOGFIL encountered during shadow only. TRAC_ERR Recovery: two active transactions for user. TROW_ERR Recovery: bad transaction owner. TBAD_ERR Recovery: bad transaction type. TRNM_ERR Recovery: file name too long. TABN_ERR Transaction abandoned: too many log extents or dynamic dump wait exhausted. FLOG_ERR Could not log file opn/cre/cls/del. BKEY_ERR ATRN_ERR Transaction allocation error. UALC_ERR User allocation error. IALC_ERR ISAM allocation error. MUSR_ERR Maximum users exceeded. LUPD_ERR Attempt to reduce write lock to read lock after update. DEAD_ERR LMEM_ERR Linked list memory allocation error. TMEM_ERR Memory allocation during tran processing. NQUE_ERR Could not create queue. QWRT_ERR Queue write error. c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Value Symbolic Constant Explanation QMRT_ERR Queue memory error during write. QRED_ERR Queue read error. PNDG_ERR Pending error: cannot save or commit tran. STSK_ERR Could not start task. LOPN_ERR Start-file/log open error. SUSR_ERR Bad user handle. BTMD_ERR Bad transaction mode. TTYP_ERR transaction type / mode conflict. ICUR_ERR No current ISAM record for data file isam_fil INOT_ERR Could not satisfy ISAM search request for index isam_fil The following 4 items are the most probable causes of the INOT_ERR Passing GetRecord() a duplicate allowed index number ( keyno GetRecord() does not support duplicate allowed indices. INOD_ERR IGIN_ERR Number of files opened exceeds fils IUND_ERR Could not undo a rejected ISAM update. Data file must be rebuilt. (During the rebuild, look for records with rejected duplicate key values.) IDRI_ERR IDRK_ERR Too many indices for data file number isam_fil IMKY_ERR keyno for index file member out of sequence. keyno must equal host index file keyno plus member number. Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation Value Symbolic Constant Explanation IKRS_ERR ISRC_ERR IKRI_ERR IPND_ERR ctENABLE ) found pending locks. No space left in c-tree Plus’s internal lock list. IRED_ERR 1st byte of fixed-length data record found by ISAM routine equals ISLN_ERR Sum of key segment lengths does not match key length for index number isam_fil IMOD_ERR IMRI_ERR SKEY_ERR SKTY_ERR RRLN_ERR Not enough dynamic memory for record buffer in ctrbld.c. KBUF_ERR Tried to update data with ctISAMKBUFhdr on. RMOD_ERR RVHD_ERR A variable-length data record is not preceded by a valid record mark. The file is apparently corrupted. INIX_ERR Number of indices in index file does not match structure in call to OpenIFile() IINT_ERR c-tree Plus is already initialized via a previous call to , , , or . ABDR_ERR ARQS_ERR Could not send request. See“Client/Server VDP Errors” in the c-tree Plus Programmer’s Reference Guide for more information. ARSP_ERR Could not receive answer. See “Client/Server VDP Errors” for more information. NINT_ERR c-tree Plus not initialized. AFNM_ERR NULL file name pointer in . AFLN_ERR File name length exceeds message size. c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Value Symbolic Constant Explanation ASPC_ERR No room for application message buffer. ASKY_ERR Could not identify Server. ASID_ERR Could not get Servers message id. AAID_ERR Could not allocate application id. AMST_ERR Could not get application message status. AMQZ_ERR AMRD_ERR Could not get rid of application message. ABNM_ERR Badly formed file name. VMAX_ERR Variable record length exceeds 65,529 bytes. AMSG_ERR Required message size exceeds maximum. SMXL_ERR Application MAXLEN Server’s MAXLEN ctoptn.h SHND_ERR Communications handler not installed. QMEM_ERR Application could not id output queue. ALOG_ERR No message space. Was login ok? VDLK_ERR Could not update available space information in variable-length data VDLFLG_ERR Record pointed to by available space information is not marked deleted in variable-length data file. VLEN_ERR Attempt to write a variable-length record into a file position which is too small for the record. VRLN_ERR Variable-length passed to AddVRecord() is less than minimum record length established at file creation. SHUT_ERR Server is shutting down. STRN_ERR Could not shut down; transactions pending. LEXT_ERR Could not extend logfile. VBSZ_ERR Buffer in call to ReReadVRecord() is too small for the variable-length record. VRCL_ERR Attempt to read (R) a zero length record from a variable-length data file. SYST_ERR Native system failure. NTIM_ERR Timeout error. VFLG_ERR ReReadVRecord() record not marked active. VPNT_ERR Zero data record position in variable-length function. ITIM_ERR Multi-user interference: key value changed between index search and subsequent data record read. Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation Value Symbolic Constant Explanation SINA_ERR User appears inactive. SGON_ERR Server has gone away. SFRE_ERR No more room in Server lock table - free up memory. SFIL_ERR File number out of range. SNFB_ERR No c-tree file control block. SNMC_ERR No more c-tree file control blocks in Server. SRQS_ERR Could not read request. SRSP_ERR Could not send answer. TCRE_ERR Create file already opened (in recovery). SFUN_ERR Bad function number at Server. SMSG_ERR Application message size exceeds Server size. SSPC_ERR Could not allocate Server message buffer. SSKY_ERR Could not identify Server. SSID_ERR Could not get Server message id SAMS_ERR Server could not allocate user message area SMST_ERR Could not get Server message status SMQZ_ERR SINM_ERR Unexpected file number assigned to [si] in recovery. SOUT_ERR Server is at full user capacity IKRU_ERR Could not read r-tree symbolic index name. IKMU_ERR Could not get dynamic memory for r-tree symbolic index name. IKSR_ERR Cannot accommodate temporary r-tree files. Increase ctMAXFIL IDRU_ERR Could not read r-tree data field symbolic names. ISDP_ERR Multiple set buffer space already allocated. ISAL_ERR ISNM_ERR IRBF_ERR Null buffer pointer in r-tree. ITBF_ERR IJSK_ERR JOINS_TO skip condition in r-tree. IJER_ERR JOINS_TO error condition in r-tree. IJNL_ERR JOINS_TO null fill condition in r-tree. c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Value Symbolic Constant Explanation IDSK_ERR IDER_ERR IDNL_ERR IDMU_ERR Could not get dynamic memory for r-tree data field symbolic names. ITML_ERR Exceeded IMEM_ERR Could not get memory for block. Improper block. NSCH_ERR Key segment refers to schema but no schema is defined. RCRE_ERR Resource already enabled. RNON_ERR Resources not enabled RXCL_ERR File must be exclusive to enable resource. Empty resource id. RBUF_ERR Output buffer to small. RDUP_ERR Resource id already added. RCSE_ERR Bad resource search mode. RRED_ERR RNOT_ERR Resource not found. USTP_ERR User not active. BSUP_ERR Not a superfile. SOPN_ERR Attempt to create open superfile member. SDIR_ERR Superfile host not opened. SNST_ERR Cannot nest superfiles. SADD_ERR Illegal AddKey() to superfile. SDEL_ERR Illegal to superfile. SPAG_ERR Superfile created with different index node size. SNAM_ERR Superfile created with maximum name length exceeding current maximum. SRCV_ERR Host superfile does not support recovery. TPND_ERR Key update with pending transaction. BTFL_ERR Filter not supported. Probably an in Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation Value Symbolic Constant Explanation BTFN_ERR Function not supported. Probably an invalid value in mode parameter BTIC_ERR Incomplete batch. You specified BTAD_ERR Add list error. Internal processing problem. May be a memory overwrite. BTIP_ERR Batch already in progress. You made a call to to open a new batch before you have completed the prior one. Make a call with a mode of BAT_CAN BTNO_ERR No batch active. You are calling with a mode of BAT_CAN BAT_NXT BTST_ERR BTMT_ERR No more info. BTBZ_ERR bufsiz is too small for a single record. You need a larger buffer for this BTRQ_ERR request is a NULL pointer. LAGR_ERR Aggregate/serialization lock denied. FLEN_ERR Fixed-length string requires len SSCH_ERR Segment definition inconsistent with schema. DLEN_ERR Very long block not supported. FMEM_ERR memory error. DNUM_ERR number. DADR_ERR NULL during GETDEFBLK() Resource found with zero (0) length. DCNV_ERR File definition conversion missing: call FairCom. DDDM_ERR Dynamic dump already in progress. DMEM_ERR No memory for dynamic dump file buffer. DAVL_ERR One or more files not available for dump. DSIZ_ERR File length discrepancy. DCRE_ERR Could not create file during dump recovery. SDAT_ERR Not enough data to assemble key. BMOD_ERR Invalid key mode. BOWN_ERR You must be the owner of this file. DEFP_ERR File definition permission denied. c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Value Symbolic Constant Explanation DADM_ERR LUID_ERR Invalid user id when logging on Server. LPWD_ERR Invalid password when logging on Server. LSRV_ERR Server could not process user/acct info. NSRV_ERR Invalid Server name. NSUP_ERR Service not supported. Using an option unavailable to this library. SGRP_ERR User does not belong to group. SACS_ERR Group access denied. SPWD_ERR File password invalid. SWRT_ERR Write permission not granted. SDLT_ERR SRES_ERR Resource not enabled. SPER_ERR Bad permission flag. SHDR_ERR No superfile directory found during CTSBLD() processing. UQID_ERR File does not have unique Server/File number. IISM_ERR ISAM level logon not performed. IINI_ERR Incremental Index: dnumidx IIDT_ERR Incremental Index: dfilno not an ISAM file. IINM_ERR Incremental Index: aidxnam NULL for 1st. IITR_ERR Incremental Index: active tran not allowed. Negative I/O request. LGST_ERR Guest logons disabled. Old log file found during log create. FIDD_ERR 500 - 505 Reserved for future use. SRFL_ERR Could not open save/restore file. SRIO_ERR Could not process save/restore file. SRIN_ERR Save/restore inconsistency. DSRV_ERR Duplicate Server. RFCK_ERR Active chkpnt at start of roll-forward. ILOP_ERR Index nodes form illegal loop: rebuild. Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation Value Symbolic Constant Explanation DLOP_ERR SBLF_ERR FPUTFGET does not support . CQUE_ERR Queue has been closed. OIFL_ERR Cannot convert old structure. ctNOGLOBALS not allocated. GNOT_ERR regid is not registered. GEXS_ERR regid is already registered. IEOF_ERR Index logical EOF error. The index end of file error gives warning when a B-tree index node appears to be past the logical end of the index file. Such an error indicates that the index is corrupted. Note the following points: Should not occur on indices under transaction processing control or in Standalone Multi-user mode. On non-transaction processed indices, something has corrupted the index. The index must be rebuilt or recovered as follows. Recover by copying the key values to a new index. The corrupted index file can be opened with the file modes: ctOPENCRPT ctREADFIL , permitting the index to be searched, and the IEOF_ERR suppressed. HTRN_ERR Attempt to update index with inconsistent transaction number. If encountered, compact and rebuild the file to resolve the error. BMAL_ERR STID_ERR Userid in InitISAM() does not match current login id. BIDX_ERR Index must be rebuilt. See CTSTATUS.FCS SLEN_ERR Key segment length error. CHKP_ERR System checkpoints terminated. LMTC_ERR Client does not match server. BREP_ERR Index reorg entry error. ASAV_ERR SetSavePoint() called with ctAUTOSAVE MTRN_ERR File header high-water-mark overflow. OTRN_ERR Transaction number overflow. REGC_ERR c-tree Plus instance not registered. Call . AREG_ERR Only automatic RegisterCTree() allowed. TCOL_ERR Transaction log collision. PIOT_ERR Client-side bad function array type. sysiocod when file does not appear to contain any valid information. c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Value Symbolic Constant Explanation PNUL_ERR LWRT_ERR Transaction log cannot be written. MCRE_ERR Could not create mirror file. MOPN_ERR Could not open mirror file. MCLS_ERR Could not close mirror file. MDLT_ERR Could not delete mirror file. MWRT_ERR Could not write mirror file. MSAV_ERR Could not save mirror file. MRED_ERR Could not read mirror file. MHDR_ERR MSKP_ERR Attempt to open primary w/o mirror: OR-ing in a file mode of ctMIRROR_SKP permits a primary file to be opened w/o error. MNOT_ERR File already opened without mirror. MSEG_ERR Segmented file cannot be mirrored. FBEG_ERR Attempt to add a record beginning with either a delete flag (0xFF) or a resource mark (0xFEFE) failed. This capability can be disabled: For non-server applications, disable the check by compiling with NO_ctBEHAV_CHECKFIX defined. For client/server applications, the configuration keyword turns off this check. ISRL_ERR Inconsistent SerialNum defn info. It is inappropriate (regardless of partitioned files or not) to use PRMIIDX to add indices that use SRGSEG indices do not already exist. First, a SRLSEG index requires space in the data record. Second, none of the existing records would have SRLSEG data already in place, even if space had been reserved. ISRL_ERR (554) is returned when PRMIIDX attempts to add indices with SRLSEG when SRLSEG has not already been used. PREA_ERR Could not read primary files, so it is switching to mirrored files. PWRT_ERR Could not write primary files, so it is switching to mirrored files. CWRT_ERR Could not write mirror files, so it is suspending mirrored files. PSAV_ERR Could not save primary files, so it is switching to mirrored files. CSAV_ERR Could not save mirror files, so it is suspending mirrored files. SMON_ERR Only one of each monitor at a time. DDMP_BEG SYSMON: dynamic dump begins. DDMP_END SYSMON: dynamic dump ends. DDMP_ERR SYSMON: dynamic dump ends (errors). Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation Value Symbolic Constant Explanation RCL1_ERR Incomplete compression. RCL2_ERR Index rebuild required. RCL3_ERR Incomplete compression and index rebuild required. RCL4_ERR Primary/mirror files out-of-syncronization. Copy good file over bad. RCL5_ERR Incomplete compression and primary/mirror files out-of-syncronization. RCL6_ERR Index rebuild required and primary/mirror files out-of-syncronization. RCL7_ERR Incomplete compression and index rebuild required and primary/mirror files out-of-syncronization. CPND_COD CPND_ERR LADM_ERR Member of ADMIN group required. NCON_ERR Could not find ISAM context ID. OCON_ERR Old context ID. Call . ECON_ERR Context ID exists. XUSR_ERR Non-ADMIN user blocked from log on. XUSR_COD Users in SEC_BLOCK class logged on. CLEN_ERR varlen too small in . CMIS_ERR Missing information. CINI_ERR Could not initialize expression. CVAL_ERR Could not evaluate conditional expression. DEXT_ERR Dynamic Dump extent error. CTHD_ERR No more client threads. VRFY_ERR ctVERIFY CMEM_ERR No memory for system lock table. FLEX_ERR Could not allocate FCB. FINC_ERR Could not increase user files. KSRL_ERR Records with bad (all FF) serial numbers. DCOD_ERR Could not handle file encoding. RCOD_ERR Recovery could not enable encoding. IAIX_ERR attributes do not match file. LTPW_ERR Temporary password failure. HNUL_ERR c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Value Symbolic Constant Explanation Could not access/find transaction log. HSTR_ERR Must make a first search call (ctHISTfirst() HONE_ERR HMAP_ERR Could not find ISAM map from specified index file to a data file. HIDX_ERR Cannot return index entries from a specified data file. HACT_ERR TransactionHistory() cannot be called during an application’s own active transaction. HNOT_ERR HENT_ERR No more transaction log entries. recbyt not permitted on this request. HSIZ_ERR Bufsiz too small. HTYP_ERR Transaction type found in log not expected. HMID_ERR HMEM_ERR Not enough memory for . HMTC_ERR Must specify exactly one matching criteria: ctHISTpos ctHISTkey or one or both of ctHISTuser ctHISTnode HUND_ERR Encountered an (undo committed transaction) going HUNK_ERR Unknown type of request. Must specify HTFL_ERR Could not initialize internal file ID: preserve files and contact FairCom. HUNX_ERR Unexpected length in log entry. SSLO_ERR Could not get ctSS_LOCK on file User lost locks found on close NPLN_ERR NULL (pointer to size). NLEN_ERR Negative length specified. TSYC_ERR Could not create thread synchronization object. TSYF_ERR TSYR_ERR Thread synchronization object ‘rel’ failed. TQUE_ERR Queue message truncated to fit. Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation Value Symbolic Constant Explanation TZRO_ERR Semaphore must be initialized with count 0. TINT_ERR Semaphore already initialized. TSYX_ERR Thread synchronization object ‘cls’ failed. EXCT_ERR Must use exact file name. DPND_ERR Reversible TRANDEP File number changed after deferred close. SDEP_ERR Superfile member/host TRANDEP specification conflict E2GB_COD No support beyond 2 GB E4GB_COD No support beyond 4 GB DUPJ_ERR Duplicate keys purged and logged. DUPX_ERR Could not process duplicate key log. DUPL_ERR Duplicate keys rejected and listed. MAPL_ERR Attempt to exceed mapped lock limit. TLNG_ERR Record length too long for log size. FREO_ERR Could not reopen using freopen() LHDR_ERR Transaction log header is bad. CPYF_ERR Could not create copy file. CPYW_ERR Could not write copy file. CPYR_ERR Could not read entire original file. CPYB_ERR CPYX_ERR Failed process duplicate log and copy mirror. CPYJ_ERR Duplicate key purged, but could not copy mirror. CPYL_ERR Duplicate key rejected, but could not copy mirror. LPRI_ERR Primary log (or start) file failed. LMIR_ERR Mirrored log (or start) file failed. LFRM_ERR incompatible log format MAXZ_ERR attempt to exceed max file size large page size not a multiple of 16K XCRE_ERR inconsistent XCREblk HMIN_ERR node sectors too small for huge file c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Value Symbolic Constant Explanation XOVR_ERR non-zero high long with non-huge file HDR8_ERR inconsistency: file attr & sys version SIG8_ERR extended header bad signature SEGM_ERR additional file segments needed SEGS_ERR file segments not supported SEGO_ERR could not open segment SEGD_ERR cannot directly operate on seg def SEGN_ERR bad file segment name SEGZ_ERR bad file segment size SEGC_ERR could not create file segment SEGH_ERR could not process segment header SEGL_ERR seg resource cannot move SEGU_ERR seg update invalid, see CTSTATUS.FCS SEGX_ERR segment update already in progress SEGF_ERR i/o on segmented file terminated SEGR_ERR segment definition too large SEGQ_ERR unexpected value during recovery SEGP_ERR pending segment mismatch SEQ8_ERR 1st & 2nd headers out of sync CREQ_ERR bad request header CheckSum CRSP_ERR bad response header CheckSum CRCQ_ERR bad request (to server) CRC CRCP_ERR bad response (from server) CRC NUNC_ERR no Unicode support BSPC_ERR could not get work buffer for blk I/O SEGK_ERR OPNFIL() called for a segment DSPC_ERR could not allocate encoding buffer OSEG_ERR could not open key segment definition CSEG_ERR could not process compression options ASEG_ERR could not process compression attributes HSEG_ERR invalid key segment handle Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation Value Symbolic Constant Explanation SSEG_ERR invalid source type DSEG_ERR segment definition already exists NSEG_ERR no segment data produced USEG_ERR no segment definition MBSP_ERR multi-byte names not supported MBNM_ERR badly formed multi-byte name MBFM_ERR multi-byte variant not supported DIDX_ERR cannot call while DROPIDX() pending PLOW_ERR partition number out of range - low PHST_ERR file is not partition host PMBR_ERR file is not partition member PNOT_ERR raw partition does not exist PXPR_ERR bad value for partition key POVR_ERR could not overload partition number PUSD_ERR partition member in use PPND_ERR partition member pending purge PPRG_ERR partition member purged PARC_ERR partition member archived PLST_ERR bad partition host list PTRY_ERR PCRP_ERR bad current ISAM position for host PVRN_ERR PARTRES version error PPRG_COD duplicate error caused by purged part PFMD_ERR PSUP_ERR Partition support not enabled PUNQ_ERR purged unique global keys encountered PHGH_ERR partition number out of range - high PRIK_ERR illegal operation with primary key UMOD_ERR illegal file mode / x8mode value PMOP_ERR cannot open this member except read-only. EXTH_ERR extended header required c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Value Symbolic Constant Explanation CUNF_ERR client does not support UNIFRMAT server AOVR_ERR async handle overflow PMTC_ERR partition member characteristics do not match MINT_ERR ctThrdInit() must be called first FFLT_ERR record does not pass filter DDCR_ERR dynamic dump refused SF member create DDDR_ERR S6BT_ERR superfile member idx / host 6BTRAN != SFHI_ERR superfile host directory index null FREL_ERR file requires unavailable feature R6BT_ERR 6BTRAN file required ACHN_ERR could not allocate I/O channel(s) RSYN_ERR partition rule syntax error REXT_ERR read failed external cause: sysiocod PBAD_ERR bad parameter value ICUV_ERR different ICU version, rebuild index CHKM_ERR checkpoint memory inconsistency SPCL_ERR cannot RST/CLR past special savepoint QOWN_ERR only Q creator can perform operation SQUE_ERR a system queue is required NACT_ERR server is not activated STPU_ERR must uninit c-tree (STPUSR) QNOT_ERR only notifications to queue QUIN_ERR wrong queue instance XMON_ERR SYSMON interrupted / cancelled NMON_ERR no active SYSMON NRNG_ERR no range defined for index segment out of range CRNG_ERR range defined but no FRS/LST RNG CIOB_ERR comm I/O has been blocked- ctcomioblk Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation Value Symbolic Constant Explanation VCLS_ERR insufficient file handles and could not find file to close for virtual processing FALG_ERR CMLK_ERR commit lock error: make sure record update performed with lock CULK_ERR unexpected CMTLOK unlock failure: call FairCom XTRN_ERR cannot turn off file's tran support in middle of transaction if file updated COMP_ERR compatibility option not enabled PLAT_ERR platform does not support compatibility option SREP_ERR superfile host & member must have same REPLICATION attribute SMEM_ERR superfile members must all be closed UNQK_ERR support for REPLICATION SUPR_ERR operation not supported for SUPERFILES REPU_ERR cannot unregister another client's replication instance REPI_ERR the specified replication instance name is not registered REPR_ERR the specified replication instance name is already registered REPA_ERR cannot attach to replication instance with active connection REPC_ERR this replication connection already has a registered instance name UCMP_ERR decompression error: unexpected output length IITI_ERR incremental index: cannot add permanent indices while temporary indices exist LDPI_ERR LDAP initialization failed LDPC_ERR error connecting to LDAP server LDPB_ERR error binding to LDAP server LDPA_ERR LDAP user authentication failed LDPG_ERR error checking user's LDAP groups LGRP_ERR member of c-tree login group required LSST_ERR strict serializer must be in transaction to access record LSSK_ERR strict serializer cannot keep locks XSHT_ERR external server shutdown disabled PKSP_ERR partial record rewrite has keys spanning partial record and remaining region of record XBUF_ERR Tried to update data with missing key buffer contents VTSM_COD recursive ctptsema() call for open or create c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Value Symbolic Constant Explanation FCPY_ERR file copy failed DRST_ERR immediate dump restore failed FBLK_ERR file is blocked, retry later FBLK_RDO file block cleared: close/reopen file TDEP_ERR TRANDEP file operation pending FBLK_PND FBLK_SUP file block not supported for file type LNEW_ERR existing lock not replaced: cts_lok81() MSTK_ERR no memory for func stack alloc KCON_ERR failed to connect to kernel engine MSTK_COD ctDBGstack limit exceeded: debugging only TRQS_ERR request timed out TRSP_ERR response timed out SLOG_ERR status log write failure IAPI_ERR update only from internal API unexpected zero node size in header UBLK_ERR unexpected state for user block obj FBLK_ACT FBLK_NTF ctFILBLK already in progress for file QTUQ_ERR only one ctQUIET process at a time QTAB_ERR transaction aborted by ctQUIET QTFB_ERR ctQUIET ctFILBLK conflict QTBB_ERR unexpected failure to block thread QTBK_PND MLAB_ERR transaction abandoned: MAX_USER_LOGS MLHG_ERR abort request would be suspended TRAB_COD QTAB_ERR MLAB_ERR but operation performed MIMP_ERR problem impersonating thread QTOP_ERR ctQUIET called with files opened QBAD_ERR improper ctQT actions: see sysiocod Chapter 4 Component Reference FairCom Corporation Copyright 2008 FairCom Corporation Value Symbolic Constant Explanation UTIM_OUT User block timed out. ICUV_COD ICU version updated. ICUV_REB ICU version updated & rebuild required. TTAB_ERR Transaction abandoned: TRAN_TIMEOUT TTHG_ERR Abort request would be suspended. ITMP_COD sysiocod value when ITIM_ERR occurs on a temporary index and record is skipped. XNOD_ERR The connection attempt has been rejected because it would exceed the maximum number of concurrent client machines allowed. XCON_ERR The connection attempt has been rejected because it would exceed the maximum number of concurrent connections allowed from this client machine. TRAB_ERR Transaction aborted (e.g., MLAB_ERR TTAB_ERR ) before the requested operation was processed. (Compare with TRAB_COD The connection attempt has been rejected because only connections from the local system are allowed. IDUP_COD sysiocod value when occurs on a temporary index and error is ignored. CEXC_ERR clnleaf(CLNIDXX) failed to clean node. Very unexpected. call FairCom. CTRN_ERR Index file requires key level lock cleaning. CTRN_COD sysiocod when read only, admin open request blocked by on the fly CLNIDXX 841 842 843 844 845 846 847 www.faircom.com All Rights Reserved Appendix B. c-treeDB Error and Return Values This table lists the possible c-treeDB errors that may be encountered during the usage of c-treeDB. Value Symbolic Constant Explanation 0 CTDBRET_OK c-treeDB C API return OK CTDBRET_DATA BASEEXIST Database already exists Appendix A. FairCom Corporation Copyright 2008 FairCom Corporation Value Symbolic Constant Explanation c-treeVCL Developer's Guide www.faircom.com All Rights Reserved Value Symbolic Constant Explanation www.faircom.com All Rights Reserved Atomicit y...............................................................123 Automatic recovery..............................................123 Class ECtError...........................................................187 TCtBlobStream.................................................169 TCtField............................................................180 TCtIndex...........................................................182 TCtObject.........................................................170 TCtRecord........................................................173 TCtSegment.....................................................184 Class hierarchy....................................................136 Compatibi lity.........................................................132 field mapping (SQL and c-treeDB)...................133 migrate c-tree Pl us files...................................134 with c-tree Plus ISAM.......................................132 with c-treeSQL.................................................133 Components class hierarchy.................................................136 modify property..................................................85 modify property using code................................86 modify property using object inspector..............85 reference..........................................................135 TCtComponent.................................................145 TCtDatabase....................................................152 FairCom Corporation Copyright 2008 FairCom Corporation update data......................................................112 variable length....................................................97 working with.....................................................112 Recovery automatic..........................................................123 ROWID index.......................................................100 Sample notes....................................................................2 Save points..........................................................124 Segments...............................................................85 modes................................................................99 Session..................................................................85 session wide lock modes.................................125 Session component auto create property...........................................89 create new session............................................87 log on to c-tree...................................................88 use.....................................................................87 Table......................................................................85 create mode.....................................................101 open mode.......................................................142 permission........................................................144 Table component add existing table to database.........................109 add fields....................................................95, 107 add index....................................................99, 107 add index to table.............................................108 alter an existi ng table.......................................107 alter table.........................................................108 change default property...................................101 close table........................................................106 create table................................................95, 103 create table under transaction control.............104 data controls.....................................................121
C TreeVCL Developer S Guide