User’s Guide
c-treeSQL Server Operations and
Utilities Guide
User’s Guide
c-treeSQL Server Operations and Utilities
Guide
Copyright Notice
Copyright © 1992-2016 FairCom Corporation. All rights reserved. No part of this publication may be stored in a retrieval
system, or transmitted in any form or by any means, electronic, mechanical, photocopying, recording or otherwise without
the prior written permission of FairCom Corporation. Printed in the United States of America.
Information in this document is subject to change without notice.
Trademarks
c-treeACE, c-treeRTG, c-treeAMS, c-tree Plus, c-tree, r-tree, FairCom and FairCom’s circular disc logo are trademarks of
FairCom, registered in the United States and other countries.
The following are third-party trademarks: AMD and AMD Opteron are trademarks of Advanced Micro Devices, Inc.
Macintosh, Mac, Mac OS, and Xcode are trademarks of Apple Inc., registered in the U.S. and other countries.
Embarcadero, the Embarcadero Technologies logos and all other Embarcadero Technologies product or service names
are trademarks, service marks, and/or registered trademarks of Embarcadero Technologies, Inc. and are protected by the
laws of the United States and other countries. Business Objects and the Business Objects logo, BusinessObjects, Crystal
Reports, Crystal Decisions, Web Intelligence, Xcelsius, and other Business Objects products and services mentioned
herein as well as their respective logos are trademarks or registered trademarks of Business Objects Software Ltd.
Business Objects is an SAP company. HP and HP-UX are registered trademarks of the Hewlett-Packard Company. AIX,
IBM, POWER6, POWER7, and pSeries are trademarks or registered trademarks of International Business Machines
Corporation in the United States, other countries, or both. Intel, Intel Core, Itanium, Pentium and Xeon are trademarks or
registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. Microsoft, the .NET
logo, the Windows logo, Access, Excel, SQL Server, Visual Basic, Visual C++, Visual C#, Visual Studio, Windows,
Windows Server, and Windows Vista are either registered trademarks or trademarks of Microsoft Corporation in the
United States and/or other countries. Novell and SUSE are registered trademarks of Novell, Inc. in the United States and
other countries. Oracle and Java are registered trademarks of Oracle and/or its affiliates. QNX and Neutrino are
registered trademarks of QNX Software Systems Ltd. in certain jurisdictions. CentOS, Red Hat, and the Shadow Man logo
are registered trademarks of Red Hat, Inc. in the United States and other countries, used with permission. UNIX and
UnixWare are registered trademarks of The Open Group in the United States and other countries. Linux is a trademark of
Linus Torvalds in the United States, other countries, or both. Python and PyCon are trademarks or registered trademarks
of the Python Software Foundation. OpenServer is a trademark or registered trademark of Xinuos, Inc. in the U.S.A. and
other countries. Unicode and the Unicode Logo are registered trademarks of Unicode, Inc. in the United States and other
countries.
Btrieve is a registered trademark of Actian Corporation.
ACUCOBOL-GT, MICRO FOCUS, RM/COBOL, and Visual COBOL are trademarks or registered trademarks of Micro
Focus (IP) Limited or its subsidiaries in the United Kingdom, United States and other countries.
isCOBOL and Veryant are trademarks or registered trademarks of Veryant in the United States and other countries.
All other trademarks, trade names, company names, product names, and registered trademarks are the property of their
respective holders.
Portions Copyright © 1991-2016 Unicode, Inc. All rights reserved.
Portions Copyright © 1998-2016 The OpenSSL Project. All rights reserved. This product includes software developed by
the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/).
Portions Copyright © 1995-1998 Eric Young (eay@cryptsoft.com). All rights reserved. This product includes cryptographic
software written by Eric Young (eay@cryptsoft.com). This product includes software written by Tim Hudson
(tjh@cryptsoft.com).
Portions © 1987-2016 Dharma Systems, Inc. All rights reserved. This software or web site utilizes or contains material
that is © 1994-2007 DUNDAS DATA VISUALIZATION, INC. and its licensors, all rights reserved.
Portions Copyright © 1995-2013 Jean-loup Gailly and Mark Adler.
7/20/2016
Contents
1.
c-treeACE SQL Operations and Utilities Guide ................................................ 1
2.
Installation ........................................................................................................... 3
2.1
2.2
Up and Running with the c-treeACE Database Engine ......................................... 4
Location ................................................................................................................. 4
License Object .................................................................................................................... 4
2.3
2.4
2.5
2.6
Starting c-treeACE ................................................................................................ 5
Stopping c-treeACE ............................................................................................... 6
Links to c-treeACE Manuals .................................................................................. 7
c-treeACE SQL Operational Files ......................................................................... 7
3.
c-treeACE SQL Features ..................................................................................... 8
3.1
3.2
3.3
3.4
3.5
3.6
3.7
3.8
3.9
3.10
Advanced Encryption for c-treeACE SQL Tables .................................................. 8
Default HUGE File Tables with c-treeACE SQL .................................................... 9
PREIMAGE Tables in c-treeACE SQL .................................................................. 9
Shared Memory Connections for c-treeACE SQL Clients on Windows .............. 10
Server-Side Connection Pooling ......................................................................... 10
Supported Transaction Isolation Levels .............................................................. 10
Case Insensitive Search Options for c-treeACE SQL LONG Field Types........... 12
Query Timeout Option ......................................................................................... 12
Logging c-treeACE SQL Query Times ................................................................ 13
Built-in Stored Procedure to Switch Transaction Mode ....................................... 14
4.
c-treeACE SQL Options .................................................................................... 15
4.1
4.2
4.3
4.4
4.5
4.6
4.7
4.8
4.9
4.10
Environment Variables ........................................................................................ 15
Default Date Handling ......................................................................................... 15
Case-Sensitivity Options ..................................................................................... 16
Optimizer Configuration Options ......................................................................... 17
c-treeDB ROWID Options ................................................................................... 17
Automatic Database Conversion Options............................................................ 18
Template Database __Master.dbs Handling ....................................................... 18
SQL_DEBUG Options ......................................................................................... 18
Advanced c-treeACE SQL Logging ..................................................................... 19
Memory Manager (MM) System for Temporary Storage ..................................... 20
5.
c-treeACE SQL Java Configuration for Stored Procedures, Triggers
and User Defined Functions ............................................................................. 22
Run-Time Settings for Java Stored Procedure Support ...................................... 22
5.1
www.faircom.com
All Rights Reserved
iv
c-treeACE SQL Operations and Utilities Guide
5.2
5.3
Debugging Java Stored Procedures.................................................................... 23
Advanced JVM Configuration .............................................................................. 26
6.
c-treeACE SQL Utilities ..................................................................................... 29
6.1
6.2
6.3
6.4
ctpath - Change Internal Database Paths ........................................................... 29
ctsqlbigint - c-treeACE SQL Big Integer Fix Utility............................................... 29
ctsqlcdb - c-treeACE SQL Database Maintenance Utility.................................... 30
ctsqlimp - c-treeACE SQL Import Utility .............................................................. 30
ctsqlimp Usage.................................................................................................................. 30
Specifying primary keys from imported indexes ............................................................... 32
Check for Max Number of Indices/Segments ................................................................... 32
Allow linking SQL indices with rightmost segment(s) on hidden field(s)........................... 32
Mapping unsigned integers with c-treeACE SQL ............................................................. 32
Check for Invalid Characters in Field Names ................................................................... 33
Support for Importing Table with an Alternative Name ..................................................... 33
Null Fields and Field Default Values Considerations ........................................................ 33
ctsqlimp Import Indices with Segment on String Field Missing Last Byte......................... 34
Import Duplicate Filenames into c-treeACE SQL ............................................................. 34
6.5
6.6
6.7
6.8
6.9
ctsqlutl - c-treeACE SQL Table Maintenance Utility ............................................ 35
ctsqlmdd - c-treeACE SQL Merge Database Utility ............................................. 35
cttrnmod - Change Transaction Mode Utility ....................................................... 37
fkverify ................................................................................................................. 40
sqlverify ............................................................................................................... 40
7.
Combining c-treeACE SQL with ISAM ............................................................. 42
7.1
Accessing c-treeACE SQL Files from ISAM Applications ................................... 42
Defining a Table Using c-treeACE SQL ............................................................................ 42
Examining Resulting File Specifications ........................................................................... 42
7.2
Using Existing ISAM Data with c-treeACE SQL .................................................. 45
Table Definition Requirements.......................................................................................... 45
Index Definition Requirements .......................................................................................... 46
Adding DODAs to Existing Files ....................................................................................... 46
7.3
Mapping of c-tree to c-treeACE SQL Types ........................................................ 47
8.
c-treeACE SQL Types SDK ............................................................................... 50
8.1
Overview of the c-treeACE SQL Types SDK....................................................... 50
An example field conversion ............................................................................................. 50
8.2
c-treeACE SQL with Callbacks ............................................................................ 52
The Server Architecture .................................................................................................... 53
c-treeACE SQL Callback Dynamic Library ....................................................................... 53
c-treeACE SQL Callback Configuration File ..................................................................... 55
How to specify MYTIME field translation .......................................................................... 57
Specifying the configuration file location ........................................................................... 58
www.faircom.com
All Rights Reserved
v
c-treeACE SQL Operations and Utilities Guide
The File Definition Generating Utility ................................................................................ 58
8.3
Importing Tables Into c-treeACE SQL ................................................................. 59
Import Utility Callback Architecture ................................................................................... 60
Import Utility Callback Configuration File .......................................................................... 60
Building the callback libraries............................................................................................ 60
8.4
Which c-treeACE and c-treeDB Functions are Safe?.......................................... 63
9.
Migrating to c-treeACE SQL ............................................................................. 65
9.1
9.2
9.3
9.4
9.5
9.6
9.7
Migration from c-tree ODBC to c-treeACE SQL ODBC ....................................... 65
Overview of the c-treeACE SQL Migration SDK.................................................. 65
Migration .............................................................................................................. 66
Key Steps ............................................................................................................ 66
Important Observations ....................................................................................... 67
Customization ...................................................................................................... 67
Migration Callbacks ............................................................................................. 68
10.
c-treeACE SQL Configuration .......................................................................... 71
10.1
10.2
10.3
10.4
10.5
10.6
10.7
10.8
10.9
10.10
10.11
10.12
10.13
10.14
10.15
10.16
10.17
10.18
10.19
10.20
10.21
10.22
10.23
10.24
c-treeACE SQL Configuration Keywords............................................................. 71
MAX_SQL_ISOLATION_LEVEL ......................................................................... 72
SQL_CONNECT_TIMEOUT_SEC ...................................................................... 73
SQL_DATABASE ................................................................................................ 74
SQL_IDLE_WAKE ............................................................................................... 75
SQL_KEEP_OPEN_TABLES .............................................................................. 76
SQL_LOGFILE .................................................................................................... 77
SQL_MIN_CARD ................................................................................................ 78
SQL_PARTOPEN_COST ................................................................................... 79
SQL_PORT ......................................................................................................... 80
SQL_TRACE_CTREE_ERROR .......................................................................... 81
SETENV CLASSPATH ........................................................................................ 82
SETENV DEBUG_JVM ....................................................................................... 83
SETENV DEBUG_JVM_PORT ........................................................................... 84
SETENV DH_CACHED_STATEMENTS............................................................. 85
SETENV DH_DO_AHEAD .................................................................................. 86
SETENV DH_DYN_CACHED_STATEMENTS ................................................... 87
SETENV DH_ENABLE_POOL ............................................................................ 88
SETENV DH_JVM_OPTION_STRINGS ............................................................. 89
SETENV DH_ENABLE_POOL ............................................................................ 90
SETENV DH_OPT_OR_CARD ........................................................................... 91
SETENV DH_POOL_SIZE .................................................................................. 92
SETENV DH_REBUILD_SEL_CUTOFF ............................................................. 93
SETENV DH_THREAD_STACK_SZ_KB ............................................................ 94
www.faircom.com
All Rights Reserved
vi
c-treeACE SQL Operations and Utilities Guide
10.25
10.26
10.27
10.28
10.29
10.30
10.31
10.32
10.33
10.34
10.35
10.36
10.37
10.38
10.39
10.40
10.41
10.42
10.43
10.44
10.45
10.46
10.47
10.48
10.49
10.50
10.51
10.52
10.53
10.54
10.55
10.56
10.57
10.58
10.59
10.60
10.61
10.62
10.63
10.64
10.65
SETENV DH_SVR_DA_BUFFER ....................................................................... 95
SETENV JAVA_COMPILER ............................................................................... 96
SETENV JVM_LIB .............................................................................................. 97
SETENV TPESQLDBG ....................................................................................... 98
SETENV TPE_DFLT_DATE ............................................................................... 99
SETENV TPE_MM_CACHESIZE...................................................................... 100
SETENV TPE_MM_COMPARE_OVHD............................................................ 101
SETENV TPE_MM_INSERT_OVHD................................................................. 102
SETENV TPE_MM_SWAPSIZE........................................................................ 103
SQL_OPTION CHECK_HEAP .......................................................................... 104
SQL_OPTION CTSTRING_VARCHAR............................................................. 105
SQL_OPTION CREATE_WITH_ROWID .......................................................... 106
SQL_OPTION CREATE_WITH_RECBYT ........................................................ 107
SQL_OPTION CTDB_ROWID .......................................................................... 108
SQL_OPTION DB_CASE_INSENSITIVE ......................................................... 109
SQL_OPTION FORCE_TEMPLATE_DB .......................................................... 110
SQL_OPTION HM_ACTIVE .............................................................................. 111
SQL_OPTION LOAD_CALLBACK_LIB............................................................. 112
SQL_OPTION NO_AUTO_ABORT ................................................................... 113
SQL_OPTION NO_BINARY_PAD .................................................................... 114
SQL_OPTION NO_CARDINALITY ................................................................... 115
SQL_OPTION NO_COSTS ............................................................................... 116
SQL_OPTION NO_CRYPT_SYSTBL ............................................................... 117
SQL_OPTION NO_DB_CONVERSION ............................................................ 118
SQL_OPTION NO_DUP_IDXNAME ................................................................. 119
SQL_OPTION NO_HUGEFILE ......................................................................... 120
SQL_OPTION NO_PUSHDOWN ...................................................................... 121
SQL_OPTION NO_REVERSE_INDEX ............................................................. 122
SQL_OPTION NO_SELECTIVITY .................................................................... 123
SQL_OPTION NO_SHARED_MEMORY .......................................................... 124
SQL_OPTION NO_SYSSUPERFILE ................................................................ 125
SQL_OPTION OWNER_FILE_NAMES ............................................................ 126
SQL_OPTION PAD_WITH_NULL ..................................................................... 127
SQL_OPTION PARTIAL_SEG .......................................................................... 128
SQL_OPTION PRESERVE_CURSOR_FREE_LOCK ...................................... 129
SQL_OPTION SUPPRESS_JVM_LOAD_ERR ................................................ 130
SQL_OPTION USE_MM ................................................................................... 131
SQL_DEBUG ABORT_ON_PANIC ................................................................... 132
SQL_DEBUG ERROR_INFO ............................................................................ 133
SQL_DEBUG INDEX ........................................................................................ 134
SQL_DEBUG INDEX_SEL ................................................................................ 135
www.faircom.com
All Rights Reserved
vii
c-treeACE SQL Operations and Utilities Guide
10.66
10.67
10.68
10.69
10.70
10.71
10.72
SQL_DEBUG INDEX_DEF_SEL....................................................................... 136
SQL_DEBUG INDEX_INFO .............................................................................. 137
SQL_DEBUG LOG_STUBS_HIGH ................................................................... 138
SQL_DEBUG LOG_STUBS_MED .................................................................... 139
SQL_DEBUG LOG_STUBS_LOW .................................................................... 140
SQL_DEBUG LOG_STMT_TIMES ................................................................... 141
SQL_DEBUG LOG_STMT_TIMES_FETCH ..................................................... 142
11.
c-treeACE SQL Built-in Stored Procedures .................................................. 143
11.1
11.2
11.3
11.4
11.5
11.6
11.7
11.8
11.9
11.10
11.11
11.12
11.13
11.14
11.15
11.16
11.17
11.18
11.19
11.20
11.21
11.22
11.23
11.24
11.25
11.26
11.27
11.28
11.29
11.30
11.31
11.32
fc_add_db( ) ...................................................................................................... 144
fc_check_file_tran_state( ) ................................................................................ 145
fc_create_db( ) .................................................................................................. 146
fc_create_user( ) ............................................................................................... 147
fc_get_cachestats() ........................................................................................... 148
fc_get_connstats() ............................................................................................. 149
fc_get_dblist( ) ................................................................................................... 150
fc_get_fcproclist( ) ............................................................................................. 151
fc_get_filestats() ................................................................................................ 152
fc_get_iostats() .................................................................................................. 153
fc_get_isamstats() ............................................................................................. 154
fc_get_lockstats() .............................................................................................. 155
fc_get_memstats() ............................................................................................. 156
fc_get_min_card( ) ............................................................................................ 157
fc_get_priority( ) ................................................................................................ 158
fc_get_partbounds() .......................................................................................... 159
fc_get_replstats() ............................................................................................... 160
fc_get_selectivity( ) ............................................................................................ 161
fc_get_server_version( ) .................................................................................... 162
fc_get_sqlstats() ................................................................................................ 164
fc_get_sysconfig() ............................................................................................. 165
fc_get_taskid( ) .................................................................................................. 166
fc_get_transtats() .............................................................................................. 167
fc_get_userlist( ) ................................................................................................ 168
fc_ptadmin_num() ............................................................................................. 169
fc_set_blockinglock( ) ........................................................................................ 170
fc_set_debug( ) ................................................................................................. 171
fc_set_file_tran_state( ) ..................................................................................... 172
fc_set_impersonation( ) ..................................................................................... 173
fc_set_min_card( ) ............................................................................................. 174
fc_set_nodename( ) .......................................................................................... 175
fc_set_priority( ) ................................................................................................. 176
www.faircom.com
All Rights Reserved
viii
c-treeACE SQL Operations and Utilities Guide
11.33 fc_set_selectivity( ) ............................................................................................ 177
11.34 fc_set_sysconfig() ............................................................................................. 178
12.
c-treeACE SQL Reserved Words ................................................................... 179
12.1
c-treeACE SQL Reserved Words ...................................................................... 179
13.
Index ................................................................................................................. 181
www.faircom.com
All Rights Reserved
ix
1.
c-treeACE SQL Operations and Utilities
Guide
Introduction
c-treeACE SQL Server is a superset of the powerful c-treeACE ISAM server providing an
industry-standard SQL interface into your c-tree data. With this advanced interface comes many
additional options for SQL-specific performance tuning and data handling.
Keep in mind that c-treeACE ISAM is the core data-handling engine and nearly all of the options
for tuning c-treeACE ISAM performance and operation apply to c-treeACE SQL. This manual
presents a comprehensive description of configuration options, utilities, and practices unique to
the FairCom c-treeACE SQL Server.
Consult your nearest FairCom office should you have questions or need additional information
about any of the options available. FairCom is committed to providing high performance
technology in an engineering level product. Let us work with you to tailor a solution for your exact
and demanding needs!
www.faircom.com
All Rights Reserved
1
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
Bold
CAPITALS
Type of Information
Used to emphasize a point or for variable expressions such
as parameters
Names of keys on the keyboard. For example, SHIFT,
CTRL, or ALT+F4
FairCom Terminology
FairCom technology term
FunctionName()
c-treeACE Function name
Parameter
Code Example
utility
filename
CONFIGURATION KEYWORD
CTREE_ERR
c-treeACE Function Parameter
Code example or Command line usage
c-treeACE executable or utility
c-treeACE file or path name
c-treeACE Configuration Keyword
c-treeACE Error Code
2.
Installation
Welcome to the c-treeACE Advanced Core Engine database server. You have just installed the
same great database technology that powers many of the world’s largest transaction systems.
Unlike other complicated database servers that require ongoing administration and extensive
hardware resources, c-treeACE is designed to be simple to install with minimal disk and memory
requirements and no ongoing maintenance. The c-treeACE Advanced Core Engine represents
the next step in the evolution of c-tree technology.
Advanced Core Engine (ACE): The “Core Database Engine” is a single Executable File (EXE)
supporting Dynamically Loadable Libraries (DLLs or SOs) that are easily installed and managed
as an operating system service. Once installed, this engine is readily accessible to all
applications, either running locally or remotely on other devices or computers (desktop, notebook,
phones, handhelds, PDAs, etc).
The c-treeACE Server is designed for ease of operation and maintenance. Simply set your
options and forget about it. The c-treeACE Server will run reliably for long periods of time with
little if any administrator attention.
This short guide introduces the most basic features the c-treeACE Server and is intended to have
you up and running in minutes. You are encouraged to review the complete manuals for the most
up-to-date information available.
www.faircom.com
All Rights Reserved
3
2.1
Up and Running with the c-treeACE Database Engine
2.2
Location
You will find your c-treeACE Server in the bin\ace\sql or bin\ace\isam directory of your c-treeACE
installation.
You will find your tools and utilities located in the tools\ directory of your c-treeACE Server
installation.
License Object
Beginning with c-treeACE V10.0 an activation process is no longer required to use the c-treeACE
Server. A much simpler approach requiring only the presence of a new License Authorization
File is now used. There are substantial advantages to this new approach. Primarily, it avoids an
extra process to use the server and handling lengthy key values. More importantly, it avoids
modifying any binary files, which can break package checksums, for example.
The License Authorization File is a binary file containing unique licensing information assigned
by FairCom. This licensing information permits the c-treeACE Server technology to operate on a
specified operating system, to support specific features, to support a fixed number of concurrent
users and/or connections to the c-treeACE Server technology, and to utilize a fixed number of
CPUs on the host machine.
The license file is named ctsrvr-<SN>.lic where <SN> is the unique Serial Number assigned to
your server instance and provided by FairCom. This file will need to be properly placed in the
same directory where the c-treeACE Server binary is located, for example,
\FairCom\V11.x.x\<platform>\bin\ace\sql\ctreesql.exe. An example developer license is shown
below:
<?xml version="1.0" encoding="us-ascii"?>
<ctlicense version="2">
<version>11</version>
<serial>39000010</serial>
<OEM>1</OEM>
<lictype>Development</lictype>
<cpus>2</cpus>
<servtype>ALL (Standard - SQL)</servtype>
<users>32</users>
<private>EDE . . . QGP</private>
<checksum>LE47LG9DNM06IA30CGAFFO00NMCEJL59</checksum>
</ctlicense>
Note that you can read the most relevant sections of this XML file in plain text regarding serial
numbers, connection and CPU counts. If this licensing file isn’t present, you'll receive a 960 error
in your CTSTATUS.FCS status log upon startup:
"LICENSE ERROR: License initialization failed: Missing license file."
www.faircom.com
All Rights Reserved
4
Installation
The Developer edition of the c-treeACE Server included with the c-treeACE Professional package
includes a ctsrvr-<SN>.lic file configured to support up to 32 concurrent connections and can
operate on up to 2 concurrent CPU cores (as reported by the operating system which may
include physical CPUs, CPU cores, or virtual CPUs assigned to a partition).
Development servers are licensed exclusively for development and testing purposes and only by
the developer who is the c-treeACE Professional license holder. They are expressly not
authorized for production use. Should you need additional licenses for testing or if you wish to
test with a license file supporting a greater number of connections or CPUs, please contact your
nearest FairCom office.
When purchasing a production c-treeACE Server license, you will receive a ctsrvr-<SN>.lic file via
e-mail, along with a “Proof of Entitlement” document that summarizes the configuration of your
c-treeACE Server license file.
2.3
Starting c-treeACE
There are many options to start the c-treeACE Server depending on your platform.
Windows
 As a Windows Service
• The Windows Service Manager - If you installed c-treeACE on a Microsoft Windows
system, c-treeACE is installed and started by default through the installer. You can verify
and manage server operation via the standard Windows service application via your
administrative control panel application.
• The net start command line function. For example:
>net start "c-treeACE Database Engine"
 As a Console or ToolTray Application - Simply double-click the executable in the ace/bin/sql
directory.
Note: When connecting via a network, be aware that the TCP/IP port should be allowed by
any local firewalls. Many modern operating systems include these security features by
default. If you cannot connect with remote clients, you may need to specifically allow the
c-treeACE Server port.
www.faircom.com
All Rights Reserved
5
Installation
Unix
Unix, Linux, and Mac OS X users can use the included start scripts.
 ./startace
This script is provided as a "C" shell script and will work in most Unix shell environments. You are
free to modify and tailor it to suit your local requirements.
2.4
Stopping c-treeACE
By default, the c-treeACE Server requires an administrator password to initiate a server
shutdown. The default (and permanent) administrator account is ADMIN with an initial default
password of ADMIN.
The Windows Service does not require the administrator password as it is assumed the
c-treeACE Server is running under administrative privileges.
Windows
 c-treeACE Monitor - Use the c-treeACE Monitor tool for Windows and stop the server.
 Windows Service - Select and stop the c-treeACE service via the windows service
administrator.
 ToolTray - Right-click on the tool tray icon and select the appropriate shutdown option.
 Console - Exit the console application via the menu or the standard Windows "X" in the
corner.
 ctadmn - The c-treeACE Administrator utility provides an option to shut down the server.
 ctstop - The c-treeACE stop utility can be used to shut down the server.
• The net stop command line function. For example:
>net stop "c-treeACE Database Engine"
Unix, Linux, and Mac
 ctadmn - The c-treeACE Administrator utility provides and option to shut down the server.
 ctstop - The c-treeACE stop utility can be used to shut down the server.
 ./ctstop - A Unix shell script preconfigured to stop the server.
 Kill the server from a Unix command line. The c-treeACE Server traps the SIGSTOP signal.
www.faircom.com
All Rights Reserved
6
Installation
#kill <c-treeACE PID>
2.5
Links to c-treeACE Manuals
For complete information, view the online manuals:
 c-treeACE Administrator’s Guide (http://docs.faircom.com/doc/ctserver)
 c-treeACE SQL Operations Guide (http://docs.faircom.com/doc/sqlops/)
2.6
c-treeACE SQL Operational Files
There are several key file components unique to the c-treeACE SQL Server when compared to
the traditional NoSQL (ISAM) version.
c-treeACE SQL requires additional dictionary files to enable the required relational features of
SQL. In particular, sessions and databases are maintained in dictionary files. These files are
located in the following hierarchy of the server's operating environment, typically located by
default in /bin/ace/sql/data.
 ctdbdict.fsd - The main session dictionary file. If you remove any SQL databases from the
server, you need to either remove this file, or ensure that it is properly updated. The
appropriate way to drop a database and ensure the session dictionary is updated is to use
the SQL Explorer utility, or the command line ctsqlcdb utility.
 ctreeSQL.dbs/ - The directory containing the SQL database files and dictionaries. All new
tables and indexes associated with this database will be created in this directory. Use the
SQL Explorer utility, or the command line ctsqlcdb utility to add new databases.
 SQL_SYS/ctreeSQL.fdd - This file location is the SQL database dictionary, or also known as
the SQL system tables. It is NEVER appropriate to directly modify this file. The system tables
are stored as a single c-tree superfile along with the database dictionary.
 sql_server.log - This file will log specific SQL messages when the appropriate debug flags
are enabled. In particular, this file is useful for tracing Java Stored Procedure compile time
errors. Java Stored Procedure can also log messages to this file at run time with the err()
method.
www.faircom.com
All Rights Reserved
7
3.
c-treeACE SQL Features
3.1
Advanced Encryption for c-treeACE SQL Tables
c-treeACE SQL supports the ability to encrypt tables from the CREATE TABLE command. Two
forms of encryption are available.
Standard proprietary FairCom encryption, CAMO, is a lightweight, high performance option that
results in little overhead of server processing. This encryption option gives a reasonable level of
protection from casual inspection of the c-tree data and index files.
Advanced encryption, including standard AES (Rijndael), Twofish, Blowfish, and DES are also
available for industry standard hardening of data. The AES encryption standard may be required
with some forms of data, such as that used in the health care industry (such as to conform to U.S.
HIPAA regulations) and the financial industry.
The following encryption options can be used with the STORAGE_ATTRIBUTES keyword.
STORAGE_ATTRIBUTES 'CAMO'
STORAGE_ATTRIBUTES 'ENCR=crypt'
crypt can be one of the following:
 AES16 (Rijndael)
 AES24
 AES32
 DES8
 DES16
 DES24
 BLF8 through BLF56 (Blowfish)
 TWF16 (Twofish)
 TWF24
 TWF32
Example
CREATE TABLE encrypted_table (name CHAR(10), age SMALLINT) STORAGE_ATTRIBUTES 'ENCR=AES32' ;
To combine STORAGE_ATTRIBUTE options, separate them with a semicolon (;). For example, to
create a non-HUGE, CAMO encrypted table, you would issue a statement such as the following.
non-HUGE CAMO Example
CREATE TABLE small_camo_table (name CHAR(10), age SMALLINT) STORAGE_ATTRIBUTES 'CAMO;NONHUGE' ;
c-treeACE SQL must have the ADVANCED_ENCRYPTION configuration keyword specified in the
ctsrvr.cfg configuration file. The table creation will fail with c-treeACE SQL error -17454 (feature
www.faircom.com
All Rights Reserved
8
c-treeACE SQL Features
not supported) if you request an encryption option without this server configuration option
enabled.
Using an encryption mode not listed above will also result in the c-treeACE SQL error -17454 (not
supported).
3.2
Default HUGE File Tables with c-treeACE SQL
HUGE files (c-tree files larger than four gigabytes) are frequently encountered with today’s
massive storage needs. To accommodate these increased table sizes, c-treeACE SQL creates
files as HUGE by default. (Prior to c-treeACE SQL V9, new tables were created as standard
non-HUGE c-tree files.) An optional STORAGE_ATTRIBUTES clause containing ‘HUGE’ was
available to create c-treeACE SQL HUGE tables.
Reversing the previous behavior, the STORAGE_ATTRIBUTES clause supports a NOT HUGE
option to create standard size c-tree tables.
For backward compatibility, it is possible to revert to the original c-treeACE SQL behavior and set
thec-treeACE SQL default to ‘NOT HUGE’ by adding the following configuration keyword to
ctsrvr.cfg:
SQL_OPTION NO_HUGEFILE
The STORAGE_ATTRIBUTES clause will override any default configuration settings. Whether a
table is created HUGE or NOT HUGE with respect to the ctsrvr.cfg configuration and the
STORAGE_ATTRIBUTES statement clause is summarized in the following table:
c-treeACE SQL
Configuration
No specific
STORAGE_ATTRIBUTES
STORAGE_ATTRIBU
TES “HUGE”
STORAGE_ATTRIBU
TES “NOTHUGE”
default ctsrvr.cfg
HUGE
HUGE
NOT HUGE
SQL_OPTION
NO_HUGEFILE
NOT HUGE
HUGE
NOT HUGE
Example
CREATE TABLE table1 (column1 INT, column2 CHAR(10)) STORAGE_ATTRIBUTES 'NOTHUGE'
CREATE TABLE table2 (column1 MONEY, column2 VARCHAR(20)) STORAGE_ATTRIBUTES 'HUGE'
To combine STORAGE_ATTRIBUTE options, separate them with a semicolon (;).
Note: HUGE file support is not available for the Windows CE version of c-treeACE SQL.
3.3
PREIMAGE Tables in c-treeACE SQL
A significant performance gain can be obtained in some situations by avoiding transaction logging
of files, thereby foregoing the protection of recovery. With c-treeACE it is possible to maintain
atomicity of transactions in this state with a transaction mode of ctPREIMG. This support is also
extended to c-treeACE SQL Tables when they are created.
An additional option has been added to thec-treeACE SQL keyword STORAGE_ATTRIBUTES.
www.faircom.com
All Rights Reserved
9
c-treeACE SQL Features
STORAGE_ATTRIUBUTES 'PREIMG'
This option disables transaction logging for the table. This can be useful for temporary tables that
are not required to be recovered in the event of catastrophic failure, yet retain atomicity of
transactions.
To combine STORAGE_ATTRIBUTE options, separate them with a semicolon (;). For example, to
create a non-HUGE, PREIMAGE table, you would issue a statement such as the following.
non-HUGE PREIMAGE Example
CREATE TABLE small_preimage_table (name CHAR(10), age SMALLINT) STORAGE_ATTRIBUTES
'NONHUGE;PREIMG'
3.4
Shared Memory Connections for c-treeACE SQL Clients
on Windows
c-treeACE SQL for the Microsoft Windows OS supports a shared memory communication
protocol for c-treeACE SQL clients. This communications option is the default for clients
connecting locally, gaining a huge performance boost over the standard TCP/IP connections. A
configuration option is available to disable this support if desired. See SQL_OPTION
NO_SHARED_MEMORY (page 124).
3.5
Server-Side Connection Pooling
Connection pooling is a mechanism for pooling existing connections so they can be reused by
subsequent clients. The connection and disconnection process adds a substantial amount of
overhead to a SQL client performing a transaction. c-treeACE SQL offers options to enable
connection pooling. This reuse of existing connections can provide significant increases in
performance with your existing c-treeACE SQL ODBC and JDBC client applications.
SETENV DH_ENABLE_POOL=y
enable the connection pooling
SETENV DH_POOL_SIZE=#n
#n of pooled connections. ;1<#n<=100
These performance gains can be demonstrated in the simple test case of a client connecting and
disconnecting repeatedly with a small amount of work performed during each connection. In one
example, the client gained a 100% reduction in total application time. This feature offers
potentially enormous gains in performance for applications with clients that perform repeated
connects and disconnects.
3.6
Supported Transaction Isolation Levels
c-treeACE SQL supports both SQL transaction isolation levels 1 and 2. Transaction isolation
levels provide defined levels as to which transaction isolation succeeds. Four transaction isolation
levels are defined (SQL-92) by several phenomena. These phenomena are defined as follows:
 Dirty Reads. A dirty read occurs when a transaction reads data that is not yet committed by
another transaction.
 Non-repeatable Reads. A non-repeatable read is when a transaction reads data from the
same row twice, and gets different results, usually as the result of updates from another,
simultaneous transaction.
www.faircom.com
All Rights Reserved
10
c-treeACE SQL Features
 Phantoms. A phantom is a row that matches some search criteria, and is not initially seen, as
adds or deletes from another transaction have changed the result set available. Upon a
second attempt, the transaction is returned a different set of rows.
The SQL-92 defined isolation levels are shown in the following table. An ‘X’ identifies an included
phenomena; ‘--’ indicates absence.
Isolation
Characteristic
Le
vel
Dirt
y
Rea
ds
Non-repeatabl
e reads
Phantom
s
Read
Uncommitted
0
X
X
X
Read
Committed
1
--
X
X
Repeatable
Read
2
--
--
X
Serializable
3
--
--
--
Keep in mind that a transaction isolation level only affects data changes between transactions.
Changes within one’s own transaction are always available and will be seen.
The c-treeACE SQL configuration keyword MAX_SQL_ISOLATION_LEVEL sets the maximum
transaction isolation level at which c-treeACE SQL clients can operate. The supported values are:
MAX_SQL_ISOLATION_LEVEL 1; READ_COMMITTED only
MAX_SQL_ISOLATION_LEVEL 2; READ_COMMITTED and REPEATABLE_READ
The c-treeACE SQL default without this configuration keyword is a maximum isolation level of 1.
Transaction isolation levels 0 (READ_UNCOMMITTED) and 3 (SERIALIZABLE) are not available
with c-treeACE SQL at this time.
If a c-treeACE SQL client requests an isolation level that exceeds the default maximum isolation
level, or a maximum level specified in the server configuration file, the c-treeACE SQL client only
operates at the maximum isolation level ofc-treeACE SQL rather than the requested isolation
level.
A c-treeACE SQL ODBC client can request a specific transaction isolation level to work in,
provided the server supports this level. The SQL_ATTR_TXN_ISOLATION connection attribute is
used to request the level with the SQLSetConnectAttr() ODBC function call.
ODBC Example
/* After a connection handle is established... */
if (SQL_ERROR == (SQLSetConnectAttr(connection_hdl,
SQL_ATTR_TXN_ISOLATION, SQL_TXN_REPEATABLE_READ, 0)) )
printf(“Failed to set the Transaction Isolation Level\n”);
The client application can also determine the transaction isolation level in effect with the
SQL_TXN_ISOLATION_OPTION and SQL_DEFAULT_TXN_ISOLATION options with the
SQLGetInfo() function call.
ODBC Example
/* After a connection handle is established... */
www.faircom.com
All Rights Reserved
11
c-treeACE SQL Features
if (SQL_ERROR == (SQLGetInfo(connection_hdl, SQL_TXN_ISOLATION_OPTION, buf,
MAX_BUF, &buf_length)))
do_error(“Failed to Retrieve Current Transaction Isolation Level\n”);
if (SQL_ERROR == (SQLGetInfo(connection_hdl, SQL_DEFAULT_TXN_ISOLATION, buf,
MAX_BUF, &buf_length)))
printf(“Failed to Retrieve Default Transaction Isolation Level\n”);
Requesting transaction isolation level 2, REPEATABLE_READ can introduce delays as additional
overhead is involved in acquiring blocking read locks to ensure repeatable reads.
3.7
Case Insensitive Search Options for c-treeACE SQL
LONG Field Types
A limitation ofc-treeACE SQL LVARCHAR and LVARBINARY fields is the inability to use SQL
functions such as UPPER() or LOWER() to perform case insensitive searches. To address this
disadvantage of these field types, a proprietary c-treeACE SQL options clause is available to
allow a case insensitive search. The ctoption(icontains) clause will allow a case
insensitive search on a specific CONTAINS query. Include this clause on a query similar to the
following:
SELECT * FROM mytable WHERE bigfield CONTAINS 'Search Phrase' ctoption(icontains)
The option is only valid for the current query. ctoption(icontains) can be used with both
c-treeACE SQL LONG fields allowing both character and binary searching.
3.8
Query Timeout Option
c-treeACE SQL supports a timeout option for an executing query. This feature can ensure that an
unintended query statement does not consume excessive processing time for c-treeACE SQL .
Examples
With c-treeACE SQL ODBC you can set the query timeout value for the statement with the
SQLSetStmtAttr() c-treeACE SQL ODBC API function and the SQL_ATTR_QUERY_TIMEOUT
parameter set to the number of seconds to wait for the query to execute before returning to the
application. A value of 0 indicates no timeout value, which is also the default. The following
example code will set a query timeout value of five seconds for the referenced statement handle.
ODBC Example
/* Set the Query timeout to 5 seconds */
SQLSetStmtAttr(hstmt, (void*)SQL_ATTR_QUERY_TIMEOUT, 5, 0);
In Java with the c-treeACE SQL JDBC Driver, you can use the setQueryTimeout() method of the
java.sql.Statement interface as shown here.
JDBC Example
Class.forName (“ctree.jdbc.ctreeDriver”);
Connection myConnection = DriverManager.getConnection(“jdbc:ctree:6597@localhost:ctreeSQL”,
ADMIN, ADMIN”);
Statement myStatement = myConnection.createStatement();
String query = “SELECT TOP 50000 FROM my_big_table WHERE this < that AND this_string = 'that_string'
ORDER BY foo”
www.faircom.com
All Rights Reserved
12
c-treeACE SQL Features
myStatement:setQueryTimeout(5);
myStatement.executeUpdate(query);
Using ADO .NET with the c-treeACE SQL Data Provider, you specify the query timeout with the
CommandTimeout property of the CtreeSQLCommand component.
ADO .NET Example
myCommand = new CtreeSqlCommand(““, this.myConnection);
myCommand.CommandText = “SELECT TOP 50000 FROM my_big_table
= 'that_string' ORDER BY foo”;
WHERE
this < that AND this_string
myCommand.CommandTimeout = 5;
try {
myCommand.ExecuteReader();
}
catch (CtreeSQLException ex) {
//Log some error.
}
Using ODBC through ADO.NET, you can specify the OdbcConnection.CommandTimeout
property to set a query timeout value on an ODBC statement as demonstrated with the following
syntax.
c-treeACE SQL ODBC via ADO .NET Example
OdbcConnection myConnection = new OdbcConnection();
myConnection.ConnectionString = "DSN=c-treeSQL ODBC Database";
myConnection.Open();
OdbcCommand oc = new OdbcCommand("SELECT TOP 50000 FROM my_big_table
this_string = 'that_string' ORDER BY foo”, myConnection);
WHERE
this < that AND
// Set a query timeout of 5 seconds.
oc.CommandTimeout = 5;
try
{
oc.ExecuteReader();
}
catch (Exception ex)
{
// Log some error
}
3.9
Logging c-treeACE SQL Query Times
A c-treeACE SQL feature is available to log query start and end times as an additional aid for
tuning and performance monitoring. The query times are output to the file sql_server.log.
The output is controlled by two server configuration keywords and specified in the file ctsrvr.cfg.
SQL_DEBUG LOG_STMT_TIMES
This option logs start and end times for the statement PREPARE, EXECUTE and OPEN
operations.
SQL_DEBUG LOG_STMT_TIMES_FETCH
This option logs start and end times of a fetch sequence (open cursor, all fetches, and close
cursor).
www.faircom.com
All Rights Reserved
13
c-treeACE SQL Features
Both options can be specified at the same time. The actual log entry occurs when the query
operation is finished.
Example Output
Start: Thu Mar 09 13:50:12 2006
- User# 00014 Elapsed:
0 sec. for PREPARE
Start: Thu Mar 09 13:50:12 2006
- User# 00014 Elapsed:
0 sec. for OPEN
Start: Thu Mar 09 13:50:12 2006
- User# 00014 Elapsed:
2 sec. for FETCH
3.10
select top 5000 * from facility
select top 5000 * from facility
select top 5000 * from facility
Built-in Stored Procedure to Switch Transaction Mode
It can be useful for performance reasons to avoid transaction memory usage in some common
maintenance operations. Consider the case of upgrading a large database where some tables
are added with a SQL query from another table that returns a large number of rows. As this
occurs inside a single SQL statement the transaction consumes memory until committed. For
large files, this can potentially exhaust memory on some systems and result in complete failure.
c-treeACE can allow the transaction processing mode of a file to be disabled which avoids
consuming memory for a very large operation. To make this available to c-treeACE SQL, a
built-in stored procedure allowing the transaction mode of a file to be changed has been added.
This operation requires exclusive file access.
fc_set_file_tran_state(VARCHAR owner, VARCHAR tablename, TINYINT mode)
Valid values for mode are
 0 : No transaction control.
 1 : Transaction control without recoverability. (ctPREIMG)
 2 : Transaction control and recoverability. (ctTRNLOG)
When a c-treeACE SQL file is set to mode of 0 (no transaction control), all changes to the file will
have immediate and permanent effect, such that a ROLLBACK operation will have no effect on
this file. If another user is able to open the file, isolation levels are undefined. Furthermore,
c-treeACE SQL operations that modify multiple rows of this table will not be atomic in the event of
an error.
For update statements, it is important to ensure no errors are encountered during execution. For
example, a statement such as
UPDATE tbl SET col=99
that encounters an error midway through the update, will leave the state of the table undefined
and the operation should be re-examined. It is possible it will be necessary to restore from a
backup to return to a previous state.
Because of these effects, the intended use of this mode is limited in scope. No file
definition/schema changes to this file should occur while in this mode. All previous schema
changes should be committed before calling this procedure. If an error occurs while operating
on a file with a mode 0, the table should be deleted and the transaction rolled back.
Note: The stored procedure fc_check_file_tran_state() can be used to ensure that no files
remain in modes other than the database default.
www.faircom.com
All Rights Reserved
14
4.
c-treeACE SQL Options
4.1
Environment Variables
c-treeACE SQL can set environment variables for the server process on startup. This functionality
is implemented via the keyword SETENV. For example, the c-treeACE SQL looks at the
CLASSPATH to find required classes for proper operation of the server. When the c-treeACE
SQL is running as a Windows 32-bit versions Service, c-treeACE SQL is launched automatically
by the SCM (Service Control Manager) when the computer starts up. Setting the CLASSPATH
via a keyword eliminates the manual operation of setting environment variables. The syntax is as
follows:
SETENV <var>=<value>
Where var is the environment variable and value is the setting. For example:
SETENV CLASSPATH=%CLASSPATH%;C:\FairCom\ctreeJQL\classes
The input line length for the server configuration file is 1024 to allow for very long configuration
values.
The c-treeACE SQL considers existing environment variables during startup processing for the
Java environment used with stored procedures. The following variables are used in the
c-treeACE SQL configuration file, ctsrvr.cfg, to set the parameters for the Java JVM and compiler.
These configurations are required for c-treeACE SQL Stored Procedures, Triggers, and User
Defined Functions:
SETENV
SETENV
SETENV
SETENV
CLASSPATH=
JVM_LIB=
JAVA_COMPILER=
DEBUG_JVM
When these values are not explicitly set within the server configuration file, the server considers
existing system environment variables.This feature simplifies setup and configuration changes for
c-treeACE SQL Stored Procedures. Refer to the Appendix Server Configuration Keywords for a
complete list of c-treeACE SQL-specific keywords.
4.2
Default Date Handling
c-treeACE SQL allows for internationalization of date formats. The following configuration option
changes the default date handling:
SETENV TPE_DFLT_DATE=XX
or
SETENV_TPE_DFLT_DATE=XX_DFLT_DATE
where XX can be one of the following options:
www.faircom.com
All Rights Reserved
15
c-treeACE SQL Options
 US
US_DFLT_DATE
 UK
UK_DFLT_DATE
 ISO
ISO_DFLT_DATE
Changing the default date format affects:
 The default output format of date values.
 How SQL interprets date literals in queries and INSERT statements.
The format value determines how c-treeACE SQL interprets character strings inserted as DATE
values or compared to DATE columns. For example, a formate value of UK_DFLT_DATE allows
users to supply date literals in British format (dd/mm/yyyy). The format value also determines the
default output format of date data.
The following table details the different formats each supported value. The boldface entries
indicate the default output format for each setting.
US_DFLT_DATE
UK_DFLT_DATE
ISO_DFLT_DATE
dd-mm-yyyy
dd/mm/yyyy
dd-mm-yy
dd/mm/yy
mm-dd-yyyy
mm-dd-yyyy
mm/dd/yyy
mm/dd/yyy
mm-dd-yy
mm/dd/yy
4.3
yyyy-mm-dd
yyyy-mm-dd
yyyy-mm-dd
yyyy/mm/dd
yyyy/mm/dd
yyyy/mm/dd
dd-mon-yyyy
dd-mon-yyyy
dd-mon-yyyy
dd/mon/yyyy
dd/mon/yyyy
dd/mon/yyyy
dd-mon-yy
dd-mon-yy
dd/mon/yy
dd/mon/yy
Case-Sensitivity Options
Sorting of fetched rows is performed as a case sensitive operation. Some applications may
require sorting that should, instead, be case insensitive with NULL values appearing first in the
sort. For instance the values “a, Z, B, g, NULL” should be sorted as “NULL, a, B, g, Z”.
A feature is available such that a database can be implied to be case sensitive (current default) or
case insensitive. When a database is enabled as case insensitive, the sorting, comparisons and
identifier will be considered case insensitive.
This feature is activated with the c-treeACE SQL configuration keyword
SQL_OPTION DB_CASE_INSENSITIVE
www.faircom.com
All Rights Reserved
16
c-treeACE SQL Options
This should be done before creating the template database. Once the template database is
created, ALL the databases will have the same settings of the template.
When using case insensitive searches, all search conditions, sorting and grouping is done in a
case insensitive manner. Metadata and character indexes are also considered to be case
insensitive. Case insensitivity is enabled on a database by database basis.
4.4
Optimizer Configuration Options
The c-treeACE SQL query optimizer plays an important role in reducing the execution time of
c-treeACE SQL queries. The role of the optimizer is to minimize the number of read requests that
are made for the data and index files.
This minimization process is computed by the optimizer based on the cardinality (the number of
records selected), selectivity (the fraction of the records selected based on an operator), and a
set of index key values. For many operations on records or indices, a cost, in terms of time units,
is used to decide between the use of a record or index-oriented scan.
Users may wish to disable the cardinality, selectivity and/or costing features to force particular
optimizations of c-treeACE SQL. Having these features enabled or disabled will induce the
optimizer to perform queries using different strategies to select the resulting dataset.
Three c-treeACE SQL configuration file keywords were added to control the optimizer's usage of
cardinality, selectivity and costing of record and index operations: NO_CARDINALITY,
NO_SELECTIVITY and NO_COSTS. These keywords must be used with the SQL_OPTION
configuration command.
 NO_CARDINALITY - disables the cardinality logic that informs the optimizer about the number
of rows in a data or index file.
 NO_SELECTIVITY - disables the selectivity logic that informs the optimizer about the
percentage of rows returned when applying a given search criteria.
 NO_COSTS - disables the logic that returns to the optimizer the cost in units of time for given
record and index operations. The optimizer will use this information to decide whether to use
a record or an index scan.
Note: Costs are not implemented in the current version of c-treeACE SQL. Behavior may change
in future releases.
To disable cardinality, selectivity, and costing logic, add the following keywords to the c-treeACE
SQL configuration file:
Example
SQL_OPTION NO_CARDINALITY
SQL_OPTION NO_SELECTIVITY
SQL_OPTION NO_COSTS
4.5
c-treeDB ROWID Options
When using c-treeDB and c-treeACE SQL, it is possible to encounter situations where c-treeDB
ROWIDs do not match c-treeACE SQL ROWIDs. With c-treeDB the first ROWID starts with 1 and
so on, as this is how the SRLSEG mode works. Conversely, c-treeACE SQL’s ROWIDs start with
0 and so on.
www.faircom.com
All Rights Reserved
17
c-treeACE SQL Options
Now the ROWID at the c-treeACE SQL level is “zero” based by default, as it previously was. For
backward compatibility with those applications requiring so, it is possible to force the “one” based
option, identical to c-treeDB, with the following c-treeACE Server configuration keyword:
SQL_OPTION CTDB_ROWID
Refer to the Appendix Configuration Keywords for a complete list of c-treeACE SQL-specific
keywords.
4.6
Automatic Database Conversion Options
Enhancements and features to c-treeACE SQL sometimes require changes to the base system
tables and internal workings of the c-treeACE SQL engine. To make this transition as seamless
as possible, an automatic verification and conversion to the new format takes place when the
server detects system tables from a previous version of the c-treeACE SQL.
To prevent this activity from occurring, a new c-treeACE SQL configuration keyword was
introduced.
SQL_OPTION NO_DB_CONVERSION
This server configuration keyword is used to instruct the c-treeACE SQL to not perform the
verification and the conversion process. To prevent a failed conversion attempt, these steps are
controlled within a transaction such that upon failure a transaction abort or automatic recovery will
restore the original data.
Refer to the Appendix Configuration Keywords for a complete list of c-treeACE SQL specific
keywords.
4.7
Template Database __Master.dbs Handling
c-treeACE SQL previously created new databases by copying a supplied template database,
__Master.dbs. (This template was automatically created if it did not exist when needed.)
c-treeACE SQL databases are now created directly without copying from a template database.
This change typically results in faster database creation in the usual case of a single database.
It is possible to revert the behavior of the template database with the following configuration
keyword:
SQL_OPTION FORCE_TEMPLATE_DB
This keyword forces template database creation upon server startup even if the template already
exists (to ensure a consistent starting database). When this keyword is specified, c-treeACE SQL
creates all new databases by copying the template database. Refer to the Appendix Server
Configuration Keywords for a complete list of c-treeACE SQL-specific keywords.
4.8
SQL_DEBUG Options
Additional c-treeACE SQL debugging control can be used with these configuration keywords:
;SQL Debugging information
;SQL_DEBUG LOG_STUBS_HIGH
;SQL_DEBUG LOG_STUBS_LOW
;SQL_DEBUG LOG_STUBS_MED
www.faircom.com
All Rights Reserved
18
c-treeACE SQL Options
;SQL_DEBUG INDEX
;SQL_DEBUG INDEX_INFO
;SQL_LOGFILE C:\sql_debug.txt
This will log additional information to a specific SQL_LOGFILE if desired.
LOG_STUBS_HIGH logs very sparse information detailing table create activities.
LOG_STUBS_MED logs basic SQL Statement information.
LOG_STUBS_LOG logs very low level stubs information, which can be quite voluminous.
INDEX and INDEX_INFO may not be active at the current time (Oct 2005).
4.9
Advanced c-treeACE SQL Logging
c-treeACE SQL has extensive internal debugging logic that can be accessed through various
means. SQL errors can be logged to the file sql_server.log in the c-treeACE SQL directory.
TPESQLDBG is an array of 12 ‘Y’/‘N’ characters that determine which debug options are
enabled. The order of the debug operations in the string is shown below:
Offset
Debug Option
0
sql_debug
1
cache_debug
2
ddm_debug
3
xec_debug
4
opt_debug
5
remt_debug
6
display_cost
7
hm_hdl_debug
8
hm_itm_debug
9
phm_debug
10
java_debug (#if
defined(DH_JAVA_SP) || defined
(DH_SUN_JDK))
11
log_error
java_debug is ignored for c-treeACE SQL operating without a defined Java environment. Options
are enabled by specifying ‘Y’. The string value to disable all debug options would look as follows:
NNNNNNNNNNNN
This value can be set through various means: a server configuration keyword; the built in
set_debug() stored procedure; and the ctsqlcdb.exe utility.
To set the debugging logic at server startup, place the following configuration keyword with the
desired debug string in ctsrvr.cfg. For example, to enable Java stored procedure debug output,
use the following configuration string:
www.faircom.com
All Rights Reserved
19
c-treeACE SQL Options
SETENV TPESQLDBG=NNNNNNNNNNYN
A stored procedure set_debug(varchar (20)) is available to dynamically change the internal
server debug features. This stored procedure sets the debug features according to the
TPESQLDBG string passed as an argument and returns a row containing the actual debug
setting (after applying the new debug settings). If an empty string (“”) is passed, set_debug()
returns the current debug setting. For example, to set the Java stored procedure debug output
call set_debug() as follows:
CALL fc_set_debug(‘NNNNNNNNNNYN’);
Additionally the ctsqlcdb utility can be used as follows:
ctsqldb -setdbg NNNNNNNNNNYN <databasename> <servername>
You can retrieve the current settings in use with the following ctsqlcdb parameter:
ctsqldb -getdbg <databasename> <servername>
4.10
Memory Manager (MM) System for Temporary Storage
For queries involving sorting and/or joins, c-treeACE SQL may create temporary tables which
exist in memory and/or on disk, depending on the amount of data in the temporary table.
c-treeACE SQL provides options to optimize these queries with regard to physical memory space
available on the server. Tuning these options can greatly enhance performance when dealing
with large result sets generating extremely large temporary tables.
An internal memory storage system provides a mechanism for c-treeACE SQL to store data in
memory instead of on disk. By using this internal storage system for volatile data such as
temporary tables and dynamic indexes, the c-treeACE SQL improves the performance of many
queries, such as joins. Depending on the amount of memory available on a system, certain
queries may create temporary tables too large to be stored in memory. In these cases, the
internal storage system swaps blocks of data to a disk file as necessary. The following variables
allow implementations to control the characteristics of how this internal storage system uses
memory to create temporary tables.
 SETENV TPE_MM_CACHESIZE: Specifies the size, in kilobytes, of the memory cache used for
temporary tables. The default value is 1,000 KB (1MB) of memory. The internal storage
system uses this cache for storing temporary tables when sorting and creating dynamic
indexes during processing. Increasing TPE_MM_CACHESIZE improves performance by
reducing the need to write to the on-disk swap file.
The TPE_MM_CACHESIZE setting determines how much memory the SQL engine uses for its
temporary tables for each SQL client. Increasing this setting increases the amount of
temporary table data the c-treeACE SQL stores in memory instead of writing this data to the
disk-based swap file. However, note that this memory is allocated for each SQL client, so you
should consider how many clients will connect to c-treeACE SQL at any given time and make
sure total cache memory doesn't exceed available physical memory on the system.
Up to 4 TB total memory is available in this subsystem.
 SETENV TPE_MM_SWAPSIZE: Specifies the maximum size, in kilobytes, of the swap file the
internal storage system uses when it writes to disk from the main memory cache. The default
is 500,000 KB (500 MB). The sorting of data larger than this size results in the following
c-treeACE SQL error
(-16001):MM No data block
www.faircom.com
All Rights Reserved
20
c-treeACE SQL Options
To resolve this error, the TPE_MM_SWAPSIZE limit needs to be increased.
Note: These swap files can be found during an active connection with a filename beginning
with ‘M’ followed by a string of random alphanumerics. These files can sometimes be left
around after an abnormal server shutdown. They can be safely deleted in such a case.
This keyword can be used to resolve error (-16025):MM sorting error.
Increasing the c-treeACE cache configurations DAT_MEMORY (data cache size) and IDX_MEMORY
(index cache size) settings can significantly reduce the number of bytes read from disk while
executing a query.
Note: The MM subsystem was replaced with a new architecture beginning with V10.3. See
SQL_OPTION USE_MM (page 131)
www.faircom.com
All Rights Reserved
21
5.
5.1
c-treeACE SQL Java Configuration for
Stored Procedures, Triggers and User
Defined Functions
Run-Time Settings for Java Stored Procedure Support
c-treeACE SQL uses the portable Java language for stored procedures, triggers, and
user-defined functions. To take advantage of these advanced features, a functioning Java
environment will need to be available on your operating platform. When the Java JVM is present,
and the server is properly configured, these features become available.
c-treeACE SQL requires the Java Runtime Engine (JRE) version 1.6 or later. To create stored
procedures requires the Java Development Kit (JDK) version 1.6 or later.
The Java JDK and JRE for many platforms are available at no cost. Click here to download
(http://www.oracle.com/technetwork/java/javase/downloads/index.html).
Note: 64-bit versions of c-treeACE SQL require a 64-bit version of the JVM to implement stored
procedures.
c-treeACE SQL Configuration
Use the following c-treeACE Server configuration keywords to set your Java environment to take
advantage of full stored procedures, triggers, and user-defined functions support.
; JDK environment settings - Be sure to set the JDK to your version.
SETENV CLASSPATH=C:\Program
Files\Java\jdk1.7.0_07\jre\lib\rt.jar;C:\FairCom\VX.X.X\win32\bin\ace\sql\classes\ctreeSQLSP.
jar (where VX.X.X refers to your c-treeACE version number)
SETENV JVM_LIB=C:\Program Files\Java\jdk1.7.0_07\jre\bin\server\jvm.dll
SETENV JAVA_COMPILER=C:\Program Files\Java\jdk1.7.0_07\bin\javac.exe
The following table lists the Java-related runtime settings needed for the c-treeACE SQL to
support Stored Procedures, Triggers and User-Defined Functions. These are required for
initializing the JVM within c-treeACE SQL.
Java Related Runtime Settings c-treeACE SQL with JSP
Environment Variable Name
Environment Variable Value
JDKHOME
DRIVE:\PATH_TO_JAVA\
CTREEHOME
DRIVE:\PATH_TO_CTREE\
www.faircom.com
All Rights Reserved
22
c-treeACE SQL Java Configuration for Stored Procedures, Triggers and User Defined Functions
5.2
Environment Variable Name
Environment Variable Value
CLASSPATH
%JDKHOME%\jre\lib\rt.jar;
%CTREEHOME%\ctreeSDK\ctreeAPI\bin.jql\classes
JVM_LIB
%JDKHOME%\jre\bin\server\jvm.dll
JAVA_COMPILER
%JDKHome%\bin\javac.exe
Debugging Java Stored Procedures
c-treeACE SQL allows Java debugging tools to connect and directly debug stored procedure
routines. To enable this feature, follow the following steps.
1. Add the following keywords to ctsrvr.cfg:
SETENV DEBUG_JVM=S
SETENV DEBUG_JVM_PORT=45987
The first keyword the enables the c-treeACE SQL JVM debug feature by creating a TCP/IP
socket at the port specified with the DEBUG_JVM_PORT keyword for a Java debugger to
attach. In addition, the DEBUG_JVM keyword instruct the server to compile stored procedures
with debugging information and to not remove the stored procedure source file from disk.
2. Start the c-treeACE SQL server.
3. Create a stored procedure (for example, “test”).
4. Examine the database directory (i.e. ctreeSQL.dbs) for a .java file. This is the Java file
source. Pay particular attention to the class name (i.e. public final class admin_test_SP
extends JavaBaseSP).
5. Start a Java debugger and attach it to localhost on the port specified by
DEBUG_JVM_PORT.
For example, using the Java debugger included with the JDK, run:
jdb -attach 45987
(run on the same machine running the server to access the Java source files).
6. Set a breakpoint on the method dhSPwrap of the stored procedure calls (i.e.
admin_test_SP.dhSPwrap).
7. Call the stored procedure from any client side SQL tool such as ISQL.
8. The debugger should break at the start of the stored procedure.
JSWAT Example
JSwat is an open-source GUI Java debugger. It can be downloaded from
https://github.com/nlfiedler/jswat (https://github.com/nlfiedler/jswat).
1. Add the following keywords to ctsrvr.cfg:
SETENV DEBUG_JVM=S
SETENV DEBUG_JVM_PORT=45987
2. Start the c-treeACE SQL Server.
3. Start ISQL and create a stored procedure as follows:
# isql -a ADMIN -u admin ctreeSQL
www.faircom.com
All Rights Reserved
23
c-treeACE SQL Java Configuration for Stored Procedures, Triggers and User Defined Functions
CREATE PROCEDURE admin.test( IN name CHAR (20) )
BEGIN
Integer testing = new Integer(24);
END
4. Start jswat.
5. Select “New Session” from the “Session” menu and edit the following information:
a. Assign a name (for instance “c-treeACE Session”).
b. Switch to the “classes” panel and add the path to the ctreeSQLSP.jar file and the path to
the ctreeSQL.dbs directory.
c. Switch to the “Sources” panel and add the path to the ctreeSQL.dbs directory.
6. Select the session just created from the Sessions Drop Down menu on the toolbar.
7. From the “Session” menu, click on “Attach”
8. Configure the Transport as "Attach by socket". Fill in Host and Port with information from your
c-treeACE SQL Server configuration.
9. Click OK (The “debugger console” should now read” “VM attached to session c-treeACE
Session”.
10. In the “Breakpoint” menu select “New Breakpoint” to create a new breakpoint.
a. Set Breakpoint type to “Method.”
b. Set Class to the stored procedure name (for example, admin_test_SP).
c. Set Method to “dhSPwrap.”
www.faircom.com
All Rights Reserved
24
c-treeACE SQL Java Configuration for Stored Procedures, Triggers and User Defined Functions
11. Return to ISQL and run the stored procedure:
call test ('John Smith');
12. The debugger displays the current line in the stored procedure.
www.faircom.com
All Rights Reserved
25
c-treeACE SQL Java Configuration for Stored Procedures, Triggers and User Defined Functions
5.3
Advanced JVM Configuration
The JVM is loaded into c-treeACE SQL and becomes part of the process when the appropriate
configuration options point to a valid Java Runtime Engine (JRE). Stored procedures, triggers,
and user-defined functions are executed within this JVM. The JVM environment can be
configured and tuned with numerous options. The deployment architect should be familiar with
these options from the available Oracle Java documentation.
http://www.oracle.com/technetwork/java/javase/tech/vmoptions-jsp-140102.html
http://www.oracle.com/technetwork/java/javase/tech/vmoptions-jsp-140102.html
The SETENV DH_JVM_OPTION_STRINGS configuration keyword can be used to specify exact
parameters for the JVM to use at runtime.
Note: Java stored procedures and triggers developers may take advantage of many different
Java features and have wide latitude in creating stored procedure logic. Due to this, it is difficult
to make general recommendations, however, information and links are provided below to
demonstrate the vast variety of options available.
Different options may be available on different platforms as Java is a highly cross-platform
environment.
Heap Memory
One of the most important considerations is memory usage of the JVM. This can result in
unexpected memory usage of the c-treeACE SQL process. As the JVM gradually allocates
additional heap memory, the process space can grow quite unexpectedly. While Java takes
advantage of advanced automatic garbage collection of unused memory references, the triggers
for this are many, and in some cases, require careful tuning for the best balance of performance
www.faircom.com
All Rights Reserved
26
c-treeACE SQL Java Configuration for Stored Procedures, Triggers and User Defined Functions
and memory use. Two options of immediate use are the minimum and maximum size of the
memory heap.
The JVM defaults to certain proportions of available memory, depending on the OS and if the
process is 32-bit or 64-bit.
The initial heap size of the JVM is the following:
 Larger of 1/64th of the machine's physical memory or some reasonable minimum. Before
J2SE 5.0, the default initial heap size was a reasonable minimum, which varies by platform.
 If the nursery size (the part of the heap memory reserved for allocation of new objects) is set
with -Xns, the default initial heap size will be scaled up to at least twice the nursery size.
You can specify the initial (and minimum) JVM heap size with the -Xms option.
SETENV
DH_JVM_OPTION_STRINGS=-Xms:4m
Note: The initial Java heap cannot be set to a value smaller than 8 MB, which is the minimum
Java heap size. If you attempt to set it to a smaller value, JVM defaults to 8 MB.
The -Xms value cannot exceed the value set for -Xmx (the maximum Java heap size).
The maximum heap size of the JVM is the following:
 Smaller of 1/4th of the physical memory or 1GB. Before J2SE 5.0, the default maximum heap
size was 64MB.
You can specify the maximum JVM heap size with the -Xmx command-line option.
SETENV
DH_JVM_OPTION_STRINGS=-Xmx:16m
http://docs.oracle.com/javase/7/docs/technotes/guides/vm/gc-ergonomics.html
http://docs.oracle.com/javase/7/docs/technotes/guides/vm/gc-ergonomics.html
Alternative Garbage Collectors
Alternative garbage collectors (GC) are available within the JVM. For particular environments, it
may be advantageous to choose an alternate GC for throughput or latency reasons.
 -XX:+UseParallelOldGC (default)
www.faircom.com
All Rights Reserved
27
c-treeACE SQL Java Configuration for Stored Procedures, Triggers and User Defined Functions
 -XX:+UseConcMarkSweepGC
 -XX:+UseG1GC (New in Java 6 and 7)
Many numerous options are available to tune each of the Java garbage collectors for
performance, throughput and low-latency. Check the current Java documentation for your chosen
JVM for complete details.
GC Monitoring
It is frequently necessary to examine actual garbage collection statistics. Java garbage collection
has many debugging options available for this task. Here is a minimum set to consider:
-Xloggc:<filename>
-XX:+PrintGCDetails
-XX:+PrintGCDateStamps
-XX:+PrintTenuringDistribution
-XX:+PrintGCApplicationConcurrentTime
-XX:+PrintGCApplicationStoppedTime
Monitoring Tools
The JVisualVM utility included with your Java installation is recommended for advanced
monitoring of the Java GC process. Load the Visual GC plugin from the "Tools->Plugins" menu.
 See Debugging Java Stored Procedures (page 23)
www.faircom.com
All Rights Reserved
28
6.
c-treeACE SQL Utilities
c-treeACE SQL provides a powerful interface over you c-tree data. Various utilities are available
to facilitate the migration, use and maintenance of c-treeACE SQL.
6.1
ctpath - Change Internal Database Paths
Changes the internal SQL dictionary paths of database locations.
Syntax
ctpath -s server -u user -p password -d database from-path-prefix to-path-prefix
Description
 When ctpath is executed without command line arguments, you get the full GUI version.
ctpath GUI (without command line arguments) always return 0.
 When ctpath is executed with command line arguments, it runs silently and all error
messages are written in a log file CTPATH.LOG stored in the same directory as the ctpath
file.Error messages are appended to CTPATH.LOG file with a date and time stamp to each
error message.
 ctpath with command line arguments returns 0 when the execution detected no errors, or a
value different than 0 when errors were detected and the error messages are written to
CTPATH.LOG.
 If you omit the -d database switch, all databases in the session will be scanned.
 Command line switches should start with a '-' or '/' character. Command line switches accept
both lowercase and uppercase characters, e.g. -s or -S are the same.
 Command line switches may have optional spaces between the switch and the argument.
Example: -s FAIRCOMS or -sFAIRCOMS are the same.
 Command line switches maybe entered in any order, but the from-path-prefix must appear
before the to-path-prefix.
6.2
ctsqlbigint - c-treeACE SQL Big Integer Fix Utility
A BIGINT issue on HIGH LOW machines could result in improper values on heterogeneous
systems. This utility is designed to detect and correct such issues should they occur. Contact
FairCom should you require this utility.
Syntax
ctsqlbigint [-<sect>] [dbname [tblname]]
This utility to be compiled as single user with tranproc and run in the c-treeACE SQL operating
directory.
www.faircom.com
All Rights Reserved
29
c-treeACE SQL Utilities
 <sect> the sector size
 dbname is specified the engine converts the tables in that database. If dbname is not
specified all databases will be converted.
 tblname only the specified table in the given database is converted.
Running the conversion twice restores records to their original values.
6.3
ctsqlcdb - c-treeACE SQL Database Maintenance Utility
Usage
ctsqlcdb <command> <dbname> [<servername>]
Valid Commands:
 -add: Adds a reference to an existing database
 -create: Creates a new database
 -drop: Removes a reference to an existing database
 -exist: Returns 1 if database exists, 0 if not, 2 on error
 -list <servername>: Lists databases available from the server
 -create_preimage: Creates a preimage only database (supporting only atomicity; no
transaction logs for durability.)
Or the following command syntax copies an existing database and adds a reference to the new
copy:
 -copy <dbname> <newname> [<servername>]
-copy also includes non c-tree files when present in the database directory area.
where:
• <dbname> is the database name, and
• <servername> is the optional c-treeACE SQL name.
The -copy command supports virtual tables (called "Multi Record Tables" or "MRT tables").
6.4
ctsqlimp - c-treeACE SQL Import Utility
The c-treeACE SQL import utility, ctsqlimp, utility “registers” or links existing c-tree Plus files with
a c-treeACE SQL database without modifying the table structure such that the files remain
accessible from the original application and also accessible from c-treeACE SQL.
ctsqlimp Usage
ctsqlimp is used as follows (after creating the database file):
ctsqlimp <filename> [-d database] [-s server] [-u userid] [-a password]
[-n symbolic] [-o userid]
[-i] [-r] [-k] [-c] [-x] [-p|-P] [-z] [-g] [-b|-B] [-j]
[-w script] [-m idxname] [-e xmlfile] [-f s|z|sz] [-l size] [-q prefix]
[-h]
 <filename>: data file name/path (relative paths to c-treeACE SQL directory)
www.faircom.com
All Rights Reserved
30
c-treeACE SQL Utilities
 -d database : database name (default: ctreeSQL)
 -s server: c-treeACE SQL Server name (default: FAIRCOMS)
 -u userid: userid for logging into c-treeACE SQL
 -a password: password for authorization
 -n symbolic: set SQL table name to symbolic symbolic
 -o userid: set owner of table to userid
 -i: non interactive mode: ignore errors and continue
 -r: remove existing linked table (file is not deleted)
 -k: skip fields that don't comply with conventional identifiers rules
 -c: allow table names not complying with conventional identifiers rules
 -x: skip indices
 -p: promote unsigned integer to greater signed type
 -P: promote unsigned types to greater signed type and set check for fitting value
 -z: allow indices with missing string terminator in key segments
 -g: ignore existing index name in IFIL resource
 -b: (lowercase) switch grants all permissions on the table to the public
 -B: (uppercase) switch grants read-only permissions on the table to the public
Note: If both -B and -b are specified, the read-only setting takes precedence. Notice that the
owner of the table and the DBA have all the permissions.
This introduces a change in behavior for existing applications because this switch is
now-case sensitive.
 -j: non-interactive relink of existing table
 -w script: write CREATE statements into script file script instead of importing the table
 -m idxname: set index idxname as primary key
 -e xmlfile: get DODA definitions from external XML file xmlfile
 -f s | z | sz: force string padding to (s)paces (z)eroes or (sz)spaces zero terminated
 -l size: specify LONGVAR* field size threshold
 -q prefix: prefix SQL table name with prefix (when the -q option is combined with the symbolic
table name option, -n, the prefix is prepended to the symbolic name instead to the table
name)
 -h: display usage help
Note: The parameters are case-sensitive. By default they are lower case unless otherwise stated.
Example
To make existing c-tree files mydata.dat (containing proper IFIL and DODA resources) and
mydata.idx accessible via c-treeACE SQL, follow these steps:
1. Create a database named ctreeSQL.
2. Copy your ISAM custmast.dat and custmast.idx files into the ctreeSQL.dbs subdirectory of
the server's working directory.
3. Ensure c-treeACE SQL is running, as ctsqlimp is a client application.
4. Run the ctsqlimp utility found in the /tools/cmdline/admin/client/ directory of your c-treeACE
installation:
www.faircom.com
All Rights Reserved
31
c-treeACE SQL Utilities
ctsqlimp custmast.dat -u ADMIN -a ADMIN -s FAIRCOMS
5. Run the Interactive SQL, isql, utility and issue the command:
SELECT * FROM custmast;
Specifying primary keys from imported indexes
A command line option is available with the c-treeACE SQL Table Import Utility, ctsqlimp to
specify a primary key from imported indexes. Use the -m option to specify an imported index of
the table to be the primary key. The -m option takes an index name as a parameter. The index
name is defined in the ridxnam member of the IFIL resource IIDX structure. Please notice that if
ridxnam is not defined, an index name is automatically assigned when the table is added to the
c-treeACE SQL system tables. The format of the automatically assigned index name is:
tablename_indexnbr where indexnbr is zero for the first index.
Example
ctsqlimp my_table -u ADMIN -p ADMIN -m my_index
Check for Max Number of Indices/Segments
As of V10.3, logic in ctsqlimp checks for the maximum number of indices or segments. When
importing tables, this logic checks if the number of indices defined is less than MAX_DAT_KEY
value and the number of segments per key is less than MAX_KEY_SEG value. This logic prevents
the import unless you are using interactive ctsqlimp, which asks if you want to continue with the
import because it may be useful to import the table and adjust the server setting afterwards.
Allow linking SQL indices with rightmost segment(s) on hidden field(s)
Prior to V11, the ctsqlimp logic did not allow importing indices if at least one of the segments
points to a field not exposed in SQL. This is encountered frequently in the c-treeRTG products.
In V11 and later, the ctsqlimp logic optionally (OFF by default) allows importing indexes having
segments pointing to hidden fields if at least one segment is valid and all segments pointing to
hidden fields are the rightmost with no intermixing of exposed and hidden fields.
This logic is controlled by a new sqlimport callback CTSQLCB_CONFIRM_INDEXTRUNC.
Mapping unsigned integers with c-treeACE SQL
A command line option is available to ctsqlimp, -p, to map an unsigned integer (CT_CHARU,
CT_INT2U and CT_INT4U) not to a corresponding c-treeACE SQL type but to the next larger
integer type, thus “promoting” it. While the c-treeACE SQL engine will use the larger integer type,
nothing at the c-tree ISAM storage level changes. This allows proper unsigned (positive) values
for those values that when mapped into a signed field would become negative.
Without the -p option the mapping from c-tree to c-treeACE SQL is the following:
 CT_CHARU - TINYINT
 CT_INT2U - SMALLINT
www.faircom.com
All Rights Reserved
32
c-treeACE SQL Utilities
 CT_INT4U - INTEGER
With the -p option the mapping becomes:
 CT_CHARU - SMALLINT
 CT_INT2U - INTEGER
 CT_INT4U - BIGINT
When using the -p switch, a SELECT * from table shows the proper values for unsigned integer
fields instead of a negative value.
When doing an insert, as long as the inserted value fits in the original type range, the value seen
at the ISAM level is the proper one. If the value inserted is outside the original type range, only
the lower significant part is stored.
Check for Invalid Characters in Field Names
The -k switch allows one to skip importing fields that do not comply with the conventional identifier
rules without being prompted every time an incompatible field is encountered.
ctsqlimp also has a “non-interactive” option (-i) which avoids prompting the user by having a list
of pre-defined default answers. The actions taken by default are the most conservative and safe.
In case an unconventional field is encountered, the default action is to import the field and inform
the user that in c-treeACE SQL statements, the resulting column name must be enclosed in
double quotation marks.
The option -k can be used in conjunction with the -i option to change the default behavior in case
an unconventional field is encountered and automatically skip it.
Support for Importing Table with an Alternative Name
The c-treeACE SQL import utility derives the table name to be stored in the c-treeACE SQL
system tables from the physical file name, for instance the table custmast.dat is imported as
custmast. It is possible to specify a c-treeACE SQL table name on the command line by using the
-n option.
Null Fields and Field Default Values Considerations
The import utility checks if a table being imported was created with NULL FIELD support (this is
true for tables created with c-treeDB APIs). If the table being imported was created with NULL
FIELD support, the import utility updates the SQL dictionaries accordingly, by setting the NULL
FIELD flag to “Y”. If a table being imported has no NULL FIELD support, the NULL FIELD flag of
the c-treeACE SQL dictionary will be set to “N” and the c-treeACE SQL dictionary default value
for that field will be set to 0 for numeric fields, or “ ” for string fields.
Default values are not available for SQL_LONGVARCHAR and SQL_LONGVARBINARY field
types and the NULL FIELD flag for those fields are always set to “Y”, even though null values are
not supported for these types of fields. A side effect would be, for example, inserting a NULL
value in a LONG VAR CHAR field and reading back an empty string when the field is retrieved from
a record. Please note that this only affects tables created without NULL FIELD support.
www.faircom.com
All Rights Reserved
33
c-treeACE SQL Utilities
ctsqlimp Import Indices with Segment on String Field Missing Last Byte
A fairly common situation C programmers may encounter is that the last byte from an index
segment is usually assumed to be ‘\0’ (nul), when in fact it is not. The index segment then does
not match the entire field (many times based on a CT_FSTRING).
There have been inquiries about importing into c-treeACE SQL indices where a segment is on a
string field, however, it is missing the last byte. While this is atypical usage, with c-tree technology
there is no actual problem in allowing these indices.
The c-treeACE SQL can map an index segment into a field even if the segment does not match
the entire field and to properly perform the segment low-level handling. No check is made on the
“nature” of the partial segment. It is up to the import utility to verify the index is proper for
c-treeACE SQL handling.
The feature itself is off by default and is activated with the SQL_OPTION PARTIAL_SEG server
configuration keyword.
Note: The only way c-treeACE SQL may be aware of an index using a partial segment is
because this index has been imported by ctsqlimp. Using an index with partial segment imported
with ctsqlimp without the SQL_OPTION PARTIAL_SEG turned on results in a
CTDBRET_NOTFIELD error.
Details
Logic was added to the ctsqlimp utility to import indices with segment on string field missing the
last byte.
Note: This feature is turned on with the -z command line switch and requires a server with
SQL_OPTION PARTIAL_SEG turned on.
Import Duplicate Filenames into c-treeACE SQL
The c-treeACE SQL import utility, ctsqlimp, has been updated to take advantage of the ability to
import multiple files with the same physical name into an SQL database. Simply use the -n
(symbolic) name option on import to uniquely identify each table in c-treeACE SQL:
>ctsqlimp ./data/A/myfile.dat -u ADMIN -a ADMIN -n myfileA
>ctsqlimp ./data/B/myfile.dat -u ADMIN -a ADMIN -n myfileB
SQL Tip
To create a consolidated view over these two files, create individual views to present the tables
as one. A "mapping" table can be created to provide table source identifying information to the
view. Consider that myfile.dat contained the fields name, id, and moddate:
CREATE TABLE map (consolidated_name CHAR(32), symbolic_name CHAR(32);
INSERT INTO map VALUES ('myfile', 'myfileA');
INSERT INTO map VALUES ('myfile', 'myfileB');
CREATE VIEW myfileA_vmap AS (
www.faircom.com
All Rights Reserved
34
c-treeACE SQL Utilities
SELECT myfileA.name, myfileA.id, myfileA.moddate, map.consolidated_name,
map.symbolic_name
FROM myfileA CROSS JOIN map
WHERE map.symbolic_name = 'myfileA'
);
CREATE VIEW myfileB_vmap AS (
SELECT myfileB.name, myfileB.id, myfileB.moddate, map.consolidated_name,
map.symbolic_name
FROM myfileB CROSS JOIN map
WHERE map.symbolic_name = 'myfileB'
);
CREATE VIEW myfile AS (
SELECT * from myfileA_vmap
UNION
SELECT * from myfileB_vmap
);
SELECT * from myfile;
6.5
ctsqlutl - c-treeACE SQL Table Maintenance Utility
The c-treeACE SQL table maintenance utility, ctsqlutl, is available as a general purpose utility to
perform maintenance on c-treeACE SQL databases. This includes renaming tables and columns.
The ctsqlutl utility syntax is as follows:
ctsqlutl [command] arg1 arg2 ... argn [options]
Valid Commands:
 -rencol: rename column: arg1= Table name arg2= Current column name arg3= New column
name
Renames a column within a specified table.
 -rentbl: rename table: arg1= Current table name arg2= New table name
Renames a table.
Valid Options:
 -o: Owner of table
 -d: Database name (default: ctreeSQL)
 -s: c-treeACE SQL Server name (default: FAIRCOMS)
 -u: UserID for logging into c-treeACE SQL
 -a: Password for authentication
 -h: Display usage help
6.6
ctsqlmdd - c-treeACE SQL Merge Database Utility
It is necessary at times to move a c-treeACE SQL database from one system to another. This can
involve path changes which need to be reflected in the session and database dictionaries. The
c-treeACE SQL Move Database Utility can be used to simplify this process. This utility allows you
www.faircom.com
All Rights Reserved
35
c-treeACE SQL Utilities
to specify target and destination c-treeACE SQL from which the database dictionary will be
moved and/or updated.
Usage
ctsqlmdd svn [-u uid] [-p upw] [-S svn] [-U uid] [-P upw] [-n sect]
Where:
 svn: source c-treeACE SQL name (may be "local" for direct access)
 -u uid: user name on source server
 -p upw: user password on source server
 -S svn: destination c-treeACE SQL Server name
 -U uid: user name on destination server
 -P upw: user password on destination
c-treeACE SQL uses the c-treeDB database API to generate and maintain the session and
database dictionaries necessary to maintain c-treeACE SQL relational databases. (The c-treeDB
functions, ctdbMergeSessionDictionary() and ctdbMergeDatabaseDictionary(), provide the
core functionality for this utility.)
The source code for this utility, ctsqlmdd.c, demonstrates a generic implementation of the
activities needed to achieve a session and/or database merge between systems. For precise
applications, or to embed these activities into an application, the user is invited to view and
inspect this source code example.
www.faircom.com
All Rights Reserved
36
c-treeACE SQL Utilities
6.7
cttrnmod - Change Transaction Mode Utility
cttrnmod allows an advanced user to change the transaction status of a c-treeACE data file and
its associated index files. The utility can also be used to display the transaction status of a c-tree
data file and its associated indices.
It is expected only advanced database administrators will run this utility.
Usage
cttrnmod (set <tranmode>|get) (-d <database>|-f <filelist>)
[-u <userid>] [-p <password>] [-s <servername>] [-n <sect>]
Where
 set <tranmode> - Set the transaction mode to one of the following:
• T - Full Transaction Control
• P - Partial Transaction Control (No Recoverability)
• N - No Transaction Control (No Recoverability)
repl=on - Enable replication (requires full transaction control).
repl=off - Disable replication.
The following extended header attributes may also be set:
• {+,-}R - {Enable,Disable} Restorable deletes
• {+,-}C - {Enable,Disable} Transaction controlled deletes
• {+,-}A - {Enable,Disable} Auto transaction switching.
 get - Display the current transaction mode.
 -d or -f - Operate on all files in the database or all listed files:
• -d <database> - Operate on all files in the c-tree database <database>.
• -f <filename> - Operate on all files listed in the file <filelist>.
 -u <userid> - Specify c-tree user ID.
 -p <password> - Specify c-tree user password.
 -s <servername> - Specify c-treeACE Server name to connect to. Default: FAIRCOMS
 -n <sect> - Specify node sector size. Default: 64 (PAGE_SIZE=8192)
The files to change are specified by either the -d <database> option or the -f <filelist> option. The
-d <database> option specifies the name of a c-tree database -- when this option is specified, the
utility operates on all files referenced in that database (excluding SQL system data and index
files). The -f <filelist> option specifies the name of a text file containing names of c-tree data files,
one per line -- when this option is specified, the utility operates on all files specified in that text
file.
Note: Indices created with ctPREIMG or ctTRNLOG are physically structured differently than
indices that do not support transactions. Thus a non-tran index cannot be converted to
transaction control, and must be rebuilt after the conversion. If an index file is created ctPREIMG
or ctTRNLOG, it can be accessed in all transaction and non-transaction access modes.
www.faircom.com
All Rights Reserved
37
c-treeACE SQL Utilities
Important Performance Considerations
When turning transaction processing off for a file, it is possible to take an even larger
performance hit under specific c-treeACE Server configurations. Be sure to remove or comment
out the line COMPATIBILITY FORCE_WRITETHRU from your c-treeACE Server configuration file
ctsrvr.cfg. While this option provides only the safest of data integrity for your non-transaction
processing controlled files, it forces an enormous performance penalty for doing so. This keyword
has historically been included by default with most c-treeACE Server installations.
Example
The following example demonstrates turning off transaction control for all c-tree data files and
their associated index files in the rdsdb database:
# cttrnmod set N -d rdsdb
Setting transaction mode to NON_TRAN for files in database rdsdb...
Tranmode
-------NON-TRAN
NON-TRAN
NON-TRAN
NON-TRAN
NON-TRAN
NON-TRAN
NON-TRAN
NON-TRAN
NON-TRAN
NON-TRAN
Filemode
-------0x0000
0x0000
0x0000
0x0000
0x0000
0x0000
0x0000
0x0000
0x0000
0x0000
Filename
-------.\rdsdb.dbs\admin_deptbl.dat
.\rdsdb.dbs\admin_deptbl.idx
.\rdsdb.dbs\admin_dept_multi_ndx.idx
.\rdsdb.dbs\admin_dept_ndx.idx
.\rdsdb.dbs\admin_emptbl.dat
.\rdsdb.dbs\admin_emptbl.idx
.\rdsdb.dbs\admin_emp_no_ndx.idx
.\rdsdb.dbs\admin_emptbl1.dat
.\rdsdb.dbs\admin_emptbl1.idx
.\rdsdb.dbs\admin_emp_no_ndx1.idx
VERIFYING No Transaction Control...
VERIFY succeeded
3 Data Files Updated
0 Errors
The following example demonstrates reading the transaction status of the data and index files in
the rdsdb database:
# cttrnmod get -d rdsdb
Reading transaction mode for files in database rdsdb...
Tranmode
-------ctTRNLOG
ctTRNLOG
ctTRNLOG
ctTRNLOG
ctTRNLOG
ctTRNLOG
ctTRNLOG
ctTRNLOG
ctTRNLOG
ctTRNLOG
Filemode
-------0x0031
0x0031
0x0031
0x0031
0x0031
0x0031
0x0031
0x0031
0x0031
0x0031
Filename
-------.\rdsdb.dbs\admin_deptbl.dat
.\rdsdb.dbs\admin_deptbl.idx
.\rdsdb.dbs\admin_dept_multi_ndx.idx
.\rdsdb.dbs\admin_dept_ndx.idx
.\rdsdb.dbs\admin_emptbl.dat
.\rdsdb.dbs\admin_emptbl.idx
.\rdsdb.dbs\admin_emp_no_ndx.idx
.\rdsdb.dbs\admin_emptbl1.dat
.\rdsdb.dbs\admin_emptbl1.idx
.\rdsdb.dbs\admin_emp_no_ndx1.idx
www.faircom.com
All Rights Reserved
38
c-treeACE SQL Utilities
ctTRANMODE Control (c-treeACE V11 and c-treeRTG V2 and later)
When using the Transaction Control utility, cttrnmod, to disable transaction support on a file with
extended file mode ctTRANMODE, the utility could report that after successfully disabling
ctTRNLOG, the file still has ctTRNLOG set. This is expected for a file with the ctTRANMODE bit
set when using a TRANPROC c-tree application.
cttrnmod has been updated to disable ctTRANMODE and ctPIMGMODE bits when it sets a file
to no-transaction support. It was also modified to support explicitly enabling or disabling one of
these bits (depending on the file mode that is in effect at the time).
Replication
New replication actions have been added to the cttrnmod utility for flexible control of replication
attributes.
 cttrnmod now displays replication state for a data file
 cttrnmod can change a file's replication state with the repl option
Note: Replication requires that the data file has a unique index and that the data and index files
are using full (ctTRNLOG) transaction control.
Examples
1. Enable full transaction logging on files:
# cttrnmod set T -f files.txt -u ADMIN -p ADMIN -s FAIRCOMS
Setting transaction mode to ctTRNLOG for files listed in file
files.txt...
Replicate
---------
Tranmode
--------
Filemode
--------
Filename
--------
NO
ctTRNLOG
ctTRNLOG
0x0032
0x0032
ctreesql.dbs\admin_t.dat
ctreesql.dbs\admin_t.idx
ctTRNLOG
0x0032
ctreesql.dbs\admin_t_ti.idx
Note the "Replicate" column for current replication state information.
2. Enable replication on files:
# cttrnmod set repl=on -f files.txt -u ADMIN -p ADMIN -s FAIRCOMS
Enabling replication for files listed in file files.txt...
Replicate
---------
Tranmode
--------
Filemode
--------
Filename
--------
YES
ctTRNLOG
ctTRNLOG
0x0032
0x8032
ctreesql.dbs\admin_t.dat
ctreesql.dbs\admin_t.idx
ctTRNLOG
0x8032
ctreesql.dbs\admin_t_ti.idx
www.faircom.com
All Rights Reserved
39
c-treeACE SQL Utilities
Note: If cttrnmod is used to disable full transaction logging for a file, it also disables replication
for that file.
6.8
fkverify
It was possible that foreign key constraints could be violated in some versions of c-treeACE
(V8.27 prior to revision 8662). A The Foreign Key Constraint Verification utility, fkverify, is
available to check all Foreign Key constraints in a database to insure that referential integrity is
maintained, and log any exceptions to a file.
This utility connects directly to c-treeACE SQL through the direct link ODBC interface thus is
cross platform, and requires no additional components.
Syntax
fkverify [-s server][-p port][-d database]-a password
Where
 -s Machine name (default: localhost)
 -p Port (default: 6597)
 -d Database (default: ctreeSQL)
 -a Admin Password
6.9
sqlverify
The sqlverify utility can be used to diagnose low lying c-treeACE SQL issues and relational
integrity. This utility connects to c-treeACE SQL databases and runs multiple tests and internal
consistency checks. If problems or unusual results are detected they are logged to verify.log. The
syntax for using this utility is as follows:
sqlverify [-s address][-p port][-d database][-n name][-f][-v] -a password
Valid Options:
 -s: Machine name(default: localhost)
 -n: Server name (default: FAIRCOMS)
 -p: SQL Port (default: 6597)
 -d: Database (default: ctreeSQL)
 -f: Fix certain problems
 -v: verbose
 -a: Admin Password
An example verify.log file might look like the following:
Info: Table admin_custmast index 6
Info: Full Key Distinct Count was 81917, now 46218
Info: Table admin_custmast index 7
Info: Full Key Distinct Count was 81917, now 48939
Error: table admin_ordritem, index 0 holds 0 keys. Expected 1(1). Rebuild
List of inconsistencies:
www.faircom.com
All Rights Reserved
40
c-treeACE SQL Utilities
table | index | field | errorcd | errormsg
1 - syscolumns | | logicalid | 4019 | Mismatch column nullflag
This example demonstrates an error as shown on line 5 of the output. In this case a rebuild of the
index is indicated. Consult with FairCom's support team should you have any questions about the
output of this utility against your database. The last section of inconsistencies should always be
reported to FairCom's support team for investigation.
www.faircom.com
All Rights Reserved
41
7.
Combining c-treeACE SQL with ISAM
This chapter details the considerations associated with accessing c-treeACE SQL created data
from a c-tree Plus ISAM application and using existing c-tree Plus ISAM created data from
c-treeACE SQL.
7.1
Accessing c-treeACE SQL Files from ISAM Applications
To highlight the factors to consider when accessing c-treeACE SQL data from ISAM applications,
consider the following example. Here we create a table using c-treeACE SQL and then examine
the c-tree file specifications. This section also discusses the reverse case: accessing a c-tree
ISAM application file from c-treeACE SQL.
Defining a Table Using c-treeACE SQL
The following c-treeACE SQL commands define a table consisting of three fields and an index
defined on one of the fields:
CREATE TABLE example (
dbl
float,
int4 INTEGER,
ch
CHAR(8));
CREATE INDEX example_chidx ON example (ch);
COMMIT WORK;
Examining Resulting File Specifications
Now that the table and index have been created, let’s look at the resulting field, table, and index
definitions.
Field Definitions
First, let’s examine the field definitions, stored as a DODA resource in the data file. The SQL
command specified three columns, but c-treeACE SQL created three additional fields for internal
use:
Field name
Offset
Type
Length
$DELFLD$ (a)
0
CT_ARRAY
4
$NULFLD$ (b)
4
CT_ARRAY
1
$ROWID$ (c)
8
CT_INT8
8
dbl
16
CT_DFLOAT
8
www.faircom.com
All Rights Reserved
42
Combining c-treeACE SQL with ISAM
Field name
Offset
Type
Length
int4
24
CT_INT4
4
ch
28
CT_FSTRING
8
(a) $DELFLD$ is a placeholder field at the beginning of the record for c-tree deleted record flag. If
the first field in a record is not a binary field or the file is VARIABLE LENGTH, $DELFLD$ is not
necessary. It can be modified, however, the first byte cannot be set to 0xFF or 0xFE for
fixed-length data files, as these are reserved values.
In V9.5, the size of $DELFLD$ changed from 4 bytes (or 5 in case of non-HUGE files) to 9 bytes.
A configuration keyword, CTSQL_OPTION OLD_DELFLD_LEN, forces the use of the old size.
(b) $NULFLD$ is a bit mask indicating which fields contain NULL values to support IFNULL
functionality. If this field is not present, then all fields of a record will always be considered NOT
NULL, and any operation to set the null flag of a particular field will be ignored. Select queries
based on NULL field expressions may not be resolved as expected.
(c) $ROWID$ is an automatic serial number to support ROWID functionality. If this field is not
present, then the SQL engine will use the record’s RECBYT. Please note that RECBYT may not
be a unique row identifier. As records are deleted and reused, the RECBYT of a deleted record
will be used for an inserted record. Select queries based on ROWID may not be resolved as
expected when the RECBYT is used.
Considerations for ISAM applications
The record starts with 16 bytes of internal field data. The fields accessible to applications via
c-treeACE SQL begin at offset 16. c-treeACE SQL automatically maintains the contents of the
internal fields using c-treeDB functions. At the ISAM level, the internal fields can be viewed and
modified. If updating records at the ISAM level, care should be taken to preserve the semantics of
these fields, as described above.
The field values in a c-treeACE SQL table are set using c-treeDB functions and can be easily
retrieved in the format of the underlying data type using c-treeDB functions. Some data types
(e.g., Date, Time, etc.) will be encoded by c-treeDB and will be difficult to interpret at the ISAM
level.
Table and Index Definitions
This section examines the table and index definitions defined using c-treeACE ISAM resources:
IFIL, IIDX, ISEG, and XCREblk.
For the sample file created using the c-treeACE SQL commands shown in this chapter, the
resulting ISAM resources are as follows:
IFIL examplefil = { // Data file definition.
".\ctreeSQL.dbs\example",
// data file name (a)
-1,
// data file number
36,
// data record length
0,
// data extension size
ctFIXED | ctTRNLOG,
// data file mode (b)
3,
// number of indices (c)
0,
// index extension size
ctFIXED | ctTRNLOG,
// index file mode (b)
exampleidx
// index pointer
};
IIDX exampleidx[] = { // Index definitions.
{ // Index #1: Internal (RECBYT) index. e
www.faircom.com
All Rights Reserved
43
Combining c-treeACE SQL with ISAM
5,
0,
1,
0,
0,
1,
&recbytseg,
"$RECBYT$",
NULL
//
//
//
//
//
//
//
//
//
key length (d)
key type
duplicate flag
null key flag
empty character
number of segments
segment pointer
r-tree symbolic index
alternate index name (a)
},
{ // Index #2: Internal (ROWID) index. e
4,
// key length
0,
// key type
0,
// duplicate flag
0,
// null key flag
0,
// empty character
1,
// number of segments
&rowidseg,
// segment pointer
"$ROWID$",
// r-tree symbolic index
NULL
// alternate index name (a)
},
{ // Index #3: User-created index on ch
12,
0,
1,
0,
0,
1,
&chidxseg,
"example_chidx",
".\ctreeSQL.dbs\example_chidx.idx"
field. f
// key length
// key type
// duplicate flag
// null key flag
// empty character
// number of segments
// segment pointer
// r-tree symbolic index
// alternate index name (a)
}
};
ISEG recbytseg =
{0, 1, RECBYT};
// One-byte record position segment.
ISEG rowidseg =
{8, 4, SRLSEG};
// Four-byte auto serial number segment.
ISEG chidxseg =
{5, 8, SCHSEG};
// User-created segment on ch field. (f)
XCREblk xcre = { // Extended creation information.
ctTRANDEP | ctRSTRDEL // x8mode (g)
};
Notes:
(a) The SQL CREATE TABLE and CREATE INDEX commands cause c-treeACE SQL to create
three files in the current database directory, which in this example is ctreeSQL.dbs. The files are:
example.dat - contains file definition resources and data records.
example.idx - contains key values for the two internal indexes.
example_chidx.idx - contains key values for the user-created index on the ch field.
If additional indexes are created, they are created as additional physical files.
(b) The files are created as transaction-processed files.
(c) Three indexes are created (two internal indexes plus the user-created index on the ch field).
(d) The first index is an internal index known as a RECBYT index used to support enhanced
space management capabilities.
www.faircom.com
All Rights Reserved
44
Combining c-treeACE SQL with ISAM
(e) The second index is an internal index known as a ROWID index used to support SQL ROWID
functionality.
(f) The third index is the user-created index on the ch field. The key is defined over the full length
of the field, uses the SCHSEG segment mode, and allows duplicates. To create an index that
does not allow duplicates use the SQL command CREATE UNIQUE INDEX.
(g) The files are created using special extended file modes. ctTRANDEP specifies a
transaction-dependent file and ctRSTRDEL specifies restorable delete capabilities. These
properties enable rollback of file create and delete operations (at both the SQL and ISAM level).
Note: c-treeACE ISAM functions can be used to create data and index files, and if the file
definitions adhere to the special properties required of c-treeACE SQL files as detailed here, the
files can be easily imported to c-treeACE SQL using the ctsqlimp utility. One reason that a
developer might choose this option is to create files with special properties (such as ctADD2END,
to create chronological files) that c-treeACE SQL currently does not provide a way to specify at
file create time.
If PRIMARY KEY is specified, c-treeACE SQL creates an additional index file with an
automatically-generated name, such as sys_001_000001078.idx, and adjusts the IFIL resource in
the data file to include an additional index definition.
The same is true if FOREIGN KEY is specified: c-treeACE SQL creates an additional index file
with an automatically-generated name and adjusts the IFIL resource in the data file to include an
additional index definition.
Note: c-treeACE ISAM has no knowledge of c-treeACE SQL referential integrity constraints. It’s
possible to violate referential integrity constraints so use caution when updating records directly
using ISAM functions.
7.2
Using Existing ISAM Data with c-treeACE SQL
In addition to creating new files under the c-treeACE SQL, it is possible to use existing c-tree Plus
files under the c-treeACE SQL.
Table Definition Requirements
 Tables must contain IFIL and DODA structures. These can be added after the fact for existing
files and are inserted automatically for files created by c-treeDB and c-treeACE SQL.
 The ISAM application must use the c-tree Plus data types (as defined in the DODA) as in the
c-tree - SQL data type mapping. For example a CT_CHAR is used in the SQL to store a
1-byte integer.
Note: There is an incompatibility between the use of CT_ARRAY in the current c-tree Plus
ODBC Driver and the use of CT_ARRAY in c-treeDB and c-c-treeACE SQL, including the
c-treeACE SQL ODBC Driver.
 The table must have either TRNLOG or PREIMG in its file mode to use the ROLLBACK WORK
and integrity constraint capabilities.
 Superfiles are not supported by c-treeACE SQL.
 To properly handle NULL, the table must contain the $NULFLD$ field, a hidden field
generated by c-treeDB at creation time. Tables created with the c-treeDB Interface (used
www.faircom.com
All Rights Reserved
45
Combining c-treeACE SQL with ISAM
under c-treeACE SQL) have a hidden field, $NULFLD$, which is used to determine if each
user-created field in the record buffer has a NULL value. c-treeACE SQL requires this
capability to implement constraints. c-treeDB and c-treeACE SQL will access tables without
the $NULFLD$ field, but the table’s fields will always return a non-NULL status.
 To properly handle JOINS referencing ROWID, the table should contain the $ROWID$ field
(a hidden field generated by the c-treeDB at creation time). c-treeDB and c-treeACE SQL
should work with tables without the $ROWID$ field, and will use the record offset as the
ROWID tuple identifier. SQL statements like “select * from table where ROWID > ‘4’” will fail
because using record offset as ROWID will give us record offsets instead of sequential
numbers.
Note: When c-tree updates a variable length record, the record offset for the record may
change if the updated record size is larger than the original record. In this particular case, the
ROWID for this ROW will not be unique, as required by the SQL standard.
Index Definition Requirements
 If an index contains a segment made by a “partial field” (i.e., does not use Schema segment
modes or the segment starting offset and the segment length are different from the field
starting offset and the field length) c-treeACE SQL cannot access this index, even though the
index is still properly updated by c-tree.
 If there is more than one logical index in one physical index file, the DROP INDEX and the
DROP TABLE commands do not work properly.
 Alter table may not work correctly if tables contain index segments that do not start at field
boundaries and/or span over several fields.
Example: If a field is deleted from the table, and this field is part of an index segment that
spans over several fields, c-treeDB may not know how to adjust the index segment length
after the field is deleted from the table. The resulting index definition may not be correct.
Tables with unusual characteristics may also not work correctly and the altered table may
inherit c-treeDB characteristics that will prevent them from working in the original application.
Adding DODAs to Existing Files
To use c-treeACE SQL with existing ISAM files that do not already have DODAs, add a DODA to
each file. This is most easily done with a developer-created utility that opens each file and calls
PutDODA() to insert the required resource into that file. The utility should:
1. Include a data object definition array (DODA), simply an array of DATOBJ structures, defined
below.
2. Open each data file in ctEXCLUSIVE mode.
3. Call PutDODA() for each file to insert the DODA resource.
4. Close the files.
A DODA is a data object definition array. Each element of the array is comprised of a structure of
type DATOBJ. Only three of the first four fields of the DATOBJ are required for c-tree Plus.
DATOBJ is defined as follows:
typedef struct {
pTEXT
fsymb;
pTEXT
fadr;
UCOUNT
ftype;
/* ptr to symbol name
*/
/* adr of field in record buffer */
/* type indicator
*/
www.faircom.com
All Rights Reserved
46
Combining c-treeACE SQL with ISAM
UCOUNT
...
} DATOBJ;
flen;
/* field length
*/
 fsymb points to a unique symbolic name for the field and should not be NULL.
 fadr is not used by c-tree Plus (its value is ignored).
 ftype is one of the field types specified in the “Field Types” table.
 flen is set to the field’s length for fixed length fields, or the known maximum for varying length
fields with a known maximum length, or zero for varying length fields without a known
maximum length. If the field type has an intrinsic length, which is true for types CT_CHAR
through CT_DFLOAT, a zero length is automatically replaced by the intrinsic length.
Given a data record with the structure:
struct {
TEXT
zipcode[10]; /* Zip code
LONG
ssn;
/* social security #
TEXT
name[50];
/* name
} DATA_FORMAT;
*/
*/
*/
The corresponding DODA would be defined as:
DATOBJ doda[] = {
{"ZipCode",NULL,CT_FSTRING,10},
{"SocialSecurity",NULL,CT_INT4},
{"Name",NULL,CT_STRING,50}
};
Note: The two string fields show the difference between fixed-length and variable-length strings.
zipcode, CT_FSTRING, takes up a fixed space in the record (10 bytes) and does not require a
NULL to terminate the string. name, CT_STRING, takes up a variable amount of space up to a
maximum of 50 bytes and is NULL terminated.
Available field types are described in “Record Schema - Field Types” in the c-tree Plus
Programmer’s Reference Guide.
PutDODA() assigns the contents of a data object definition array (DODA) to data file datno, which
must be opened in ctEXCLUSIVE mode. DODA points to the beginning of the DODA as
described above. The numfld parameter indicates how many data fields are in the DODA, three in
the example above. PutDoda() has the following syntax:
COUNT PUTDODA(COUNT datno,pDATOBJ doda,UCOUNT numfld)
See the PutDODA() function description in the c-tree Plus Function Reference Guide and
“Record Schemas” in the c-tree Plus Programmer’s Reference Guide for additional details.
Contact your nearest FairCom office for assistance if needed.
7.3
Mapping of c-tree to c-treeACE SQL Types
c-tree DODA Type
Default SQL Type Mapping
CT_BOOL
BIT
CT_CHAR
CT_CHARU
TINYINT
CT_INT2
CT_INT2U
SMALLINT
www.faircom.com
All Rights Reserved
47
Combining c-treeACE SQL with ISAM
CT_INT4
CT_INT4U
INTEGER
CT_MONEY
CT_CURRENCY
MONEY
CT_DATE
DATE
CT_TIME
TIME
TIMES
TIMESTAMP
CT_SFLOAT
REAL
CT_DFLOAT
CT_EFLOAT
DOUBLE
CT_SQLBCD
NUMERIC
CT_FSTRING
CT_FPSTRING
CT_F4STRING
if ( length <= 8192 && length != 0 )
CHAR
else
LVARCHAR
CT_STRING
CT_PSTRING
if ( length <= maxlen && length != 0 )
if ( isvlen )
VARCHAR
else
CHAR
else
LVARCHAR
CT_F2STRING
CT_ARRAY
if ( length <= 8192 )
BINARY
else
LVARBINARY
CT_2STRING
if (length <= maxlen && length != 0 )
(binflag == CTDB_BINARY_VARCHAR) ? VARCHAR : VARBINARY
else
LVARBINARY
CT_4STRING
switch( binflag )
case CTDB_BINARY_VARCHAR
LVARCHAR
case CTDB_BINARY_CLOB
CLOB
case CTDB_BINARY_BLOB
BLOB
default:
LVARBINARY
CT_INT8
CT_INT8U
BIGINT
CT_FUNICODE
CT_F2UNICODE
NCHAR
www.faircom.com
All Rights Reserved
48
Combining c-treeACE SQL with ISAM
CT_UNICODE
CT_2UNICODE
NVARCHAR
www.faircom.com
All Rights Reserved
49
8.
c-treeACE SQL Types SDK
8.1
Overview of the c-treeACE SQL Types SDK
c-treeDB is a high-level, easy to use API in addition to the traditional c-tree APIs: ISAM and
low-level. c-treeDB is intended as the standard for c-treeACE programming. When compared to
ISAM and low-level APIs, c-treeDB introduced a formal definition on the structure of data and
index files, introduced concepts such as ROWID and NULL field support, and more specifically, a
formal definition for each field type supported.
Existing application data and index files, i.e. data created prior to the publication of the c-treeDB
API, may have implemented certain field types in a way that may be incompatible with c-treeDB.
Hence, they will be incompatible with c-treeACE SQL as c-treeACE SQL relies upon c-treeDB
functionality. Field types such as CT_DATE, CT_TIME and CT_TIMES are probably the most
common examples of existing data that may be incompatible with c-treeDB.
The c-treeDB Callback feature was implemented to provide our customers a means to intercept
certain c-treeDB operations and add custom code to manipulate record buffer layouts or change
field data on the fly and make the record and field data compatible with c-treeDB. Please refer to
the “c-treeDB Callback” document for detailed information concerning this new feature.
The c-treeDB Callback feature was introduced into c-treeACE SQL to allow for easy and
transparent translation of customers’ existing ISAM or low-level native data to a data format that
is compatible with c-treeACE SQL requirements. This new feature is called c-treeACE SQL
Callbacks.
This section describes the utilization of the c-treeACE SQL Callback feature to introduce code to
allow existing ISAM data to be used transparently with c-treeACE SQL. When c-treeACE SQL
reads data from native ISAM tables, the callback code translates the data record to make every
data field compatible with SQL. When c-treeACE SQL writes new data, or updates existing data,
the callback code will translate the data in SQL format to comply with the native format used by
the ISAM application. The ISAM table will be available for use with c-treeACE SQL, yet remains
compatible with existing ISAM applications.
An example field conversion
Consider a field called “MYTIME”. It is declared in the DODA as a CT_INT4 field. Just by
inspecting the table definition data, there is not enough information to decide if a CT_INT4 field is
in fact an integer field or a MYTIME field.
The MYTIME information stored in a CT_INT4 field is based on the C Runtime Library time (RTL)
routines. The C RTL time value is a number that represent the number of seconds since a given
date in the past. The value implementation is system dependent and the C RTL time handling
functions should be used to guarantee portability.
www.faircom.com
All Rights Reserved
50
c-treeACE SQL Types SDK
The MYTIME’s CT_INT4 fields are transparently converted to CT_TIMESTAMP fields by the
callback code. This transparent conversion allows c-treeACE SQL to properly display the time
stamp data and the c-treeACE SQL parser will allow the use of SQL date, time and time stamp
functions to be applied to the field data. Without the transparent conversion performed by the
callback code, the MYTIME fields would be handled by c-treeACE SQL as integer fields.
The MYTIME data is converted to CT_TIMESTAMP format using the following pseudo code.
Example Conversion
time_t tmpval;
struct tm* ptr;
/* copy the MYTIME value to a temporary variable */
memcpy(&tmpval, &src_recbuf[srcofs], srclen);
/* adjust local timezone to UTC timezone */
tmpval -= 21600;
/* convert a time_t value into a broken-down time, expressed in UTC */
if ((ptr = gmtime(&tmpval)) != NULL)
{
CTDATETIME stamp;
/* convert the broken-down time_t values to c-treeDB time stamp */
if ((Retval = ctdbDateTimePack(&stamp, (ptr->tm_year + 1900), (ptr->tm_mon + 1), ptr->tm_mday,
ptr->tm_hour, ptr->tm_min, ptr->tm_sec)) != CTDBRET_OK)
goto Exit;
/* write the converted time stamp data to the destination record */
os_memcpy(&dst_recbuf[dstofs], &stamp, sizeof(stamp));
}
else
{
Retval = CTDBRET_INVDATETIME;
goto Exit;
}
In the example above, the src_recbuf is a source record buffer read from an ISAM data file with a
MYTIME field. srcofs is the offset in the record buffer of the MYTIME field. dst_recbuf is a
translated record buffer that will be presented to c-treeACE SQL with the MYTIME’s CT_INT4
fields translated to CT_TIMESTAMP field type.
The CT_TIMESTAMP data is converted back to MYTIME format using the following pseudo code.
Example Reverse Conversion
CTDATETIME stamp;
NINT year, month, day, hour, min, sec;
time_t tmpval = 0;
struct tm ptr;
/* copy the time stamp field to temporary variable */
os_memcpy(&stamp, &src_recbuf[srcofs], sizeof(stamp));
/* clear the C RTL time structure */
os_memset(&ptr, 0, sizeof(ptr));
www.faircom.com
All Rights Reserved
51
c-treeACE SQL Types SDK
if (stamp != 0.0)
{
/* break down c-treeDB time stamp data */
if ((Retval = ctdbDateTimeUnpack(stamp, &year, &month, &day, &hour, &min, &sec)) != CTDBRET_OK)
goto Exit;
/* set the C RTL time struct */
ptr.tm_year = year - 1900;
ptr.tm_mon = month - 1;
ptr.tm_mday = day;
ptr.tm_hour = hour;
ptr.tm_min = min;
ptr.tm_sec = sec;
/* build a new time_t value */
tmpval = mktime(&ptr);
/* convert from UTC time to local timezone */
#ifdef ctPortWIN32
tmpval = tmpval - _timezone + 21600;
#else
tmpval = tmpval - timezone + 21600;
#endif
}
/* copy XTIME data to record buffer */
os_memcpy(&dst_recbuf[dstofs], &tmpval, sizeof(tmpval));
In the example above, the src_recbuf is a source record buffer passed by c-treeACE SQL with
CT_TIMESTAMP fields. srcofs is the offset in the source record buffer of the CT_TIMESTAMP
field. dst_recbuf is a translated record buffer that will be written to an ISAM table with the
appropriate CT_TIMESTAMP fields translated to CT_INT4 fields. dstofs is the offset into the
destination record buffer of the MYTIME field.
8.2
c-treeACE SQL with Callbacks
The introduction of the c-treeDB Callback feature into c-treeACE SQL makes possible an easy
and transparent translation of customers’ existing ISAM or low-level native data to a data format
that is compatible with c-treeACE SQL requirements.
The key advantage of this implementation is the callback feature can be used with standard
production c-treeACE SQL. If the callback dynamic library is not present, c-treeACE SQL
performs normally as before. When the callback dynamic library is present c-treeACE SQL will
automatically load the dynamic callback library every time a new c-treeACE SQL user logon is
performed.
The current implementation of the c-treeACE SQL Callback library makes use of a configuration
file as there is no practical way to detect which CT_INT4 fields are actually a MYTIME field or a
CT_INT4 field. The configuration file is loaded automatically by the dynamic library.
www.faircom.com
All Rights Reserved
52
c-treeACE SQL Types SDK
The Server Architecture
On startup, c-treeACE SQL will attempt to load the c-treeACE SQL dynamic callback library when
the SQL_OPTION LOAD_CALLBACK_LIB configuration option is specified in the server
configuration file, ctsrvr.cfg.
Note: For Windows systems, the dynamic callback library is named ctsqlcbk.dll. For Unix-based
systems, the dynamic callback library is named libctsqlcbk with a filename extention appropriate
to that operating system's default shared library conventions (.so, .sl., .dynlib, etc.).
The diagram below depicts the relationship of c-treeACE SQL with the callback library and its
configuration file:
Figure 1: Import Utility with Callback Library and Configuration File
If the callback library is not found, no messages are reported because the dynamic library is not
required for normal c-treeACE SQL operation, however, types conversion will not take place.
If the callback library is located and loaded, the following steps are taken:
 The ctsqlcbk.ini configuration file is loaded and parsed;
 The appropriate c-treeDB callbacks are established;
Windows and Unix-based systems use different methods for locating dynamic libraries. In
Windows systems dynamic libraries are called DLLs - Dynamic Link Libraries (.dll), while
Unix-based systems use the term Shared Libraries (.so, .sl). Please refer to the c-treeACE SQL
Callback Dynamic Library (page 53) section below for detailed information on the use of the
libraries on Windows and Unix based systems.
The configuration file is described in detail in the section.
c-treeACE SQL Callback Dynamic Library
A shared library provides a mechanism that allows a single copy of code to be shared by several
instances of programs in a system. Programs can be written to load dynamic libraries without any
prior arrangement at link time. Shared libraries are loaded dynamically while the program is
running.
One of the major advantages of using dynamic libraries is the possibility to provide new,
specialized, or enhanced functionality by developing components that can be loaded at runtime,
under program control.
Note: To instruct the server to load the callback library, the SQL_OPTION LOAD_CALLBACK_LIB
c-treeACE Server configuration keyword must be specified.
www.faircom.com
All Rights Reserved
53
c-treeACE SQL Types SDK
Windows environment
Under Windows, the c-treeACE SQL callback dynamic library is called ctsqlcbk.dll, and is created
as a Windows DLL.
When loading a DLL under Windows, the system looks through a series of directories, as follows:
 The directory from which the application loaded
 The current directory
 The Windows System32 directory
 The Windows System directory
 The Windows directory
 Directories listed in the PATH variable
We recommend the c-treeACE SQL callback DLL be located in the c-treeACE SQL operating
directory.
Unix environment
Under Unix based systems, the c-treeACE SQL callback dynamic library is called libctsqlcbk, with
a file extension appropriate for that operating system's shared library conventions (.so, .sl, .dynlib,
etc.) and it is created as a Unix shared library.
Unix shared libraries must be located and loaded by the system on demand. In order for shared
libraries to be loaded at runtime, the Unix dynamic loader must know where to locate it at run
time.
Unix systems use environment variables to select custom library directories. Among the different
Unix platforms, there are three search path variables in use.
The table below lists these variables and the platforms that use them.
Environment Variable
Unix Platforms
LD_LIBRARY_PATH
Solaris, UnixWare, Linux
LIBPATH
AIX
SHLIB_PATH
HP-UX
We recommend that the c-treeACE SQL callback shared library be located in the c-treeACE SQL
operating directory. For example, if the c-treeACE SQL directory is /home/ctreeSQL, the
LD_LIBRARY_PATH environment variable could be:
$ LD_LIBRARY_PATH = /home/ctreeSQL
$ export LD_LIBRARY_PATH
If the LD_LIBRARY_PATH environment variable is already set, it may be necessary to append
the c-treeACE SQL operating directory at the end of the path as shown here:
$ LD_LIBRARY_PATH = $LD_LIBRARY_PATH:/home/ctreeSQL
$ export LD_LIBRARY_PATH
www.faircom.com
All Rights Reserved
54
c-treeACE SQL Types SDK
c-treeACE SQL Callback Configuration File
Since there is no practical way to inspect a table and detect which CT_INT4 fields are actually
MYTIME fields, a configuration is necessary for describing every table that has at least one
MYTIME field.
By default, the c-treeACE SQL callback configuration file is called ctsqlcbk.ini. Both Windows and
Unix based systems use the same configuration syntax and file name convention.
The syntax of the configuration file is similar to Windows .INI files. Comments are started with a
semicolon character. Every character after a semicolon is treated as comments and will be
ignored, as shown here.
Configuration .ini
; this is a table declaration
[nmalert]
field = number, CT_FSTRING, 10 ; first field
Each table is described in the configuration file with the table name inside square brackets. Each
table represents a section entry, followed by the table’s field, index and index segment definitions
as shown above:
[nmalert]
The fields are defined using the following syntax:
field = field-name, field-type, field-length
field-name is a string containing the field name. The field name should not be placed inside single
or double quotes, and a comma must not be part of the field name.
field-type is one of the following:
Available Field Types
CT_BOOL
CT_MONEY
CT_FSTRIN
G
CT_CHAR
CT_CURRENCY
CT_FPSTRIN
G
CT_CHAR
U
CT_NUMBER
CT_F2STRIN
G
CT_INT2
CT_DATE
CT_F4STRIN
G
CT_INT2U
CT_TIME
CT_STRING
CT_INT4
CT_TIMES
CT_PSTRIN
G
CT_INT4U
CT_SFLOAT
CT_2STRIN
G
CT_INT8
CT_DFLOAT
CT_4STRIN
G
CT_INT8U
CT_ARRAY
field-length is an integer value representing the field length.
www.faircom.com
All Rights Reserved
55
c-treeACE SQL Types SDK
Conversion Example
[nmalert]
field = number, CT_FSTRING, 10
field = seq, CT_INT2, 2
field = modwhen, CT_TIMES, 8
field = modby, CT_INT2, 2
field = code, CT_FSTRING, 5
After the field definitions, each index, with its segments, must be declared. The syntax for an
index definition is:
index = keylen, nsegs
Conversion Example
[nmalert]
field = number, CT_FSTRING, 10
field = seq, CT_INT2, 2
field = modwhen, CT_TIMES, 8
field = modby, CT_INT2, 2
field = code, CT_FSTRING, 5
index = 12, 2
segment = number, 2
segment = seq, 8
index = 13, 2
segment = code, 2
The index segment must follow the index declaration. Each index segment must be declared
using the following syntax:
1. If an index segment consists of a whole field:
segment = field-name, segmode
field-name is a string containing the field name. The field name should not be placed inside
single or double quotes, and a comma must be part of the field name.
segmode is an integer value representing an index segment mode.
2. If an index segment consists of an arbitrary offset in the record buffer that cannot be mapped
back to the offset of a field in the DODA, or an index segment length does not match a field
length, the index segment syntax is:
seg = segoffset, seglength, segmode
segoffset is an integer value indicating the offset of the segment in the record buffer.
seglength is an integer value indicating the segment length in bytes.
segmode is an integer value representing an index segment mode.
Conversion Example
[nmalert]
field = number, CT_FSTRING, 10
field = seq, CT_INT2, 2
field = modwhen, CT_TIMES, 8
field = modby, CT_INT2, 2
field = code, CT_FSTRING, 5
index = 12, 2
segment = number, 2
segment = seq, 8
index = 13, 2
segment = code, 2
www.faircom.com
All Rights Reserved
56
c-treeACE SQL Types SDK
Every table that has one or more MYTIME fields must be added to the configuration file. There is
no special ordering of the tables. Below is an example of a configuration file with two tables:
nmalert and nmmdesc.
Conversion Example
[nmalert]
field = number, CT_FSTRING, 10
field = seq, CT_INT2, 2
field = modwhen, CT_TIMES, 8
field = modby, CT_INT2, 2
field = code, CT_FSTRING, 5
index = 12, 2
segment = number, 2
segment = seq, 8
index = 13, 2
segment = code, 2
[nmmdesc]
field = number, CT_FSTRING, 10
field = modby, CT_INT2, 2
field = modwhen, CT_TIMES, 8
field = text, CT_STRING, 0
index = 10, 1
segment = number, 2
How to specify MYTIME field translation
A MYTIME field, i.e. a CT_INT4 field used to store the MYTIME data, should be declared in the
configuration file as a CT_TIMES field type.
For example in the nmalert table the modwhen field is an MYTIME field type. The definition of the
modwhen field in the configuration file should have a field type of CT_TIMES.
Conversion Example
[nmalert]
field = number, CT_FSTRING, 10
field = seq, CT_INT2, 2
field = modwhen, CT_TIMES, 8
field = modby, CT_INT2, 2
field = code, CT_FSTRING, 5
index = 12, 2
segment = number, 2
segment = seq, 8
index = 13, 2
segment = code, 2
When the callback sees a table declared in the configuration file with a DODA field of type
CT_INT4 and a field definition of CT_TIMES in the configuration file, it automatically performs the
data translation between the C RTL time functions and the c-treeACE SQL time stamp data type.
www.faircom.com
All Rights Reserved
57
c-treeACE SQL Types SDK
Specifying the configuration file location
We recommend that the c-treeACE SQL callback configuration file be located in the operating
directory. By default the c-treeACE SQL callback dynamic library will try to locate the
configuration file in the current directory.
There are certain circumstances that can cause the current directory to change, or to be
undefined, after the server begins execution. If the server is started as a service under Windows,
the current directory may be undefined, or if the server is started as a daemon under Unix
systems, the current directory may change.
For these circumstances, the location of the configuration file may be specified using the
c-treeACE SQL configuration file. The following entry can be added to the server’s configuration
file to specify the location of the c-treeACE SQL callback configuration file:
APP_NAME_LIST full-path-of-configuration-file
Example
SERVER_NAME FAIRCOMS
SQL_DATABASE ctreeSQL
COMPATIBILITY LOG_WRITETHRU
CONSOLE NO_SHUTDOWN_PROMPT
DAT_MEMORY 5000000
IDX_MEMORY 9000000
APP_NAME_LIST C:\FairCom\V8.27\ctreeServers\ctreeSQLServer\ctsqlcbk.ini
When using the APP_NAME_LIST server configuration keyword to specify the location of the
configuration file, make sure the APP_NAME_LIST is the first one in the configuration file, that is,
no other APP_NAME_LIST entries may appear before the entry that specify the location of the
configuration.
The File Definition Generating Utility
A utility has been created to aid in the process of creating a configuration file with table, field and
index definitions. The utility is called the File Definition Generating Utility, ctgendef, and its
syntax is as follows:
$ ctgendef table-name -u username -p password -s servername
Where:
table-name -- file name with or without a .dat extension.
 username -- username username
 password -- password of user
 servername -- server where the file resides
The output of the ctgendef utility is sent to the console. It may be captured to a file using default
shell arguments. For example:
$ ctgendef table-name -u username -p password -s servername > ctsqlcbk.ini
If multiple tables are to be added to the configuration file, the following commands may be used:
$ ctgendef table1 -u username -p password -s servername > ctsqlcbk.ini
$ ctgendef table2 -u username -p password -s servername >> ctsqlcbk.ini
$ ctgendef table3 -u username -p password -s servername >> ctsqlcbk.ini
www.faircom.com
All Rights Reserved
58
c-treeACE SQL Types SDK
$ ctgendef table4 -u username -p password -s servername >> ctsqlcbk.ini
Example
$ ctgendef nmalert
[nmalert]
field = number, CT_FSTRING, 10
field = seq, CT_INT2, 2
field = modwhen, CT_INT4, 4
field = modby, CT_INT2, 2
field = code, CT_FSTRING, 5
index = 12, 2
segment = number, 2
segment = seq, 8
index = 13, 2
segment = code, 2
Notice that the ctgendef utility outputs the definition of the modwhen field as CT_INT4 as
declared in the nmalert’s DODA. You need to edit the configuration file and, in the particular case
of the nmalert table, change the definition of the modwhen field to CT_TIMES. After this
modification, the configuration looks as the following, noting the change to the field=modwhen
entry.
Example
[nmalert]
field = number, CT_FSTRING, 10
field = seq, CT_INT2, 2
field = modwhen, CT_TIMES, 8
field = modby, CT_INT2, 2
field = code, CT_FSTRING, 5
index = 12, 2
segment = number, 2
segment = seq, 8
index = 13, 2
segment = code, 2
8.3
Importing Tables Into c-treeACE SQL
Before you can access data and index files created by an ISAM application with c-treeACE SQL,
you need to import the data into c-treeACE SQL. For this purpose, FairCom has created the
c-treeACE SQL Import Utility, ctsqlimp.
ctsqlimp - c-treeACE SQL Import Utility
The c-treeACE SQL import utility, ctsqlimp, utility “registers” or links existing c-tree Plus files with
a c-treeACE SQL database without modifying the table structure such that the files remain
accessible from the original application and also accessible from c-treeACE SQL.
Details
As we import a table into c-treeACE SQL, the utility reads the field definitions from the table’s
DODA and populates c-treeACE SQL system catalog tables. We cannot allow the import utility to
import the MYTIME fields as CT_INT4 field types. We have to make sure the import utility will
import the MYTIME fields as CT_TIMES fields (equivalent to c-treeACE SQL TIMESTAMP field
type).
www.faircom.com
All Rights Reserved
59
c-treeACE SQL Types SDK
Import Utility Callback Architecture
Each time a table is imported into c-treeACE SQL, the import utility will try to load an import utility
dynamic callback library.
Note: For Windows systems, the dynamic callback library is called ctsqlimp.dll. For Unix based
systems, the dynamic callback library is named libctsqlimp with a filename extention appropriate
to that operating system's default shared library conventions (.so, .sl., .dynlib, etc.).
The diagram below depicts the relationship of the import utility with the callback library and its
configuration file:
Figure 2: c-treeSQL Server with Callback Library and Configuration File
If the callback library is not located, the import utility proceeds normally with the table import
process. No errors are reported since the presence of the dynamic library is not required for
normal import utility operations.
If the callback library is located and loaded, the following steps are taken:
1.
2.
3.
4.
The ctsqlcbk.ini configuration file is loaded and parsed.
The appropriate c-treeDB callbacks are established.
The import utility continues if no errors are reported.
The configuration file is the same used by c-treeACE SQL and it is described in detail in the
c-treeACE SQL callback configuration file (page 55) section.
Import Utility Callback Configuration File
The configuration file used by the import utility dynamic library is the same configuration file used
by c-treeACE SQL.
The import utility expects the configuration file to be located in the same directory as the import
utility executable file, and that the current directory is set to the directory where the import utility
executable file is located.
Building the callback libraries
The only source modules used to build the callback libraries are ctsqlcbk.c and ctcbklib.c. Under
Windows systems we also need ctsqlcbk.def to build the c-treeACE SQL callback library, and
ctsqlimp.def to build the import utility callback library.
The callback libraries have no dependencies on c-treeACE or c-treeDB libraries. Only the header
files are referenced.
www.faircom.com
All Rights Reserved
60
c-treeACE SQL Types SDK
Below are example make files you could use to build the ctsqlcbk.dll for Windows. Unix shared
library files are quite similar, and you should consult your local compiler documentation for
details.
Note: The compiler and c-treeACE paths will need to be adjusted for your particular development
environment. You may wish to investigate your own compiler options and flags based upon your
unique needs.
Example Server Callback Makefile
#############################################################
# Your c-treeSQL callback dll makefile
#
# Operating Sys: MS-Windows NT/XP (Intel)
# Compiler:
Visual C/C++ (v6.x , v12.xx.xxxx) -VC98:
32bit
# Memory Model: Flat Memory Model
# Protocol:
TCP/IP Sockets
#############################################################
# PATH Definition Section
mtBAS =mtmake
coBAS =C:\PROGRA~1\MICROS~3\VC98
coBIN =C:\PROGRA~1\MICROS~3\VC98\bin
coBINB=C:\PROGRA~1\MICROS~3\Common\msdev98\bin
coLIB =C:\PROGRA~1\MICROS~3\VC98\lib
coINC =C:\PROGRA~1\MICROS~3\VC98\include
fcBAS =D:\fc8\ctreeSDK\ctreeAPI
fcSRC =D:\fc8\ctreeSDK\ctreeAPI\ctree\source
fcINC =D:\fc8\ctreeSDK\ctreeAPI\ctree\include
fcTOM =D:\fc8\ctreeSDK\ctreeAPI\custom.sql
#
#
#
#
#
#
#
#
#
#
m-tree's Base
Compiler's Base
Compiler's BIN
Compiler's BINB
Compiler's LIB
Compiler's INCLUDE
FairCom Base
FairCom Source
FairCom Include
Custom client Settings
# Compiler/Linker Macro Definition Section
# Object File Switch
CCOF =/Fo
.SUFFIXES:
.SUFFIXES: .c .obj
CP = copy
CPP= $(coBIN)\cl
CC = $(coBIN)\cl
LIBRARIAN = $(coBIN)\lib
RC = $(coBINB)\rc
IMPLIB = $(coBIN)\implib
LINKPP = $(coBIN)\link -subsystem:windows
-debug:full -debugtype:cv -pdb:none
LINK = $(coBIN)\link -subsystem:windows
-debug:full -debugtype:cv -pdb:none
LINK3 = $(coBIN)\link -subsystem:console
-debug:full -debugtype:cv -pdb:none
CFLAGS = -c -DWIN32 -D_X86_=1 -GX $(fcDDD) -Zi -Od
CFLAG2 = -c -DWIN32 -D_X86_=1 -GX $(fcDDD) -Zi -Od
CFLAG3 = -c -DWIN32 -D_X86_=1 -GX $(fcDDD) -Zi -Od
# Make the following components
ALL :: ctsqlcbk.dll
ctsqlcbk.dll: ctsqlcbk.obj ctcbklib.obj
$(LINK) /DLL /MACHINE:IX86 /DEF:ctsqlcbk.def /OUT:ctsqlcbk.dll ctsqlcbk.obj ctcbklib.obj
ctsqlcbk.obj: ctsqlcbk.c
$(CC) -I$(fcINC) -I$(fcSRC) -I$(fcTOM) $(CFLAG2) ctsqlcbk.c
www.faircom.com
All Rights Reserved
61
c-treeACE SQL Types SDK
ctcbklib.obj: ctcbklib.c
$(CC) -I$(fcINC) -I$(fcSRC) -I$(fcTOM) $(CFLAG2) ctcbklib.c
Example Import Utility Callback Makefile
#############################################################
# import utility callback dll
#
# Operating Sys: MS-Windows NT (Intel)
# Compiler:
Visual C/C++ (v6.x , v12.xx.xxxx) -VC98:
32bit
# Memory Model: Flat Memory Model
# Protocol:
TCP/IP Sockets
#############################################################
# PATH Definition Section
mtBAS =mtmake
coBAS =C:\PROGRA~1\MICROS~3\VC98
coBIN =C:\PROGRA~1\MICROS~3\VC98\bin
coBINB=C:\PROGRA~1\MICROS~3\Common\msdev98\bin
coLIB =C:\PROGRA~1\MICROS~3\VC98\lib
coINC =C:\PROGRA~1\MICROS~3\VC98\include
fcBAS =D:\fc8\ctreeSDK\ctreeAPI
fcSRC =D:\fc8\ctreeSDK\ctreeAPI\ctree\source
fcINC =D:\fc8\ctreeSDK\ctreeAPI\ctree\include
fcTOM =D:\fc8\ctreeSDK\ctreeAPI\custom.cli
#
#
#
#
#
#
#
#
#
#
m-tree's Base
Compiler's Base
Compiler's BIN
Compiler's BINB
Compiler's LIB
Compiler's INCLUDE
FairCom Base
FairCom Source
FairCom Include
Custom client Settings
# Compiler/Linker Macro Definition Section
# Object File Switch
CCOF =/Fo
.SUFFIXES:
.SUFFIXES: .c .obj
CP = copy
CPP= $(coBIN)\cl
CC = $(coBIN)\cl
LIBRARIAN = $(coBIN)\lib
RC = $(coBINB)\rc
IMPLIB = $(coBIN)\implib
LINKPP = $(coBIN)\link -subsystem:windows
-debug:full -debugtype:cv -pdb:none
LINK = $(coBIN)\link -subsystem:windows
-debug:full -debugtype:cv -pdb:none
LINK3 = $(coBIN)\link -subsystem:console
-debug:full -debugtype:cv -pdb:none
CFLAGS = -c -DWIN32 -D_X86_=1 -GX $(fcDDD) -Zi -Od
CFLAG2 = -c -DWIN32 -D_X86_=1 -GX $(fcDDD) -Zi -Od
CFLAG3 = -c -DWIN32 -D_X86_=1 -GX $(fcDDD) -Zi -Od
# Make the following components
ALL :: ctsqlimp.dll
ctsqlimp.dll: ctsqlcbk.obj ctcbklib.obj
$(LINK) /DLL /MACHINE:IX86 /DEF:ctsqlimp.def /OUT:ctsqlimp.dll ctsqlcbk.obj ctcbklib.obj
ctsqlcbk.obj: ctsqlcbk.c
$(CC) -I$(fcINC) -I$(fcSRC) -I$(fcTOM) $(CFLAG2) ctsqlcbk.c
ctcbklib.obj: ctcbklib.c
$(CC) -I$(fcINC) -I$(fcSRC) -I$(fcTOM) $(CFLAG2) ctcbklib.c
www.faircom.com
All Rights Reserved
62
c-treeACE SQL Types SDK
8.4
Which c-treeACE and c-treeDB Functions are Safe?
When implementing a callback function, avoid calls to c-treeACE functions or to c-treeDB
functions that in turn make calls to other c-treeACE functions, as these calls may interfere with
any current internal states maintained by c-tree or by c-treeDB.
There are some c-treeDB functions that are safe to be called from inside callback functions since
they do not make c-treeACE calls and do not affect the internal state maintained by c-treeDB.
The following c-treeDB functions are safe to be called from inside callback functions:
ctdbSetCallback
ctdbGetCallback
ctdbClearCallback
ctdbClearAllCallback
ctdbGetHandleType
ctdbSetLocalTag
ctdbGetLocalTag
ctdbGetRebuildProgr
ess
ctdbDateCheck
ctdbDatePack
ctdbDateUnpack
ctdbDateToString
ctdbStringToDate
ctdbGetDay
ctdbGetMonth
ctdbGetYear
ctdbIsLeapYear
ctdbDayOfWeek
ctdbGetDefDateType
ctdbSetDefDateType
ctdbCurrentDate
ctdbTimeCheck
ctdbTimePack
ctdbTimeUnpack
ctdbTimeToString
ctdbStringToTime
ctdbGetHour
ctdbGetMinute
ctdbGetSecond
ctdbGetDefTimeType
ctdbSetDefTimeType
ctdbCurrentTime
ctdbDateTimePack
ctdbDateTimeSetDate
ctdbDateTimeSetTime
ctdbDateTimeUnpack
ctdbDateTimeGetDate
ctdbDateTimeGetTim
e
ctdbMoneyToLong
ctdbLongToMoney
ctdbMoneyToFloat
ctdbFloatToMoney
ctdbMoneyToString
ctdbStringToMoney
ctdbMoneyAdd
ctdbMoneySub
ctdbMoneyMul
ctdbMoneyDiv
ctdbMoneyCmp
ctdbMoneyAbs
ctdbBlobAlloc
ctdbBlobFree
ctdbBlobGetData
ctdbBlobGetSize
ctdbBlobSet
ctdbBlobCmp
ctdbBlobClear
ctdbBigIntToLong
ctdbLongToBigInt
ctdbBigIntToFloat
ctdbFloatToBigInt
ctdbBigIntToString
ctdbStringToBigInt
ctdbMoneyToCurrenc
y
ctdbCurrencyToMone
y
ctdbCurrencyToLong
ctdbLongToCurrency
ctdbCurrencyToBigIn
ctdbStringToDateTim
e
ctdbCurrentDateTime
ctdbCurrencyToStrin
g
ctdbStringToCurrenc
y
ctdbCurrencyAdd
ctdbCurrencySub
ctdbCurrencyMul
ctdbCurrencyDiv
ctdbCurrencyCmp
ctdbCurrencyAbs
ctdbCurrencyRound
ctdbMoneyToNumber
ctdbNumberToMoney
ctdbNumberToLong
ctdbLongToNumber
ctdbNumberToBigInt
ctdbBigIntToNumber
ctdbNumberToCurren
cy
ctdbCurrencyToNum
ber
ctdbNumberToFloat
ctdbFloatToNumber
ctdbNumberToString
ctdbStringToNumber
ctdbNumberAdd
ctdbNumberSub
ctdbNumberMul
ctdbNumberDiv
ctdbNumberZero
ctdbIsNumberZero
ctdbNumberCmp
ctdbNumberAbs
www.faircom.com
All Rights Reserved
63
c-treeACE SQL Types SDK
ctdbDateTimeToStrin
g
t
ctdbBigIntToCurrenc
y
ctdbCurrencyToFloat
ctdbFloatToCurrency
ctdbNumberNegate
ctdbNumberCopy
ctdbNumberRound
ctdbNumberGetDeci
mal
www.faircom.com
All Rights Reserved
64
9.
Migrating to c-treeACE SQL
9.1
Migration from c-tree ODBC to c-treeACE SQL ODBC
With more and more traditional c-tree users leveraging the power of c-treeACE SQL, FairCom
has labored to keep this transition as easy as possible. While we have strived for the utmost in
compatibility, we occasionally find areas where it is possible to encounter unexpected situations.
The c-tree ODBC and c-treeACE ODBC drivers are both fully standards compliant, however,
subtle differences do exist. We have summarized these differences here.
 All table names returned by the c-treeACE ODBC Driver are as "owner.tablename" without
regard to the server configuration option SQL_OPTION OWNER_FILE_NAMES.
 The SQL_OPTION OWNER_FILE_NAMES only affects the name of the table created on disk. It
determines whether the owner name is prepended to the physical table name or not. Table
names returned by the ODBC driver are not affected by this c-treeACE SQL option.
 Using the c-tree ODBC driver it was common practice to represent the symbolic table name
in uppercase. You can use uppercase table names in c-treeACE SQL as long as you do not
wrap them in double quotes.
Another option is to use the SQL_OPTION DB_CASE_INSENSITIVE keyword before creating
the template database and the c-treeACE SQL databases.
9.2
Overview of the c-treeACE SQL Migration SDK
Many customers have a long history using FairCom’s ISAM and low-level APIs. With the
introduction of the additional capabilities of the c-treeACE SQL, there are many users who would
like to migrate their existing c-tree applications and data to take advantage of this powerful new
SQL technology. The rich flexibility given to database architects through the years with c-tree now
presents a challenge when moving to the standards-driven SQL interface.
This SDK is provided to assist in the migration of existing ISAM tables for use with c-treeACE
SQL. Unlike the c-treeACE SQL Import Utility (ctsqlimp), which makes only existing tables
accessible through SQL, the migration SDK physically relocates data files for use with c-treeACE
SQL. It is important to note the migrated new tables could very well not be accessible with your
existing ISAM application. If you have requirements to share data between existing ISAM
applications and c-treeACE SQL you should consider using the c-treeACE SQL Import Utility in
place of the c-treeACE SQL Migration SDK.
With modifications, the c-treeACE SQL Migration Utility can do data transformations, filtering and
other changes to the data files which may be required with a migration from ISAM to SQL. Source
code is provided and callback “hooks” are available to the advanced user to implement these
capabilities. This requires a certain level of programming ability. The migrate utility does not
www.faircom.com
All Rights Reserved
65
Migrating to c-treeACE SQL
update indices during the data transfer but does attempt to rebuild the indices after moving the
records.
9.3
Migration
The following sequence of steps assume you have a standard (non-SQL) c-treeACE Server in
operation, and are switching to c-treeACE SQL. You may create your new tables immediately if
you are already using c-treeACE SQL, and proceed with step 4. Actual procedures will vary
depending upon your applications, data, and needs. See below for detailed information on
customizing this utility for your specific data transformation needs. Please contact your nearest
FairCom office if you need assistance in determining or addressing your specific needs.
9.4
Key Steps
These steps assume you will keep you existing standard c-treeACE Server directory untouched
and intact. You should always back up all of your existing data and configuration files before
upgrading to any new c-treeACE Server to ensure complete data integrity.
1. Log off all clients and shut down an existing standard c-treeACE Server if it is running.
2. Restart the server with no clients attached, and then shut down again. This ensures
automatic recovery has taken place, and the c-tree data files are in a clean state.
3. Copy your ctsqlimp utility into your c-treeACE SQL directory.
4. Copy you data file(s) into your c-treeACE SQL directory.
5. Use the ctsqlimp utility with the -w switch to generate an ISQL script. This script allows you
to automatically build the tables you require based on your existing data files. Your server
must be up and running to run this utility.
ctsqlimp yourdatafile.dat <other options> -w newscript.sql
You should add the line COMMIT WORK; to the end of this script to ensure the transaction is
committed.
6. Start c-treeACE SQL.
7. Create the tables you will use with your schema, using the script generated from ctsqlimp in
step #5. With ISQL this looks like this:
isql -u ADMIN -a ADMIN -s newscript.sql 6597@hostname:database
8. Shut down c-treeACE SQL.
9. Copy the c-tree Migration Utility, ctsqlmgr, into the c-treeACE SQL operating directory. The
ctsqlmgr utility requires access to certain c-treeACE SQL system files.
10. Run the Migration Utility with the following command line arguments, where Mem_KB is the
amount of memory to use during the rebuild process (50Mb default):
ctsqlmgr <sourcefile> <destfile> [-s <sectors>] [-m <Mem_KB>]
11. Restart c-treeACE SQL and you should find your data has been copied into the c-treeACE
SQL data directory.
www.faircom.com
All Rights Reserved
66
Migrating to c-treeACE SQL
9.5
Important Observations
 The index rebuilding phase occurs even if you have not defined any indices or keys on your
tables as the utility updates internal indices (ROWID and RECBYT) necessary for c-treeACE
SQL.
 By default, records are moved across two tables, field by field, for fields with matching
names. Fields in the destination table that do not have a matching field in the source table
are set to NULL.
 Type conversion support is only between variable and fixed strings (both directions).
However, this behavior can be changed by implementing the fmap member in the Migration
Info structure as described later.
 If the original table is a table created with c-treeDB and contains a ROWID field, that value is
maintained in the destination table.
 If the utility fails with error CTDB_INTERNAL (4025), the destination table may be corrupt
and should be recovered from a backup or recreated.
 The c-tree standalone, single user model with transaction processing is used by this utility.
 A default 50MB buffer is used for rebuilding operations. Using as much memory as you have
available will increase the speed of the data migration.
9.6
Customization
The c-treeACE SQL Migration Utility requires two ‘C’ source files, ctsqlmgr.c and migrfncs.c,
which can be modified extensively, as described below, to meet the exact needs of your
application. These two files can be found in ctreeSDK\ctreeAPI\ctree\samples\special\sqlmigr. To
compile the program, you will need to generate and link against a c-tree Plus single user
standalone library with c-treeDB support and transaction processing.
The mainline of the migration utility is in ctsqlmgr.c, and this is the module to which you will add
any customized code. The migrfncs.c file can be modified as well, although this should not be
necessary under normal circumstances. The core of the migrate.c module is the following
function:
MigrateTable(pCTDBSESSION hSession, pTEXT orig, pTEXT dest, MigrationInfo *fconv).
This function takes a pointer, hSession, to a c-treeDB session which is currently logged in, the
source file name, orig, the destination file name, dest, and a pointer to a structure containing
information about the migration process, fconv. The majority of your customizations will be
located in this MigrationInfo structure. It may be necessary to add custom logon information for
your particular installation. That information is located outside of this structure.
If the migration structure is not provided to the MigrateTable() function (i.e., fconv is set to
NULL), the code internally populates a MigrationInfo structure based on the default
implementation described above.
The MigrationInfo structure is defined in migrfncs.c and described as follows.
typedef struct _MigrationInfo
{
/* callbacks */
MigrFunc AfterRecRead;
www.faircom.com
All Rights Reserved
67
Migrating to c-treeACE SQL
MigrFunc
MigrFunc
MigrFunc
MigrFunc
AfterRecWrite;
AfterRecConv;
BeforeOpens;
BeforeFirst;
/* ErrMsgFunc */
ErrMsgFunc ErrorMessage;
/* memory usage */
ULONG memoryKB;
/* source/dest objects */
pCTDBTABLE hSourceTbl;
pCTDBTABLE hDestTbl;
pCTDBRECORD hSourceRec;
pCTDBRECORD hDestRec;
/* field mapping */
FieldMap *fmap;
/* internals */
pTEXT strBuffer;
VRLEN strSize;
pCTBLOB pBlob;
} MigrationInfo;
9.7
Migration Callbacks
AfterRecRead(), AfterRecWrite(), AfterRecConv(), BeforeOpens(),and BeforeFirst() are
callback functions that can be used to perform verifications on the record being migrated,
implementing custom error handling, setting table and record properties, etc.
The callbacks have the following prototype:
NINT (* MigrFunc) (CTHANDLE Source, CTHANDLE Dest, CTDBRET err);
 Source and Dest are the source and the destination record or table (depending on the
callback) handle.
 err is the error code generated by the last operation (only for the Afterxxx() functions).
The callbacks should handle the error code passed in and return one of:
 ERR_STOP to stop the migration execution
 ERR_CONT to continue the execution
 ERR_SKIP to continue the execution by fetching a new record; the current record is not
migrated to the new table.
AfterRecRead(): The migration logic calls this function callback after having read a record from
the source table. It is important to note this callback is not called immediately by c-treeDB after
reading the record from the table at the ISAM level, but by the migration logic after c-treeDB
reads the record and performs any c-treeDB internal operations needed for c-treeDB
functionalities. When this function is implemented, it should perform error handling. The Source
parameter is the record handle. Dest is always NULL.
AfterRecWrite(): This function callback is called after having written a record to the destination
table. Source and Dest parameters of the function call are record handles.
www.faircom.com
All Rights Reserved
68
Migrating to c-treeACE SQL
AfterRecConv(): This function callback is called after converting the source record into the
destination record. This is most useful for error checking. Source and Dest parameters of the
function call are record handles.
BeforeOpens(): This function callback is called before opening the tables. Source and Dest
parameters of the function call are table handles.
BeforeFirst(): This function callback is called before reading the first record, hence before
starting the actual record migration. Source and Dest parameters of the function call are table
handles.
Error Handling Callback
ErrorMessage(): When specified, this function callback is called in order to display error
messages. If set to NULL, the error message display is skipped.
The function prototype is as follows:
VOID (* ErrMsgFunc) (pTEXT msg);
msg is the error message. You can take advantage of this callback if you need to output error
messages inside the callbacks implementation by using the macro PRINT_ERROR(msg).
Memory Usage
memoryKB: This is the amount of memory to use for the rebuild (default is 50Mb).
Source and Destination Objects:
hSourceTbl, hDestTbl: These are pointers to the source and destination table handles. These can
be set to NULL and, in this case, the handles are allocated and freed internally. Providing these
handles is useful in cases when it is necessary to set a table property, such as a callback at
c-treeDB level. The handle must not be active; there should be no open table linked to the
handle.
hSourceRec, hDestRec: These are pointers to the source and destination record handles. These
can be set to NULL and, in this case, the handles are allocated and freed internally. The handle
must relate to the proper table (i.e., hSourceRec = ctdbAllocRecord(hSourceTbl);)
Field Mappings
fmap: This is the structure where the bulk of your customizations will take place. This is a pointer
to a field conversion array, which is NULL for default behavior. When this field is not NULL, it is
expected to contain an array of FieldMap elements. The number of elements in the array MUST
equal the number of fields in the destination table (do not count internal c-treeDB fields). Each
element is related to a field in the destination table in order, i.e., the first field corresponds to the
first element in the array, the second field to the second array element and so forth. This structure
provides a mechanism allowing code to read a field (sfldno) from a source table and store this
field in a string used to insert the field into the destination record using ctdbSetFieldAsString().
FieldMap has the following definition:
typedef struct _fieldmap {
NINT sfldno;
GetBufferLenFunc GetBufferLen;
GetFieldFunc GetFieldAsString;
IsNullFunc IsNullField;
pTEXT dfl_value;
} FieldMap;
www.faircom.com
All Rights Reserved
69
Migrating to c-treeACE SQL
sfldno: This is the field number on the source table. Set to CT_MIGRATE_NEW_FIELD in the
case when there is no corresponding field in the source table.
GetBufferLen: This optional pointer points to a function returning the size of the string used when
retrieving the source field into a string using the GetFieldAsString function pointer. When this field
is not specified, the field is copied without any kind of conversion, i.e., a binary copy.
The function prototype is as follows:
VRLEN (* GetBufferLenFunc) (CTHANDLE Handle, NINT FieldNbr);
Where Handle is the record handle the logic will pass to the function and FieldNbr is the field
number on the source table. The function should return the buffer size.
GetFieldAsString: This optional pointer refers to a function to convert the field in the source
record into a proper string that can be stored into the destination field using the
ctdbSetFieldAsString() function. Please notice that the destination field does not necessarily
need to be a string field as c-treeDB is able to convert the string into the appropriate field type.
When GetBufferLen is not specified, this is copied without any conversion.
The function prototype is as follows:
CTDBRET (* GetFieldFunc) (CTHANDLE Handle, NINT FieldNbr, CTSTRING pValue, VRLEN size);
Where Handle is the record handle, FieldNbr is the field number in the source table, pValue is a
buffer of size bytes that the function must fill with the proper information as fetched from the
source record. The function should return CTDBRET_OK on success, otherwise an error code.
Where Handle is the record handle, FieldNbr is the field number in the source table. The function
should return YES if the field is NULL (or should be considered as NULL), NO otherwise.
dfl_value: A string containing the default value to store in the field when sfldno is
CT_MIGRATE_NEW_FIELD or the source field is set to NULL.
www.faircom.com
All Rights Reserved
70
10. c-treeACE SQL Configuration
10.1
c-treeACE SQL Configuration Keywords
c-treeACE SQL is generally configured with standard c-treeACE configuration options, (cache
sizes, transaction logging, etc.). Specific configurations are available in c-treeACE SQL for
additional SQL operational parameters and performance tuning. Only a few of these are
considered for routine use. For example,
 SQL_PORT (page 80)
 SETENV TPE_DFLT_DATE (page 99)
 SETENV TPE_MM_SWAPSIZE (page 103)
 SETENV TPE_MM_CACHESIZE (page 100)
Your application my require other options based on how the product was developed. Consult your
application vendor should you have questions about the use of other options. The FairCom
support team is always available to help guide the most applicable configurations and usage.
In V11 and later, the number of bytes to hold the content of ctsrvr.cfg and expand the
environment variables referenced in it has been raised from 1024 to 8192. This is important when
ctsrvr.cfg contains a SETENV configuration referencing an environment variable resulting in more
than 1024 bytes.
www.faircom.com
All Rights Reserved
71
c-treeACE SQL Configuration
10.2
MAX_SQL_ISOLATION_LEVEL
MAX_SQL_ISOLATION_LEVEL
<level>
Sets the maximum transaction isolation level at which SQL clients can operate. The supported
values are:
MAX_SQL_ISOLATION_LEVEL
1 Support READ_COMMITTED only
MAX_SQL_ISOLATION_LEVEL
2 Support READ_COMMITTED and REPEATABLE_READ.
MAX_SQL_ISOLATION_LEVEL
SERIALIZABLE.
3 Support READ_COMMITTED, REPEATABLE_READ, and
If a SQL client requests an isolation level that exceeds the maximum SQL isolation level specified
in the server configuration file, the SQL client operates at the maximum SQL isolation level rather
than its requested isolation level.
www.faircom.com
All Rights Reserved
72
c-treeACE SQL Configuration
10.3
SQL_CONNECT_TIMEOUT_SEC
SQL_CONNECT_TIMEOUT_SEC <seconds>
Sets the c-treeACE SQL connection timeout in seconds. The default is 1 second. A setting of 0
will revert to the behavior prior to V10.3.
www.faircom.com
All Rights Reserved
73
c-treeACE SQL Configuration
10.4
SQL_DATABASE
SQL_DATABASE <dbname>
Specifies the default c-treeACE SQL database name to create if one doesn't exist at server
startup.
www.faircom.com
All Rights Reserved
74
c-treeACE SQL Configuration
10.5
SQL_IDLE_WAKE
SQL_IDLE_WAKE #of_seconds
Sets a time to close tables that are not in use however, remain open in the open table cache.
A 0 or negative values disables this feature.
Default: 2
www.faircom.com
All Rights Reserved
75
c-treeACE SQL Configuration
10.6
SQL_KEEP_OPEN_TABLES
SQL_KEEP_OPEN_TABLES
<# of tables>
Sets how many tables to remain open per connection although not in use in SQL in order to
improve performance. A negative value enables the default.
Default: 60
www.faircom.com
All Rights Reserved
76
c-treeACE SQL Configuration
10.7
SQL_LOGFILE
Enable Logging of c-treeACE SQL debugging information.
In V10.3 and later, this configuration option can include an environment variable name that will be
substituted with its value when the configuration file is read.
www.faircom.com
All Rights Reserved
77
c-treeACE SQL Configuration
10.8
SQL_MIN_CARD
SQL_MIN_CARD
<# of rows>
Forces the SQL optimizer to consider that the tables contain, at minimum, <# of rows>.
Setting this value to any number greater than 0 (let say X) forces the optimizer to think that any
table with less than X records contain X records. This may potentially help the optimizer, in
certain cases, to chose the proper execution plan for tables even if the tables are actually empty.
Default: 0
www.faircom.com
All Rights Reserved
78
c-treeACE SQL Configuration
10.9
SQL_PARTOPEN_COST
SQL_PARTOPEN_COST <multiplier>
Adjusts the partition file open cost optimization.
A partitioned file open cost is available for the SQL cost analyzer such that SQL takes into
account the cost of opening partitions. Costs are calculated as follows:
 For an index on a partitioned file that is the partition key, the original table open cost is
reported.
 For an index on a partitioned file that is not related to the partition key, the original table cost
plus a multiplier times the number of active partitions is reported.
 For an index on a partitioned file that covers the partition key but does not order like the
partition key, the original table cost plus a multiplier times the number of active partitions
divided by 2 is reported.
Default: 10000
www.faircom.com
All Rights Reserved
79
c-treeACE SQL Configuration
10.10 SQL_PORT
TCP/IP Port Number for c-treeACE SQL
Default: 6597
www.faircom.com
All Rights Reserved
80
c-treeACE SQL Configuration
10.11 SQL_TRACE_CTREE_ERROR
SQL_TRACE_CTREE_ERROR
<error code>
Forces a stack trace to be generated in <error code> is encountered. This helps determine the
exact location of difficult to diagnose errors. Note that unhandled errors returned in c-treeDB
layer result in 2 stack traces generated for these errors.
www.faircom.com
All Rights Reserved
81
c-treeACE SQL Configuration
10.12 SETENV CLASSPATH
Sets the path to the JAR file containing the Java classes. The exact path will depend on the
version of Java you have installed.
Example
See Run-Time Settings for Java Stored Procedure Support (page 22).
See Also
 SETENV JAVA_COMPILER (page 96)
 SETENV JVM_LIB (page 97)
www.faircom.com
All Rights Reserved
82
c-treeACE SQL Configuration
10.13 SETENV DEBUG_JVM
Y (client) | S (server) When specified, the stored procedure is compiled with debug information
and the server modified Java source file and the class file are not removed from disk.
Example
SETENV DEBUG_JVM=Y
www.faircom.com
All Rights Reserved
83
c-treeACE SQL Configuration
10.14 SETENV DEBUG_JVM_PORT
The Debug port to connect the Java debugger to (jdb).
Example
SETENV DEBUG_JVM_PORT=50001
Default: 5678
www.faircom.com
All Rights Reserved
84
c-treeACE SQL Configuration
10.15 SETENV DH_CACHED_STATEMENTS
Number of static statements to cache.
c-treeACE SQL statement caches provide a performance benefit by allowing the SQL engine to
reuse previously parsed and optimized statements. Proper sizing of this cache can offer
significant performance improvements to applications. Two independent caches are used, a static
statement cache and a dynamic statement cache. c-treeACE SQL supports setting the size of
these statement caches (the number of entries that can be stored) up to 16000.
Default: On Windows the default size is 150; on Unix systems the default size is 250.
See Also
 SETENV DH_DYN_CACHED_STATEMENTS (page 87)
www.faircom.com
All Rights Reserved
85
c-treeACE SQL Configuration
10.16 SETENV DH_DO_AHEAD
Disables 'FETCH AHEAD' logic. Fetch ahead logic normally provides database stability with
only a small performance hit on fetches.
Example
SETENV DH_DO_AHEAD=N
www.faircom.com
All Rights Reserved
86
c-treeACE SQL Configuration
10.17 SETENV DH_DYN_CACHED_STATEMENTS
Number of prepared statements to cache.
c-treeACE SQL statement caches provide a performance benefit by allowing the SQL engine to
reuse previously parsed and optimized statements. Proper sizing of this cache can offer
significant performance improvements to applications. Two independent caches are used, a static
statement cache and a dynamic statement cache. c-treeACE SQL supports setting the size of
these statement caches (the number of entries that can be stored) up to 16000.
Default: On Windows the default size is 150; on Unix systems the default size is 250.
See Also
 SETENV DH_CACHED_STATEMENTS (page 85)
www.faircom.com
All Rights Reserved
87
c-treeACE SQL Configuration
10.18 SETENV DH_ENABLE_POOL
Enables connection pooling.
Example
SETENV DH_ENABLE_POOL=Y
www.faircom.com
All Rights Reserved
88
c-treeACE SQL Configuration
10.19 SETENV DH_JVM_OPTION_STRINGS
Allows specifying specific options to the JVM.
Example
SETENV DH_JVM_OPTIONS_STRINGS=-XX:+UseG1GC;-Xms40m;-Xmx40m
JVM environments might require specific tuning parameters, for example, changing the default
Garbage Collector (GC) or setting memory limits on JVM heap usage. Use this parameter to pass
in those values to fine tune your specific JVM environment.
The example below limits JVM memory (this is the default specified in ctsrvr.cfg in V11 and later):
SETENV
DH_JVM_OPTION_STRINGS=-Xms100m -Xmx300m
www.faircom.com
All Rights Reserved
89
c-treeACE SQL Configuration
10.20 SETENV DH_ENABLE_POOL
Configures the limit of open cursors available in a SQL session.
Example
SETENV DH_OPEN_CURSORS=xxx
Default: 50
www.faircom.com
All Rights Reserved
90
c-treeACE SQL Configuration
10.21 SETENV DH_OPT_OR_CARD
An OR clause optimization was improved, ensuring that the execution node restriction was
broken down even when there is only one table. Functionality was added to convert OR into
UNION, which is beneficial if the cardinality of each ORed predicate is small. This keyword
specifes the threshold for this conversion
Example
SETENV DH_OPT_OR_CARD=xxx
Default: 1000
www.faircom.com
All Rights Reserved
91
c-treeACE SQL Configuration
10.22 SETENV DH_POOL_SIZE
Set number of pooled connections. 1< n <=100
Example
SETENV DH_POOL_SIZE=20
www.faircom.com
All Rights Reserved
92
c-treeACE SQL Configuration
10.23 SETENV DH_REBUILD_SEL_CUTOFF
This controls the regeneration of the plan for queries with parameter references, during
execution, based on the value set: -1 < n <= 100.
 If the value is set to -1, query plans are never regenerated during execution.
 If the value is set to 0, query plans are always regenerated during execution.
 If the value is set between 1 and 100, query plans will be regenerated whenever the
percentage difference in selectivity (i.e., the selectivity that was used during the generation of
the original plan and the selectivity for the actual parameter values passed during execution)
exceeds this value. For example, if the value is set to 25, the plan will be regenerated only if
the selectivity of the actual parameter is different from the original selectivity than 25%.
Example
SETENV DH_REBUILD_SEL_CUTOFF=25
Default: (-1) Query plans are never regenerated during execution.
www.faircom.com
All Rights Reserved
93
c-treeACE SQL Configuration
10.24 SETENV DH_THREAD_STACK_SZ_KB
The stack space utilized by c-treeACE SQL threads (in kilobytes).
Example
SETENV DH_THREAD_STACK_SZ_KB=512
www.faircom.com
All Rights Reserved
94
c-treeACE SQL Configuration
10.25 SETENV DH_SVR_DA_BUFFER
Controls the size of the SQLDA structure within the server and the size of the fetch ahead buffer.
www.faircom.com
All Rights Reserved
95
c-treeACE SQL Configuration
10.26 SETENV JAVA_COMPILER
Indicates the full path to the Java compiler. The exact path will depend on the version of the
compiler you have installed.
Example
See Run-Time Settings for Java Stored Procedure Support (page 22).
See Also
 SETENV CLASSPATH (page 82)
 SETENV JVM_LIB (page 97)
www.faircom.com
All Rights Reserved
96
c-treeACE SQL Configuration
10.27 SETENV JVM_LIB
Indicates the full path to the Java Virtual Machine (JVM) installed on your system. The exact path
will depend on the version of the JVM you have installed.
Example
See Run-Time Settings for Java Stored Procedure Support (page 22).
See Also
 SETENV CLASSPATH (page 82)
 SETENV JAVA_COMPILER (page 96)
www.faircom.com
All Rights Reserved
97
c-treeACE SQL Configuration
10.28 SETENV TPESQLDBG
c-treeACE SQL has extensive internal debugging logic that can be accessed through various
means. SQL errors can be logged to the file sql_server.log in the c-treeACE SQL directory.
TPESQLDBG is an array of 12 ‘Y’/‘N’ characters that determine which debug options are
enabled.
Example
SETENV TPESQLDBG=NNNNNNNNNNYN
See
 Advanced c-treeACE SQL Logging (page 19)
www.faircom.com
All Rights Reserved
98
c-treeACE SQL Configuration
10.29 SETENV TPE_DFLT_DATE
Changes the default date format used by c-treeACE SQL. Changing the default date format
affects:
 The default output format of date values;
 How SQL interprets date literals in queries and INSERT statements.
The following date types are supported:
 US - US_DFLT_DATE
 UK - UK_DFLT_DATE
 ISO - ISO_DFLT_DATE
Examples
SETENV TPE_DFLT_DATE=UK
SETENV TPE_DFLT_DATE=ISO_DFLT_DATE
Default: US_DFLT_DATE
www.faircom.com
All Rights Reserved
99
c-treeACE SQL Configuration
10.30 SETENV TPE_MM_CACHESIZE
LEGACY Option
Specifies the size, in kilobytes, of the memory cache used for temporary tables. The default value
is 1,000 Kb of memory. The internal storage system uses this cache for storing temporary tables
when sorting and creating dynamic indexes during processing. Increasing
TPE_MM_CACHESIZE improves performance by reducing the need to write to the on-disk swap
file.
The TPE_MM_CACHESIZE setting determines how much memory the SQL engine uses for its
temporary tables for each SQL client. Increasing this setting increases the amount of temporary
table data the c-treeACE SQL stores in memory instead of writing this data to the disk-based
swap file. But note that this memory is allocated for each SQL client, so you should consider how
many clients will connect to the server at any given time and make sure total cache memory
doesn't exceed available physical memory on the system.
These swap files can be found during an active connection with a filename beginning with ‘M’
followed by a string of random alphanumerics. These files can sometimes be left around after an
abnormal server shutdown. They can be safely deleted once the server has been properly shut
down.
Example
SETENV TPE_MM_CACHESIZE=1024
Note: The MM subsystem was replaced with a new architecture beginning with V10.3. Only
enable the legacy MM subsystem on the advice of FairCom's engineering team.
www.faircom.com
All Rights Reserved
100
c-treeACE SQL Configuration
10.31 SETENV TPE_MM_COMPARE_OVHD
LEGACY Option
The type of query shown below was found to run slower than expected in certain situations:
SELECT (TOP k) * FROM tbl WHERE x BETWEEN a AND b ORDER BY y
The default cost estimates used in choosing an execution plan have been updated to improve
general performance of this type of query. Additional options are also available to further adjust
costing used in this optimization.
 TPE_MM_COMPARE_OVHD (default value is 1)
 TPE_MM_INSERT_OVHD (default value is 250)
Note: The MM subsystem was replaced with a new architecture beginning with V10.3. Only
enable the legacy MM subsystem on the advice of FairCom's engineering team.
www.faircom.com
All Rights Reserved
101
c-treeACE SQL Configuration
10.32 SETENV TPE_MM_INSERT_OVHD
LEGACY Option
The type of query shown below was found to run slower than expected in certain situations:
SELECT (TOP k) * FROM tbl WHERE x BETWEEN a AND b ORDER BY y
The default cost estimates used in choosing an execution plan have been updated to improve
general performance of this type of query. Additional options are also available to further adjust
costing used in this optimization.
 TPE_MM_COMPARE_OVHD (default value is 1)
 TPE_MM_INSERT_OVHD (default value is 250)
Note: The MM subsystem was replaced with a new architecture beginning with V10.3. Only
enable the legacy MM subsystem on the advice of FairCom's engineering team.
www.faircom.com
All Rights Reserved
102
c-treeACE SQL Configuration
10.33 SETENV TPE_MM_SWAPSIZE
LEGACY Option
Specifies the maximum size, in kilobytes, of the swap file the internal storage system uses when
it writes to disk from the main memory cache.
Setting this value too small will result in error -16001:MM No data block for queries that require
more swap space than is available. A maximum memory limit of 4TB is available.
Example
SETENV TPE_MM_SWAPSIZE=500000
Note: Prior to c-treeACE V9.3.41446 Build 110507, a limit of 2Gb existed. Values larger than this
improperly "wrapped" around.
Note: The MM subsystem was replaced with a new architecture beginning with V10.3. Only
enable the legacy MM subsystem on the advice of FairCom's engineering team.
www.faircom.com
All Rights Reserved
103
c-treeACE SQL Configuration
10.34 SQL_OPTION CHECK_HEAP
SQL_OPTION CHECK_HEAP
Enables the c-treeACE SQL memory free function to check for memory overwrites and double
frees. If it detects one of these situations, it logs a message to CTSTATUS.FCS and raises an
unhandled exception that terminates the process. The messages are:
SQL_HEAP_CHECK: operator delete detected double free of memory
SQL_HEAP_CHECK: operator delete detected memory overwrite
www.faircom.com
All Rights Reserved
104
c-treeACE SQL Configuration
10.35 SQL_OPTION CTSTRING_VARCHAR
SQL_OPTION CTSTRING_VARCHAR
Allows VARCHAR and LVARCHAR fields to be created as CT_STRING fields for backwards
compatibility. These are normally created as CT_[ 2 | 4 ]_STRING.
www.faircom.com
All Rights Reserved
105
c-treeACE SQL Configuration
10.36 SQL_OPTION CREATE_WITH_ROWID
SQL_OPTION CREATE_WITH_ROWID
Enables default ROWID for new tables. By default, tables are created with a ROWID and without
a RECBYT index.
www.faircom.com
All Rights Reserved
106
c-treeACE SQL Configuration
10.37 SQL_OPTION CREATE_WITH_RECBYT
SQL_OPTION CREATE_WITH_RECBYT
Enables default RECBYT fields for new tables. By default, tables are created with a ROWID and
without a RECBYT index.
www.faircom.com
All Rights Reserved
107
c-treeACE SQL Configuration
10.38 SQL_OPTION CTDB_ROWID
Revert to a different ROWID value starting points (0 vs. 1) for c-treeDB and c-treeACE SQL.
www.faircom.com
All Rights Reserved
108
c-treeACE SQL Configuration
10.39 SQL_OPTION DB_CASE_INSENSITIVE
Enables case insensitive comparisons, sorting, and identifiers within a database and is enabled
on a database by database basis.
www.faircom.com
All Rights Reserved
109
c-treeACE SQL Configuration
10.40 SQL_OPTION FORCE_TEMPLATE_DB
Use the legacy __Master.dbs database template for new databases.
LEGACY OPTION: NOT RECOMMENDED
www.faircom.com
All Rights Reserved
110
c-treeACE SQL Configuration
10.41 SQL_OPTION HM_ACTIVE
Note: FairCom Internal option only .
www.faircom.com
All Rights Reserved
111
c-treeACE SQL Configuration
10.42 SQL_OPTION LOAD_CALLBACK_LIB
Load the data type SDK callback library.
(In V10.3 and later) As the callback library is critical for proper data interpretation, when its
loading is required by specifying the above configuration keyword, a failed load generates a panic
condition and terminates the c-treeACE SQL Server operation with the following message logged
in CTSTATUS.FCS:
- User# 00001 : PANIC - TPEUTIL LoadSQLSDK callback library load failed PID 5996
- User# 00001 SQL PANIC, attempting shutdown
www.faircom.com
All Rights Reserved
112
c-treeACE SQL Configuration
10.43 SQL_OPTION NO_AUTO_ABORT
SQL_OPTION NO_AUTO_ABORT
Disables the automatic ABORT (ROLLBACK) feature should an error occur while processing.
Note: This option is disabled by default.
www.faircom.com
All Rights Reserved
113
c-treeACE SQL Configuration
10.44 SQL_OPTION NO_BINARY_PAD
This is a behavior change that affects how the values of BINARY fields are stored in V11 and
later.
Prior to V11, the server was not padding BINARY fields with 0x00 when the values were less than
the defined length. Because of this, both the values stored on disk and the values returned may
have been shorter than the defined length (basically BINARY and VARBINARY behaved in the
same manner). This behavior has been corrected in V11 and later so that BINARY fields are
properly padded with 0x00 both on disk and when retrieved. Existing data is not touched on disk,
however the values returned in SQL are now padded.
The previous behavior can be restored by using the keyword SQL_OPTION NO_BINARY_PAD in
ctsrvr.cfg.
www.faircom.com
All Rights Reserved
114
c-treeACE SQL Configuration
10.45 SQL_OPTION NO_CARDINALITY
Disables cardinality logic that informs the optimizer about the number of rows in a data or index
file.
www.faircom.com
All Rights Reserved
115
c-treeACE SQL Configuration
10.46 SQL_OPTION NO_COSTS
Disables logic that returns to the optimizer the cost in units of time for given record and index
operations. The optimizer will use this information to decide whether to use a record or an index
scan.
Note: This option is not implemented and is reserved for future use.
www.faircom.com
All Rights Reserved
116
c-treeACE SQL Configuration
10.47 SQL_OPTION NO_CRYPT_SYSTBL
SQL_OPTION NO_CRYPT_SYSTBL
In V10.3 and later, c-treeACE SQL system tables are encrypted by default to protect sensitive
database meta data. The encryption algorithm is AES with a 128-bit key when advanced
encryption is in use. It is protected with CAMO when not using the advanced encryption.
To have system tables in clear text, SQL_OPTION NO_CRYPT_SYSTBL must be placed in
ctsrvr.cfg before the database is created.
www.faircom.com
All Rights Reserved
117
c-treeACE SQL Configuration
10.48 SQL_OPTION NO_DB_CONVERSION
When upgrading between c-treeACE SQL versions, the database engine will attempt to upgrade
system tables, etc. to the latest formats. In some cases this is not desired. This option disables
the database conversion on startup.
www.faircom.com
All Rights Reserved
118
c-treeACE SQL Configuration
10.49 SQL_OPTION NO_DUP_IDXNAME
SQL_OPTION NO_DUP_IDXNAME
Support was added that changed the way index file names are generated to guarantee name
uniqueness. This naming convention can cause compatibility problems with existing ISAM
application containing hard-coded index names for tables created using SQL. This option reverts
this new support.
www.faircom.com
All Rights Reserved
119
c-treeACE SQL Configuration
10.50 SQL_OPTION NO_HUGEFILE
Do not create tables as HUGE (> 4GB).
Default: HUGE files are enabled for all c-treeACE SQL created tables.
www.faircom.com
All Rights Reserved
120
c-treeACE SQL Configuration
10.51 SQL_OPTION NO_PUSHDOWN
Internal logic change for filtering of records.
WARNING: Only use on the advice of FairCom. This will negatively impact performance in most
cases.
www.faircom.com
All Rights Reserved
121
c-treeACE SQL Configuration
10.52 SQL_OPTION NO_REVERSE_INDEX
Note: FairCom Internal option only .
www.faircom.com
All Rights Reserved
122
c-treeACE SQL Configuration
10.53 SQL_OPTION NO_SELECTIVITY
Disables selectivity logic that informs the optimizer about the percentage of rows returned when
applying a given search criteria.
www.faircom.com
All Rights Reserved
123
c-treeACE SQL Configuration
10.54 SQL_OPTION NO_SHARED_MEMORY
Do not use the shared memory protocol as the default on localhost connections. When this option
is specified, TCP/IP is used by default.
Note: Unless this option is specified, shared memory is the default for local SQL connections
regardless of the protocol used for ISAM connections. See the c-tree Server Administrator's
Guide (/doc/ctserver/#27910.htm) for information about the communication protocol for ISAM
connections.
www.faircom.com
All Rights Reserved
124
c-treeACE SQL Configuration
10.55 SQL_OPTION NO_SYSSUPERFILE
Creates c-treeACE SQL system tables as individual files rather than a single c-tree Superfile.
www.faircom.com
All Rights Reserved
125
c-treeACE SQL Configuration
10.56 SQL_OPTION OWNER_FILE_NAMES
c-treeACE SQL is a file based database engine. To avoid naming collisions between files it is
usually necessary to maintain additional information in the file name. This option prepends the
owner ('admin' by default) to the file front of the file name, much as a schema might be
considered.
www.faircom.com
All Rights Reserved
126
c-treeACE SQL Configuration
10.57 SQL_OPTION PAD_WITH_NULL
Create system tables to set padding to NULL.
www.faircom.com
All Rights Reserved
127
c-treeACE SQL Configuration
10.58 SQL_OPTION PARTIAL_SEG
Allow use of imported c-tree indexes containing partial segments in keys.
Note: This option only applies to legacy imported tables.
www.faircom.com
All Rights Reserved
128
c-treeACE SQL Configuration
10.59 SQL_OPTION PRESERVE_CURSOR_FREE_LOCK
Free all locks when isolation level is READ_COMMITTED and keep only read locks when
isolation level is higher.
www.faircom.com
All Rights Reserved
129
c-treeACE SQL Configuration
10.60 SQL_OPTION SUPPRESS_JVM_LOAD_ERR
SQL_OPTION SUPPRESS_JVM_LOAD_ERR
Disables JVM error messages at server startup. A "No Java capabilities" message is output
instead.
www.faircom.com
All Rights Reserved
130
c-treeACE SQL Configuration
10.61 SQL_OPTION USE_MM
SQL_OPTION USE_MM
(LEGACY) Switch back to the legacy MM temp sorting subsystem.
See Also
 SETENV TPE_MM_CACHESIZE (page 100)
 SETENV TPE_MM_COMPARE_OVHD (page 101)
 SETENV TPE_MM_INSERT_OVHD (page 102)
 SETENV TPE_MM_SWAPSIZE (page 103)
Note: The MM subsystem was replaced with a new architecture beginning with V10.3. Only
enable the legacy MM subsystem on the advice of FairCom's engineering team.
www.faircom.com
All Rights Reserved
131
c-treeACE SQL Configuration
10.62 SQL_DEBUG ABORT_ON_PANIC
SQL_DEBUG ABORT_ON_PANIC
Enables c-treeACE SQL shutdown on a panic condition for debugging purposes. By default, a
panic is only logged to CTSTATUS.FCS.
www.faircom.com
All Rights Reserved
132
c-treeACE SQL Configuration
10.63 SQL_DEBUG ERROR_INFO
SQL_DEBUG ERROR_INFO
Enables c-treeACE SQL logging to sql_server.log when a query fails.
www.faircom.com
All Rights Reserved
133
c-treeACE SQL Configuration
10.64 SQL_DEBUG INDEX
Advanced debugging of index key retrievals.
WARNING: Extreme performance impact.
See Also
 SQL_DEBUG INDEX_INFO (page 137)
www.faircom.com
All Rights Reserved
134
c-treeACE SQL Configuration
10.65 SQL_DEBUG INDEX_SEL
SQL_DEBUG INDEX_SEL
Enables output selectivity information also for index selectivity.
www.faircom.com
All Rights Reserved
135
c-treeACE SQL Configuration
10.66 SQL_DEBUG INDEX_DEF_SEL
SQL_DEBUG INDEX_DEF_SEL
Enables checks for cases where calculating the default selectivity is suspect and logs
"COMPLEX SELECTIVITY" messages in the function monitor window with information on why
the calculation is suspect. There are no corrective actions.
www.faircom.com
All Rights Reserved
136
c-treeACE SQL Configuration
10.67 SQL_DEBUG INDEX_INFO
Advanced debugging of index key retrievals.
WARNING: Extreme performance impact.
See Also
 SQL_DEBUG INDEX (page 134)
www.faircom.com
All Rights Reserved
137
c-treeACE SQL Configuration
10.68 SQL_DEBUG LOG_STUBS_HIGH
Logs sparse information detailing table create activities.
www.faircom.com
All Rights Reserved
138
c-treeACE SQL Configuration
10.69 SQL_DEBUG LOG_STUBS_MED
Logs basic c-treeACE SQL Statement information.
www.faircom.com
All Rights Reserved
139
c-treeACE SQL Configuration
10.70 SQL_DEBUG LOG_STUBS_LOW
Logs low level information, which can be quite voluminous.
Note: Due to the volume of information logged, this option can negatively impact performance.
Please consult FairCom support before enabling this option.
www.faircom.com
All Rights Reserved
140
c-treeACE SQL Configuration
10.71 SQL_DEBUG LOG_STMT_TIMES
SQL_DEBUG LOG_STMT_TIMES
Enables logging of start and end times for statements PREPARE, EXECUTE and OPEN.
See Also
 SQL_DEBUG LOG_STMT_TIMES_FETCH (page 142)
www.faircom.com
All Rights Reserved
141
c-treeACE SQL Configuration
10.72 SQL_DEBUG LOG_STMT_TIMES_FETCH
SQL_DEBUG LOG_STMT_TIMES_FETCH
Log start and end times of a fetch sequence (open cursor, all fetches and close cursor). Logging
is to the CTSTATUS.FCS file.
See Also
 SQL_DEBUG LOG_STMT_TIMES (page 141)
www.faircom.com
All Rights Reserved
142
11. c-treeACE SQL Built-in Stored
Procedures
A variety of built in procedures are available for administrative database tasks. These can be
called in the same manner as user defined procedures:
call fc_get_fcproclist();
A result set, if returned, is handled in the standard caller manner.
www.faircom.com
All Rights Reserved
143
c-treeACE SQL Built-in Stored Procedures
11.1
fc_add_db( )
Adds an existing c-treeACE SQL database to the list of registered databases.
Parameters (1)
dbname
VARCHAR(1024)
Example
call fc_add_db('ctreeSQL');
www.faircom.com
All Rights Reserved
144
c-treeACE SQL Built-in Stored Procedures
11.2
fc_check_file_tran_state( )
Returns the current c-treeACE transaction mode for the specified table.
Result Set Fields (2)
owner
table
VARCHAR(64)
VARCHAR(64)
Returned modes:
 0 No transaction control.
 1 Transaction control without recoverability. (ctPREIMG)
 2 Transaction control and recoverability. (ctTRNLOG)
Example
call fc_check_file_tran_state();
owner
----admin
admin
admin
admin
table_name
---------custmast
custorder
ordritem
itemmast
www.faircom.com
All Rights Reserved
145
c-treeACE SQL Built-in Stored Procedures
11.3
fc_create_db( )
Creates a new c-treeACE SQL database named dbname.
Parameters (1)
dbname
VARCHAR(1024)
Example
call fc_create_db('ctreeSQL');
www.faircom.com
All Rights Reserved
146
c-treeACE SQL Built-in Stored Procedures
11.4
fc_create_user( )
Creates a new c-treeACE SQL user username with initial password pass.
Parameters (2)
username VARCHAR(32)
pass
VARCHAR(32)
Example
call fc_create_user('accounting', 'unbreakable');
www.faircom.com
All Rights Reserved
147
c-treeACE SQL Built-in Stored Procedures
11.5
fc_get_cachestats()
Returns c-treeACE SQL current cache subsystem statistics.
Result Set Fields (2)
Description VARCHAR(64)
Value
BIGINT
Example
>call fc_get_cachestats();
DESCRIPTION
----------data buffer requests
data buffer hits
index buffer requests
index buffer hits
index buffer pages in use
max index buffers in use
available data cache pages
data cache pages in use
max data cache pages in use
# of index buffers on upd list (tran)
# of index buffers on upd list
# of data caches on upd list (tran)
# of data caches on upd list
avail
data file special cache pages
actual data file special cache pages
maximum data file special cache pages
VALUE
----9860
9772
883
817
15
26
1253
57
57
0
1
0
0
626
0
0
16 records returned
www.faircom.com
All Rights Reserved
148
c-treeACE SQL Built-in Stored Procedures
11.6
fc_get_connstats()
Returns c-treeACE SQL current connection statistics.
Result Set Fields (2)
Description VARCHAR(64)
Value
BIGINT
Example
>call fc_get_connstats();
DESCRIPTION
----------Number of connected users
Maximum connected users
Threads in use total (ctaddwork)
Max threads in use (ctaddwork)
Num threads active in foreground
VALUE
----1
1
1
2
1
5 records returned
www.faircom.com
All Rights Reserved
149
c-treeACE SQL Built-in Stored Procedures
11.7
fc_get_dblist( )
Returns a resultset listing registered database names.
Result Set Fields (1)
dbname
VARCHAR(1024)
Example
call fc_get_dblist();
dbname
-----demoSQL
ctreeSQL
testing
www.faircom.com
All Rights Reserved
150
c-treeACE SQL Built-in Stored Procedures
11.8
fc_get_fcproclist( )
Returns a listing of available built-in stored procedures.
Result Set Fields (1)
proclist
VARCHAR(1024)
Example
call fc_get_fcproclist();
proclist
-------fc_create_user
fc_get_userlist
fc_get_fcproclist
fc_set_debug
fc_set_priority
fc_get_priority
fc_set_blockinglock
fc_get_dblist
fc_create_db
fc_add_db
fc_set_min_card
fc_get_min_card
fc_set_selectivity
fc_get_selectivity
fc_get_taskid
fc_check_file_tran_state
fc_get_server_version
fc_set_impersonation
fc_set_file_tran_state
www.faircom.com
All Rights Reserved
151
c-treeACE SQL Built-in Stored Procedures
11.9
fc_get_filestats()
Returns c-treeACE SQL current physical file control statistics.
Result Set Fields (2)
Description VARCHAR(64)
Value
BIGINT
Example
>call fc_get_filestats();
DESCRIPTION
----------Number of open physical files
Number of open logical files
Number of c-tree FCBs in use
Max physical files opened
Max logical files opened
Max c-tree FCBs in use
Number of virtual files open
Number available file control blocks
VALUE
----8
25
34
8
35
53
0
1001
8 records returned
www.faircom.com
All Rights Reserved
152
c-treeACE SQL Built-in Stored Procedures
11.10 fc_get_iostats()
Returns c-treeACE SQL current I/O statistics.
Result Set Fields (2)
Description VARCHAR(64)
Value
BIGINT
Example
>call fc_get_iostats();
Description
Value
--------------number of read operations
1,182
bytes read
1,626,850
number of write operations
33
bytes written
158,080
number of comm read operations
0
comm bytes read
0
number of comm write operations
0
comm bytes written
0
number of log write operations
2
bytes written to log file
16,384
number of log read operations
5
bytes read from log file
17,416
number of log extension operations
0
log file extension bytes
0
14 records returned
www.faircom.com
All Rights Reserved
153
c-treeACE SQL Built-in Stored Procedures
11.11 fc_get_isamstats()
Returns c-treeACE SQL current ISAM statistics.
Result Set Fields (2)
Description VARCHAR(64)
Value
BIGINT
Example
>call fc_get_isamstats();
DESCRIPTION
----------ISAM record
ISAM record
ISAM record
ISAM record
VALUE
----add count
delete count
update count
read count
0
0
0
124
4 records returned
www.faircom.com
All Rights Reserved
154
c-treeACE SQL Built-in Stored Procedures
11.12 fc_get_lockstats()
Returns c-treeACE SQL current lock statistics.
Result Set Fields (2)
Description VARCHAR(64)
Value
BIGINT
Example
>call fc_get_lockstats();
DESCRIPTION
----------count of lock attempts
subcount of hdr lock attempts
count of locks denied
count of locks blocked
subcount of header blocks
count of dead locks
count of locks freed
count of blocks released
current count of locks held
current count of blocked requests
cumulative lock wait time^
cumulative lock wait count
maximum elapsed lock wait time^
net locks over unlocks
max net locks over unlocks
VALUE
----249
2
0
0
0
0
249
0
0
0
0
0
0
0
1
15 records returned
www.faircom.com
All Rights Reserved
155
c-treeACE SQL Built-in Stored Procedures
11.13 fc_get_memstats()
Returns c-treeACE SQL current memory statistics.
Result Set Fields (2)
Description VARCHAR(64)
Value
BIGINT
Example
>call fc_get_memstats();
DESCRIPTION
----------SQL current aggregate summary
SQL memory highwater
Net SQL memory allocations
System memory highwater mark
System aggregate sum
VALUE
----2508841
2908540
1880
51370239
50968434
5 records returned
www.faircom.com
All Rights Reserved
156
c-treeACE SQL Built-in Stored Procedures
11.14 fc_get_min_card( )
Returns the minimum cardinality value currently in use by the c-treeACE SQL database engine.
Result Set Fields (1)
value
INTEGER
Example
call fc_get_min_card()
value
----0
www.faircom.com
All Rights Reserved
157
c-treeACE SQL Built-in Stored Procedures
11.15 fc_get_priority( )
Returns the c-treeACE SQL client thread priority.
Note: This feature is supported only on the Windows operating system.
Result Set Fields (1)
priority
TINYINT
Example
call fc_get_priority()
priority
-------0
www.faircom.com
All Rights Reserved
158
c-treeACE SQL Built-in Stored Procedures
11.16 fc_get_partbounds()
fc_get_partbounds(owner, table_name)
Returns the first and last active partition numbers for a partitioned table. This is useful to
determine the oldest (Firstactprt) partition to purge, for example. You must be connected to the
database that contains the table.
Parameters (2)
-----------------owner
VARCHAR(64)
table_name VARCHAR(64)
Result Set Fields (2)
-----------------Firstactprt -- "First Active Partition number"
Lastactprt -- "Last Active Partition number"
www.faircom.com
All Rights Reserved
159
c-treeACE SQL Built-in Stored Procedures
11.17 fc_get_replstats()
Returns c-treeACE SQL current replication statistics.
Result Set Fields (2)
Description VARCHAR(64)
Value
BIGINT
Example
>call fc_get_replstats();
DESCRIPTION
VALUE
--------------Total successful operations
0
Successful apply operations
1339713297
Successful transaction begins
7233801
Successful transaction aborts
6832485
Successful transaction commits
27
Successful transaction success
19
Successful user-defined entries
30
Successful record adds
20
Successful record updates
25769806224
Successful record deletes
644245094407
Successful physical file opens
42949672970
Successful physical file closes
1134704589799574
Total failed operations
4294967297
Failed apply operations
1
Failed transaction begins
644245094400
Failed transaction aborts
0
Failed transaction commits
0
Failed transaction success
0
Failed record adds
70
Failed record updates
0
Failed record deletes
0
Failed physical file opens
0
Failed physical file closes
0
Log number of current scan pos
0
Offset of current scan pos
0
current status of replication agent
0
current c-tree API function
0
server connection status
0
28 records returned
www.faircom.com
All Rights Reserved
160
c-treeACE SQL Built-in Stored Procedures
11.18 fc_get_selectivity( )
Returns the selectivity. false if the selectivity is off; true when on.
Result Set Fields (1)
active
BIT
Example
call fc_get_selectivity()
active
-----true
www.faircom.com
All Rights Reserved
161
c-treeACE SQL Built-in Stored Procedures
11.19 fc_get_server_version( )
Returns the version information for the c-treeACE SQL database engine.
Result Set Fields (6)
VERSION VARCHAR(40)
VER_MAJOR
INTEGER
VER_MINOR
INTEGER
VER_REVISION
INTEGER
BUILD_DATE
VARCHAR(14)
VER_MINI INTEGER
Example 1: Using ISQL
call fc_get_server_version();
VERSION
VER_MAJOR
--------------10.0.1.60592(Build-121011)
10
VER_MINOR VER_REVISION BUILD_DATE
--------- ------------ ---------0
60592 121011
VER_MINI
-------1
Example 2: Using DSQL
The following code can be added to DSQL Tutorial 1 to call this function:
printf("\tGet server version info...\n");
pCTSQLCURSOR
CTSQLCHAR
CTSQLCHAR
hCursor = NULL;
CTVersion[64];
CTMajor[64];
rc = ctsqlPrepare(hCmd, "CALL fc_get_server_version()");
if (rc != CTSQLRET_OK)
Handle_Error("fc_get_server_version() Prepare");
rc = ctsqlExecute(hCmd, &hCursor);
if (rc != CTSQLRET_OK)
Handle_Error("fc_get_server_version() Execute");
/* fetch and display each individual record */
while ((rc = ctsqlNext(hCursor)) == CTSQLRET_OK)
{
ctsqlGetChar(hCursor, 0, CTVersion);
ctsqlGetChar(hCursor, 1, CTMajor);
printf("\n\t\t%s - %s\n", CTMajor, CTVersion);
}
ctsqlFreeCursor(hCursor);
www.faircom.com
All Rights Reserved
162
c-treeACE SQL Built-in Stored Procedures
The resulting output will appear as follows (notice the version number displayed at the end of
INIT):
www.faircom.com
All Rights Reserved
163
c-treeACE SQL Built-in Stored Procedures
11.20 fc_get_sqlstats()
Returns c-treeACE SQL current SQL subsystem statistics.
Result Set Fields (2)
Description VARCHAR(64)
Value
BIGINT
Example
>call fc_get_sqlstats();
DESCRIPTION
VALUE
--------------SQL memory highwater
current aggregate sum
current net SQL memory allocations
dynamic statement cache requests
59
dynamic statement cache hits
static statement cache requests
36
static statement cache hits
current dynamic stmt cache entries
highest dynamic stmt cache entries
maximum dynamic stmt cache entries
current static stmt cache entries
10
highest static stmt cache entries
10
maximum static stmt cache entries
150
current number of dynamic caches
1
current number of static caches
1
current number of local caches
1
current local stmt cache entries
0
highest local stmt cache entries
0
maximum local stmt cache entries
150
local statement cache requests
0
local statement cache hits
0
Tuple fetches by index only scan
0
Tuple fetches by index scan with record retrieval
2908764
2507391
1884
44
26
13
14
150
76
23 records returned
www.faircom.com
All Rights Reserved
164
c-treeACE SQL Built-in Stored Procedures
11.21 fc_get_sysconfig()
Returns c-treeACE SQL current server configuration information:
Result Set Fields (2)
Description VARCHAR(64)
Value
BIGINT
Example
>call fc_get_sysconfig();
Description
----------REPL_MAPPINGS Enabled
Max num segments per index
Max num indices per data file
Server path separator
Client path separator
Server Serial Number
Value
----0
12
32
92
92
89,123,456
6 records returned
www.faircom.com
All Rights Reserved
165
c-treeACE SQL Built-in Stored Procedures
11.22 fc_get_taskid( )
Returns the current c-treeACE task ID associated with the c-treeACE SQL connection.
Result Set Fields (1)
id
INTEGER
Example
call fc_get_taskid()
id
-19
www.faircom.com
All Rights Reserved
166
c-treeACE SQL Built-in Stored Procedures
11.23 fc_get_transtats()
Returns c-treeACE SQL current transaction control statistics.
Result Set Fields (2)
Description VARCHAR(64)
Value
BIGINT
Example
>call fc_get_transtats();
DESCRIPTION
----------# transaction begins
# transaction ends
# transaction aborts
# transaction savepoints
# transaction restores
# transaction log flush writes
DOSFLUSH sync calls
transaction log sync calls
cumulative transaction time^
cumulative transaction count
maximum elapsed tran time^
check point count
cumulative checkpoint time^
cumulative checkpoint size
checkpoint index buffer writes
checkpoint data cache writes
log flush count
log flush time
VALUE
----0
0
0
1
0
0
0
2
0
0
0
1
0
0
0
0
0
0
18 records returned
www.faircom.com
All Rights Reserved
167
c-treeACE SQL Built-in Stored Procedures
11.24 fc_get_userlist( )
Returns the current list of c-treeACE SQL defined users.
Result Set Fields (3)
USER
DBA
RESOURCE
VARCHAR(32)
VARCHAR(3)
VARCHAR(3)
Example
call fc_get_userlist();
USER
DBA
RESOURCE
------------admin
Yes
Yes
accounting (null) (null)
guest
(null) (null)
sales
(null) (null)
www.faircom.com
All Rights Reserved
168
c-treeACE SQL Built-in Stored Procedures
11.25 fc_ptadmin_num()
Performs partition administration actions to a partitioned table based on the partition number. You
must be connected to the database that contains the table. This uses the ptADMINnewthd mode
which requires the table to be closed.
Parameters (4)
owner
VARCHAR(64)
table_name VARCHAR(64)
action
VARCHAR(16)
part_num
INTEGER
action is one of the following strings:
( 'purge' | 'reuse' | 'archive' | 'activate' | 'add'
| 'rebuild')
Example
>call fc_ptadmin_num('admin', 'custmast', 'purge', 12345);
Requires DBA privilege.
www.faircom.com
All Rights Reserved
169
c-treeACE SQL Built-in Stored Procedures
11.26 fc_set_blockinglock( )
Sets the blocking lock strategy for c-treeACE SQL queries. mode = 1 to block; 0 to unblock.
Parameters (1)
mode SMALLINT
Example
call fc_set_blockinglock( 0 );
www.faircom.com
All Rights Reserved
170
c-treeACE SQL Built-in Stored Procedures
11.27 fc_set_debug( )
Sets the debug level of the c-treeACE SQL database engine for advanced diagnostics.
Parameters (1)
dbg_info
VARCHAR(20)
Result Set Fields (1)
DBG_INFO
VARCHAR(20)
Example
To enable Java debugging:
call fc_set_debug('NNNNNNNNNNYN');
DBG_INFO
-------NNNNNNNNNNYN
See Also
 Advanced c-treeACE SQL Logging (page 19)
www.faircom.com
All Rights Reserved
171
c-treeACE SQL Built-in Stored Procedures
11.28 fc_set_file_tran_state( )
Sets the c-treeACE transaction mode for a table.
WARNING: Do not set this value without a complete understanding of c-tree transaction control.
There is great potential for data loss if not properly set.
Parameters (3)
owner
VARCHAR(64)
table_name VARCHAR(64)
mode
TINYINT
Valid modes:
 0 No transaction control.
 1 Transaction control without recoverability. (ctPREIMG)
 2 Transaction control and recoverability. (ctTRNLOG)
Example
call fc_set_file_tran_state( 'admin', 'custmast', 0 );
www.faircom.com
All Rights Reserved
172
c-treeACE SQL Built-in Stored Procedures
11.29 fc_set_impersonation( )
Enables impersonation of a c-treeACE SQL connection. Specify a taskid of zero to disable
impersonation of the connection (default). Specify a taskid of 1 to enable impersonation of the
connection by any other connection. Specify a taskid greater than 1 to enable impersonation of
the connection only by a connection having that specific task ID.
Parameters (1)
taskid
INTEGER
Example
call fc_set_impersonation( 19 )
www.faircom.com
All Rights Reserved
173
c-treeACE SQL Built-in Stored Procedures
11.30 fc_set_min_card( )
Sets the minimum cardinality value used by the c-treeACE SQL database engine.
Parameters (1)
value
INTEGER
Example
call fc_set_min_card( 1000 );
www.faircom.com
All Rights Reserved
174
c-treeACE SQL Built-in Stored Procedures
11.31 fc_set_nodename( )
Sets the NODE name of the connection. The c-tree NODE name identifies a connection with a
string value, that can then be conveniently viewed with monitoring tools.
fc_set_nodename() can be called multiple times within a c-treeACE SQL session to change the
node name. It can also be called with an empty string to clear the NODE name.
Parameters (1)
nodename VARCHAR(31)
Example
call fc_set_nodename('accounting');
www.faircom.com
All Rights Reserved
175
c-treeACE SQL Built-in Stored Procedures
11.32 fc_set_priority( )
Sets the c-treeACE SQL client thread priority.
Note: This feature is supported only on the Windows operating system.
Parameters (1)
priority
INTEGER
priority = -3 to +3.
Example
call fc_set_priority( 0 );
WARNING: Use extreme caution when changing this value. If the priority is set too high relative
to other tasks, c-treeACE SQL may exhibit unpredictable behavior as other threads may not get
enough CPU time by the process scheduler.
www.faircom.com
All Rights Reserved
176
c-treeACE SQL Built-in Stored Procedures
11.33 fc_set_selectivity( )
Set the selectivity off (0) or on (1)
Parameters (1)
value
BIT
Example
call fc_set_selectivity( 1 );
www.faircom.com
All Rights Reserved
177
c-treeACE SQL Built-in Stored Procedures
11.34 fc_set_sysconfig()
Dynamically enables a limited set of system configuration options as defined by the
SetSystemConfigurationOption() API call.
Parameters (2)
option
value
VARCHAR(64)
VARCHAR(64)
option is one of the following:
'checkpoint_monitor'
'ctstatus_mask'
'diagnostics'
'dynamic_dump_defer'
'function_monitor'
'memory_monitor'
'request_time_monitor'
'vss_writer'
Examples
fc_set_sysconfig('vss_writer', 'YES');
fc_set_sysconfig('diagnostics', 'LOWL_FILE_IO');
fc_set_sysconfig('diagnostics', 'REPLICATE');
fc_set_sysconfig('ctstatus_mast', '~DYNAMIC_DUMP_FILES');
Requires DBA privilege.
www.faircom.com
All Rights Reserved
178
12. c-treeACE SQL Reserved Words
Frequently, an application developer chooses a logically apt column name, however, this name
happens to collide with a c-treeACE SQL reserved word. Surrounding identifiers in double quotes
ensures they are properly interpreted as a table name, column name, or other identifier.
Example
CREATE TABLE "version" ("character" VARCHAR(10), "hour" VARCHAR(10));
INSERT INTO "version" VALUES ("Cinderella", "midnight");
SELECT "character", "hour" FROM "version";
To ensure your application is always prepared for future versions of c-treeACE SQL it could be
considered prudent to always quote identifiers, thus avoiding issues with future reserved words.
A complete list of Reserved Words follows.
12.1
c-treeACE SQL Reserved Words
A
a, abs, acos, add, add_months, after, all, alter, an, and, any, array, as, ascii, asin, atan, atan2, avg
B
before, begin, between, bigint, binary, bind, binding, bit, blob, both, by
C
call, cascade, case, cast, ceiling, char, char_length, character, character_length, chartorowid, check,
chr, cleanup, , close, clustered, coalesce, colgroup, collate, column, commit, complex, compress,
concat, connect, constraint, contains, continue, convert, cos, cot, count, create, cross, curdate, current,
current_date, current_user, cursor, curtime, current_time, current_timestamp, cvar
D
database, datapages, date, dateadd, datediff, dayname, dayofmonth, dayofweek, dayofyear, db_name,
dba, dec, decimal, declaration, declare, decode, default, definition, degrees, delete, desc, describe,
descriptor, dhtype, difference, distinct, double, drop
E
each, else, end, escape, exclusive, exec, execute, exists, exit, exp, explain, explicit, extract
F
fetch, field, file, float, floor, for, foreign, found, from, full, function
G
go, goto, grant, greatest, group
H
hash, having, hour
I
identified, identity, ifnull, immediate, in, index, indexpages, indicator, initcap, inner, inout, input, insert,
instr, int, integer, interface, intersect, into, is, isnull
J
join
K
key
L
large, last_day, lcase, least, leading, left, length, like, link, list, localtime, localtimestamp, locate, lock,
log, log10, long, lower, lpad, ltrim, lvarbinary, lvarchar
M
main, max, metadata_only, min, minus, minute, mod, mode, modify, money, month, monthname,
months_between
N
national, natural, nchar, nclob, newrow, next_day, nocompress, not, now, nowait, null, nullif, nullvalue,
number, numeric, nlvarchar, nvl nvarchar
www.faircom.com
All Rights Reserved
179
c-treeACE SQL Reserved Words
O
object, object_id, odbc_convert, odbcinfo, of, oldrow, on, open, option, or, order, out, outer, output
P
pctfree, percent, pi, placing, plan, position, power, precision, prefix, prepare, primary, privileges,
procedure, public
Q
quarter
R
radians, rand, range, raw, real, record, recursive, references, referencing, rename, repeat, replace,
resource, restrict, result, return, returns, revoke, right, rollback, row, rowid, rowidtochar, rownum, rpad,
rtrim
S
schema, searched_case, second, section, select, service, set, session_user, share, short, sign,
simple_case, sin, size, smallint, some, soundex, space, sql, sql_bigint, sql_binary, sql_bit, sql_char,
sql_date, sql_decimal, sql_double, sql_float, sql_integer, sql_longvarbinary, sql_longvarchar,
sql_numeric, sql_real, sql_smallint, sql_time, sql_timestamp, sql_tinyint, sql_tsi_day,
sql_tsi_frac_second, sql_tsi_hour, sql_tsi_minute, sql_tsi_month, sql_tsi_quarter, sql_tsi_second,
sql_tst_week, sql_tsi_year, sql_varbinary, sql_varchar, sqlerror, sqlwarning, sort, start, statement,
statement_id, statistics, storage_attributes, storage_manager, substr, substring, suffix, sum, synonym,
sysdate, systime, systimestamp
T
table, tan, then, ties, time, timeout, timestamp, timestampadd, timestampdiff, tinyint, to, top, to_char,
to_date, to_number, to_time, to_timestamp, tpe, trailing, transaction, translate, trigger, trim, truncate,
type
U
ucase, uid, union, unique, unsigned, update, upper, user, user_id, user_name, using, uuid
V
values, varbinary, varchar, variables, varying, version, view
W
week, when, whenever, where, with, work
Y
year
www.faircom.com
All Rights Reserved
180
13. Index
4
4025 CTDB_INTERNAL ......................................... 67
A
Accessing c-treeACE SQL Files from ISAM
Applications ........................................................ 42
Adding DODAs to Existing Files ............................. 46
Advanced c-treeACE SQL Logging ........................ 19
Advanced Encryption for c-treeACE SQL Tables..... 8
Advanced JVM Configuration ................................. 26
Allow linking SQL indices with rightmost
segment(s) on hidden field(s) ............................. 32
An example field conversion ................................... 50
Automatic Database Conversion Options............... 18
B
Building the callback libraries ................................. 60
Built-in Stored Procedure to Switch Transaction
Mode ................................................................... 14
C
callbacks
ctcbklib.c ............................................................. 60
c-treeDB .............................................................. 52
ctsqlcbk.dll .......................................................... 53
ctsqlcbk.ini .......................................................... 53
ctsqlimp.dll .......................................................... 60
data type conversion........................................... 52
libctsqlcbk.so ...................................................... 53
migration utility .................................................... 68
unsafe c-treeDB functions .................................. 63
Case Insensitive Search Options for c-treeACE
SQL LONG Field Types ...................................... 12
Case-Sensitivity Options ........................................ 16
Check for Invalid Characters in Field Names ......... 33
Check for Max Number of Indices/Segments ......... 32
Combining c-treeACE SQL with ISAM ................... 42
Considerations for ISAM applications..................... 43
conversion
ctsqlcbk.def ......................................................... 60
Copyright Notice ...................................................... iii
ctcbklib.c
callbacks ............................................................. 60
CTDB_INTERNAL .................................................. 67
CTDB_INTERNAL (4025) ....................................... 67
ctpath - Change Internal Database Paths .............. 29
c-treeACE SQL Built-in Stored Procedures .......... 143
c-treeACE SQL Callback Configuration File ........... 55
c-treeACE SQL Callback Dynamic Library ............. 53
c-treeACE SQL Configuration ................................ 71
c-treeACE SQL Configuration Keywords................ 71
c-treeACE SQL Features .......................................... 8
c-treeACE SQL Java Configuration for Stored
Procedures, Triggers and User Defined
Functions ........................................................... 22
c-treeACE SQL Operational Files ............................ 7
c-treeACE SQL Operations and Utilities Guide ....... 1
c-treeACE SQL Options ......................................... 15
c-treeACE SQL Reserved Words ........................ 179
c-treeACE SQL Types SDK ................................... 50
c-treeACE SQL Utilities ......................................... 29
c-treeACE SQL with Callbacks .............................. 52
c-treeDB
data types SDK .................................................. 50
unsafe callback functions ................................... 63
c-treeDB ROWID Options ...................................... 17
c-treeSQL
migration
CTDB_INTERNAL error................................. 67
types................................................................... 50
ctsqlbigint - c-treeACE SQL Big Integer Fix
Utility .................................................................. 29
ctsqlcbk.def
data type conversion .......................................... 60
ctsqlcbk.dll
data type conversion .......................................... 53
ctsqlcbk.ini
callbacks ............................................................ 53
c-treeDB callbacks ............................................. 53
ctsqlcdb - c-treeACE SQL Database
Maintenance Utility............................................. 30
ctsqlimp
data type conversion .......................................... 59
migrating data .................................................... 66
ctsqlimp - c-treeACE SQL Import Utility................. 30
ctsqlimp Import Indices with Segment on String
Field Missing Last Byte ...................................... 34
ctsqlimp Usage ...................................................... 30
ctsqlimp.dll
building ............................................................... 60
callbacks ............................................................ 60
makefile .............................................................. 60
ctsqlmdd - c-treeACE SQL Merge Database
Utility .................................................................. 35
ctsqlutl - c-treeACE SQL Table Maintenance
Utility .................................................................. 35
cttrnmod - Change Transaction Mode Utility ......... 37
Customization ........................................................ 67
D
data types
conversion with c-treeDB ................................... 50
c-treeSQL types SDK......................................... 50
Debugging Java Stored Procedures ...................... 23
Default Date Handling ............................................ 15
Default HUGE File Tables with c-treeACE SQL ...... 9
Defining a Table Using c-treeACE SQL ................ 42
www.faircom.com
All Rights Reserved
181
Index
E
Environment Variables ........................................... 15
errors
CTDB_INTERNAL (4025) ................................... 67
Examining Resulting File Specifications ................. 42
Example Import Utility Callback Makefile ............... 62
Example Server Callback Makefile ......................... 61
F
FairCom Typographical Conventions ....................... ii
fc_add_db( ).......................................................... 144
fc_check_file_tran_state( ) ................................... 145
fc_create_db( )...................................................... 146
fc_create_user( )................................................... 147
fc_get_cachestats() .............................................. 148
fc_get_connstats() ................................................ 149
fc_get_dblist( ) ...................................................... 150
fc_get_fcproclist( ) ................................................ 151
fc_get_filestats() ................................................... 152
fc_get_iostats() ..................................................... 153
fc_get_isamstats() ................................................ 154
fc_get_lockstats().................................................. 155
fc_get_memstats() ................................................ 156
fc_get_min_card( ) ................................................ 157
fc_get_partbounds().............................................. 159
fc_get_priority( ) .................................................... 158
fc_get_replstats() .................................................. 160
fc_get_selectivity( ) ............................................... 161
fc_get_server_version( ) ....................................... 162
fc_get_sqlstats() ................................................... 164
fc_get_sysconfig()................................................. 165
fc_get_taskid( ) ..................................................... 166
fc_get_transtats() .................................................. 167
fc_get_userlist( ) ................................................... 168
fc_ptadmin_num() ................................................. 169
fc_set_blockinglock( ) ........................................... 170
fc_set_debug( ) ..................................................... 171
fc_set_file_tran_state( ) ........................................ 172
fc_set_impersonation( ) ........................................ 173
fc_set_min_card( ) ................................................ 174
fc_set_nodename( ) .............................................. 175
fc_set_priority( ) .................................................... 176
fc_set_selectivity( ) ............................................... 177
fc_set_sysconfig() ................................................. 178
Field Definitions ...................................................... 42
fkverify .................................................................... 40
H
How to specify MYTIME field translation ................ 57
I
Import Duplicate Filenames into c-treeACE SQL ... 34
Import Utility Callback Architecture......................... 60
Import Utility Callback Configuration File................ 60
Important Observations .......................................... 67
Importing Tables Into c-treeACE SQL .................... 59
Index Definition Requirements ............................... 46
indexes
rebuilding
during c-treeSQL migration............................ 67
when migrating data ...................................... 67
Installation ................................................................ 3
K
Key Steps............................................................... 66
L
libctsqlcbk.so
data type conversion .......................................... 53
Logging c-treeACE SQL Query Times................... 13
M
Mapping of c-tree to c-treeACE SQL Types .......... 47
Mapping unsigned integers with c-treeACE SQL .. 32
MAX_SQL_ISOLATION_LEVEL ........................... 72
Memory Manager (MM) System for Temporary
Storage............................................................... 20
migrate.c and migration utility ................................ 67
Migrating to c-treeACE SQL .................................. 65
Migration ................................................................ 66
Migration Callbacks................................................ 68
Migration from c-tree ODBC to c-treeACE SQL
ODBC ................................................................. 65
migration utility
callbacks ............................................................ 68
ctsqlmgr.c ........................................................... 67
migrate.c ............................................................ 67
MigrationInfo structure ....................................... 67
migrfncs.c ........................................................... 67
N
Null Fields and Field Default Values
Considerations ................................................... 33
O
Optimizer Configuration Options............................ 17
Overview of the c-treeACE SQL Migration SDK.... 65
Overview of the c-treeACE SQL Types SDK ......... 50
P
PREIMAGE Tables in c-treeACE SQL .................... 9
Q
Query Timeout Option ........................................... 12
R
rebuilding indexes
migrating data .................................................... 67
Run-Time Settings for Java Stored Procedure
Support............................................................... 22
S
Server-Side Connection Pooling............................ 10
SETENV CLASSPATH .......................................... 82
SETENV DEBUG_JVM ......................................... 83
SETENV DEBUG_JVM_PORT ............................. 84
SETENV DH_CACHED_STATEMENTS ............... 85
www.faircom.com
All Rights Reserved
182
Index
SETENV DH_DO_AHEAD ..................................... 86
SETENV DH_DYN_CACHED_STATEMENTS ...... 87
SETENV DH_ENABLE_POOL .........................88, 90
SETENV DH_JVM_OPTION_STRINGS ................ 89
SETENV DH_OPT_OR_CARD .............................. 91
SETENV DH_POOL_SIZE ..................................... 92
SETENV DH_REBUILD_SEL_CUTOFF ................ 93
SETENV DH_SVR_DA_BUFFER .......................... 95
SETENV DH_THREAD_STACK_SZ_KB ............... 94
SETENV JAVA_COMPILER .................................. 96
SETENV JVM_LIB .................................................. 97
SETENV TPE_DFLT_DATE ................................... 99
SETENV TPE_MM_CACHESIZE......................... 100
SETENV TPE_MM_COMPARE_OVHD............... 101
SETENV TPE_MM_INSERT_OVHD.................... 102
SETENV TPE_MM_SWAPSIZE........................... 103
SETENV TPESQLDBG .......................................... 98
Shared Memory Connections for c-treeACE SQL
Clients on Windows ............................................ 10
Specifying primary keys from imported indexes ..... 32
Specifying the configuration file location ................ 58
SQL_CONNECT_TIMEOUT_SEC ......................... 73
SQL_DATABASE ................................................... 74
SQL_DEBUG ABORT_ON_PANIC ...................... 132
SQL_DEBUG ERROR_INFO ............................... 133
SQL_DEBUG INDEX ............................................ 134
SQL_DEBUG INDEX_DEF_SEL.......................... 136
SQL_DEBUG INDEX_INFO ................................. 137
SQL_DEBUG INDEX_SEL ................................... 135
SQL_DEBUG LOG_STMT_TIMES ...................... 141
SQL_DEBUG LOG_STMT_TIMES_FETCH ........ 142
SQL_DEBUG LOG_STUBS_HIGH ...................... 138
SQL_DEBUG LOG_STUBS_LOW ....................... 140
SQL_DEBUG LOG_STUBS_MED ....................... 139
SQL_DEBUG Options ............................................ 18
SQL_IDLE_WAKE .................................................. 75
SQL_KEEP_OPEN_TABLES ................................. 76
SQL_LOGFILE ....................................................... 77
SQL_MIN_CARD .................................................... 78
SQL_OPTION CHECK_HEAP ............................. 104
SQL_OPTION CREATE_WITH_RECBYT ........... 107
SQL_OPTION CREATE_WITH_ROWID ............. 106
SQL_OPTION CTDB_ROWID ............................. 108
SQL_OPTION CTSTRING_VARCHAR................ 105
SQL_OPTION DB_CASE_INSENSITIVE ............ 109
SQL_OPTION FORCE_TEMPLATE_DB ............. 110
SQL_OPTION HM_ACTIVE ................................. 111
SQL_OPTION LOAD_CALLBACK_LIB................ 112
SQL_OPTION NO_AUTO_ABORT ...................... 113
SQL_OPTION NO_BINARY_PAD ....................... 114
SQL_OPTION NO_CARDINALITY ...................... 115
SQL_OPTION NO_COSTS .................................. 116
SQL_OPTION NO_CRYPT_SYSTBL .................. 117
SQL_OPTION NO_DB_CONVERSION ............... 118
SQL_OPTION NO_DUP_IDXNAME .................... 119
SQL_OPTION NO_HUGEFILE ............................ 120
SQL_OPTION NO_PUSHDOWN ........................ 121
SQL_OPTION NO_REVERSE_INDEX ............... 122
SQL_OPTION NO_SELECTIVITY ...................... 123
SQL_OPTION NO_SHARED_MEMORY ............ 124
SQL_OPTION NO_SYSSUPERFILE .................. 125
SQL_OPTION OWNER_FILE_NAMES .............. 126
SQL_OPTION PAD_WITH_NULL ....................... 127
SQL_OPTION PARTIAL_SEG ............................ 128
SQL_OPTION
PRESERVE_CURSOR_FREE_LOCK ............ 129
SQL_OPTION SUPPRESS_JVM_LOAD_ERR .. 130
SQL_OPTION USE_MM ..................................... 131
SQL_PARTOPEN_COST ...................................... 79
SQL_PORT ............................................................ 80
SQL_TRACE_CTREE_ERROR ............................ 81
sqlverify .................................................................. 40
Support for Importing Table with an Alternative
Name.................................................................. 33
Supported Transaction Isolation Levels ................ 10
T
Table and Index Definitions ................................... 43
Table Definition Requirements .............................. 45
Template Database __Master.dbs Handling ......... 18
The File Definition Generating Utility ..................... 58
The Server Architecture ......................................... 53
U
Unix environment ................................................... 54
Up and Running with the c-treeACE Database
Engine .................................................................. 4
Using Existing ISAM Data with c-treeACE SQL .... 45
W
Which c-treeACE and c-treeDB Functions are
Safe? .................................................................. 63
Windows environment ........................................... 54
www.faircom.com
All Rights Reserved
183