Knowledgebase

Transcription

Knowledgebase

Knowledgebase
Knowledgebase
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 ([email protected]). All rights reserved. This product includes cryptographic
software written by Eric Young ([email protected]). This product includes software written by Tim Hudson
([email protected]).
Portions © 1987-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 Architectural Concepts..................................................................... 1
1.1
1.2
1.3
Server Advantages vs. Multiuser Standalone........................................................ 1
c-treeACE Storage System Support ...................................................................... 3
Positioning the c-treeACE in the System Architecture .......................................... 4
Single c-treeACE Architecture ............................................................................................ 5
Multiple c-treeACE Architecture .......................................................................................... 6
2.
System Requirements ......................................................................................... 9
2.1
2.2
Platform Support ................................................................................................... 9
Minimum Software Requirements for c-treeACE................................................... 9
Using Java 1.7 or Later on Windows ................................................................................ 10
2.3
2.4
2.5
Minimum Hardware Requirements for c-treeACE V10 ........................................ 10
Java Version ........................................................................................................ 11
.NET Framework Requirements .......................................................................... 11
.NET Tools for VS2010 - All projects updated to use .NET Framework v4.0 ................... 11
.NET - Removed STRONGSIGN from assemblies ........................................................... 11
2.6
ADO.NET Entity Framework V2 - V4 Support ..................................................... 12
3.
c-tree OLTP Solutions ....................................................................................... 13
3.1
3.2
3.3
Background ......................................................................................................... 13
Hardware Component Sizing .............................................................................. 13
c-tree Customer Performance Metrics................................................................. 15
4.
Best Practices .................................................................................................... 16
4.1
Selecting c-treeACE Features Used in the System ............................................. 16
Data and Index Caching Options ...................................................................................... 16
Transaction-Controlled Files ............................................................................................. 20
Non-Transaction Files ....................................................................................................... 29
WRITETHRU Files ............................................................................................................ 31
Large File Support............................................................................................................. 33
Memory Files..................................................................................................................... 36
Partitioned Files ................................................................................................................ 38
File Mirroring ..................................................................................................................... 40
Summary of c-treeACE Features ...................................................................................... 41
4.2
4.3
4.4
4.5
4.6
c-tree Files to Include in a Dynamic Dump .......................................................... 42
Automatic Recovery ............................................................................................ 43
Restrict Access to c-treeACE Server Files .......................................................... 44
External Third-Party Utilities ................................................................................ 44
Safely Copying c-treeACE Controlled Files ......................................................... 44
www.faircom.com
All Rights Reserved
iv
c-treeACE Architectural Concepts
4.7
4.8
4.9
4.10
4.11
4.12
4.13
4.14
4.15
File Rebuilds ........................................................................................................ 46
Java Requirements for c-treeACE SQL............................................................... 46
Better Performance with NXTVREC() vs GTVREC() .......................................... 47
8 Tips for a Fast Data Load ................................................................................. 48
Calculating Memory Usage ................................................................................. 49
Controlling Server Memory .................................................................................. 50
Calculating File Storage Space ........................................................................... 51
Calculating Index Sizes ....................................................................................... 51
Migrating Data Between Platforms and Operational Models ............................... 52
Single-User Standalone .................................................................................................... 52
Multi-User Standalone ...................................................................................................... 52
Client/Server ..................................................................................................................... 53
File Migration..................................................................................................................... 53
4.16
Migrating Your Application Between Operational Models ................................... 54
Single-User to Multi-User Standalone or Client/Server .................................................... 55
Multi-user Standalone to Client/Server ............................................................................. 55
Adding Transaction Processing ........................................................................................ 57
Single-threaded to Multi-Threaded ................................................................................... 57
5.
Helpful Examples .............................................................................................. 58
5.1
5.2
5.3
5.4
5.5
c-treeACE SQL - Microsoft SQL Server Integration ............................................ 58
Connect Microsoft 64-bit SQL Server 2005 to c-treeACE SQL ........................... 66
ctKEEPOPEN File Mode to Retain Cached Server Data .................................... 66
Notification Example ............................................................................................ 67
Moving a HP-UX c-treeACE SQL Database to Windows .................................... 68
convert.sh.......................................................................................................................... 68
5.6
5.7
5.8
Keep a CTUSER Library Open............................................................................ 70
Utility To Search Logs For Open Transactions.................................................... 70
c-treeACE OEM Installation Notes - V9 through V11 .......................................... 71
c-treeACE Database Engine ............................................................................................. 71
c-treeACE SQL ADO.NET Data Provider ......................................................................... 74
c-treeACE SQL ODBC Driver ........................................................................................... 76
c-treeACE SQL JDBC Driver ............................................................................................ 77
6.
Configuration and Tuning................................................................................. 78
6.1
6.2
V10 and V11 Configuration Recommendations .................................................. 78
c-treeACE Server Configuration Recommendations ........................................... 80
SKIP_MISSING_FILES ..................................................................................................... 80
KEEP_LOGS..................................................................................................................... 80
FORCE_LOGIDX .............................................................................................................. 80
6.3
Large Page Support to Improve Large Cache Performance ............................... 80
64-bit Windows Filesystem Behavior ................................................................................ 81
www.faircom.com
All Rights Reserved
v
6.4
6.5
6.6
Configuring 32-bit ODBC Drivers on 64-bit Windows Versions ........................... 81
Relocating Transaction Logs ............................................................................... 81
Maximum Number of Indices Per Data File ......................................................... 82
7.
Monitoring Performance ................................................................................... 83
7.1
Monitoring System Resource Usage ................................................................... 83
Monitoring CPU Usage ..................................................................................................... 83
Monitoring Disk Usage ...................................................................................................... 84
Monitoring Memory Usage ................................................................................................ 85
Monitoring Network Usage................................................................................................ 86
Other System Monitoring Options ..................................................................................... 87
7.2
Monitoring c-treeACE Internal Resource Usage ................................................. 87
Monitoring c-treeACE Using Snapshot Support ............................................................... 87
Monitoring c-treeACE Using ctstat Utility .......................................................................... 88
Monitoring c-treeACE Using SystemConfiguration API .................................................... 88
Monitoring c-treeACE Memory Use .................................................................................. 88
Monitoring c-treeACE Lock Table ..................................................................................... 89
Monitoring c-tree Client Activity ........................................................................................ 90
Monitoring c-treeACE Transaction Activity ....................................................................... 92
Monitoring c-treeACE Transaction Numbers and Transaction File Numbers .................. 92
Monitoring c-treeACE File Usage ..................................................................................... 93
Monitoring c-treeACE Dynamic Dumps ............................................................................ 93
Monitoring c-treeACE Automatic Recovery ...................................................................... 94
Monitoring c-treeACE Cache Usage ................................................................................. 94
Monitoring c-treeACE Status Log Messages .................................................................... 94
Monitoring c-treeACE Process State ................................................................................ 95
Monitoring c-treeACE Server with strace .......................................................................... 95
8.
Troubleshooting and Debugging ..................................................................... 99
8.1
Failures During c-treeACE Startup ...................................................................... 99
Server Fails to Start .......................................................................................................... 99
Server Startup Hangs or Takes Excessive Time ............................................................ 103
Java 1.7 uses large amount of virtual memory at startup ............................................... 104
8.2
Failures During c-treeACE Operation ................................................................ 105
Clients Cannot Connect to Server .................................................................................. 105
Clients Lose Connection to Server ................................................................................. 110
Number of Active Transaction Logs Unexpectedly Increases ........................................ 112
Server Is In A Non-Responsive State ............................................................................. 113
Some Clients Are In A Non-Responsive State ............................................................... 114
Errors Occur When Opening c-tree Files ........................................................................ 115
Errors Occur When Reading or Writing c-tree Files ....................................................... 117
c-tree API Call Fails With Unexpected Error ................................................................... 119
Server Writes Unexpected Messages to Status Log ...................................................... 120
Server Exhibits Atypical Performance............................................................................. 120
www.faircom.com
All Rights Reserved
vi
Server Exhibits Unexpected Resource Usage ................................................................ 120
Dynamic Dump Fails ....................................................................................................... 121
Data or Index File Sizes Grow Unexpectedly ................................................................. 121
Server Terminates Abnormally ....................................................................................... 122
8.3
Failures During c-treeACE Shutdown................................................................ 123
Server Shuts Down Improperly ....................................................................................... 124
Server Shutdown Hangs or Takes Excessive Time........................................................ 124
8.4
Failures During System Recovery ..................................................................... 125
Automatic Recovery Fails ............................................................................................... 126
Dynamic Dump Restore Fails ......................................................................................... 128
File Rebuild Fails............................................................................................................. 129
File Compact Fails .......................................................................................................... 129
8.5
LockDump Output ............................................................................................. 130
Types of Locks ................................................................................................................ 132
8.6
8.7
8.8
8.9
8.10
8.11
8.12
8.13
8.14
8.15
8.16
8.17
8.18
8.19
8.25
8.26
How do I clean and reset the transaction numbers for my files? ....................... 133
Pending File ID Overflow: Error 534 in CTSTATUS.FCS .................................. 134
Timeout Error Diagnosis .................................................................................... 135
Heap Debugging on Solaris 9+ Operating Systems .......................................... 136
prstat and Performance Monitoring on Solaris Operating Systems ................... 137
Using Windows Process Explorer to Obtain Thread Call Stacks ...................... 137
Generating Dump Files on 64-bit Windows ....................................................... 138
Transaction Log Increases ................................................................................ 139
Additional Transaction Log Number Messages ................................................. 139
Dynamic Dump Restore FMOD_ERR (48) ........................................................ 140
FUSE_ERR (22) During Automatic Recovery ................................................... 140
Activation Failures (Error 26) on AIX 6 .............................................................. 140
Analyzing ctsemrqs() Calls on AIX systems ...................................................... 140
CPUs Report Different Times on Linux, Causing Unexpectedly Long
sleep() Times ..................................................................................................... 143
Prevent FPUTFGET LNOD_ERR Error (50) from OpenIFile() .......................... 144
Troubleshooting Replication Issues................................................................... 144
gdb Remote Debugging .................................................................................... 145
"ctntio error" Entries in Status Log File CTSTATUS.FCS .................................. 146
"WARNING: ct_lflsema livelock" Entries in Status Log File
CTSTATUS.FCS ............................................................................................... 147
Disappearing c-treeACE Core Files on Linux .................................................... 148
c-treeACE Memory Use and glibc malloc per-thread Arenas ............................ 149
9.
c-treeACE SQL Troubleshooting ................................................................... 151
9.1
Java Configuration for c-treeACE SQL Stored Procedures, Triggers and
User Defined Functions ..................................................................................... 151
Setting/Enabling Advanced Features in SQL Explorer ...................................... 151
8.20
8.21
8.22
8.23
8.24
9.2
www.faircom.com
All Rights Reserved
vii
9.3
9.4
9.5
9.6
9.7
9.8
9.9
9.14
SRLSEG not Available in c-treeACE SQL When ROWID is Used .................... 152
What are .fdk Files in the SQL_SYS Directory? ................................................ 152
What is __Master.dbs? ...................................................................................... 153
Error While Creating SQL Database ................................................................. 153
DBLOAD Debugging Help ................................................................................. 154
Debugging Java Stored Procedures.................................................................. 154
Stored Procedure Error: Could not initialize class
sun.util.calendar.ZoneInfoFile ........................................................................... 157
Stored Procedure Java Class Resolution .......................................................... 157
When do I have to specify the owner of a table?............................................... 158
How do I convert tables in a database to be case insensitive? ......................... 159
Analyzing JVM Memory usage with c-treeACE SQL Java Stored
Procedures ........................................................................................................ 159
Compiling c-treeACE SQL PHP on Linux/Unix.................................................. 162
10.
COBOL Help ..................................................................................................... 163
10.1
10.2
10.3
COBOL Compilers Supported by c-treeRTG COBOL Edition ........................... 163
Troubleshooting Data Conversion Errors .......................................................... 164
Error: Requested def blk is empty ..................................................................... 165
9.10
9.11
9.12
9.13
Appendix A.
c-treeRTG Errors................................................................................. 167
11.
Reference Material .......................................................................................... 168
11.1
mtmake Command Line .................................................................................... 168
mtmake Advanced Options ............................................................................................. 168
11.2
11.3
11.4
11.5
11.6
Typical Unix Errors From errno.h Header File ................................................... 169
c-treeACE Server Files ...................................................................................... 173
c-treeACE Utilities ............................................................................................. 174
NULL Handling .................................................................................................. 176
ISAM Parameter Files (Legacy) ........................................................................ 176
ISAM Parameter File Organization ................................................................................. 176
Parameter File Contents ................................................................................................. 177
Fixed-Length Parameter File Examples.......................................................................... 180
Variable-Length Parameter File Example ....................................................................... 181
Multiple Data File Parameter Setup ................................................................................ 182
Parameter Files in Client Server Models ........................................................................ 183
11.7
11.8
11.9
Prototyping ........................................................................................................ 183
2xx Internal Error Codes ................................................................................... 183
Internal 749X Error Codes ................................................................................. 185
12.
Operating System Specific ............................................................................. 186
12.1
Microsoft Windows ............................................................................................ 186
Installation Error Due to XML Encoding .......................................................................... 186
www.faircom.com
All Rights Reserved
viii
Windows Vista Network AutoTuning Parameters ........................................................... 186
Configuring 32-bit ODBC Drivers on 64-bit Windows Versions ...................................... 187
Connect Microsoft 64-bit SQL Server 2005 to c-treeACE SQL ...................................... 187
Slow Windows Network Traffic ....................................................................................... 188
12.2
Linux .................................................................................................................. 189
CPUs Report Different Times on Linux, Causing Unexpectedly Long sleep()
Times ........................................................................................................................ 189
Compiling c-treeACE SQL PHP on Linux/Unix ............................................................... 190
Memory Use of Linux Processes .................................................................................... 190
12.3
Solaris ............................................................................................................... 193
Heap Debugging on Solaris 9+ Operating Systems ....................................................... 193
12.4
AIX ..................................................................................................................... 193
IBM AIX Multicore/CPU Performance Tuning Options ................................................... 193
IBM AIX Large Page Support.......................................................................................... 194
IBM AIX Mutex Performance Tuning Options ................................................................. 194
Analyzing ctsemrqs() Calls on AIX systems ................................................................... 195
Activation Failures (Error 26) on AIX 6 ........................................................................... 198
12.5
HP-UX ............................................................................................................... 198
Moving a HP-UX c-treeACE SQL Database to Windows ............................................... 198
13.
Function Name Cross Reference ................................................................... 201
13.1
13.2
13.3
Full Names ........................................................................................................ 201
Abbreviated (short) Names ............................................................................... 209
Function API Listing .......................................................................................... 217
Initialization API............................................................................................................... 217
Data Definition API .......................................................................................................... 218
Data Manipulation API .................................................................................................... 219
Utility Functions ............................................................................................................... 221
14.
Common Entry Point Functions..................................................................... 223
14.1
14.2
Forced Single Entry Point Capability ................................................................. 223
Extended Feature Parameter Blocks ................................................................ 223
Logon Block .................................................................................................................... 224
ISAM Block...................................................................................................................... 224
IFIL Block ........................................................................................................................ 224
Create File Block ............................................................................................................. 225
Open File Block ............................................................................................................... 225
Key Estimate Block ......................................................................................................... 225
14.3
Function Calls .................................................................................................... 226
15.
Important Technical Updates ......................................................................... 232
15.1
Highly Concurrent c-treeACE SQL Updates Involving Floating Point
Conversions ...................................................................................................... 232
Prevent FPUTFGET Data Corruption with Concurrent Updates ....................... 233
15.2
www.faircom.com
All Rights Reserved
ix
15.3
15.7
15.8
15.9
Potential Variable Length Data Corruption Prevented During Automatic
Recovery ........................................................................................................... 233
Prevent Termination of c-treeACE from LRU Cache Miss Limitations .............. 234
Potential c-tree Server Automatic Recovery Failures with the LOGIDX
Feature .............................................................................................................. 235
Avoid Index Errors Caused by memcpy() Implementation on Latest
Operating Systems ............................................................................................ 236
Correct Handling of Segmented Files During Automatic Recovery ................... 236
Microsoft Vista Locks Out FPUTFGET .............................................................. 237
Transaction Number Rollover ............................................................................ 238
16.
Upgrading from Previous Editions ................................................................ 239
16.1
Steps to Upgrade c-treeACE Server ................................................................. 239
15.4
15.5
15.6
Upgrade Notes for Developers ....................................................................................... 240
Upgrade Notes for Administrators................................................................................... 242
More about Upgrading c-treeACE................................................................................... 243
Let Your Existing ISAM Applications Co-Exist With c-treeSQL ...................................... 244
16.2
Upgrading V6 Applications ................................................................................ 263
Duplicate Keys ................................................................................................................ 263
#defines ........................................................................................................................... 264
16.3
Converting c-tree V4.1F-V4.3C Applications ..................................................... 264
Application Conversion Details ....................................................................................... 265
16.4
Backward Compatibility ..................................................................................... 268
17.
Index ................................................................................................................. 269
www.faircom.com
All Rights Reserved
x
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
1.
1.1
Server Advantages vs. Multiuser Standalone
Applications that rely on the c-tree “standalone” architecture use file and data management
operations to directly manipulate groups of files and information in those files. The focus is on
controlling files, and data, directly from an application. In a multi-user environment, as users and
needs grow, the simple data access afforded by the multi-user standalone architecture
(sometimes referred to as “FPUTFGET”) become cumbersome, unstable, or impossible to
implement and maintain in a practical manner due to the fact that files and user applications
reside on physically separate systems. The data integrity of the application is largely dependent
on the file locking provided by the operating system -- complexities that are amplified when client
machines are not on the exact same version and patch level.
The client/server architecture divides a logical application into a front-end client and a back-end
database server. The client interacts with the application user to determine specific needs and
only sends relevant requests to the server asking that the needed service be performed. The
server accepts this request, performs the needed service, and relays the results back to the
client. The client can then present the information to the user through whatever interface is
appropriate. The server acts as a central traffic cop and can support many clients simultaneously.
In addition, clients may even be different applications for a truly robust application suite.
The key advantage becomes a division of labor between the client application and the centralized
database server. Clients focus solely on the tasks they're intended to carry out for the user, while
the server is solely dedicated to the most efficient data handling possible. This also eliminates the
duplication of valuable resources such as memory and disk space that exists when these data
management capabilities are incorporated into each application.
The most visible advantage, however, is pure performance. The complex issues of multiple users
storing and retrieving data can be isolated within a single server process. As users increase in a
strictly file-based environment, contention for those file resources quickly adds up. The server can
consolidate those resources and take advantage of in-memory caching of data and indexes for
scalability up to hundreds and even thousands of concurrent client connections. This is simply not
possible with the standalone multi-user model.
www.faircom.com
All Rights Reserved
1
Client/server and multi-tier computing have become the models of choice in database systems for
the most basic of reasons: increased speed, control, and efficiency in data management.
c-treeACE brings these benefits over traditional standalone models:
 Performance: In memory data and index caches mean data is immediately available to
clients without expensive disk I/O. Standalone multi-user applications must flush every read
and write operation to disk.
 Scalability: Scale from a few users to many users with a simple activation key. The
multi-threaded server engine provides enhanced concurrency control and allows many more
concurrent users to efficiently operate than is possible in a standalone multi-user
environment.
 Security: Centralized data management provided by the server makes available many
additional security features that are not practical in a standalone environment, such as user
and file passwords; user, group, and file permissions; file and communication encryption; and
logon control options. With only one process requiring access to data and index files, OS file
permissions can be applied to restrict access to these files from casual users providing
another layer of security. This is critically beneficial in health and financial industries in
meeting HIPPA and other compliance measures.
 Data Integrity: Transaction processing makes available a multitude of advanced features not
possible in multi-user standalone applications. Automatic-recovery with roll-forward/rollback
control, dynamic "hot" backups, and a unique transaction history feature for elevated security
tracking of changes are among these. Heavily used indices are automatically maintained for
optimal speed and size, eliminating the need for rebuilding for performance.
 Flexibility: Heterogeneous support means Unix/Windows/Mac clients can share data across
any combination of client/server platforms. Connect any client to any Server.
 SQL: c-treeACE SQL provides complete relational capabilities and is only available as an
integral component of server-based models. SQL extends access to data through a variety of
popular programming interfaces including ODBC, JDBC, ADO.NET, and PHP. These industry
standard protocols allow data integration among multiple systems in the enterprise
www.faircom.com
All Rights Reserved
2
environment, vastly enhancing the availability of information through multiple channels
including the web. Server-side stored procedures and triggers enforce business integrity rules
on data and access for the ultimate in data integrity and security.
1.2
c-treeACE Storage System Support
Background
Database systems are by nature designed to store and maintain data in a durable manner. This
requires a storage medium, typically a hard disk drive. More data required more storage and as a
result, storage has become cheaper and vastly more scalable. Other important considerations of
a storage architecture are ease of backup, partitioning, and mirroring of data. As storage systems
continue to emerge and diversify, FairCom is frequently asked about support for various storage
architectures. The following information is provided to address these most common inquiries.
Database Caching
The c-treeACE database engine provides in-memory caching of updated data and index
information for performance. This data is periodically flushed to disk with standard IO filesystem
calls.
Filesystem Semantics
Depending on the nature of the data, such as the case with an index node page or a transaction
log buffer, these may be requested to go directly to disk to guarantee absolute data integrity. To
provide these integrity guarantees, it is important the data storage system provides adequate
capability. The database engine must know that a write request returned successfully to ensure
the data is secured to the storage medium. Not only must the write request succeed, the ordering
of the requests must be respected. This may not be the case with all storage architectures.
Two major categories of shared storage are described below.
Storage Array Networks (SAN)
SAN devices are a proven and powerful data storage technology that can offer impressive
performance characteristics. SAN devices share the raw physical storage device. For large
organizations requiring sophisticated data storage and fast response times, a SAN architecture is
often the recommended approach. In general, SAN technologies satisfy the ordering of writes and
guarantees data integrity once a write request returns, even if the SAN device itself provides
internal buffering of data for enhanced performance. The most secure SAN devices provide
battery backup of their internal caches for the utmost of protection.
c-treeACE is successfully deployed in many SAN environments. While relatively expensive
compared to local storage, FairCom recommends and supports SAN storage architectures for
large capacity solutions in high throughput systems.
Remote File Systems
Remote filesystems typically share a filesystem. Contrast this to SAN devices which share the
physical storage medium. Several varieties of remote filesystems are typically encountered:
 Network Attached Storage (NAS)
www.faircom.com
All Rights Reserved
3
NAS systems are shared filesystems attached to a client via a standard network connection,
usually TCP/IP.
 Network Filesystems (NFS)
NFS systems are hierarchically organized filesystems most often found in Unix environments.
There are many standard and proprietary implementations, usually available to the system as
a remote network mount in the filesystem table. The most notable concept of which is the
stateless client.
 Windows Network Shares
Microsoft Windows provides a file sharing protocol (SMB, and beginning with Windows Vista,
SMB2) that allows users to easily share folders and files between workstations.
While remote file systems are relatively much cheaper than their SAN cousins, in general, they do
not provide an adequate level of IO capability for database integrity as they do not fully support
the filesystem semantics required. That is, there is no guarantee that a write request has
succeeded in most cases and the ordering of IO operations is not respected to guarantee data
protection for a database. In addition, there is often a significant network IO latency for these
storage systems that can severely impact performance.
NFS systems also implement file locking mechanisms which are not compatible with performance
sensitive distributed lock management.
With these considerations in mind, FairCom does not recommend nor support remote filesystems
for c-treeACE database storage.
1.3
Positioning the c-treeACE in the System Architecture
When designing a system, the system architect determines the appropriate positioning of
c-treeACE in the system architecture based upon system requirements. In some cases simplicity
is the primary requirement. In other cases, scalability and fault tolerance are the primary
requirements. This section discusses two options for integrating c-treeACE into a system
architecture: a single c-treeACE architectural model and the multiple c-treeACE architectural
model.
www.faircom.com
All Rights Reserved
4
Single c-treeACE Architecture
The single c-tree Server architectural model is the simpler of the two models. In this model, one
c-tree Server serves all clients. The advantage of this model is its simplicity. Because this model
involves only one c-tree Server, there is no application routing logic and no synchronization of
data among multiple servers. The application simply connects to the server and accesses the
data.
Figure 1: Single c-tree Server Architecture
www.faircom.com
All Rights Reserved
5
The tradeoff for the simplicity of this approach is that the client load and scalability of the
database system is limited to the capacity of the machine on which the c-tree Server runs. This
choice of system architecture limits the ability of the system to scale to meet increased capacity
requirements over time. Also, the availability of the system is determined by the availability of the
single c-tree Server process and the machine on which it runs. If a software or hardware
component failure renders the c-tree Server process or its data inaccessible, the availability of the
system is directly affected.
Figure 2: Effect of Unavailable Server in Single c-tree Server Architecture
Multiple c-treeACE Architecture
Given the scalability and fault tolerance implications of a single c-tree Server model, many
enterprise-level systems choose to implement a multiple c-treeACE architectural model. In this
model, multiple c-treeACE servers serve clients, and the architecture frequently includes load
balancing and data synchronization components.
Load balancing components route incoming requests to c-treeACE in such a way as to spread
the load evenly among the servers. The use of load balancing enables efficient use of multiple
systems, enhancing scalability of the system.
www.faircom.com
All Rights Reserved
6
In a system with more than one c-treeACE server, each server manages its own data set. The
system architect decides how to partition data sets among c-treeACE. For example, the design
could specify that each server maintains a full copy of the data set, or that each server maintains
a subset of the data set. Data synchronization components apply changes made to one data set
to other data sets as required by the system.
Figure 3: Multiple c-tree Server Architecture
www.faircom.com
All Rights Reserved
7
In the event of a failure in one portion of the system, client access is automatically rerouted
ensuring continuous operations.
Figure 4: Effect of Unavailable Server in Multiple c-tree Server Architecture
www.faircom.com
All Rights Reserved
8
2.
System Requirements
This section summarizes the hardware and software required for running c-treeACE server. If you
have special requirements that are not addressed here, such as embedded systems or multiple
servers, please contact FairCom for assistance.
2.1
Platform Support
Supported platforms include:
Platform
Version
Windows
Windows Vista through Windows 8
Windows Compiler
HP Unix (HP-UX)
HP-UX v11.x (HP-UX v10.x remains
supported as a legacy operating
system)
IBM Unix (AIX)
AIX Unix V Rel 5.3 (and earlier releases
back to AIX Unix V Rel 4.2)
Solaris
Solaris 10 (includes support for 9 and
earlier)
QNX
latest
SCO
2.2
VC 6, Visual Studio 2003 through 2012
Borland Builder v5.x, v7.x (CodeGear
C++ Builder 2006/2007)
SCO OpenServer versions 5 and 6.
Linux
Linux Kernel 2.4, 2.6 or later (and
legacy support for some earlier
releases)
FreeBSD
latest
Apple
Mac OS X 10.8 (Mountain Lion), Mac
OS X 10.5 (Leopard), Mac OS X 10.4
(Tiger), Mac OS X 10.3 (Panther), Mac
OS X 10.2, and earlier
Minimum Software Requirements for c-treeACE
c-treeACE V10.4 and later require the following:
 Windows XP/2003 or newer
www.faircom.com
All Rights Reserved
9
System Requirements
 Microsoft .NET Framework 4 or newer.
 For the c-treeACE SQL JDBC Driver: To develop using JDBC, you will need JDK 1.6 or
newer and the c-treeACE SQL Server.
 Stored procedures for the c-treeACE SQL Server:
• To develop a Java stored procedure, you will need JDK 1.6 or newer.
• To execute a Java stored procedure, you will need JRE 1.6 or newer.
Using Java 1.7 or Later on Windows
To use stored procedures, triggers and user-defined functions on Windows with Java 1.7 or later,
you will need the MSVCR100.DLL, which is required by the Java Virtual Machine (jvm.dll).
Because the Java installer does not provide the required DLL, the Visual C++ 2010
Redistributable package must be installed to get it.
Notice that 32-bit Java SDK installations require the 32-bit redistributable and 64-bit Java SDK
installations require the 64-bit redistributable. To download:
32-bit redistributable - http://www.microsoft.com/en-us/download/details.aspx?id=5555
(http://www.microsoft.com/en-us/download/details.aspx?id=5555)
64-bit redistributable - http://www.microsoft.com/download/en/details.aspx?id=14632
(http://www.microsoft.com/download/en/details.aspx?id=14632)
2.3
Minimum Hardware Requirements for c-treeACE V10
c-treeACE SQL Server (SQL Version)
The minimum CPU and memory requirements for operating the SQL version of the c-treeACE
SQL Server for Windows are:
 Pentium 1 GHz CPU
 512 MB RAM
 500 MB Disk space + space for your data + index files (assuming default 120MB transaction
LOG_SPACE setting in ctsrvr.cfg)
c-treeACE Server (ISAM Version)
The minimum CPU and memory requirements for operating the ISAM version of the c-treeACE
Server for Windows are:
 Pentium 300 MHz CPU
 300 MB RAM
 250 MB Disk space + space for your data + index files (assuming default 120MB transaction
LOG_SPACE setting in ctsrvr.cfg)
Note: Additional memory will be needed for additional users beyond 16 concurrent users and
larger data and index caches. 1+ GB of RAM is recommended for c-treeACE SQL Server.
Cache sizes larger than 2GB require a 64-bit version of the OS and c-treeACE.
www.faircom.com
All Rights Reserved
10
System Requirements
2.4
Java Version
c-treeACE SQL V10 and V11 require the Java 1.6 JDK and JRE environment for Stored
Procedures, Triggers, and User Defined Scalar Functions (UDFs), JDBC, and c-treeDB Java.
Java is readily available from the Oracle Java downloads
(http://www.oracle.com/technetwork/java/javase/downloads/index.html) website. c-treeACE
supports Java on any platform that the Java environment is currently available, including
Windows, AIX, Oracle Sun, and Linux.
Note that Oracle has announced an end of life
(http://www.oracle.com/technetwork/java/javase/eol-135779.html) policy for Java 1.6 beginning
February 2013. Check the FairCom http://www.faircom.com/ web site for the latest Java
compatibility announcements and availability of the latest Java support.
2.5
.NET Framework Requirements
c-treeACE V10 requires at least Framework Version 3.5 SP1 complete (e.g., the complete
version, not just the "client" version).
c-treeACE V10.4 and later requires Microsoft .NET 4.0 Framework.
.NET Tools for VS2010 - All projects updated to use .NET Framework v4.0
All the .NET projects for VS2010 have been updated to use the v4.0 .NET framework. If you
target the .NET v3.5 framework, it uses the VS2008 compiler 'tool chain' which can result in an
internal compiler error in VS2010. The target framework was changed to v4.0 in the *_v10.sln
files to eliminate that error.
See Also
 http://support.microsoft.com/kb/976656
 http://connect.microsoft.com/VisualStudio/feedback/details/644532/internal-compiler-error-c1
001-using-c-cli-on-vs2010
.NET - Removed STRONGSIGN from assemblies
To be more compliant with standard practice for C# programmers, STRONGSIGN has been
removed from .NET assemblies. We no longer force the assembly to be signed with the FairCom
key. This allows developers to sign with their own key, which they can keep secret.
www.faircom.com
All Rights Reserved
11
System Requirements
2.6
ADO.NET Entity Framework V2 - V4 Support
The c-treeACE SQL ADO.NET Data Provider has support for Entity Framework V2 through V4
(for EF6, see Entity Framework 6 Support in the c-treeACE SQL ADO.NET Data Provider
http://docs.faircom.com/doc/ado_net/ manual). When Visual Studio 2008 or later is detected
during c-treeACE Professional installation, support is integrated by default.
System Requirements
The minimum development system requirements for c-treeACE SQL ADO.NET Entity Framework
support are:
1. Visual Studio 2008 Service Pack 1
2. Microsoft .NET Framework 3.5 Service Pack 1
Auto Incrementing Field Type Restriction
Entity Framework Models allow Int16, Int32 or Int64 field types to be specified as Auto
Incrementing in model design. Auto Incrementing fields are also known as Identity fields in some
schemas.
c-treeACE SQL now allows one user Auto Incrementing field type. Note that c-treeACE already
supported a serial segment field, currently used by default as the ROWID value. As there is a
limitation of one SRLSEG field type per data file (table), this precluded the addition of a
user-defined field. An IDENTITY attribute is now available for this purpose.
Other Known Limitations
The following are other known c-treeACE SQL limitations that can be encountered when using
Entity Framework support. These are in various stages of development. Contact your nearest
FairCom office for the latest information concerning specific support for these items.
 The SKIP operator is not currently supported. The SKIP operator is commonly used with the
TOP operator for “paging” purposes.
 The EXCEPT operator is not currently supported.
 Parameters are not currently supported in functions and in the TOP operator.
 BIT (Boolean) columns can currently only be tested against 1 or 0 (that is, if ( bitColumn ==
1 ). Entity Framework requires a test against true/false (for example, if ( bitColumn == true )
or more simply if ( bitColumn )
www.faircom.com
All Rights Reserved
12
3.
c-tree OLTP Solutions
This document provides guidance in selecting optimal hardware for a high-speed transaction
processing environment utilizing the c-treeACE Server and c-treeACE SQL Server, FairCom's
high performance database technology. Performance metrics from real-world implementations
are also presented to demonstrate the transaction processing power available from FairCom
c-tree database engine technology.
3.1
Background
The c-tree database engine has been designed from the ground up to provide the fastest possible
database insert and retrieval operations. For the greatest performance, FairCom empowers
advanced application developers an ability to precisely control their database operations. Some
of the features incorporated into FairCom technology that allow this level of control include:
 A finely tuned re-entrant threaded database kernel
 Tunable database and index caches
 Programmable control over the transaction processing engine
 High speed index operations
 Flexible APIs
These features function together to make c-tree one of the most powerful and flexible database
engines available for high volume online transaction processing (OLTP) systems such as those
found in the financial and telecommunications sectors.
3.2
Hardware Component Sizing
Database performance is dictated by a number of factors including:
 Architecture of the application
 Composition of the data
 Hardware underlying the system
Because there are multiple factors involved, there is no single answer to the question of what
hardware will yield the fastest application performance. However, the usual best practices for
optimizing data intensive applications mostly apply to tuning a c-tree Server hardware
environment. The primary computer hardware subsystems to be cognizant of when selecting
hardware for a high speed c-tree database installation are:
 Disk I/O subsystem
 Network infrastructure
 System memory
www.faircom.com
All Rights Reserved
13
 Number of CPU's
 CPU clock speed
Because the c-tree Server is a very efficient database engine, the baseline hardware
requirements are minimal - far lower than with most enterprise-level database technology. Yet as
more resources are available, the c-tree Server can be configured to use those resources,
making it very scalable.
The best mechanism for properly sizing a system is to perform a real-world test simulating peak
numbers of concurrent users, record sizes and data flow. Then, using operating system tools and
tools provided with c-tree (e.g., Snapshot and server administration utilities), one can observe
where the performance bottlenecks are occurring. Determinations can then be made as to
whether adjustments to the hardware configuration or c-tree Server configuration are warranted.
FairCom has extensive experience in this regard, and our technicians may be able to engage with
the application development team to help identify and overcome bottlenecks.
Absent the ability to perform such a real-world simulation, most transaction-laden applications
tend to be I/O bound, usually within the disk subsystem. Therefore FairCom customers tend to
focus their hardware budgets on first optimizing the disk subsystem. Items such as large memory
caches on the I/O controller, fiber optic backplanes, high RPM drives, etc. tend to be wise
investments. Additionally, storing the c-tree Server transaction logs on a different hard drive
spindle than the data and index files can also provide a data throughput improvement.
The network infrastructure is also performance sensitive and the network should be sized to
support the peak data throughput requirements without developing any latency.
The c-tree Server memory requirements can be reasonably approximated with the following
equation:
Base line Memory =
Server EXE size + 1 MB +
Communications Library size (if applicable) +
Data cache (DAT_MEMORY) +
Index buffer (IDX_MEMORY) +
(900 bytes * Number of files (FILES)) +
(325 bytes * Maximum number of connections (CONNECTIONS)) +
(4 bytes * Maximum number of connections (CONNECTIONS)
* Maximum number of connections (CONNECTIONS)) +
(16000 bytes * Number of actual connections) +
(256 bytes per connection per file actually opened))
The c-tree Server is able to utilize very large data and index caches (tens to hundreds of
gigabytes each). In addition, the cache subsystem is very granular so the system can be
precisely tuned to optimize the data throughput. For example, one can elect to cache an entire
file, cache a percentage of a file, exclude specific files from the cache, etc.
The c-tree Server is able to automatically scale across multi-CPU systems. Although the CPU
requirements for the c-tree Server are a fraction of other database engines, multiple CPU's can
provide performance benefits. Furthermore, many systems are architected such that the c-tree
Server is run on the same machine as the core components of the application in order to
minimize network traffic.
www.faircom.com
All Rights Reserved
14
3.3
c-tree Customer Performance Metrics
FairCom's c-tree database technology is a popular choice for any marketplace that deals with a
large volume of data and requires real-time data access. Two such markets are the Financial and
Telecommunication markets. In these markets, FairCom technology has been implemented in
applications such as:
 High speed data repositories for stock markets the world over
 Back-end processing of market analysis data by investment companies
 Enterprise level data switches for credit card companies
 High speed phone number lookup and phone usage information for telecom companies
 Fraud detection analysis
Typical hardware configurations in these markets are mid-range enterprise boxes from
manufactures such as Sun Microsystems, IBM, Hewlett Packard and Stratus. Machines typically
have from 4 to as many as 48 CPUs, many gigabytes of RAM, and state of the art disk array
subsystems from manufacturers such as EMC and HP. The disk subsystems are typically NAS or
SAN devices connected to the network via fiber channel and utilize the latest in disk array
stripping technology to provide the appropriate blend of redundancy and performance.
FairCom metrics that we see in these markets across an entire system (which may include
multiple c-tree Servers) are:
# of Files
File Sizes
Total Data
Storage
400-30,000 files
per application
100+ GB per
single data file
4.3 TB-10 TB
Data Volume/Day
Transaction/Day
Transaction/Seco
nd
20GB - 1,000 GB
per day
25 million - 300
million per day
400 - 100,000
For example, one high-end financial application was tested on a Stratus 5700 machine, running
Red Hat Linux with 4 Dual Core Xeon 2.8GHz processors, on an internal ATA disk drive with a
single c-tree Server operating at a sustained rate of 20,000 transactions per second.
www.faircom.com
All Rights Reserved
15
4.
Best Practices
4.1
Selecting c-treeACE Features Used in the System
c-treeACE supports many options that affect the availability of the server’s data over time and the
state of the data in the event of a catastrophic failure. Many of the features discussed in this
section can be configured on a file-by-file basis. The system architects and application designers
can determine the appropriate features to use for each data and index file based on the role the
files play in the system and by understanding the effect of these features on availability and
recovery of the data.
Data and Index Caching Options
Figure 5: c-tree Server Caching Options
The c-tree Server maintains data and index caches in which it stores the most recently used data
images and index nodes. The caches provide high-speed memory access to data record images
and index nodes, reducing demand for slower disk I/O on data and index files. The server writes
data and index updates first to cache and eventually to disk. Data and index reads are satisfied
from the server’s cache if a cache page contains the requested data record image or index node.
When necessary, the server writes pages to disk using a least recently used (LRU) scheme. The
server also supports background flushing of cache buffers during system idle times.
The size of the data and index caches are determined by server configuration file settings. It is
also possible to disable caching of specific data files and to dedicate a portion of the data cache
to specific data files.
www.faircom.com
All Rights Reserved
16
Best Practices
Caching of Data Records
The c-tree data cache uses the following approach to cache data record images: if the data
record fits entirely within one or two cache pages, then the entire record is stored in the cache.
Note: Even a record smaller than a single cache page may require two cache pages as the
record position is generally not aligned on a cache page boundary.
If the data record image covers more than two cache pages, then the first and last segments of
the record are stored in the cache, but the middle portion is read from or written to the disk. This
direct I/O is generally efficient as the reads are aligned and are for a multiple of the cache page
size.
The nature of this approach can be modified. If the server keyword MPAGE_CACHE is set to a
value greater than zero, say N, then records that fall within N+2 cache pages will be stored
entirely within the cache. The default value is zero. This causes the cache to behave as
described above.
Note: Setting MPAGE_CACHE greater than zero does NOT ensure faster system operation. It is
more likely to be slower than faster. It does cause more of a record to be in cache, but there is
increased overhead managing each individual cache page. The cache pages for consecutive
segments of a record (where a segment fills a cache page) are completely independent of each
other. They are not stored in consecutive memory. And I/O is performed separately for each
cache page. This configuration option should only be used for special circumstances with careful,
realistic testing.
Caching of Index Nodes
Figure 6: Data Length to Page Size
www.faircom.com
All Rights Reserved
17
Best Practices
To understand the c-tree Server’s caching of index nodes, it is necessary to review the
relationship between the server’s PAGE_SIZE setting, the size of index cache pages, and the
size of index nodes.
The server’s PAGE_SIZE setting determines the size of index cache pages and the size of index
nodes for index files created by the server. Because the server must be able to fit an index node
into a single index cache page, the server’s PAGE_SIZE setting determines the maximum size of
index nodes supported by the server. The server can access index files that were created with an
index node size less than or equal to the server’s PAGE_SIZE setting, but attempting to open an
index whose index node size exceeds the server’s PAGE_SIZE fails with error KSIZ_ERR (40,
index node size too large).
Properties of Cached Files
Although caching data benefits server performance, it is important to be aware of the effect of
caching data on the recoverability of updates. The state of a cached file after an abnormal server
termination depends on the c-tree options in effect for that file. Below is a summary of the effect
of caching on each file type. The following sections discuss this topic in detail.
 TRNLOG files: Caching does not affect recoverability. The server’s transaction processing
logic ensures that all committed transactions are recovered in the event of an abnormal
server termination.
 PREIMG or non-transaction files: Caching can lead to loss of unwritten cached data in the
event of an abnormal server termination. For these file types, the server does not guarantee
a persistent version of the unwritten updated cache images exists on disk, so any unwritten
cached data is lost in the event of an abnormal server termination.
 WRITETHRU (applies to PREIMG and non-transaction files): To minimize loss of cached
data, the WRITETHRU attribute can be applied to a PREIMG or non-transaction file.
WRITETHRU causes writes to be written through the server’s cache to the file system (for
low-level updates) or flushed to disk (for ISAM updates).
Configuring Caching
The memory allocated to the data and index caches is set in the c-treeACE configuration file,
ctsrvr.cfg, using the DAT_MEMORY and IDX_MEMORY options. For example, to allocate 1 GB data
cache and 1 GB index cache, specify these settings in ctsrvr.cfg:
DAT_MEMORY 1 GB
IDX_MEMORY 1 GB
The server allocates this memory at startup and partitions it into cache pages. The server’s
PAGE_SIZE setting determines the size of the data and index cache pages.
The c-treeACE Server’s data and index cache configuration options support specifying a scaling
factor used when interpreting cache memory sizes. The supported scaling factors are:
 KB: interpret the specified value as a number of kilobytes.
 MB: interpret the specified value as a number of megabytes.
 GB: interpret the specified value as a number of gigabytes.
You are always free to specify the exact numerical value as well. The following web page lists
those keywords that accept the scaling factors and their limits:
www.faircom.com
All Rights Reserved
18
Best Practices
Scaling Factors for Configuration Keyword Values
http://docs.faircom.com/doc/ctserver/48623.htm
Per File Cache Options
In some cases it may be advantageous to turn off data file caching, especially for files with very
long variable length records. Configuration entries of the form:
NO_CACHE <data file name>
result in caching for the specified data files to be disabled. Note that <data file name> may
specify a wildcard pattern. You can specify multiple entries for more than one file.
Cache memory can be dedicated to specific data files using the following server configuration
option:
SPECIAL_CACHE_FILE <data file name>#<bytes dedicated>
This option is useful for files that you wish to always remain in memory. For example, when
occasionally reading other large files, this avoids required files being pushed out of cache.
For even more control, you can also specify percentage of total cache to be reserved for the
specially cached files.
SPECIAL_CACHE_PERCENT <percentage>
This option specifies the overall data cache space that may be dedicated to individual files.
Priming Cache
The c-treeACE database engine optionally maintains a list of data files and the number of bytes
of data cache to be primed at file open. When priming cache, c-treeACE reads the specified
number of bytes for the given data file into data cache when physically opening the data file.
Data files are added to the priming list with configuration entries of the form:
PRIME_CACHE
<data file name>#<bytes primed>
The <bytes primed> parameter accepts scaling factors (for example 2GB).
Example: The following keyword instructs the Server to read the first 100,000 bytes of data
records from customer.dat into the data cache at file open:
PRIME_CACHE
customer.dat#100000
A dedicated thread performs cache priming, permitting the file open call to return without waiting
for the priming to be completed.
Use PRIME_CACHE with the SPECIAL_CACHE_FILE keyword to load dedicated cache pages at
file open.
To prime index files, use configuration entries of the form:
PRIME_INDEX
<index file name>#<bytes primed>[#<member no>]
If the optional <member no> is omitted, all index members are primed. If an index member
number is specified, only that member is primed.
For example, the following keyword instructs the Server to read the first 100,000 bytes of index
nodes in customer.idx into the index buffer space at file open:
PRIME_INDEX
customer.idx#100000
www.faircom.com
All Rights Reserved
19
Best Practices
The nodes are read first for the host index, and then for each member until the entire index is
primed or the specified number of bytes has been primed.
The following example restricts the priming to the first member (the index after the host index):
PRIME_INDEX
customer.idx#100000#1
The <data file name> or <index file name> can be a wild card specification using a ‘?’ for a single
character and a ‘*’ for zero or more characters.
c-treeACE also supports priming the data cache in forward AND reverse order by index.
PRIME_CACHE_BY_KEY <data_file_name>#<data_record_bytes_to_prime>#<index_number>
For example
PRIME_CACHE_BY_KEY mark.dat#-1#100000000
Primes up to 100,000,000 bytes from mark.dat reading by the first index in reverse key order.
Control of Cache Flushing
By default, c-treeACE creates two idle flush threads at startup. One thread flushes transaction file
buffers, and the other flushes non-transaction file buffers. The threads wake up periodically and
check if the server is idle. If so, the flush is begun. If subsequent server activity causes the server
to no longer be idle, then the flushes are terminated. Low priority background threads, such as
the delete node thread, do not affect the server’s idle state. c-tree clients and c-treeACE SQL
clients and checkpoints do cause the idle status to be modified.
The configuration file can modify the characteristics of these idle flush threads:
IDLE_TRANFLUSH <idle check-interval for tran files>
IDLE_NONTRANFLUSH <idle check-interval for nontran files>
The idle check interval values are specified in seconds. Setting the interval to zero or a negative
value disables the thread. The defaults for these intervals are each set at 15 seconds.
Transaction-Controlled Files
An application can use the c-tree Server’s transaction capabilities to guarantee atomicity and,
optionally, recoverability of data. The c-tree Server supports the following transaction processing
options:
 PREIMG (provides atomicity without recoverability)
 TRNLOG (provides atomicity with recoverability)
 TRNLOG with LOGIDX indexes (provides atomicity with recoverability, with logging of index
reorganization operations to speed automatic recovery).
The application selects the transaction processing options that are in effect for the file when it
creates data and index files using c-tree file creation API functions. The following sections
discuss the properties of each transaction processing option, including their effect on the state of
files in the event of an abnormal server termination.
www.faircom.com
All Rights Reserved
20
Best Practices
PREIMG Transaction Files
The PREIMG (“pre-image”) transaction mode supports transaction atomicity but not transaction
recoverability. PREIMG files may be updated only within an active transaction. The server stores
PREIMG file updates in memory known as ‘preimage space’ until the transaction is committed or
aborted. This use of preimage space guarantees atomicity and isolation of transaction operations:
changes are made on an all or nothing basis and other clients do not see changes until the
transaction is committed.
Properties of PREIMG Files
Figure 7: c-tree Server PreImage File Handling
The state of a PREIMG file at a point in time is stored in a combination of the following locations:
 Updated buffers held in preimage space. (Pending updates held in server memory: this is
volatile storage)
 Updated server data/index cache pages. (Committed updates held in server memory: this is
volatile storage)
 Filesystem cache pages. (Committed updates written to filesystem but not flushed to disk
held in system memory: this is volatile storage)
 Disk file contents. (Committed updates written to filesystem and flushed to disk: this is
non-volatile storage)
Only the disk file contents are persistent and unlike TRNLOG transaction file updates (discussed
below), PREIMG file updates are not logged to the server’s transaction logs. For this reason,
PREIMG files are not recoverable in the event of an abnormal server termination. In such a
situation a PREIMG file is in an unknown state because an unknown number of updates may
have not yet been written to disk at the time of the abnormal server termination. Also, because
www.faircom.com
All Rights Reserved
21
Best Practices
automatic recovery does not process PREIMG files, a PREIMG file rebuilt after an abnormal
server termination is not guaranteed to be in a consistent transaction state. In such a situation,
PREIMG files could contain data that was in the process of being committed but for which the
commit had not yet been completed.
Backup and Restore Options for PREIMG Files
Backup copies of PREIMG files can be made using the following approaches:
Online backup using dynamic dump
Although automatic recovery is not available to PREIMG files, it is possible to perform periodic
dynamic backups of PREIMG files using the c-tree Server’s dynamic dump feature. Using the
PREIMAGE_DUMP dynamic dump script option promotes PREIMG files to full TRNLOG files
during the dynamic dump process. The promotion to a TRNLOG file means that a full transaction
log is maintained during the dump process. This process guarantees that any changes made to
the files during the backup are saved in these specially maintained transaction logs. The ability to
dynamically back up user data files minimizes the loss of the automatic recovery feature with this
mode. The dynamic dump produces a dump stream file containing the disk contents of the
PREIMG files and the changes made during the dynamic dump. If it becomes necessary to
restore the backup copy of the PREIMG files, the ctrdmp utility can be used to extract the
PREIMG files from the dump stream file, restoring them to their state at the time of the backup.
Offline backup using file copy
An offline backup of PREIMG files can be performed using system file copy utilities when the
server is shut down or when the server is running and the files to be backed up are closed. It is
important to ensure that the server is shut down or the files are closed before making a backup
copy of files using a system file copy utility in order to ensure that all updated buffers are flushed
to disk. Otherwise, data may be lost and the file may be in an inconsistent state.
When to Use PREIMG Files
The benefit of PREIMG is that it avoids the overhead associated with writing to and flushing the
transaction logs. If atomicity is required for a file but recoverability is not, PREIMG may be an
appropriate choice. Some specific cases in which PREIMG may be appropriate include:
 Using TRNLOG data files and PREIMG indexes if you are willing to rebuild the indexes after
an abnormal server termination.
 Using PREIMG on files that can be re-created in the event of an abnormal server termination.
To minimize loss of unwritten cached PREIMG file updates in the event of an abnormal server
termination, consider using WRITETHRU for PREIMG files or periodically calling the c-tree API
function CtreeFlushFile() to flush PREIMG data and index cache pages to disk.
Creating and Using PREIMG Files
To create a PREIMG data or index file, include the PREIMG filemode in the filemode value
specified when creating the file.
 If using an ISAM-level file creation function, include PREIMG in the dfilmod and ifilmod fields
of the IFIL structure supplied to the function.
www.faircom.com
All Rights Reserved
22
Best Practices
 If using a low-level file creation function, include PREIMG in the filemode parameter supplied
to the function.
The c-tree Server allows updates to PREIMG files only within an active transaction. To start a
transaction, call the c-tree Plus API function Begin() with a transaction mode of either PREIMG or
TRNLOG. A PREIMG file may participate in either a PREIMG or a TRNLOG transaction.
Regardless of which transaction type is specified, updates to PREIMG files are not logged to the
server’s transaction logs. An update on a PREIMG file that is attempted outside a transaction fails
with c-tree error TTYP_ERR (99, transaction type/filmod conflict).
TRNLOG Transaction Files
The TRNLOG (“tran-log”) transaction mode supports both transaction atomicity and transaction
recoverability. TRNLOG files may be updated only within an active transaction. The server stores
TRNLOG file updates in memory known as “preimage space” until the transaction is committed or
aborted and logs transaction begin and commit operations and file updates to disk-based
transaction log files. The use of preimage space guarantees atomicity and isolation of transaction
operations: changes are made on an all-or-nothing basis and other clients do not see changes
until the transaction is committed. The use of transaction logs guarantees recoverability of
transactions in the event of an abnormal server termination.
Properties of TRNLOG Files
www.faircom.com
All Rights Reserved
23
Best Practices
Because the c-tree Server logs updates made to TRNLOG files to its transaction logs, TRNLOG
files are fully recoverable in the event of an abnormal server termination. The server ensures
TRNLOG files are in a consistent state by performing automatic recovery at server startup. The
server’s automatic recovery procedure involves scanning the transaction log to determine which
transactions must be undone and which must be redone, based on the transaction log entries and
the state of the files involved in the transactions.
Figure 8: c-tree Server TRANLOG File Handling
The state of a TRNLOG file at a point in time is stored in a combination of the following locations:
 Updated buffers held in preimage space. (Pending updates held in server memory: this is
volatile storage)
 Updated server data/index cache pages. (Committed updates held in server memory: this is
volatile storage)
 Filesystem cache pages. (Committed updates written to filesystem but not flushed to disk
held in system memory: this is volatile storage)
 Disk file contents. (Committed updates written to filesystem and flushed to disk: this is
 Transaction log contents. (Transaction state entries and file updates flushed to disk: this is
Only the disk file and transaction log contents are persistent. The c-tree Server can guarantee
recoverability of TRNLOG files in the event of an abnormal server termination because it logs to
disk the transaction state and updated buffers necessary to guarantee recoverability. At startup,
www.faircom.com
All Rights Reserved
24
Best Practices
the automatic recovery procedure applies the necessary changes to TRNLOG data and index
files to ensure the system is in a consistent transaction state.
Backup and Restore Options for TRNLOG Files
Backup copies of TRNLOG files can be made using the following approaches:
The c-tree Server’s dynamic dump feature can be used to make a consistent point in time backup
of TRNLOG files. The server maintains a full transaction log during the dump process and
produces a dump stream file containing the disk contents of the TRNLOG files and the changes
made during the dynamic dump. If it becomes necessary to restore the backup copy of the
TRNLOG files, the ctrdmp utility can be used to extract the TRNLOG files from the dump stream
file, restoring them to their state at the time of the backup.
Online backup using system disk snapshot
Some systems provide the ability to perform an instantaneous transparent copy of the contents of
a disk. This approach can be used to backup TRNLOG files provided that the copy operation
produces a point in time image of the disk and the server’s transaction logs are included with the
TRNLOG files. If this is done, the TRNLOG files can be restored to a consistent transaction state
corresponding to the time the backup was taken by restoring the saved files (transaction logs and
TRNLOG files), then starting the server and allowing it to perform automatic recovery on the
TRNLOG files. The disk-level snapshot is typically a feature offered by intelligent disk storage
subsystems, such as a Storage Area Network (SAN).
An offline backup of TRNLOG files can be performed using system file copy utilities when the
When to Use TRNLOG Files
Create data and index files as TRNLOG files when operations on the files must be atomic and
updates must be recoverable in the event of an abnormal server termination. If only atomicity is
needed, PREIMG may be more appropriate.
The performance impact of TRNLOG due to checkpoint operations, transaction log flushing and
transaction file buffer flushing can be minimized using transaction-related server configuration
options such as:
CHECKPOINT_FLUSH
CHECKPOINT_INTERVAL
COMMIT_DELAY
LOG_SPACE
LOG_TEMPLATE
TRANSACTION_FLUSH
Creating and Using TRNLOG Files
www.faircom.com
All Rights Reserved
25
Best Practices
To create a TRNLOG data or index file, include the TRNLOG filemode in the filemode value
specified when creating the file.
 If using an ISAM-level file creation function, include TRNLOG in the dfilmod and ifilmod fields
of the IFIL structure supplied to the function.
 If using a low-level file creation function, include TRNLOG in the filemode parameter supplied
to the function.
The c-tree Server allows updates to TRNLOG files only within an active TRNLOG transaction. To
start a TRNLOG transaction, call the c-tree Plus API function Begin() with a transaction mode of
TRNLOG. An update on a TRNLOG file that is attempted outside a TRNLOG transaction fails
with c-tree error TTYP_ERR (99, transaction type/filmod conflict).
TRNLOG Transaction Files with LOGIDX Indexes
TRNLOG indexes can optionally be created with the LOGIDX attribute. This attribute causes the
server to log index reorganization operations to the transaction logs in order to facilitate automatic
recovery of large indexes.
During automatic recovery, the c-tree Server scans the transaction logs in order to determine
which TRNLOG index files must be processed by automatic recovery. For TRNLOG index files
that were not created with the LOGIDX attribute, the server scans the leaf nodes, verifying links
and rebuilding the upper part of the index tree. For large indexes, scanning the leaf nodes can be
time-consuming.
Creating TRNLOG indexes with the LOGIDX attribute allows the server to make local repairs to
index nodes (made possible by the additional LOGIDX transaction log entries) rather than
requiring a full index leaf node scan, verification, and reconstruction. For this reason, using
LOGIDX indexes can significantly speed up recovery time in the case of large TRNLOG indexes.
Using the LOGIDX attribute for an index file causes the c-tree Server to perform the following
additional steps for index reorganization operations on that index:
 Write begin/end entries to the transaction log for index reorganizations (i.e., node splits or
underflow node recovery). Before the “end” entry is written to the log, the index updates are
saved to disk. If a begin is found without a corresponding end during automatic recovery,
then the index must be examined in the region of the reorganization.
 Write vulnerable node entries to the transaction log to identify nodes which must be cleaned
during automatic recovery. It is not necessary to place images of nodes in the log. Instead,
the server logs the node position and optionally a key value which identifies the node’s logical
position in the index.
Properties of LOGIDX Index Files
The format of a TRNLOG index created with the LOGIDX attribute is identical to that of a
TRNLOG index created without the LOGIDX attribute. The only difference is the generation of
additional log entries for index reorganization operations, which automatic recovery uses to speed
recovery of the indexes as described above.
When to Use LOGIDX Index Files
The LOGIDX attribute is appropriate to use when a database contains large TRNLOG indexes
and the application requires fast automatic recovery. The tradeoff for faster automatic recovery is
www.faircom.com
All Rights Reserved
26
Best Practices
that using LOGIDX might introduce a slight performance penalty for index update operations due
to the generation of additional log entries and forced flushing of updated index buffers.
Creating and Using LOGIDX Index Files
To create a TRNLOG index file with LOGIDX support enabled, include the TRNLOG and LOGIDX
filemodes in the filemode value specified when creating the index file.
 If using an ISAM-level file creation function, include TRNLOG | LOGIDX in the ifilmod field of
the IFIL structure supplied to the function.
 If using a low-level file creation function, include TRNLOG | LOGIDX in the filemode
parameter supplied to the function.
Because LOGIDX affects only the server’s transaction processing behavior and does not affect
the format of the index file, LOGIDX can be enabled at run-time for all TRNLOG indexes by
specifying the following server configuration option in the server configuration file, ctsrvr.cfg:
FORCE_LOGIDX ON
The FORCE_LOGIDX keyword provides a simple way to enable LOGIDX processing for TRNLOG
indexes, including those that were not created with the LOGIDX attribute. When this option is
specified in the server configuration file, all TRNLOG indexes are treated as LOGIDX files. Using
this keyword is a good way to ensure that LOGIDX processing is in effect for all TRNLOG indexes
in order to ensure fast recovery.
6-Byte Transaction Numbers
The c-tree Server associates a unique transaction number with every transaction. The transaction
numbers assigned by the server start with transaction number 1 and are ever-increasing during
the server’s operation.
When a c-tree client begins a transaction, the return value is the transaction number assigned to
that transaction (or 0 in the case of an error). The server writes transaction numbers to the
following persistent locations:
 Transaction logs (the start files S*.FCS, and the log files L*.FCS)
 TRNLOG indexes (in leaf nodes and header)
 Superfile hosts (including the server’s FAIRCOM.FCS)
Transaction Number Limitations Prior to V8
Versions 6 and 7 of the c-tree Server support a 4-byte transaction number, of which 30 bits form
the transaction number. For this reason, the maximum transaction number these versions of the
c-tree Server support is 1,073,741,808 (0x3ffffff0).
When the server detects that the current transaction number is approaching the transaction
number limit, it logs messages to the server status log, CTSTATUS.FCS, to inform the server
administrator of an impending transaction number overflow. When the server detects a
transaction number overflow it shuts down.
In the event of an impending transaction number overflow, the server administrator can follow
these steps to restart the transaction numbering:
 Perform a clean shutdown of the c-tree Server as indicated by the “Perform system
checkpoint” in the server status log.
www.faircom.com
All Rights Reserved
27
Best Practices
 Delete the transaction logs: files S0000000.FCS, S0000001.FCS, and L*.FCS.
 Use the ctclntrn utility on all TRNLOG indexes and superfile hosts (this includes the c-tree
Server files FAIRCOM.FCS and SYSLOGIX.FCS) to reset the transaction numbers in the leaf
nodes and index header.
 Restart the c-tree Server. The server creates new transaction logs and starts numbering
transactions from 1 again.
Note: When the c-tree Server opens a TRNLOG index, the server compares the transaction
number high water mark in the index header to the current transaction number. If the value in the
index header is larger than the current transaction number and the open occurs outside a
transaction, the server sets the current transaction number to the transaction number high water
mark value from the index header. This behavior is significant because it means that opening an
index containing a reference to a large transaction number can cause the transaction number to
jump to a large value. This could happen if an index was omitted from the ctclntrn processing or
an index was restored from a backup taken before the clean operation.
c-tree Server V8 Transaction Number Enhancements
For systems that must sustain a high transaction rate, the transaction number limit of the version
6 and version 7 c-tree Server can have significant implications for the availability of the c-tree
Server. As an example, a system with a sustained rate of 1000 transactions per second would
exceed the 4-byte transaction number limit in about 12 days of continuous operation.
To overcome this limitation, FairCom added support for 6-byte transaction numbers (also known
as extended transaction numbers) to version 8 of the c-tree Server. The use of 6-byte transaction
numbers (46 bits of which are used for the transaction number) provides the server the ability to
sustain a rate of 1000 transactions per second for over 2000 years (as compared to the 12 day
limit when using 4-byte transaction numbers).
The V8 c-tree Server always stores transaction numbers in the transaction logs as 6-byte values
and stores transaction numbers as either 4-byte or 6-byte numbers depending on the index
creation options. All indexes that the server creates for its own internal use are created as 6-byte
transaction number indexes, so the only possible source of 4-byte transaction numbers is an
application that creates index files as 4-byte transaction number files. If the application creates all
its indexes as 6-byte transaction number files, the server will not be subject to the 4-byte
transaction number limit.
When to Use 6-Byte Transaction Number Files
Use 6-byte transaction number files for high transaction rate systems to avoid the 4-byte
transaction number limit, because the server must be shut down and indexes and superfile hosts
cleaned when the transaction number limit is reached.
Creating 6-Byte Transaction Number Files
To create 6-byte transaction number files (this applies to superfile hosts and indexes), create an
array of XCREblk (extended create block) structures, one for each physical data and index file to
be created. Include the ct6BTRAN attribute in the x8mode field of each extended create block
structure corresponding to an index file or superfile host. Call an Xtd8 create function such as
CreateIFileXtd8(), passing the extended create block array to the function.
In order to ensure that only 6-byte transaction number files are opened by the server, specify the
following keyword in the server configuration file:
www.faircom.com
All Rights Reserved
28
Best Practices
COMPATIBILITY EXTENDED_TRAN_ONLY
This keyword causes a R6BT_ERR (745, 6BTRAN file required) on an attempt to create or open
a non-extended-transaction-number file. (Note that a read-only open is not a problem since the
file cannot be updated.)
Configurable Transaction Number Overflow Warning Limit
When c-treeACE supports 6-byte transaction numbers it does not display transaction overflow
warnings until the current transaction number approaches the 6-byte transaction number limit. But
if 4-byte transaction number files are in use, a key insert or delete will fail if the current transaction
number exceeds the 4-byte transaction number limit (however, c-treeACE will continue
operating).
To allow a server administrator to determine when the server’s transaction number is
approaching the 4-byte transaction number limit, the following configuration option was added:
TRAN_OVERFLOW_THRESHOLD <transaction_number>
This keyword causes the c-tree Server to log the following warning message to CTSTATUS.FCS
and to standard output (or the message monitor window on Windows systems) when the current
transaction number exceeds the specified transaction number:
WARNING: The current transaction number (####) exceeds the user-defined threshold.
The message is logged every 10000 transactions once this limit has been reached. The
TRAN_OVERFLOW_THRESHOLD limit can be set to any value up to 0x3ffffffffffff, which is the
highest 6-byte transaction number that c-treeACE supports.
Non-Transaction Files
Depending on the application’s requirements, it may be appropriate to create certain data and
index files without transaction control. Non-transaction files avoid the overhead associated with
transaction processing but do not guarantee atomicity of operations or recoverability of updates.
www.faircom.com
All Rights Reserved
29
Best Practices
Properties of Non-Transaction Files
Figure 9: c-tree Server non-Transaction File Handling
The state of a non-transaction file at a point in time is stored in a combination of the following
locations:
 Updated server data/index cache pages. (Updates held in server memory: this is volatile
storage)
 Filesystem cache pages. (Updates written to filesystem but not flushed to disk held in system
memory: this is volatile storage)
 Disk file contents. (Updates written to filesystem and flushed to disk: this is non-volatile
storage)
The server does not guarantee that unwritten updated data and index cache pages are backed by
a persistent copy on disk, so non-transaction files are not recoverable in the event of an abnormal
server termination. In such a situation a non-transaction file is in an unknown state because an
unknown number of updates may have not yet been written to disk at the time of the abnormal
server termination.
Backup and Restore Options for Non-Transaction Files
Backup copies of non-transaction files can be made using the following approaches:
The c-tree Server’s dynamic dump feature can be used to backup non-transaction files. However,
unlike PREIMG and TRNLOG files the dynamic dump cannot guarantee a consistent point in time
backup for non-transaction files. Non-transaction files are flushed if possible at the beginning of
the dynamic dump. If successfully flushed and not updated during the dynamic dump, the file is
marked clean in the dynamic dump stream file; otherwise it is marked dirty. At dump restore time,
clean files have their update flags cleared but the update flag remains set for dirty files. A dirty
restored file could be missing updates and dirty data and index files could be out of sync. Dirty
www.faircom.com
All Rights Reserved
30
Best Practices
restored files must be rebuilt to clear the update flag and to ensure consistency between data and
index files.
An offline backup of TRNLOG files can be performed using system file copy utilities when the
When to Use Non-Transaction Files
Use non-transaction files when the files are of a temporary nature and can be re-created or the
data in the files can be restored from another source in the event of an abnormal server
termination.
To minimize loss of unwritten cached non-transaction file updates in the event of an abnormal
server termination, consider using WRITETHRU for non-transaction files or periodically calling the
c-tree API function CtreeFlushFile() to flush non-transaction data and index cache pages to disk.
Creating Non-Transaction Files
To create a non-transaction data or index file, do not include the TRNLOG or PREIMG file modes
in the filemode value specified when creating the file.
 If using an ISAM-level file creation function, do not include TRNLOG or PREIMG in the
dfilmod and ifilmod fields of the IFIL structure supplied to the function.
 If using a low-level file creation function, do not include TRNLOG or PREIMG in the filemode
parameter supplied to the function.
WRITETHRU Files
For non-WRITETHRU files, the server stores data and index updates in its internal cache and
does not write updates immediately to disk. For TRNLOG files, this is not a concern because
committed updates to TRNLOG files are logged to the transaction logs. For non-TRNLOG files,
however, in the event of an abnormal server termination the contents of the cache (and hence
any unwritten updates to data and index files) will be lost.
In this situation, the server marks non-TRNLOG files as corrupt to indicate that the file was
opened, updated, and not properly closed, so its state is unknown. Attempting to open such a file
fails with error FCRP_ERR (14, file corrupt at open). Rebuilding the data file and its associated
indexes resets the update flag and allows the application to open the file, but all cached updates
that had not yet been written to disk are lost.
The WRITETHRU file mode can be applied to c-tree data and index files to cause the server to
write updates through the server’s cache to the file system cache or to disk, thereby minimizing
the potential for loss of cached updates in the event of an abnormal server termination. While
ensuring the updates are written to the file system or to disk, WRITETHRU preserves the updates
in the server’s cache so that reads can be satisfied from the server’s cache.
www.faircom.com
All Rights Reserved
31
Best Practices
A data or index file can be created as a WRITETHRU file (in which case WRITETHRU is a
permanent attribute of the file), or it can be opened as a WRITETHRU file (in which case the file
is treated as WRITETHRU until it is closed).
Properties of WRITETHRU Files
For non-transaction WRITETHRU files, all updates are written through the server’s cache to the
file system cache. In addition, the server flushes file system buffers on each ISAM update
operation for WRITETHRU files. (Low-level updates on WRITETHRU files are written through the
server’s cache to the file system cache but are not flushed to disk.)
Figure 10: c-tree WRITETHRU File Handling
For PREIMG files opened or created with the WRITETHRU attribute, the server behaves as
follows:
 PREIMG indexes are placed into standard WRITETHRU mode except that changes in the
number of index entries are output at transaction commit time.
 PREIMG data files are placed into a modified mode in which file updates and header updates
are only output at transaction commit time.
WRITETHRU minimizes the possibility of lost updates in the event of a catastrophic event
because it writes updated cache pages to disk at the time of the update operation. However,
WRITETHRU does not provide the guarantee of recoverability that TRNLOG provides. It is still
possible when using WRITETHRU for some updates to be lost or for data and index file
inconsistencies to exist following a catastrophic event.
www.faircom.com
All Rights Reserved
32
Best Practices
Backup and Restore Options for WRITETHRU Files
The backup and restore options for WRITETHRU files are the same as for non-WRITETHRU
files. The distinction is that using WRITETHRU can help minimize data loss that could occur due
to unwritten updated buffers for PREIMG and non-transaction files (although WRITETHRU does
not provide an absolute guarantee of data/index consistency or recoverable updates as TRNLOG
does).
When to Use WRITETHRU Files
WRITETHRU is useful for ensuring that updates to data and index files are written to the file
system cache (or to disk in the case of ISAM updates) at the time of the update (or commit in the
case of PREIMG WRITETHRU files). PREIMG and non-transaction files that do not use
WRITETHRU can experience significant data loss due to unwritten cached data in the event of an
abnormal server termination.
Creating WRITETHRU Files
To create a WRITETHRU data or index file, include the WRITETHRU filemode in the filemode
value specified when creating the file.
 If using an ISAM-level file creation function, include WRITETHRU in the dfilmod and ifilmod
fields of the IFIL structure supplied to the function.
 If using a low-level file creation function, include WRITETHRU in the filemode parameter
supplied to the function.
A data or index file that was not created using WRITETHRU can be opened as a WRITETHRU
file by specifying WRITETHRU in the filemode when opening the file.
The following server configuration settings can be used to alter the server’s WRITETHRU
behavior:
 The COMPATIBILITY FORCE_WRITETHRU configuration option causes the server to enable
WRITETHRU semantics for all non-TRNLOG data and index files. This option provides a
simple way to enable WRITETHRU for all files that are not under full transaction control.
 The COMPATIBILITY WTHRU_UPDFLG configuration option causes the server to avoid
setting the update flag for updated WRITETHRU files. This option provides a simple way to
avoid error FCRP_ERR (14) for WRITETHRU files in the event of an abnormal server
termination. Note that this option should be used with caution, as an abnormal server
termination could leave a data file out of sync with its corresponding indexes (if the data flush
completed but the index flush had not yet completed when the server terminated abnormally).
Large File Support
When FairCom first released the c-tree Server, 10 MB hard drives were considered large. A 2 GB
maximum file size was sufficient, if not unimaginable. For this reason, the c tree Server was
originally designed to use 4-byte file offsets, which limited the size of files to 2 GB or 4 GB
depending on the platform.
Today, with 64-bit operating systems becoming common and 4 GB hard drives being considered
bottom-of-the-line, the need has developed to support very large physical files. Starting with
www.faircom.com
All Rights Reserved
33
Best Practices
version 7 of the c-tree Server V7, FairCom introduced large file support. The c-tree Server
supports large files in two ways:
 Huge files: Physical files that use 8-byte offsets that can grow to over 4 GB in size. Huge files
can be used to support large files up to the maximum physical file size supported by modern
filesystems.
 Segmented files: Logical files distributed across multiple physical files, which can optionally
be huge. Huge segmented files can be used to overcome system limitations on physical file
sizes.
Huge Files
A c-tree data or index file that is created with 8-byte offset support is known as a HUGE file. A
non-HUGE file is limited to 2 or 4 GB in size, depending on system file limits. An 8-byte file offset
provides a maximum file size of more than 1.844 x 1019 bytes per file, so a HUGE file effectively
eliminates practical constraints on the file size.
When to Use Huge Files
Use HUGE files when the maximum size of a file is expected to exceed 2 GB. The consequence
of using a non-HUGE file is that the system-imposed 4-byte offset file limit places a hard limit on
the supported file size. When a non-huge file reaches the system file size limit, operations that
require the file size to increase (such as adding records or updating variable-length records) will
fail. Only deleting records or creating a new file will allow additional records to be added to a
non-huge file when it reaches this state. Using huge files avoids this limitation.
Note that even when using huge files, the maximum size of a file the c-tree Server can create is
limited by operating system and file system limits on file sizes. For example, on many Unix
systems, the ulimit or limit command can set arbitrary limits on the size of a physical file. When
developing a system, review operating system and file system file size limits to ensure they
support the system’s physical file size requirements. If the system’s file size limits are too
restrictive, consider using the c tree Server’s segmented file support (described later) to
overcome the file size limitations.
Creating Huge Files
To create HUGE data and index files, create an array of XCREblk (extended create block)
structures, one for each physical data and index file to be created. Include the ctFILEPOS8
attribute in the x8mode field of each extended create block structure. Call an Xtd8 create function
such as CreateIFileXtd8(), passing the extended create block array to the function.
Note: Any index referencing a data file created using 8-byte file addresses must also use 8-byte
file addresses. A ctFILEPOS8 data file requires a ctFILEPOS8 index. A ctFILEPOS8 index
supporting duplicate keys must allow for 8 bytes in its key length for the automatic tie-breaker that
c-tree Plus automatically appends to the key value.
www.faircom.com
All Rights Reserved
34
Best Practices
Segmented Files
Figure 11: c-tree Segmented Files
Segmented file support allows a single logical file to occupy multiple physical files. This allows
data files to exceed the physical file size limits imposed by the operating system, and when
combined with Huge File Support, provides the added benefit of very large file sizes. The physical
file segments can be kept together or distributed over multiple volumes.
When to Use Segmented Files
Use segmented files in the following situations:
 When the total physical size of a c-tree file is expected to exceed operating system or file
system limits. In this case, the file can be segmented into multiple physical files, each of
which is within the system’s file size limitations.
 When enough total disk space is available for the expected physical file size, but the disk
space is spread over multiple volumes. In this case, the file’s various segments can be
placed where the disk space is available.
Creating Segmented Files
Files can be segmented automatically or the size and location of specific segments can be
defined programmatically. Follow these steps to create segmented files:
1. Create an array of extended create block (XCREblk) structures, one for each physical file to
be created. Include the following flags as appropriate in the x8mode field of the XCREblk
structures:
a. The ctFILEPOS8 file mode permits huge files. This mode is required if the logical file will
exceed 4GB total file size, but is not required for segmented files in general.
b. The ctSEGAUTO file mode allows automatic segment generation. When this file mode is
used, SetFileSegments() is not required. Simply set the host segment size and
maximum segments (the segsize and segmax elements of the Extended File Creation
Block). All additional segments will be the same size as the host file and will be stored in
the same directory. The segment names generated for a file start by adding “.001” to the
existing file name, then incrementing the numeric extension. For example: The automatic
segment names for the file sample.dat would start with sample.dat.001 and continues
with sample.dat.002, and so on.
2. Call a c-tree Plus Xtd8 file creation function, passing it the XCREblk structure array.
www.faircom.com
All Rights Reserved
35
Best Practices
3. If not using automatic segments, define a SEGMDEF structure detailing the segments to be
used. To establish the initial segments, call SetFileSegments(), passing it the SEGMDEF
structure.
The extended creation functions can only provide minimal information for segmented files. The
XCREblk structure only holds the size of the host segment and the maximum number of
segments. To fill in the details, the SetFileSegments() function specifies segment definitions for
newly created files dynamically while the file is open. Also, SetFileSegments() can optionally set
or change the size limit on the host segment. However, SetFileSegments() can only be called for
files created with the Xtd8 API, which causes the file to have an extended header.
The Xtd8 create functions always create Extended files, even if no extended features are
requested (unless the ctNO_XHDRS file mode is turned on). Files created with the original API
(e.g., CreateIFileXtd()) are in the Standard c-tree Plus format.
Note: Files are created in ctEXCLUSIVE mode, so you must close and reopen the file after it is
created to allow it to be shared. Since files are created in ctEXCLUSIVE mode, this is a
convenient time to execute additional configuration functions, such as SetFileSegments() and
PutDODA().
Memory Files
Figure 12: c-tree Plus Memory Files
Memory files are data and index files that are purely memory-resident files that do not exist on
disk.
The memory in which memory file data records and index nodes are stored is allocated using the
server’s internal memory allocation routines and is separate from the server’s data and index
caches. The server uses its memory-management subsystem to allocate and free memory
associated with memory files. If the request for memory is at or below 2K bytes, the server uses
its own memory sub sub-manager; otherwise, it calls the system memory-allocation routine.
When a record or node is deleted, the memory is returned.
www.faircom.com
All Rights Reserved
36
Best Practices
Properties of Memory Files
Because memory files exist purely in server memory (the data never goes to disk), an abnormal
server termination or final close of the file destroys the memory file and its existing memory
records.
Memory files can be created as PREIMG files or non-transaction files. PREIMG memory files
support atomic operations just as disk-based PREIMG files do.
The maximum size of a memory file is limited by the file size specified when creating the memory
file. When selecting memory file sizes, take into account the amount of available physical memory
on the system. Creating memory files whose size exceeds the amount of available physical
memory on the system will cause the operating system to swap memory to disk, which degrades
performance.
A memory-resident file cannot be mirrored, partitioned or segmented.
A memory file cannot be backed up by a dynamic dump.
A memory file on a 32-bit server must use 32-bit file offsets (so it cannot be huge); a memory file
on a 64-bit server must use 64-bit file offsets (so it must be huge).
 When creating a memory file on a 64-bit server at the c-treeDB level: It is recommended to
explicitly include the HUGEFILE attribute in the create statement. This will ensure consistent
operation and avoid triggering a potential 582 error.
 When using memory files on a 64-bit server: If you create any indexes that allow duplicates,
be sure to include 8 bytes in the total key length (rather than the typical 4 bytes) for the
record offset indicator. This will avoid potentially triggering a 582 error.
When to Use Memory Files
Memory files are appropriate to use for data that does not need to be stored to disk. Examples
include temporary data that is useful during server operation but would normally be discarded
when the server is shutdown and restarted and data that can be restored from another source in
the event of an abnormal server termination.
Creating Memory Files
To create a c-tree data or index file as a memory file, create an array of XCREblk (extended
create block) structures, one for each data and host index file to be created. For each extended
create block structure, include the ctMEMFILE attribute in the x8mode field and set the mxfilzhw
and mxfilzlw fields to the maximum file size (mxfilzhw is the high-order word and mxfilzlw is the
low-order word). Call an Xtd8 create function such as CreateIFileXtd8(), passing the extended
create block array to the function.
An attempt to add a new record that causes the memory file to exceed this limit fails, and returns
a MAXZ_ERR (667, attempt to exceed maximum file size).
The final close of a memory file causes the server to delete the file. A final close is a file close
that causes the user count of the file to drop to zero. In order to ensure that the contents of a
memory file are not lost due to an unintentional close of the file, it is possible to make the data file
persist even after the final close by including the ctKEEPOPEN bit in the splval member of the
file’s extended create block when creating the file. Then the final close leaves the file open (but
www.faircom.com
All Rights Reserved
37
Best Practices
without any user attached to the file). It can then be opened again, and the data still exists. The
file will be closed when the server terminates, or when a call is made to the c-tree Plus API
function CloseCtFileByName().
Partitioned Files
The c-tree Server supports a unique feature known as Partitioned Files. A partitioned file logically
appears to be one file (or more accurately one data file and its associated index files), but is
actually a set of files whose contents are partitioned by the value of the partition key. Both the
data files and index files are partitioned. This permits data with a defined range of values for the
partition key to be rapidly purged or archived (instead of having to delete record-by-record each
record within this range).
A partitioned file is comprised of a host data file and its associated indices combined with a rule.
The rule determines how to map the partition key value (e.g., a date, or invoice number, or some
other characteristic) into a particular partition member of the host. The host file does not contain
any actual data, but serves as a logical file that appears to contain all the data.
A partition member file has the same definition as the host, but only holds data whose partition
key maps to the member. For example, customer orders may be partitioned by calendar quarter.
All orders booked in the same quarter are stored in the same member. A member is comprised of
a standard c-tree data file and its associated indices.
To add data to the partitioned file, simply call an add routine for the host. The code will add the
record in the proper partition member, creating the partition member if necessary. Rewriting a
data record may move the record between partitions if the partition key entry for the record is
changed. Under transaction control, such a delete/add record operation is done atomically.
Searching the partitioned file in key order is fairly straightforward and efficient if the key is the
partition key (the key used to determine which partition should contain the record). Searches on
other, non-partition, keys are less efficient than normal because the record may exist in any of the
partition members. The more active partition members there are in the logical file, the less
efficient the non-partition key search will be.
www.faircom.com
All Rights Reserved
38
Best Practices
It is possible to manage the partition members so that archiving or purging partitions is very quick
and efficient.
When to Use Partitioned Files
Use partitioned files when the ability to easily purge or archive individual member files is desired.
For example, partitioned files can be used to store records by date, so that all records in a given
month are stored in one partition. Then, when the month’s activity is complete, the partition can
be taken offline and archived or purged.
Creating Partitioned Files
To create partitioned files, follow these steps:
1. Activate the partitioned files capabilities at compile time with the ctPARTITION define. This
define is on by default, provided the ctHUGEFILE, RESOURCE, CTS_ISAM, and
ctCONDIDX defines are in place. Check ctree.mak, ctoptn.h and ctopt2.h for the current
settings.
2. To create a partitioned file using the default partition naming, partition rule, and maximum
number of partitions, simply create an Extended file with ctPARTAUTO in the x8mode
parameter of the extended file creation block. Partitioned files do not have to be HUGE
unless the logical file size will exceed the 2GB/4GB limit, and they also require the extended
header, that is, they are Extended files; hence they cannot be accessed by V6 code even
when the individual partition file is accessed separately.
Note that partitioned file support requires a special c-tree Server with application-specific partition
rule support. For details, see the c-tree Server SDK documentation and contact FairCom for the
required server libraries.
www.faircom.com
All Rights Reserved
39
Best Practices
File Mirroring
Figure 13: File Mirroring
The c-tree Server’s mirroring facility makes it possible to create and maintain copies of important
files on different drive volumes, partitions or physical drives. If the primary storage location is lost
due to some form of catastrophe (i.e., head crash) the mirroring logic can automatically detect the
lost connection and switch to the secondary or “mirrored” storage area.
By default, read and write operations on mirrored files will continue without returning an error if
one of the files fails, but the other succeeds. When this happens, the failed file is shut down, all
subsequent I/O operations continue only with the remaining file and the file name for the shut
down file is logged in the server status log, CTSTATUS.FCS.
Both non-transaction controlled and transaction-controlled files can be mirrored. For a transaction
controlled file, if a primary and mirror file get out-of-sync beyond the ability of automatic recovery
to make them both good, the most up-to-date file is recovered.
When to Use Mirrored Files
Use mirrored files in a system where disk I/O errors might be expected to occur. Placing a
mirrored copy of a file on a different drive than the primary copy of the file can protect against
failure of either of the drives. Following a failure of the primary or mirror, the server automatically
www.faircom.com
All Rights Reserved
40
Best Practices
switches to using only the remaining copy of the file and clients can continue to access the file.
Restoring primary and mirror copies involves taking the remaining copy off-line and using a
system file copy utility to restore the second copy of the file from the remaining good copy.
Update speed for mirrored files is no different than for non-mirrored files when the updates are
written to the server’s cache. When updates are written to disk, however, both the primary and
the mirror files are updated, which may cause updates to be slower for a mirrored file compared
to a non-mirrored file.
Another option is to use a mirroring approach that operates at the disk level, such as RAID, rather
than using the server’s mirroring support. Such an approach may provide the following abilities
not supported by the c-tree Server’s mirroring facility:
 Easily mirroring the entire contents of a disk.
 Maintaining more than two copies of disk contents.
 Better performance due to parallel disk transfer operations.
Creating Mirrored Files
To create a mirrored file, call a c-tree Plus file creation function specifying a name of the form
“<primary>|<mirror>”, where <primary> is the name of the primary file and <mirror> is the name
of the mirror file. The server automatically applies updates made to the primary file to the mirror
file.
The c-tree Server also supports mirroring the user/group definition file, FAIRCOM.FCS, and the
transaction logs and transaction start files. For details on enabling mirroring for these files, see
the Mirroring Control options in the “Advanced Configuration Options” section of the c-tree Server
Administrator’s Guide.
Summary of c-treeACE Features
Below is a summary of the recommended usage of the c-tree Server’s features described in this
section:
 When designing a system that uses the c-tree Server, first consider using TRNLOG for all
files, then determine if requirements can be relaxed to include the use of PREIMG or
non-transaction files in some cases. Understand the effect of using PREIMG and
non-transaction files.
 Use TRNLOG files for critical data whose updates must be fully recoverable in the event of
an abnormal server termination. TRNLOG provides the best fault tolerance but transaction
logging has performance implications.
 If using TRNLOG index files, use LOGIDX to speed automatic recovery. LOGIDX may slightly
impact performance but can significantly improve recovery times for large TRNLOG indexes.
 Use PREIMG files for atomic operations on files without the assurance of recoverable
updates. In the event of an abnormal server termination, lost updates are likely for a PREIMG
file and the file must be re-created, rebuilt, or restored from backup.
 Use non-transaction files for data not requiring atomic operations without the assurance of
recoverable updates. In the event of an abnormal server termination, lost updates are likely
for a non-transaction file and the file must be re-created, rebuilt, or restored from backup.
 Use WRITETHRU (or periodic cache flush calls) to minimize unwritten cached data loss for
PREIMG and non-transaction files in the event of an abnormal server termination, but be
www.faircom.com
All Rights Reserved
41
Best Practices
aware of the limitations of WRITETHRU: lost updates and out of sync data and index files are
still possible, and there is no guarantee of consistency for PREIMG files.
 Create c-tree data and index files as huge files when the size of the file is expected to exceed
2 GB. Otherwise, at some point the file will reach its maximum size and updates that would
cause the file to grow will fail. Also be aware of system limitations on file sizes (operating
system and filesystem settings).
 Create c-tree data and index files as segmented files when the file size is expected to exceed
the available space on a single disk volume or when the file size is expected to exceed the
supported maximum file size on the system. Otherwise, at some point the file will exhaust
available disk space or will exceed the maximum file size and updates that would cause the
file to grow will fail.
 Use mirrored files when disk I/O errors are likely to occur. Mirroring protects against the
failure of one copy of the file. Another alternative is to use a disk-level mirroring approach
such as RAID.
 Use memory files to create memory-based data and index files that exist only while the c tree
Server is active. The final close of a memory file frees its memory, destroying its contents.
Because memory file data is not persistent, a common use of memory files is to store data
that can be reloaded from an external source.
 Use partitioned files when the ability to easily purge or archive portions of a file is desired.
4.2
c-tree Files to Include in a Dynamic Dump
A c-treeACE SQL dictionary is composed of several files. You will need to back up all of these
files if you want to be able to restore the entire SQL dictionary from your backup. By backing up
the correct set of files, you will be able to do a full restore and have your SQL dictionary
ready-to-go.
The following files need to be backed up if you want to be able to restore the entire SQL
dictionary:
 FAIRCOM.FCS
 ctdbdict.fsd
 *.dat in the ctreeSQL.dbs folder
 *.idx in the ctreeSQL.dbs folder
 ctreeSQL.fdd in ctreeSQL.dbs\SQL_SYS
The !FILES section of your dynamic dump script will look like this:
!FILES
FAIRCOM.FCS
ctdbdict.fsd
ctreeSQL.dbs\*.dat
ctreeSQL.dbs\*.idx
ctreeSQL.dbs\SQL_SYS\ctreeSQL.fdd
!END
www.faircom.com
All Rights Reserved
42
Best Practices
More generally, the following files are FairCom internal files that need to be included in backups
to allow recovery to function without SKIP_MISSING_FILES YES (in the event these files are
changed during the backup interval):
 FAIRCOM.FCS
 SYSLOG*.FCS
 SEQUENCE*.FCS
 DFRKSTATE*.FCS
 ctdbdict.fsd
 *.dbs\SQL_SYS\*.fdd
 RSTPNT*.FCS
 REPLSTATE*.FCS (created on the target server by the Replication Agent)
Testing the Backup
The following test should demonstrate that you have backed up everything you need:
1. Use the dynamic dump utility, ctdump, to back up your files into SYSTEM.BAK.
The !FILES section of your dynamic dump script should include the entries shown earlier.
2. Shut down your c-treeACE Server and rename your
C:\FairCom\V10.3.0\winX64\bin\ace\sql\data folder to a new (unused) folder name, such as
data.old:
C:\FairCom\V10.3.0\winX64\bin\ace\sql\data.old
3. Create a new data folder and copy the following files to this location:
ctrdmp.exe
SYSTEM.BAK
Your backup script (the text file that contains the !FILES section shown above)
4. Run ctrdmp to restore your files in place.
5. Now start your c-treeACE Server and connect using c-treeACE Explorer. You should be able
to see your restored SQL tables.
4.3
Automatic Recovery
Never interrupt the c-treeACE process during automatic recovery. Data and indexes will be left in
an unknown state, resulting in probable data loss. This situation may require restoring data from a
clean backup to ensure absolute data integrity.
File ID Overflow during Recovery
When a transaction controlled file is opened by the server, it is assigned a unique fileid which is
used to reference it in the transaction logs. This number is stored as a 4 byte integer. If large
numbers of files are opened and closed repeatedly, available file numbers can be rapidly
consumed , leading to a "Pending File ID overflow" message to be logged. This message is
logged once every 10,000 file opens. The fileid can be reset by shutting down the server cleanly
(so no recovery is needed), and removing existing transaction logs (L*.FCS and S000*.FCS).
www.faircom.com
All Rights Reserved
43
Best Practices
An FUSE_ERR error (22) during recovery indicates that the FILES setting should be increased to
complete recovery. A RECOVER_FILES keyword (NO by default) is also available that controls
this specifically.
RECOVER_FILES <number of files | NO>
Note: Recent improvements to only assign the fileid when a file is actually updated, and not just
opened and read from, can substantially reduce the file numbers consumed.
4.4
Restrict Access to c-treeACE Server Files
The c-treeACE Server engine requires exclusive access to the files under its control. Therefore
do not attempt to copy, delete or in any way replace a file being controlled by the c-treeACE
Server engine while the Server is running. This can lead to data corruption and Server instability.
4.5
External Third-Party Utilities
c-treeACE server technology requires that it is the only process operating over any data and
index files under its control. Third-party backup (and some virus scan) utilities should never touch
any files while the c-tree Server has the files open. Doing so on the transaction logs or on a
transaction controlled file may terminate the server process. When c-treeACE encounters a write
error on these types of files it can no longer guarantee integrity or recovery and must terminate to
protect the state of the current system.
If a third-party backup is desired, either use the c-tree Dynamic Dump backup facility to create a
copy of the files and point the third-party backup to the resulting backup file, or shut down the
c-tree Server. and then perform the backup.
It is also possible to use a disk-level copy as an acceptable backup strategy, provided c-treeACE
is put into a quiet state (using either “Quiesce” or File Block) before the hardware-level copy.
c-treeACE V9.2 and later for Windows also includes Windows VSS support (Volume Shadow
Service) for enhanced integration with third-party backup tools.
4.6
Safely Copying c-treeACE Controlled Files
Warning: c-treeACE controlled files should only be copied, moved, or deleted when the c-tree
Server is shut down. Copying, moving, or deleting files while the c-tree Server is in operation can
lead to unpredictable errors.
The following are important points for c-treeACE administrators to observe:
 Do not use system copy utilities to copy c-tree data and index files or server administration
files (*.FCS) while they are in use by the c-tree Server. To safely copy files while the server is
operational follow the approaches discussed in the “Online Backup Options” of this
document.
 Do not use third-party file scan or backup utilities on c-tree data and index files or server
administration files (*.FCS) while they are in use by the c-tree Server.
Failing to observe the above recommendations could prevent the c-tree Server from accessing
the files, which could lead to errors returned to client applications or could cause the server to
www.faircom.com
All Rights Reserved
44
Best Practices
terminate abnormally. Consider setting file permissions on the c tree data and index files and
server administrative files to ensure that only the c-tree Server can access these files while the
server is running.
Administrators should also be aware of the use of file IDs in the header of c-tree data and index
files. When a file open is attempted, the c-tree Server checks to see if either a file with the same
name has already been opened, or if a file with the same unique ID has already been opened. In
either case, the match means that a physical file open is not required. Instead the open count for
the file is incremented. Checking the unique file ID permits different applications and/or client
nodes to refer to the same file with different names: maybe different clients have different drive or
path mappings.
However, if two different files have the same ID (a 12-byte value comprised of a Server ID, a time
stamp, and a transaction log sequence number), problems could arise because the second file
would not actually be opened. The ID is constructed so that no two files could have the same ID
unless someone copies one file on top of another. See the warning listed below.
When a file without a matching name does match the unique file ID, a message is sent to the
system console indicating the names of the two files involved. This message can be suppressed
by adding the following entry to the c-tree Server configuration file:
MONITOR_MASK
MATCH_FILE_ID
Warning: As discussed above, copying a file to a new name is typically the only way the file IDs
can match. If this becomes necessary (that is, only copied when the server is stopped -- do NOT
copy, move, or delete files controlled by the server while the server is in operation), use the
Update File ID utility, ctfileid.
 ctfileid.c is located in ctree\samples\special\utils and replaces the previous informal and
undocumented utilities, updateid.c and newid.c.
Copying Over Transaction-Controlled Files
Copying over transaction-controlled files poses an additional concern. Even if the server is
stopped, it may still need to go through recovery on restart. If files were copied over existing files
that need to go through recovery then two outcomes are possible:
1. If the file IDs do NOT match, the server will detect a file ID mismatch during recovery and fail
to start, with messages logged to CTSTATUS.FCS detailing the problem.
2. If the file IDs match, the server will apply changes from the transaction logs to the new
version of the file which are not valid, resulting in the silent corruption of the new data/index.
To verify that the server does not need to go through recovery before copying over existing
transaction controlled files, check that CTSTATUS.FCS ends with the normal shutdown
sequence, and includes the messages "Perform system checkpoint" and "Server shutdown
completed." (The system checkpoint occurred when all connections were closed and the server
wrote a clean checkpoint at shutdown so it will not need to perform a recovery upon restarting.)
Tue Sep 23 16:58:08 2014
- User# 00015
Server shutdown initiated
Tue Sep 23 16:58:09 2014
- User# 00015
Communications terminated
Tue Sep 23 16:58:09 2014
- User# 00015
Perform system checkpoint
Tue Sep 23 16:58:09 2014
- User# 00015
Server shutdown completed
www.faircom.com
All Rights Reserved
45
Best Practices
Tue Sep 23 16:58:09 2014
- User# 00015
Maximum
Tue Sep 23 16:58:09 2014
- User# 00015
Maximum
Tue Sep 23 16:58:09 2014
- User# 00015
Maximum
Tue Sep 23 16:58:09 2014
- User# 00015
Maximum
4.7
memory used was 1544324594 bytes
number of lock hash bins for a file was 16384
number of lock hash bins for a user was 16384
number of preimg hash bins for a user was 16384
File Rebuilds
In the event a problem does occur and requires files to be rebuilt, it is possible to rebuild the files
using either a stand-alone utility, or through the c-treeACE Server. To avoid the potential for
wrong PAGE_SIZE settings, and creating indexes without the TRNLOG file mode, FairCom
recommends performing all rebuilds through the c-treeACE Server.
 The c-treeACE V9 Server includes a new keyword, MAX_K_TO_USE, controlling the amount
of memory utilized for file rebuilds. The default is 64 KB. Increasing this value to as large as
practical (not starving the operating system for memory) can provide faster rebuilds than
using single-user rebuild utilities.
 The stand-alone utility has traditionally been a faster method to rebuild files, however, it is
important to ensure that the index page size is set appropriately (using the PAGE_SIZE
switch). The c-treeACE Server defaults to 8192 byte page sizes (64 sectors - 128
bytes/sector), while c-tree standalone technology defaults to 2048 bytes (16 sectors). The
stand-alone rebuild utility should also be built with c-tree Transaction Processing Logic
enabled such that files are created with the appropriate TRNLOG file mode.
4.8
Java Requirements for c-treeACE SQL
Here are the Java requirements for past and current versions of c-treeACE SQL. Remember,
Java is used for Stored Procedures, Triggers, and User Defined Functions. If the Java runtime
engine (JRE) is not available, then these features are unsupported. The Java SDK is required to
compile the source Java modules prior to running.
c-treeACE SQL Version
Java Version Required
11
1.6 or later
10.3
1.6
10.0
1.6
V9.3+
1.6
V9.2
1.5
V9.1
1.5
V9.0
1.5
V8.27
1.5
V8.14
1.4 (1.3 on AIX)
www.faircom.com
All Rights Reserved
46
Best Practices
4.9
Better Performance with NXTVREC() vs GTVREC()
The c-treeACE SNAPSHOT feature provides a wealth of performance and tuning information,
including function call timing. Profiling c-treeACE function calls can provide a very precise tuning
method for looking at performance issues. Consider an application that spends an inordinate
amount of time processing GTVREC() calls; 61% of the total c-tree call time is spent in
GTVREC():
function
GTVREC
TRANEND
DELVREC
EQLVREC
TRANBEG
LTVREC
count
1562390
230398
883241
998513
230399
230445
elapsed
47368
13092
11051
4251
661
489
average
0.0303
0.0568
0.0125
0.0043
0.0029
0.0021
% of tot
61%
17%
14%
6%
1%
1%
Here's a suggestion that can improve performance in this situation. There may be GTVREC()
calls that can be replaced with NXTVREC(). For example, the function monitor log showed the
following sequence of calls:
TRANBEG
EQLVREC ../CURRENTFILESCANPAGES/Listings.idx
DELVREC ../CURRENTFILESCANPAGES/Listings.dat
GETCURK ../CURRENTFILESCANPAGES/Listings.idx M#1
GTVREC ../CURRENTFILESCANPAGES/Listings.idx M#1
TRANEND
In this case, if you reading the key of the record that you just deleted and then reading the next
record you could simply call NXTVREC() like this instead:
TRANBEG
EQLVREC ../CURRENTFILESCANPAGES/Listings.idx
DELVREC ../CURRENTFILESCANPAGES/Listings.dat
NXTVREC ../CURRENTFILESCANPAGES/Listings.idx M#1
TRANEND
Here's why we suggest you use NXTVREC() instead of GTVREC() when possible:
GTVREC() does a full key search starting from the root node. NXTVREC() already knows which
leaf node corresponds to your current ISAM position (that was set when you called EQLVREC()),
and so it goes directly to that node and searches from there for the next key value.
What can happen in some cases is that leaf nodes become empty as keys were deleted, and
before the delete node thread had removed them from the index tree, the application made a
number of calls to GTVREC() which visited those nodes and added them to the delete node
queue again. With these simple code changes above, no duplicate entries will be added to the
delete node queue, however, there is slight overhead in performing the tree search and checking
if the entry is already in the delete node queue. We expect NXTVREC() to be more efficient than
GTVREC() as it starts at the current leaf node.
www.faircom.com
All Rights Reserved
47
Best Practices
4.10
8 Tips for a Fast Data Load
The following eight tips can be used to speed up the process of inserting data into your
c-treeACE database:
1. Turn off transaction processing
Transaction processing control can be turned off during these steps. Assuming you have the data
preserved where you can start over in the event of a problem, you don't need transaction
processing control for this process.
If you desire to have transaction processing control down the road, then ensure you create the
data and index files with TRNLOG file mode active. Once you create the file initially with
TRNLOG enabled, you can disable TRNLOG programmatically to speed up the operations as
indicated in the c-treeACE Programmer Reference Guide in the topic titled Transaction
Processing On/Off http://docs.faircom.com/doc/ctreeplus/#29980.htm.
Or you can call the cttrnmod program, explained in the topic titled cttrnmod - Change
Transaction Mode Utility (http://docs.faircom.com/doc/ctreeplus/#49162.htm).
2. Multi-thread the inserts
The next way to boost performance is use one of the Non-Relational c-tree APIs, such as the
ISAM or the c-treeDB API.
If you can break the data coming into the program into multiple chunks, these APIs allow you to
take advantage of multi-threading to do the inserts. A good rule of thumb is to use one thread for
each virtual CPU core.
3. Disable indexes using CTOPEN_DATAONLY file mode
You can drop the index support when you are doing the data load. This will get the data into the
data file in the fastest manner and will avoid the time it takes to update your indexes on the fly.
 See Opening a Table http://docs.faircom.com/doc/ctreedb/#23603.htm in the c-treeDB C API
Developer's Guide.
4. Batches
With V10 and newer, we've added batch inserts. This is quicker than individual adds because we
can maximize the OS packet size and get the maximum amount of data fed into the c-treeACE
Server process with each batch call.
 Review c-treeDB batches http://docs.faircom.com/doc/ctreedb/#15406.htm.
5. Turn transaction processing back on
See the links given previously in Tip 1 for instructions for turning TRNLOG back on:
 Transaction Processing On/Off http://docs.faircom.com/doc/ctreeplus/#29980.htm
 cttrnmod - Change Transaction Mode Utility
(http://docs.faircom.com/doc/ctreeplus/#49162.htm)
www.faircom.com
All Rights Reserved
48
Best Practices
6. Rebuild
Once you have all of the data loaded into the data files, do a rebuild to generate the indexes. This
is the fastest way to build the indexes because you now have all of the data in the c-tree data
files, so the indexes can be built from scratch with a known set of data. To generate your indexes,
use the function call ctdbRebuildTable http://docs.faircom.com/doc/ctreedb/#48516.htm
discussed in the c-treeDB Developer's Guide.
Or you can call the ctrbldif (http://docs.faircom.com/doc/ctreeplus/#31093.htm) program
discussed in the c-treeACE Programmer's Reference.
To improve the performance of an index rebuild through the Server, increase these two settings
in your ctsrvr.cfg file:
MAX_HANDLES (http://docs.faircom.com/doc/ctserver/#52143.htm)
SORT_MEMORY (http://docs.faircom.com/doc/ctserver/#27977.htm)
7. SHARED MEMORY protocol
If at all possible, run the data load program on the same machine hosting the c-treeACE data.
This will allow the Server to use the shared memory communication protocol which is much faster
than TCP/IP.
If you need to use TCP/IP, increase the number of threads to multiple threads per CPU core to
compensate for the network latency.
8. Direct I/O (V11 and later only)
When using c-treeACE V11 and later, please review Direct I/O support. This will provide some
help when building and working with larger files. See Linux Direct I/O (UNBUFFERED I/O)
Performance Support http://docs.faircom.com/doc/v11ace/#66369.htm in the V11 Update Guide.
The tips given above should help you complete the data load process in much less time than a
single-threaded program using ctdbWriteRecord() inserts. In one customer case where we have
used this process, the time to load 2.2 billion records, with several indices, went from
approximately 2 weeks, to less than 2 days.
4.11
Calculating Memory Usage
The c-treeACE Server startup memory requirements can be reasonably approximated with the
following equation:
Base line Memory =
Server EXE size + 1 MB +
Communications Library size (if applicable) +
Data cache (DAT_MEMORY) +
Index buffer (IDX_MEMORY) +
(900 bytes * Number of files (FILES)) +
(325 bytes * Maximum number of connections (CONNECTIONS)) +
(16000 bytes * Number of actual connections) +
(256 bytes per connection per file actually opened))
Note the following points:
 DAT_MEMORY and IDX_MEMORY default to 225,000 bytes each.
www.faircom.com
All Rights Reserved
49
Best Practices
 FILES defaults to 100.
 CONNECTIONS default to 128.
 IDX_MEMORY is the MAX of:
• IDX_MEMORY or
• 3 * CONNECTIONS * (PAGE_SIZE + 400), where PAGE_SIZE defaults to 8192.
The following locking/transaction processing related items should be considered when
approximating the c-treeACE Server dynamic memory requirements:
 Each record locked consumes 24 bytes.
For transaction processing files only:
 Each data record written consumes (record length + 42) bytes.
 Each index operation consumes (key length + 42) bytes.
4.12
Controlling Server Memory
This section is a summary of the c-treeACE Server memory limit behavior and associated
transaction controls. The Server has two means of controlling memory use:
 User memory limits
 Total memory limit
The user memory limit is specified through system-wide defaults using the USR_MEMORY and
GUEST_MEMORY configuration keywords, which take as their arguments the memory threshold
defaults at the user level. The GUEST_MEMORY limit applies to applications that connect to the
c-treeACE Server without a user ID. The USR_MEMORY limit applies to applications that do
provide a user ID as part of their Server logon. These thresholds default to zero, which implies no
limit on user memory. The system-wide user memory defaults can be overridden by specifying a
user memory limit when adding a user ID to the Server administrative database with the ctadmn
program.
The user memory limit can be either a guideline or an absolute limit. The memory limit defaults to
a guideline. In the guideline mode, when a user exceeds the user memory limit (if set), an attempt
is made to flush preimage memory to disk. However, the preimage control block still resides in
memory. In any event, the user is able to continue getting more memory even if the user limit is
exceeded. The effect of exceeding the guideline limit is two-fold:
1. Preimage memory is swapped to disk, and
2. The OPS_MEMORY_SWP bit in the user’s c-treeACE status word is turned on, (see
SetOperationState in the c-treeACE Programmers Reference Guide
(http://docs.faircom.com/doc/ctreeplus/)). This bit stays on until a new transaction is started.
In absolute mode, memory is denied the user if the limit is exceeded, which will lead to
aborted transactions and/or errors during update operations.
The system memory limit is specified through the TOT_MEMORY keyword, which takes as its
argument the limit on the total bytes of memory that the c-treeACE Server can allocate. If this limit
is exceeded, it may cause a user to flush preimage memory, but it will cause a TSHD_ERR (72) if
the system limit is exceeded during preimage operations. Although an effort has been made to
www.faircom.com
All Rights Reserved
50
Best Practices
avoid the following situation, it is possible that exceeding the limit on total system memory could
cause an internal error if the system needs memory in a critical situation and cannot get memory.
To avoid large amounts of memory use by an application performing large transactions, a special
automatic commit mode can be enabled through Begin().
4.13
Calculating File Storage Space
Approximate the file storage space used by the c-treeACE Server with the following equation:
Storage requirement in bytes =
server size +
communication libraries (if applicable) +
utility program size(s) +
transaction log files +
data files +
index files
The transaction log files initially increase in size as adds, deletes and updates are performed on
the c-treeACE Server controlled files. The c-treeACE Server configuration keyword LOG_SPACE,
which defaults to 10MB, indicates the amount of disk space allocated to store active transaction
logs. Generally, the active transaction log files will not exceed the LOG_SPACE value. If
transaction processing is used, it is not recommended to decrease the LOG_SPACE keyword.
4.14
Calculating Index Sizes
Index sizes are tricky to accurately predict. However, there are a few calculations to give you the
bounds to expect on index size based on the following criteria:
 index node size (page size)
 key length
 four or eight byte record offset value
 six-byte transaction number for transaction controlled files
Consider an index with a four byte key size and the following information provided by the ctflvrfy
utility:
 Disk size was nearly 1GB
 1 root node
 17 internal nodes at the first level
 2692 internal nodes at the second level
 451,645 leaf nodes. (All key values are stored in the leaf nodes)
 49,604,909 key values
There are 454,355 total index nodes in this example.
As this is a transaction controlled, HUGE file (eight bye offsets), actual metrics can be computed
as follows:
454,355 * 2048 node size = 930,519,040 bytes (~1GB)
49,604,909 key values / 451,645 leaf nodes = ~109 keys / node
key length (4) + 8 (record offset) + 6 (transaction #) = 18 bytes / key
www.faircom.com
All Rights Reserved
51
Best Practices
109 * 18 = 1962 bytes / node on average.
Each leaf node can hold a maximum of 112 keys.
2048 byte node size - 28 byte node header = 2020 available bytes.
2020 bytes / 18 = 112.
Note in this example that the leaf nodes are nearly full. In normal key distributions, you can
expect index nodes to be 1/2 full on average, thus, this index could theoretically be much larger
with the same number of keys.
4.15
Migrating Data Between Platforms and Operational
Models
FairCom created c-treeACE with the intent to provide cross-platform support with a standardized
database, no matter which operational model is used or what mix of platforms are involved. In
some cases, this capability is invisible to the developer, in others careful consideration is required
to allow various applications to work together.
This section provides an overview of topics covered in more detail in later sections. It is intended
to provide background information to help you choose the appropriate operational model for your
present and future implementations.
The considerations are broken down by operational model: Single-user standalone, Standalone
Multi-user, and client/server. Applications from different models should not share files
concurrently, though files can be exchanged as described in File Migration (page 53).
Single-User Standalone
Single-user applications should not share c-treeACE files simultaneously. There is no mechanism
in the single-user library to prevent multi-user interference. However, files can be exchanged
between different instances of an application for sequential, not simultaneous, use. See “File
Migration (page 53)” for details.
Multi-User Standalone
The multi-user standalone model has the same issues with exchanging files described in File
Migration (page 53) in the c-treeACE Programmers Reference Guide
(http://docs.faircom.com/doc/ctreeplus/).
However, sharing files between platforms simultaneously introduces additional complications with
byte order and alignment, and adds the issue of record locking.
 Byte order is critical. Applications expecting different byte orders cannot seamlessly share
files in this model.
Note: The c-treeACE Server does allow seamless file sharing!
However, the UNIFRMAT define allows HIGH_LOW applications to store and retrieve data in
LOW_HIGH format instead of HIGH_LOW. This allows the files to be shared. If a record
schema is present in the form of a DODA, data records will be adjusted automatically. See
the “c-treeACE Features” chapter for more information on UNIFRMAT. Record Schemas in
www.faircom.com
All Rights Reserved
52
Best Practices
the c-treeACE Programmers Reference Guide (http://docs.faircom.com/doc/ctreeplus/)
describes the DODA.
 All applications sharing c-treeACE files must use the same alignment settings. If not, the
application developer is responsible for ensuring record layouts are consistent.
 Locking between cross-platform applications introduces the complications of different locking
standards and network file sharing mechanisms.
• In multi-user standalone mode, c-treeACE uses three different locking systems to deal
with the different locking standards used by various operating systems. Any combination
of systems sharing files must use the same locking method with the same settings or
they will not properly identify each other’s locks. See Multi-User Concepts in the
c-treeACE Programmers Reference Guide (http://docs.faircom.com/doc/ctreeplus/) for
information on locking methods and their implementation.
• Different network file sharing systems handle locks in different ways. Sometimes, this
leads to incompatible locking systems between applications. When mixing applications
from different environments, verify that locks are working. A simple test is to use a
sample application, such as ctixmg, a c-treeACE example program. In one instance of
the application, enable locking and add a record (which locks that record automatically).
On the other platform, open ctixmg, enable locking and attempt to read the record added
by the other application. If ctixmg returns a error DLOK_ERR (42), locking is functioning
properly. Otherwise, there is a locking issue requiring troubleshooting.
• Note, the c-treeACE Server relieves the programmer of many of the issues regarding
heterogeneous networking and data integrity as described in the following sections.
Client/Server
The client/server model must also deal with byte order, but the c-treeACE Server handles this
automatically when a record schema, in the form of a DODA, is present in the data file. Clients
manipulate the data in their native format, and the c-treeACE Server manipulates the data in its
native format. Translation takes place automatically during communication between the clients
and the server.
This automatic translation allows a variety of clients using a variety of standards to cooperate with
minimal effort on the part of the developer. For example, c-treeACE Servers running on Mac,
Windows, and Unix systems can communicate simultaneously with any combination of clients on
Mac, Windows, and Unix systems. This allows the customer flexibility in their selection of client
and server systems, and allows clients in a mixed environment to share data.
See Record Schemas in the c-treeACE Programmers Reference Guide
(http://docs.faircom.com/doc/ctreeplus/) for more information about the DODA.
The client/server models also require the extended initialization functions, such as InitISAMXtd(),
which pass logon information and trigger automatic target key transformation. See TransformKey
in the c-treeACE Programmers Reference Guide (http://docs.faircom.com/doc/ctreeplus/) for
more information.
File Migration
Applications of any model can exchange files, sharing them sequentially but not simultaneously.
Ensure the applications involved do not have the files open when they are copied or moved. If the
www.faircom.com
All Rights Reserved
53
Best Practices
application in question is the c-treeACE Server, this is especially important. See Copying Server
Controlled Files in the c-treeACE Programmers Reference Guide
(http://docs.faircom.com/doc/ctreeplus/) for additional information.
Issues that affect file exchanging include byte ordering of numeric values and alignment of data
structures. c-treeACE uses the same default for byte order as the hardware CPU and the default
structure alignment dictated by the compiler.
 Byte Ordering is a processor-related issue. Intel-based processors store numeric values
least-significant byte first (LOW_HIGH), while other processors store numeric values
most-significant byte first (HIGH_LOW). So a four-byte integer containing the value “16”
stored on an LOW_HIGH system as the hexadecimal value 10 00 00 00 would be stored on a
HIGH_LOW system as the hexadecimal value 00 00 00 10. The order of the bits is consistent
within the bytes, but the order of the bytes in the numeric value is reversed. By default,
c-treeACE files are stored in the native format to the operating system, so files created on a
HIGH_LOW machine cannot be exchanged directly with applications on a LOW_HIGH
machine. See Portable Data Through UNIFRMAT Support, in the c-treeACE Programmers
Reference Guide (http://docs.faircom.com/doc/ctreeplus/), which allows HIGH_LOW systems
to work with LOW_HIGH files.
 Different compilers align data structures in different ways, but most have compile-time
options allowing the alignment to be adjusted. Some compilers default to 1-byte alignment,
which means structures are not adjusted in any way. With 2-byte or higher alignment,
variables are aligned to the boundary matching the alignment or the variable’s size,
whichever is smaller. There is a potential for the compiler to add dead space within a data
structure. See Buffer Regions in the c-treeACE Programmers Reference Guide
(http://docs.faircom.com/doc/ctreeplus/) for more information on alignment.
Some of the common problems caused by alignment differences are:
1. Record lengths when different applications use different amounts of padding;
2. Indexing when padding shifts key segments to different locations than specified in the ISEG
structure;
3. Data corruption when applications align the record buffer differently.
Use the c-treeACE ctunf1 reformat utility to adjust the alignment and byte ordering for a given file
before exchanging it with another platform. See CTUNF1 - File Reformatting Utility in the
c-treeACE Programmers Reference Guide (http://docs.faircom.com/doc/ctreeplus/) for more
information on this utility.
4.16
Migrating Your Application Between Operational Models
c-treeACE is designed to simplify the transition between different platforms or operational models.
For the most part, changing models is simply a matter of compiling new libraries and re-linking
your application.
However, some concepts are specific to one operational model. The transition can be made
smoother by reading this section and Chapters 2-4 in the Quick Start and Product Overview
Guide.
www.faircom.com
All Rights Reserved
54
Best Practices
Single-User to Multi-User Standalone or Client/Server
Changing from a single-user application to multi-user (either standalone or client/server)
introduces the possibility of multi-user interference. This is prevented by proper locking
techniques and/or transaction processing (available with the c-treeACE Server). See Multi-User
Concepts and Data Integrity in the c-treeACE Programmers Reference Guide
(http://docs.faircom.com/doc/ctreeplus/) for more information.
A single-user standalone application can support transaction processing. If switching to multi-user
standalone, transaction processing will not be available. Transaction processing is possible when
migrating from single-user standalone to multi-user client/server, since both support transaction
processing. In fact, this simplifies the locking issue since locking can easily be added to existing
transaction processing calls. For example, replacing Begin(ctTRNLOG) with Begin(ctTRNLOG |
ctENABLE). See Adding Transaction Processing (page 57) and Data Integrity in the c-treeACE
Programmers Reference Guide (http://docs.faircom.com/doc/ctreeplus/) for more information.
Multi-user Standalone to Client/Server
A frustrating scenario, relating to users migrating from c-treeACE Multi-User FPUTFGET model to
the c-treeACE Server, needs to be discussed. The dilemma relates to users of the c-treeACE
Server receiving FCRP_ERR (14) error codes when opening server based files. The message
text for the FCRP_ERR (14) error states “File corrupt at open”. Keep in mind that this scenario
only exists due to a power loss, a machine being tuned off without stopping the server, or a
miscoded program that does not close its files, only when the c-tree developer chooses NOT TO
implement transaction control as suggested for the c-treeACE Server.
The FCRP_ERR (14) did not exist in the multi-user mode, so therefore a scenario was created in
which customers, who have been running successfully for years, upgrade to the c-treeACE
Server for stronger data integrity, start to receive “corrupt data errors”. The error is due to either
the user shutting off the power to their server computer or an application not properly closing its
files. Under FPUTFGET, the end-user (or the application) could get away with this. Now they get
errors. Can you imagine the end-user frustration?
First, it is in order to discuss the FCRP_ERR (14) error. In c-treeACE single-user mode and under
the c-treeACE Server, a file update flag is maintained within the header of each file. When a file is
written to, in any manner, this flag is set to indicate the file has been updated. When the file is
closed, this flag is re-set, indicating that the application has properly closed the file. Any attempt
to open a file which has been marked update and which has not been properly closed, will result
in a FCRP_ERR (14) error. The c-treeACE Server has no way of knowing the state of this file,
and therefore must return this state back to the application as an integrity error/warning.
In c-tree’s multi-user FPUTFGET mode, the write operation is immediate secured to disk and
therefore this flag is not maintained nor considered. An error 14 simply did not exist under
FPUTFGET. An application could exit without properly closing a file, or a computer or file server
(i.e.: NetWare Server) could be powered off (switched off by end-user) without causing any
immediate catastrophic results for the customer. Perhaps the last “enter-key” entry at the time of
power loss could be out of sync, yet the entire file would not be in question.
So now, take the scenario where one has a user, who has been running for years under
FPUTFGET, who upgrades to the c-treeACE Server. As a reasonable half-step, the developer
chooses to start with the application running in the same matter as it did with FPUTFGET, and
www.faircom.com
All Rights Reserved
55
Best Practices
intends to add the necessary code changes for transaction processing at a later date. The
developer’s efforts are easy, simply re-link the application with the c-treeACE Client library
instead of the FPUTFGET library, and it is ready to go. Now, the updated application and new
c-treeACE Server are deployed at the customer’s site. The customer proceeds to operate in the
same manner before, now complimented by the Client/Server architecture, experiencing less
network traffic, and better performance due to the Server’s data caches. Now, as before, the
customer “flips the switch” at the end of the day, just like they have done for years (without you
knowing it). CATASTROPHIC situation. Now all data/index files open at the time are in question.
Because of the c-treeACE Server’s caches, not just the last “enter-key”, but the entire file is now
undefined. A FCRP_ERR (14) is properly returned the next time the file is opened. The user, who
is used to coming in the next day, switching on the machine and going back to work, was now
calling the developer’s tech support line reporting numerous error 14 messages and corrupt data.
The following solutions are available to solve this dilemma:
1. Of course, the ultimate solution is to secure the data using transaction control. This way all
entries are 100% secure, up to the point of the last transaction commit. When migrating from
FPUTFGET, this solution requires application code changes to implement the transaction
control, as transaction processing does not exist in FPUTFGET.
2. When the c-treeACE Server was introduced, a file mode was added to c-treeACE called
ctWRITETHRU. If a developer defined a file as ctWRITETHRU, all its write operations would
be flushed to disk in the same manner of the FPUTFGET model. What is different about
server ctWRITETHRU versus the FPUTFGET is that the server continues to maintain the
update flag in the file’s header as described above. Therefore, if the machine is switched off,
the data is in the same state as the FPUTFGET model. The exception is that the open
request returns the 14 error, where under FPUTFGET it does not. The server keyword
COMPATIBILITY WTHRU_UPDFLG exists for the c-treeACE Server to instructs the server not
to maintain this update flag for ctWRITETHRU files. Therefore to completely “clone” the
FPUTFGET results, a developer needs to add the ctWRITETHRU file mode to all file
definitions within the program, and activate the COMPATIBILITY WTHRU_UPDFLG keyword in
the server’s configuration file (ctsrvr.cfg). (Actually, this is better than a clone, for all read
operations may safely remain cached under the c-treeACE Server.)
3. There is an additional additional feature which prevents the need to change the client
application. Once the server configuration keyword COMPATIBILITY FORCE_WRITETHRU
has been activated, all files opened in non-transaction processing mode (nonTRNLOG), are
automatically set to ctWRITETHRU. In other words, this has the same effect as the developer
changing all this file modes to include ctWRITETHRU, but because this is automatically done
on the server side, the client side application does not need to be touched. This solution is
the best and easiest for developers who want to take easy step from FPUTFGET to
Client/Server without changing the application.
By activating the following keywords in your server’s configuration file (ctsrvr.cfg), the bases
are covered:
COMPATIBILITY
COMPATIBILITY
FORCE_WRITETHRU
WTHRU_UPDFLG
In addition, a warning message helps the developer recognize this vulnerability. If a server
does NOT have COMPATIBILITY WTHRU_UPDFLG in its configuration file, and if
non-transaction files are opened without ctWRITETHRU in the file mode, then a warning will
be issued in CTSTATUS.FCS concerning the vulnerability to FCRP_ERR (14) if a server is
not shutdown properly. The warning is only entered into CTSTATUS.FCS one time, after
each server startup when a vulnerable file is detected. The keyword STATUS_MASK
WARNING_FCRP_ERR may be added to the configuration file to eliminate this warning
message.
www.faircom.com
All Rights Reserved
56
Best Practices
Adding Transaction Processing
Adding transaction processing to an application permits complex, atomic updates and automatic
recovery in the case of software or hardware failures. Transaction processing can be added with
the transaction processing sub-API or with SetOperationState().
To add efficient transaction processing, use the transaction processing sub-API described in Data
Integrity in the c-treeACE Programmer's Reference Guide
(http://docs.faircom.com/doc/ctreeplus/). If your application is already prepared for multi-user use,
replacing LockISAM(ctENABLE) calls with Begin(ctTRNLOG | ctENABLE) and replacing
LockISAM(ctFREE) calls with Commit(ctFREE) or Abort(ctFREE) calls, depending on the status
of the transaction at that point, is a simple method of implementing transaction processing. See
ctixmg.c for an example and Data Integrity for more details.
To add transaction processing quickly, though not in the most efficient manner, use
SetOperationState() with the OPS_AUTOISAM_TRN mode. This performs a transaction around
each ISAM update. See “SetOperationState” for more details. This method does not effectively
lock updates. You will still need to use some form of locking control. Consider the
OPS_LOCKON_GET mode for SetOperationState() to minimize network traffic.
Once the application supports transaction processing, add either of the transaction processing file
modes, ctTRNLOG or ctPREIMG, to the data files requiring transaction processing using the
UpdateFileMode() function. Index files must be rebuilt to add or remove transaction processing.
For additional information on Transaction Processing, please see Data Integrity.
Single-threaded to Multi-Threaded
Switching to a multi-threaded, ctThrd, library is similar to adding transaction processing:
superficially very easy, but with many implications.
As a minimum when using the ctThrd library, you must implement the ctThrd API. You must call
ctThrdInit() before initializing c-treeACE, just as you must initialize c-tree before calling any other
c-treeACE API functions.
Any new threads that call c-treeACE API functions must be created with ctThrdCreate() or
attached with ctThrdAttach().
In the Multi-threaded Standalone model, do not mix the c-treeACE Instance API
(RegisterCtree(), etc.) with the ctThrd API. Each thread is it’s own instance of c-treeACE, and
handles instance switching via the ctThrd functions. This is not an issue with the Multi-threaded
Client Model.
See ctThrd Function Overview in the c-treeACE Programmers Reference Guide
(http://docs.faircom.com/doc/ctreeplus/) for more detail.
www.faircom.com
All Rights Reserved
57
5.
Helpful Examples
5.1
c-treeACE SQL - Microsoft SQL Server Integration
1. Start c-treeACE SQL as a Windows service. If both c-treeACE SQL and SQL Server are on
the same machine, they will use a shared memory protocol. Since Windows Vista, both
Microsoft SQL Server and c-treeACE SQL must be started as Windows services to establish
a Named Pipe connection.
2. Set up an ODBC “System Data Source”. The “User Data Source” type is not applicable for a
linked database.
3. Create the “account” table in the c-treeACE SQL database.
create table "admin"."account" (
"id" integer not null,
"person_id" integer,
"balance" float (8),
"obs" varchar (128),
primary key ("id")
);
insert into "admin"."account" values('1','1','99.23','None');
insert into "admin"."account" values('2','2','12.11',NULL);
insert into "admin"."account" values('3','1','73.34','Secondary');
insert into "admin"."account" values('4','3','155.84','Primary');
insert into "admin"."account" values('5','3','12.19',NULL);
insert into "admin"."account" values('6','4','0.18','None');
commit work;
4. Set up c-treeACE SQL as a Linked Server in Microsoft SQL Server. Using the Microsoft SQL
Server Management Studio (SSMS), execute the following steps.
a.
In the “Object Explorer”, right click on “Server Objects / Linked Servers” and select
the “New Linked Server” option.
b. Enter a “Linked Server name”, select the “OLE DB Provider for ODBC drivers” as the
provider, “product name” and the “System Data Source” name created in item 2.
www.faircom.com
All Rights Reserved
58
Helpful Examples
c.
Click the “Security” option and add a map to the remote (c-tree) authentication. After
clicking “Add”, select the authentication option on the “Local Login” and enter your
c-treeACE SQL User ID and Password in the “Remote User” and “Remote Password”
boxes.
www.faircom.com
All Rights Reserved
59
Helpful Examples
d. Click the “Server Options” page, enable “RPC” and “RPC Out” options, and confirm.
e. Right click on the “CTREESQL” linked server and select the “Test Connection” option.
f. Check that the “account” c-treeACE SQL table is present in the linked server.
5. Query a c-treeACE SQL table in SSMS. Execute the following query in SSMS.
select * from OPENQUERY(CTREESQL, 'select * from account where id > 2')
select * from CTREESQL..admin.account where id > 2
6. Create Microsoft SQL data. Execute the following commands.
CREATE TABLE [dbo].[person](
www.faircom.com
All Rights Reserved
60
Helpful Examples
[id] [int] NOT NULL,
[name] [char](32) NOT NULL,
CONSTRAINT [PK_person] PRIMARY KEY CLUSTERED
(
[id] ASC
)
) ON [PRIMARY]
GO
insert into person values(1, 'Mary')
insert into person values(2, 'Rick')
insert into person values(3, 'Jack')
insert into person values(4, 'Julia')
7. Execute a join between Microsoft SQL and c-treeACE SQL tables with the following query.
select p.name, a.id, a.balance, a.obs
from person p, OPENQUERY(CTREESQL, 'select * from account') a
where a.person_id = p.id
order by p.name
select p.name, a.id, a.balance, a.obs
from person p, CTREESQL..admin.account a
where a.person_id = p.id
order by p.name
8. Create a view with a table in Microsoft SQL Server and another in c-treeACE SQL with the
following commands.
CREATE VIEW [dbo].[account_view]
AS
SELECT
FROM
p.name, a.id, a.balance, a.obs
dbo.person AS p INNER JOIN
OPENQUERY(CTREESQL, 'select * from account') AS a ON p.id = a.person_id
The view can be executed as any ordinary SQL Server statement:
select * from account_view where name = 'Mary'
9. Create a c-treeACE SQL table in SSMS. Execute the following commands.
exec ('create table "admin"."holiday" (
"id" integer not null,
"description" varchar (32),
"hol_month" integer not null,
"hol_day" integer not null,
primary key ("id")
)') at CTREESQL
GO
exec ('insert into "admin"."holiday" values (1, ''Christmas'', 12, 25)')
at CTREESQL
GO
www.faircom.com
All Rights Reserved
61
Helpful Examples
exec ('insert into "admin"."holiday" values (2, ''New Year'', 1, 1)')
at CTREESQL
GO
select * from OPENQUERY(CTREESQL, 'select * from holiday')
10. Create a similar table in Microsoft SQL Server. Execute the following commands.
CREATE TABLE [dbo].[holiday](
[id] [int] NOT NULL,
[description] [varchar](32) NULL,
[hol_month] [int] NOT NULL,
[hol_day] [int] NOT NULL,
CONSTRAINT [PK_holiday] PRIMARY KEY CLUSTERED
(
[id] ASC
)
) ON [PRIMARY]
GO
insert into holiday values(1, 'Christmas', 12, 25)
GO
insert into holiday values(2, 'New Year', 1, 2)
GO
select * from holiday
11. Create queue table for “holiday” in Microsoft SQL Server. This table will store the
modifications to be replicated to the “linked server”. Execute the following commands.
select * into holiday_queue from holiday where 1 = 2
GO
alter table holiday_queue add action char(1)
GO
alter table holiday_queue add prev_id integer
GO
12. Create triggers for “holiday” in Microsoft SQL Server. To create triggers for Insert, Update
and Delete operations to populate the “holiday_queue” table, execute the following
commands.
CREATE TRIGGER holidayINS ON holiday
AFTER INSERT
AS
INSERT holiday_queue
SELECT *, 'I', NULL
FROM
GO
inserted
CREATE TRIGGER holidayDEL ON holiday
AFTER DELETE
AS
SELECT *, 'D', id
www.faircom.com
All Rights Reserved
62
Helpful Examples
FROM
GO
deleted
CREATE TRIGGER holidayUPD ON holiday
AFTER UPDATE
AS
SELECT *, 'U', (select id from deleted)
FROM
inserted
GO
13. Create a Stored Procedure to sync “linked server” table. To create stored procedures that
reads the “holiday_queue” rows and execute the actions in the “linked server” table, execute
the following commands.
------------------------------------------------------ This stored procedure retrieves the actions queued
-- and "replicates" the modifications in the linked
-- server
----------------------------------------------------CREATE PROCEDURE usp_sync_linkedsrv
AS
DECLARE @err_message nvarchar(255)
-------------------------- holiday replication -------------------------DECLARE @id int
DECLARE @description varchar(32)
DECLARE @hol_month int
DECLARE @hol_day int
DECLARE @action char(1)
DECLARE @previd int
-- declare cursor for reading all the holiday events
DECLARE holiday_queue_cursor CURSOR FOR
SELECT * FROM holiday_queue
FOR UPDATE
-- open cursor
OPEN holiday_queue_cursor
-- retrieve the data from the cursor
FETCH FROM holiday_queue_cursor
INTO @id, @description, @hol_month, @hol_day, @action, @previd
www.faircom.com
All Rights Reserved
63
Helpful Examples
WHILE @@FETCH_STATUS = 0
BEGIN
IF @action = 'I'
-- process the INSERT event
INSERT CTREESQL..admin.holiday (
id,
description,
hol_month,
hol_day )
VALUES (
@id,
@description,
@hol_month,
@hol_day )
ELSE
BEGIN
IF @action = 'U'
-- process the UPDATE event
UPDATE CTREESQL..admin.holiday
SET
id = @id,
description = @description,
hol_month = @hol_month,
hol_day = @hol_day
WHERE id = @previd
ELSE
BEGIN
-- process the DELETE event
IF @action = 'D'
DELETE CTREESQL..admin.holiday
WHERE id = @previd
ELSE
BEGIN
SET @err_message = 'Invalid action: ' + @action
RAISERROR (@err_message,10, 1)
www.faircom.com
All Rights Reserved
64
Helpful Examples
END
END
END
-- remove the current event from the queue
DELETE FROM holiday_queue WHERE CURRENT OF holiday_queue_cursor
-- retrieve the next event
FETCH NEXT FROM holiday_queue_cursor
INTO @id, @description, @hol_month, @hol_day, @action,
@previd
END
-- close cursor
CLOSE holiday_queue_cursor
-- deallocate cursor
DEALLOCATE holiday_queue_cursor
GO
14. Create a Job to execute the linked server table sync. To create and schedule a Job for calling
the “usp_sync_linkedsrv” stored procedure created in the previous item to replicate the table
changes from the Microsoft SQL Server to c-treeACE SQL every 10 seconds, execute the
following commands.
exec msdb.dbo.sp_add_job
@job_name = 'CTREESQL replication',
@enabled=1
GO
exec msdb.dbo.sp_add_jobstep
@step_name = 'Check for changes to be replicated',
@subsystem = 'TSQL',
@command = 'exec dbo.usp_sync_linkedsrv',
@database_name = 'ctreeTest'
GO
exec msdb.dbo.sp_add_schedule
@schedule_name = 'CTREESQL replication schedule',
@enabled = 1,
@freq_interval = 1,
@freq_type = 4,
@freq_subday_type = 2,
www.faircom.com
All Rights Reserved
65
Helpful Examples
@freq_subday_interval = 10
GO
exec msdb.dbo.sp_attach_schedule
@schedule_name = 'CTREESQL replication schedule'
GO
exec msdb.dbo.sp_add_jobserver
@server_name = 'ENRICO-PC'
GO
5.2
Connect Microsoft 64-bit SQL Server 2005 to c-treeACE
SQL
 First configure your 32-bit driver as described in this article:
Configuring 32-bit ODBC Drivers on 64-bit Windows Versions (page 81)
 Using the SQL Server Import and Export Wizard, you will get a pop-up screen that is asking
for a Data Source.
 You will not see the 32-bit DSN in the drop down menu. Select ".Net Framework Data
Provider for ODBC". On most systems it's probably the top one in the list, however, you need
to scroll up to see it as the list usually displays in the middle.
 Enter further connection information on the resulting dialog screens.
 Under NamedConnection String there is a field for "dsn". In this field put the name of the DSN
created in Step 1.
 Click on Next and follow the rest of the instructions to copy the desired data.
5.3
ctKEEPOPEN File Mode to Retain Cached Server Data
The final close of a c-tree file causes all existing file contents (data records or index nodes) to be
flushed from cache to disk. A final close refers to a file close that causes the user count of the file
to drop to zero. For applications opening and closing files during operation, it is often times
advantageous for a file to remain cached for best performance. Many applications simply open a
file at startup within a "private" c-tree connection and then close the file at application end.
It is possible to have the file's data persist in cache even after a final close by including
ctKEEPOPEN bit in the splval member of the data file’s XCREblk. In this case, the final close
leaves the file open (without any user attached to the file) and any cached data will be retained.
When the file is again reopened, the data is immediately available for use saving expensive I/O
time reloading data and index cache pages. This frees the application from having to maintain
any state knowledge of the file.
www.faircom.com
All Rights Reserved
66
Helpful Examples
The file is always closed when the server terminates protecting any data in cache. To force a
ctKEEPOPEN file close, call the CloseCtFileByName()
http://docs.faircom.com/doc/ctreeplus/closectfilebyname.htm c-tree API function:
CloseCtFileByName(pTEXT filnam, pTEXT fileword)
It is possible to use the ctKEEPOPEN flag on the create, and then close and reopen the file
shared, but only if the file’s creation is not pending commit. In this case, the sequence would be
like:
XCREblk xcreblk[] = {
{ctMEMFILE, 0, 0, 104857600, 0,0,0,0,0,0, ctKEEPOPEN, 0,0,0,0,0},
{ctMEMFILE, 0, 0, 104857600, 0,0,0,0,0,0, ctKEEPOPEN, 0,0,0,0,0}
};
if (CreateIFileXtd8(&vcustomer,NULL,NULL,0,NULL,NULL,xcreblk))
{
ctrt_printf("\nCould not create file %d with error %d.\n",
isam_fil,isam_err);
}
else
{
CloseIFile(&vcustomer);
if ((eRet = OpenIFileXtd(&vcustomer,NULL,NULL,NULL)) != 0)
{
ctrt_printf("\nUNEXPECTED ERROR %d ON REOPEN.\n",eRet);
}
else
{
ctrt_printf("\nFile created.");
}
}
5.4
Notification Example
ctntfy reads input file ctntfy.in, which contains a list of servers and files to monitor.
Below is an example of an input file showing three servers and two files to monitor and their
corresponding target files to update.
;Server id
1
2
3
Server name
FAIRCOM1@localhost
FAIRCOM2@localhost
FAIRCOM3@localhost
;Source server id
1
1
1
1
Source file
Actions Target server id
vcusti
ADU
2
custmaster.dat ADU
2
vcusti
ADU
3
custmaster.dat ADU
3
Target file
vcusti
custmaster.dat
vcusti
custmaster.dat
2
2
2
2
vcusti
custmaster.dat ADU
vcusti
custmaster.dat ADU
ADU
vcusti
custmaster.dat
vcusti
custmaster.dat
3
3
3
vcusti
custmaster.dat ADU
vcusti
ADU
1
1
ADU
3
3
1
1
ADU
2
vcusti
custmaster.dat
vcusti
www.faircom.com
All Rights Reserved
67
Helpful Examples
3
custmaster.dat ADU
2
custmaster.dat
ctntfy creates a thread for each entry in the list of files to monitor. Each thread connects to the
source and target server and opens the source and target files, then enables monitoring of the
source file and reads queue entries as they arrive and processes them. The add processing has
been verified to work with non-TRANPROC and TRANPROC files.
This example doe not hand delete and update requests as changes to the queue information
must be provided for the utility to be able to find the record to delete or update in the target file. A
suggestion for how this can be accomplished is the following: if a key that does not allow
duplicates is available, include with a delete or update queue entry the key number and key value
that can be used to find the record to delete or update in the target table.
5.5
Moving a HP-UX c-treeACE SQL Database to Windows
c-treeACE is a flexible database engine capable of running on many platforms and system
architectures. It is frequently useful to move a database from a Unix based high low architecture
to a Windows low-high Intel architecture. There are a couple issues with doing so:
 File headers
 Binary data
FairCom has long provided utilities for doing such data and index file conversions, namely,
ctunf1. To apply these to a full c-treeACE SQL database, perform the following steps.
1. Shutdown the server. Check for a clean shutdown logged in CTSTATUS.FCS with the final
messages:
- User# 00016
- User# 00016
Maximum memory used was 230102654 bytes
2. Backup the database directory, making sure to include files ctdbdict.fsd, <dbname>.dbs/*.dat,
<dbname>.dbs/*.idx, and <dbname>.dbs/SQL_SYS/<dbname>.fdd.
3. Copy ctunf1 and convert.sh into the same directory as the server. (See below for convert.sh)
4. Run ./convert.sh <dbname>
5. Copy ctdbdict.fsd and the <dbname>.dbs folder to the windows machine if no errors
occurred.
6. Start the Windows c-treeACE Server process.
7. Use the ctpath utility to change paths from ./<dbname>.dbs/SQL_SYS/ to
.\<dbname>.dbs\SQL_SYS\
8. Use the ctpath utility to change paths from .<dbname>.dbs/ to .\<dbname>.dbs\
convert.sh (page 68)
convert.sh
#!/bin/sh
# usage: convert.sh DATABASE
# runs ctunf1 on a database and session dictionary
# converts from HIGH-LOW to LOW-HIGH ENDIAN-NESS
err(){
echo ERROR converting file $1
echo Check convert.log for error code
www.faircom.com
All Rights Reserved
68
Helpful Examples
exit 1
}
usage(){
echo usage:
echo convert DATABASE
echo runs ctunf1 on DATABASE and session dictionary
echo converts from HIGH-LOW to LOW-HIGH ENDIANNESS.
exit 1
}
dbname=$1
echo ${dbname}
if [ ! -d ${dbname}.dbs ]; then
echo Database ${dbname}.dbs not found
usage
fi
if [ ! -f ${dbname}.dbs/SQL_SYS/${dbname}.fdd ]; then
echo Database Dictionary not found
exit 1
fi
if [ ! -f ctdbdict.fsd ]; then
echo Session dictionary ctdbdict.fsd not found
exit 1
fi
echo
echo
echo
echo
echo
echo
echo
read
STARTING DATABASE ENDIAN CONVERSION.
ENSURE SERVER WAS SHUTDOWN CLEANLY.
ENSURE DATABASE $dbname HAS BEEN BACKED UP.
THIS UTILITY CONVERTS FILES IN PLACE.
ANY ERROR DURING CONVERSION WILL CORRUPT DATA.
PRESS ctrl-z TO EXIT.
PRESS ENTER TO CONTINUE CONVERSION.
echo CONVERTING DATABASE DICTIONARY
./ctunf1 ./${dbname}.dbs/SQL_SYS/${dbname}.fdd 8 L Y B2 512 >convert.log
if [ $? != 0 ]; then
err ${dbname}.dbs/SQL_SYS/${dbname}.fdd
fi
echo CONVERTING ALL DATA... Please be patient
for i in ./${dbname}.dbs/*.dat
do
./ctunf1 $i 8 L Y B2 256 >>convert.log
if [ $? != 0 ]; then
err $i
fi
done
echo DATA FILE CONVERSION SUCCESS!
echo CONVERTING INDEX FILES
for i in ./${dbname}.dbs/*.idx
do
if [ $? != 0 ]; then
err $i
fi
done
www.faircom.com
All Rights Reserved
69
Helpful Examples
echo INDEX FILE CONVERSION SUCCESS!
echo CONVERTING Session dictionary
./ctunf1 ctdbdict.fsd 8 L Y B2 512 >>convert.log
if [ $? != 0 ]; then
err ctdbdict.fsd
fi
echo CONVERSION COMPLETE!
exit 0
5.6
Keep a CTUSER Library Open
CT_USER can execute whatever user code is placed into it. Often an input parameter is used as
a command string indicating what action to take. To allow the library to remain open for
performance reasons, simply add the following two command string options:
1. ctuserload: When CT_USER is called with this option, call dlopen() on your shared library.
Save the handle (probably a global variable) such that you can unload the library later.
2. ctuserunload: when CT_USER is called with this option, call dlclose() on your shared library
(using the handle you saved when the ctuserload option was specified).
This has the effect of keeping the CT_USER shared library loaded because the system maintains
a reference count and so the dlclose() call only unloads a shared library when the number of
closes matches the number of opens.
5.7
Utility To Search Logs For Open Transactions
FairCom developers have encountered situations where it is necessary to determine the
existence of open transactions pending with the c-tree Server. On such situation is cases where a
single open transaction has resulted in the number of transaction logs to accumulate beyond the
capacity of the I/O system, causing a c-tree Server failure.
Diagnosing recent c-tree Server replication enhancements is another situation. The c-tree Server
replication facilities are transaction log based. That is, contents of the transaction logs can be
read and applied to a remote server through the c-tree Plus Replication SDK. During
development of a replication enabled application, it can prove useful to determine which open
transactions are pending.
The c-tree Plus Open Transaction Search utility, ctodmp, was created to search and identify
open transactions pending in c-tree transaction logs.
ctodmp is very similar to ctldmp except that instead of dumping the contents of transaction logs,
ctodmp searches for unmatched transaction begin and end entries. Specifically, ctodmp looks
for TRANBEG, TRANEND and TRANABT entries as well as searching checkpoints for open
(and/or vulnerable) transactions. ctodmp provides a list unmatched entries. These unmatched
entries are specified by transaction number, location in the log files, and user thread handle, and
are classified as:
 BEG - found TRANBEG, but no TRANEND or TRANABT
 END - found TRANEND, but no TRANBEG
 ABT - found TRANABT, but no TRANBEG
www.faircom.com
All Rights Reserved
70
Helpful Examples
 CHK - found transaction in checkpoint, but no subsequent TRANEND or TRANABT. This is
ambiguous, since the transaction may have already committed, but still be awaiting related
buffer flushes or a TRANABT is not part of the log set scanned by ctodmp. The user thread
handle is for the checkpoint thread, not the actual user.
5.8
c-treeACE OEM Installation Notes - V9 through V11
c-treeACE Database Engine
The c-treeACE database engine is designed for ease of deployment and administration. In many
cases, a deployment can simply copy the server executable and configuration, start the server
process and walk away for unattended operation. Described below are the specific files and
options available for the deployment process to successfully install the c-treeACE database
engine as part of an OEM total package deployment.
Required Executable Files to Copy
The required c-treeACE server files will be found in the \bin\ace\sql directory (\bin\ace\isam for
non-SQL installations). The files listed below are the only required files for a c-treeACE database
engine installation. These can be placed together in any single directory with appropriate
permissions.
 ctreesql.exe
 ctreedbs.dll
 CTSRES.DLL
 ctsrmc.dll
 F_TCPIP.DLL
 FSHAREMM.DLL
c-treeACE Configuration File
A c-treeACE configuration file provides directives for various server options. This file typically
resides in the same directory as the server executable, however, it may be located elsewhere and
pointed to by either a command line option when starting the server, or an environment variable
(refer to the c-treeACE Server Administrator's Guide for details).
 ctsrvr.cfg
c-treeACE Administrator Utilities
The following executables are provided for the c-treeACE administrator. These can be located in
a central secured location to protect the integrity of the c-treeACE installation.
 ctcpvf.exe - generates the master server password for encryption.
 ctcfgset.exe - creates an encrypted server configuration file
 fcactvat.exe - command line server activation utility
 Activate.exe - GUI activation utility (Windows only)
Note: The ctntinst.exe utility no longer ships with the product as of V10.3. The Microsoft
www.faircom.com
All Rights Reserved
71
Helpful Examples
Windows Services Control Panel applet is the preferred method for service installation,
configuration, and other administration, such as starting/stopping the service.
Many other administrator utilities are available, including statistics monitoring, administrator utility,
and backup and restore utilities. These are located in the \tools\cmdline\admin\client directory of
the c-treeACE installation. The suite of GUI based utilities is also available for distribution.
Note: The c-treeACE restore utility, ctrdmp.exe, is available from the command line tools
package in \tools\cmdline\admin\standalone.
c-treeACE Java Environment
c-treeACE SQL Stored Procedures and Triggers require a functioning Java environment. This is
not supplied with the c-treeACE installation and should be obtained and installed independently.
Java 6 (1.6) is the recommended Java framework. Three (3) server configuration environment
settings specified in ctsrvr.cfg enable these features by providing the paths for the required Java
components.
 SETENV CLASSPATH=<directory path>\ctreeSQLSP.jar
 SETENV JVM_LIB=<directory path>\jre\bin\server\jvm.dll
 SETENV JAVA_COMPILER=<directory path>\bin\javac.exe
To create stored procedures requires the full Java SDK with the javac.exe compiler. To execute
stored procedures and triggers requires only the Java run-time engine (JRE).
The ctreeSQLSP.jar file is required for creating or executing Java stored procedures and triggers
and will be found in the \bin\ace\sql\classes directory of the default c-treeACE installation. This
file can be installed wherever appropriate for your installation and is referenced with the above
configuration.
Creating the c-treeACE Windows Service
There are several options available to install the c-treeACE database engine as a Windows
Service.
 Use the Windows Service Control manager utility, sc.exe, provided with your Windows
installation. For example:
>sc <windows UNC> create "c-treeACE Database Engine V9" binPath=
c:\FairCom\V9.2.0\win32\bin\ace\sql\ctreesql.exe start= auto
DisplayName= "c-treeACE Database Engine"
 Create a custom service with these details. The Description and Display strings can be
modified to match your application requirements.
www.faircom.com
All Rights Reserved
72
Helpful Examples
[HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\ctreesql.exe]
Note: Use caution when specifying that the service can interact with the desktop. Newer
versions of Windows do not allow service interaction and any displayed windows that require
interaction will "hang" the server as they will not be displayed.
 Use the FairCom ctntinst.exe utility (DEPRICATED).
usage: ctntinst [ <executableName> ] <option> [ <serviceName> ]
where <executableName> is one of the following:
ctsrvr.exe
ctreesql.exe
FairCom (non-SQL) c-treeACE Server.
FairCom c-treeACE SQL Server.
where <option> is one of the following:
-install [-u<username> [-p<password>]]
Install the FairCom c-treeACE Server service.
-remove
-auto
Uninstall the FairCom c-treeACE Server service.
Set service to start up automatically.
-demand
-showconfig
-status
Set service to start up on demand.
Show service settings.
Show current status of service.
-start
-stop
Start the FairCom c-treeACE Server service.
Stop the FairCom c-treeACE Server service.
and <serviceName> is an optional service name.
If not specified, <serviceName> defaults to ctreeServer, ctreeSQLServer, or
ctreeJQLServer based on specified executable name.
www.faircom.com
All Rights Reserved
73
Helpful Examples
c-treeACE SQL ADO.NET Data Provider
The c-treeACE ADO.NET Driver integrates directly into the Microsoft Development environments
Visual Studio 2005 and Visual Studio 2008.
Files Installed:
 All files in \bin\sql.ado.net
Registry Keys
The following Windows registry keys are are required to integrate the c-treeACE SQL ADO.NET
Data Provider into Visual Studio 2005 (8.0) and 2008 (9.0):
 SOFTWARE\Microsoft\VisualStudio\8.0\DataProviders\{0EBAAB6E-CA80-4b4a-8DDF-CBE6
BF058C77}
• (Default) = .NET Framework Data Provider for FairCom c-treeACE
• Codebase = Ctree.VisualStudio.Data.Dll
• Description = Provider_Description, Ctree.VisualStudio.Data.Resources
• DisplayName = Provider_DisplayName, Ctree.VisualStudio.Data.Resources
• InvariantName = Ctree.Data.SqlClient
• ShortDisplayName = Provider_ShortDisplayName, Ctree.VisualStudio.Data.Resources
• Technology = {77AB9A9D-78B9-4ba7-91AC-873F5338F1D2}
BF058C77}\SupportedObjects\DataConnectionProperties
• (Default) = Ctree.VisualStudio.Data.FcDataConnectionProperties
BF058C77}\SupportedObjects\DataConnectionSupport
• (Default) = Ctree.VisualStudio.Data.FcDataConnectionSupport
BF058C77}\SupportedObjects\DataConnectionUIControl
• (Default) = Ctree.VisualStudio.Data.FcDataConnectionUIControl
BF058C77}\SupportedObjects\DataObjectSupport
BF058C77}\SupportedObjects\DataSourceInformation
• (Default) = Ctree.VisualStudio.Data.FcDataSourceInformation
BF058C77}\SupportedObjects\DataViewSupport
 SOFTWARE\Microsoft\VisualStudio\8.0\DataSources\{516F984E-FE16-4acb-ACFA-BBB905
4C68B3}\SupportingProviders\{0EBAAB6E-CA80-4b4a-8DDF-CBE6BF058C77}
4C68B3}
• (Default) = FairCom c-treeACE
• DefaultProvider = {0EBAAB6E-CA80-4b4a-8DDF-CBE6BF058C77}
www.faircom.com
All Rights Reserved
74
Helpful Examples
BF058C77}
• (Default) = .NET Framework Data Provider for FairCom c-treeACE
• Codebase = Ctree.VisualStudio.Data.Dll
• Description = Provider_Description, Ctree.VisualStudio.Data.Resources
• DisplayName = Provider_DisplayName, Ctree.VisualStudio.Data.Resources
• InvariantName = Ctree.Data.SqlClient
• ShortDisplayName = Provider_ShortDisplayName, Ctree.VisualStudio.Data.Resources
• Technology = {77AB9A9D-78B9-4ba7-91AC-873F5338F1D2}
BF058C77}\SupportedObjects\DataConnectionProperties
• (Default) = Ctree.VisualStudio.Data.FcDataConnectionProperties
BF058C77}\SupportedObjects\DataConnectionSupport
• (Default) Ctree.VisualStudio.Data.FcDataConnectionSupport
BF058C77}\SupportedObjects\DataConnectionUIControl
• (Default) = Ctree.VisualStudio.Data.FcDataConnectionUIControl
BF058C77}\SupportedObjects\DataObjectSupport
BF058C77}\SupportedObjects\DataSourceInformation
• (Default) = Ctree.VisualStudio.Data.FcDataSourceInformation
BF058C77}\SupportedObjects\DataViewSupport
4C68B3}
• (Default) = FairCom c-treeACE
• DefaultProvider = {0EBAAB6E-CA80-4b4a-8DDF-CBE6BF058C77}
GAC (Global Assembly Cache)
Register the \bin\sql.ado.net\Ctree.Data.SqlClient into the .NET Framework GAC using the
GACUTIL.EXE utility provided by Microsoft.
.NET Framework machine.config Update
Make the following additions to the machine.config .NET framework configuration file found in the
following Windows directory:
C:\Windows\Microsoft.NET\Framework\v2.0.50727\CONFIG
Add the following XML tags:
• Into <configuration> <configSections>
www.faircom.com
All Rights Reserved
75
Helpful Examples
 <section name="ctree.data.sqlclient"
type="System.Data.Common.DbProviderConfigurationHandler, System.Data,
Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>
• Into <configuration><system.data><DbProviderFactories>
 <add name="c-treeACE Data Provider" invariant="Ctree.Data.SqlClient"
description=".Net Framework Data Provider for FairCom c-treeACE"
type="Ctree.Data.SqlClient.CtreeSqlClientFactory, Ctree.Data.SqlClient,
Version=9.1.1.0, Culture=neutral, PublicKeyToken=0ce73727dc1039a8"/>
c-treeACE SQL ODBC Driver
The installer for the c-treeACE SQL ODBC Driver should register the driver into the Windows
ODBC Administrator and create a data source using the driver. Below are the registry entries
required for installation of the driver:
Driver
[ HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI ]
"c-treeACE ODBC Driver"
• Driver: \bin\sql.odbc\ctodbc9.dll
• Setup: \bin\sql.odbc\ctsetup9.dll
Data Source
[ HKEY_CURRENT_USER\Software\ODBC\ODBC.INI\c-treeACE ODBC Driver ]
"c-treeACE ODBC Driver"
• Driver: "c-treeACE ODBC Driver" (references the driver registry entry above)
• Description: "c-treeACE ODBC Driver"
• Password: "ADMIN"
• User ID: "ADMIN"
• Database: "ctreeSQL"
• Host: "localhost"
www.faircom.com
All Rights Reserved
76
Helpful Examples
• Service: "6597"
c-treeACE SQL JDBC Driver
The c-treeACE SQL JDBC driver is a full type 4 (native Java) JDBC driver, and as such, is
platform independent. The c-treeACE SQL JDBC Driver jar file is located in the following
c-treeACE installation directory:
 \lib\sql.jdbc\ctreeJDBC.jar
This file can be located anywhere in an application installation and is referenced solely with an
appropriate Java CLASSPATH specification. For example:
 CLASSPATH=.;C:\FairCom\Vx.x.x\win32\lib\sql.jdbc\ctreeJDBC.jar (where Vx.x.x refers to
the c-treeACE version)
The c-treeACE SQL JDBC Driver file requires no other changes to any other system component.
www.faircom.com
All Rights Reserved
77
6.
Configuration and Tuning
6.1
V10 and V11 Configuration Recommendations
c-treeACE V10 introduced numerous performance gains and tightened security measures. To
take a advantage of the power-packed release, you will need to be sure your system is
configured correctly. Other options have either been deprecated or changed in behavior.
Customers moving from prior releases should consider the following options and changes in
configuring their V10 servers.
Performance
Shared Memory on Unix Systems
V10 now supports shared memory for localhost application connections. Enabling this should give
a major performance boost for those applications. The following keyword enables this feature:
COMM_PROTOCOL
FSHAREMM
Memory Suballocation Subsystem
There is a configuration for our memory suballocator lists. We strongly recommend testing with
this option for performance comparison. Set this value to the number of CPUs available to the
c-treeACE process for optimal advantage.
MEMORY_HASH
<N>
 Memory Suballocator Configuration
http://docs.faircom.com/doc/v10ace/index.htm#57185.htm
Data Integrity
Enhanced Automatic Recovery
The RECOVER_DETAILS setting is now default. This option can be removed from previous
configuration files.
 RECOVER_DETAILS Default http://docs.faircom.com/doc/v10ace/index.htm#54405.htm
LOGIDX Improves Recovery
In V10, a mode called LOGIDX is now enabled by default. This potentially adds slightly more
overhead than you had in prior versions. However, the payoff is great during recovery. We
recommend leaving this default in place.
 LOGIDX Default http://docs.faircom.com/doc/v10ace/index.htm#57147.htm
www.faircom.com
All Rights Reserved
78
RECOVER_MEMLOG Speeds Recovery Times
We also recommend adding the RECOVER_MEMLOG option to your configuration. It can greatly
speed recovery times and has no effect during normal operation.
Access Security
Encrypted User/Group Information
ADMIN_ENCRYPT YES is the default in V10. By default, this option encrypts the user group
information file FAIRCOM.FCS using FairCom's "camo" encryption. AES encryption is available if
ADVANCED_ENCRYPTION YES is specified in ctsrvr.cfg.
 Encrypted User/Group Information http://docs.faircom.com/doc/v10ace/#57798.htm
To disable this encryption level, add ADMIN_ENCRYPT NO to your configuration file.
Guest Logons Denied
Guest logons (logons without any provided user name) are now denied by default. To enable
applications that don't use c-treeACE user authentication you now need to explicitly allow those
connections.
GUEST_LOGON YES
Guest Logons Denied http://docs.faircom.com/doc/v10ace/index.htm#55298.htm
Compatibility
Transaction Log Writing
The COMPATIBILITY SYNC_LOG setting is now deprecated. Use COMPATIBILITY
LOG_WRITETHRU (which has exactly the same behavior) :
 SYNC_LOG Deprecated http://docs.faircom.com/doc/v9ace/#14747.htm
Commit Read Locks
Commit read locks prevent dirty record reads during the commit phase of a transaction.
COMPATIBILITY COMMIT_READ_LOCK is now default. You can remove this option from previous
configuration files if used (introduced in V9).
 Commit Read Locks http://docs.faircom.com/doc/v9ace/#51840.htm
Caching: TDATA_WRITETHRU vs. UNBUFFERED_IO
TDATA_WRITETHRU uses the file system cache. The file is placed into a mode that causes the
write to go to file system cache and then to disk before returning; the data still resides in file
system cache.
UNBUFFERED_IO completely bypasses the file system cache.
www.faircom.com
All Rights Reserved
79
6.2
c-treeACE Server Configuration Recommendations
The following options can be defined in the c-treeACE Server configuration file ctsrvr.cfg and
should be taken into consideration for all new and existing c-treeACE customers:
SKIP_MISSING_FILES
Do not operate with SKIP_MISSING_FILES enabled in the ctsrvr.cfg configuration file by default.
This configuration may cause files to be inadvertently skipped during recovery, making it difficult
to restore the database back to a consistent state. This keyword should only be utilized when
confirmed necessary (by reviewing specific error messages in the CTSTATUS.FCS status log
file), and then promptly removing it. (Commenting the keyword in the configuration file is
suggested, as it is then readily available if absolutely needed.)
KEEP_LOGS
To take fullest advantage of c-tree’s recovery options, it is advisable to keep as many transaction
logs as practical -- up through the last two backups if possible. The c-tree restore process can
start with an existing backup and roll forward through remaining logs if available, restoring data to
the latest possible time point.
FORCE_LOGIDX
FairCom has a feature that reduces the amount of time it takes for automatic recovery to
complete, especially in systems with high transaction rates. By adding the keyword
FORCE_LOGIDX ON to your ctsrvr.cfg file, the c-tree Server will store a few additional bytes of
information per index node within the c-treeACE transaction logs, which will greatly reduce the
amount of time automatic recovery will take. There is no performance loss with the production
system for enabling this feature and you do not need to rebuild indexes to enable this feature.
FORCE_LOGIDX supports these settings:
 ON forces all indices to use LOGIDX entries.
 OFF forces all indices not to use LOGIDX entries.
 NO uses existing file modes to control LOGIDX entries.
Note: LOGIDX is ON by default with c-treeACE V9.2 and later.
6.3
Large Page Support to Improve Large Cache
Performance
Symptom
Pages being stolen by another process or the file system cache.
www.faircom.com
All Rights Reserved
80
Diagnose
Monitor the RSS memory of the c-treeACE process (ps v PID) to see if it drops at the times of
poor performance.
Solution
Set the c-treeACE SQL executable and/or the system for large page support.
64-bit Windows Filesystem Behavior
On 64-bit Windows systems, by default, the Windows file system cache can grow without limit,
causing Windows to "steal" memory pages from user processes such as c-treeACE. The reported
symptom is that c-treeACE sometimes becomes unexpectedly slow, in particular for accessing
memory files and cached data.
Microsoft provides a utility that limits the file system cache size. The link below can be used to
download this utility:
Dynamic Cache Service
http://www.microsoft.com/downloads/details.aspx?FamilyID=e24ade0a-5efe-43c8-b9c3-5d0ecb2f
39af&displaylang=en
6.4
Configuring 32-bit ODBC Drivers on 64-bit Windows
Versions
With 64-bit versions of Windows, the previous 32-bit ODBC Driver Manager is now located in a
different location, and is not used by default. To configure a 32-bit driver on these systems, use
the following steps:
 Execute: %WINDIR%\syswow64\odbcad32.exe
 Create a DSN using the 32-bit version of the Administrator
See Also
 DSN-less ODBC Connections (http://docs.faircom.com/doc/ctpodbc/index.htm#38030.htm).
6.5
Relocating Transaction Logs
Transaction logs can be relocated to a different physical drive so they reside in a different
directory than the data. Relocating to a different physical drive can improve performance by
giving you two channels to write the data. Use these configuration keywords to relocate
transaction logs:
 LOG_EVEN (http://docs.faircom.com/doc/ctserver/#27941.htm)
 LOG_ODD (http://docs.faircom.com/doc/ctserver/#27943.htm)
 START_EVEN (http://docs.faircom.com/doc/ctserver/#27980.htm)
 START_ODD (http://docs.faircom.com/doc/ctserver/#27982.htm)
www.faircom.com
All Rights Reserved
81
In V10.3 and later, these configuration options can include an environment variable name that will
be substituted with its value when the configuration file is read.
See the c-treeACE Server Administrator's Guide for information about these keywords.
6.6
Maximum Number of Indices Per Data File
Occasionally data files require a large number of indexes. Commencing with c-treeACE V10.3,
the number of indices default limit was increased from 32 to 64. Customers using the c-treeACE
Server can use the MAX_DAT_KEY keyword to change the limit on the number of indices per data
file.
If this limit is too low, the typical error code that would be seen is error 107, IDRK_ERR "too
many keys for ISAM data file."
This value affects the amount of memory that is allocated to store ISAM index state information. It
can be increased without a major impact on performance unless c-treeACE Server is being run in
an environment with very little memory (e.g., certain embedded applications).
Note: In the standalone model, MAX_DAT_KEY is a compile-time setting. If this value is changed,
the code must be recompiled with the new setting.
www.faircom.com
All Rights Reserved
82
Consider connecting a ctadmn client to the server and leaving it connected so that client activity can be
monitored even if the server enters a state in which it refuses client connections.
7.
Monitoring Performance
Below are recommended monitoring procedures for system administrators to follow to ensure
proper monitoring of c-treeACE:
 Use system tools and c-tree Server utilities to monitor the state of the c-treeACE process.
The ctadmn and ctstat utilities can be used for this purpose.
 Use system tools and c-tree Server utilities to monitor the state of c-tree clients and client
activity. The ctadmn utility and server configuration keywords can be used for this purpose.
 Use system tools and c-treeACE utilities to monitor system and c-treeACE resource usage.
The ctstat utility can be used to collect historical system resource usage and performance
statistics in order to detect unexpected changes in resource usage or performance.
 Monitor the c-tree Server status log for unexpected warning and error messages. The
ctsysm utility can be used for this purpose.
 Monitor c-tree API function return codes. The application should log occurrences of
unexpected errors.
7.1
Monitoring System Resource Usage
c-treeACE relies upon system resources such as the CPU, disk, memory and the network.
Typically each system includes its own tools for monitoring system resources. The following
sections provide an overview of system-specific monitoring tools for system resources.
Monitoring CPU Usage
The system administrator should know the expected pattern of CPU use by c-treeACE during
normal operation of the system. CPU metrics such as user time, system time, I/O wait time, idle
time, and context switches for the server process should be tracked so that unexpected changes
in CPU usage can be detected, analyzed, and corrected.
Solaris supports the following utilities for monitoring CPU usage. Other Unix systems support
these and similar utilities:
 mpstat reports per-processor statistics including counts for interrupts, context switches, spins
on mutexes and reader/writer locks, system calls, and user/system/wait/idle times.
 prstat reports active process statistics including process state, priority, number of lightweight
processes, and CPU usage.
 top displays the top processes on the system and periodically updates this information. Raw
CPU percentage is used to rank the processes.
 ps prints information about active processes.
The Windows Performance Monitor utility (perfmon) can be used to monitor CPU usage. The
Processor performance object maintains counters for each CPU. The available counters include
the following (descriptions taken from the Performance Monitor’s explanatory text):
www.faircom.com
All Rights Reserved
83
 % Processor Time is the percentage of elapsed time that the processor spends to execute a
non-Idle thread. It is calculated by measuring the duration of the idle thread is active in the
sample interval, and subtracting that time from interval duration. (Each processor has an
idle thread that consumes cycles when no other threads are ready to run). This counter is the
primary indicator of processor activity, and displays the average percentage of busy time
observed during the sample interval. It is calculated by monitoring the time that the service is
inactive, and subtracting that value from 100%.
 % Privileged Time is the percentage of elapsed time that the process threads spent executing
code in privileged mode. When a Windows system service in called, the service will often
run in privileged mode to gain access to system-private data. Such data is protected from
access by threads executing in user mode. Calls to the system can be explicit or implicit,
such as page faults or interrupts. Unlike some early operating systems, Windows uses
process boundaries for subsystem protection in addition to the traditional protection of user
and privileged modes. Some work done by Windows on behalf of the application might
appear in other subsystem processes in addition to the privileged time in the process.
 % User Time is the percentage of elapsed time the processor spends in the user mode. User
mode is a restricted processing mode designed for applications, environment subsystems,
and integral subsystems. The alternative, privileged mode, is designed for operating system
components and allows direct access to hardware and all memory. The operating system
switches application threads to privileged mode to access operating system services. This
counter displays the average busy time as a percentage of the sample time.
Monitoring Disk Usage
The system administrator should know the expected pattern of disk use by the c-tree Server
during normal operation of the system. Expected data and index file sizes and disk I/O should
be tracked so that unexpected changes in disk usage can be detected, analyzed, and corrected.
Solaris supports the following utilities for monitoring disk usage. Other Unix systems support
these and similar utilities:
 vmstat reports virtual memory statistics regarding process, virtual memory, disk, trap, and
CPU activity.
 iostat iteratively reports terminal, disk, and tape I/O activity, as well as CPU utilization.
The Windows Performance Monitor utility (perfmon) can be used to monitor system disk usage.
The PhysicalDisk performance object maintains counters for each physical disk. The available
counters include the following (descriptions taken from the Performance Monitor’s explanatory
text):
 % Disk Read Time is the percentage of elapsed time that the selected disk drive was busy
servicing read requests.
 % Disk Write Time is the percentage of elapsed time that the selected disk drive was busy
servicing write requests.
 % Idle Time reports the percentage of time during the sample interval that the disk was idle.
 Avg. Disk Queue Length is the average number of both read and write requests that were
queued for the selected disk during the sample interval.
The LogicalDisk performance object maintains counters for each logical disk. The available
counters include the following:
www.faircom.com
All Rights Reserved
84
 Free Megabytes displays the unallocated space, in megabytes, on the disk drive in
megabytes. One megabyte is equal to 1,048,576 bytes.
 Current Disk Queue Length is the number of requests outstanding on the disk at the time the
performance data is collected. It also includes requests in service at the time of the collection.
This is a instantaneous snapshot, not an average over the time interval. Multi-spindle disk
devices can have multiple requests that are active at one time, but other concurrent requests
are awaiting service. This counter might reflect a transitory high or low queue length, but if
there is a sustained load on the disk drive, it is likely that this will be consistently high.
Requests experience delays proportional to the length of this queue minus the number of
spindles on the disks. For good performance, this difference should average less than two.
The Cache performance object maintains counters for the file system cache. The available
counters include the following:
 Data Flushes/sec is the rate at which the file system cache has flushed its contents to disk as
the result of a request to flush or to satisfy a write-through file write request. More than one
page can be transferred on each flush operation.
 Lazy Write Flushes/sec is the rate at which the Lazy Writer thread has written to disk. Lazy
Writing is the process of updating the disk after the page has been changed in memory, so
that the application that changed the file does not have to wait for the disk write to be
complete before proceeding. More than one page can be transferred by each write
operation.
In addition to system tools available for monitoring disk usage, the c-tree Server supports options
to limit disk usage. The server’s Disk Full feature offers three levels of control over disk full
checks:
 The DISK_FULL_LIMIT keyword provides checking on all files.
 The DISK_FULL_VOLUME keyword sets a volume-specific limit that overrides the
system-wide limit.
 The file-specific check (set by creating a file using an Xtd8 create function with the dskful
member of the XCREblk structure set to the desired file size limit in bytes) overrides the
system-wide and volume-specific checks.
If extending the size of the file would leave less than the specified threshold, then the write
operation causing the file extension fails, returning SAVL_ERR (583).
Monitoring Memory Usage
The system administrator should know the expected memory use by the c-tree Server during
normal operation of the system. Memory use should be tracked so that unexpected changes in
memory usage can be detected, analyzed, and corrected.
Solaris supports the following utility for monitoring memory usage. Other Unix systems support
similar utilities:
 vmstat reports virtual memory statistics regarding process, virtual memory, disk, trap, and
CPU activity.
The Windows Performance Monitor utility (perfmon) can be used to monitor system memory
usage. The Memory performance object maintains counters for memory usage. The available
www.faircom.com
All Rights Reserved
85
counters include the following (descriptions taken from the Performance Monitor’s explanatory
text):
 AvailableMBytes is the amount of physical memory available to processes running on the
computer, in Megabytes, rather than bytes as reported in Memory\\Available Bytes. It is
calculated by adding the amount of space on the Zeroed, Free, and Stand by memory lists.
Free memory is ready for use; Zeroed memory are pages of memory filled with zeros to
prevent later processes from seeing data used by a previous process; Standby memory is
memory removed from a process’ working set (its physical memory) on route to disk, but is
still available to be recalled. This counter displays the last observed value only; it is not an
average.
 Pages/sec is the rate at which pages are read from or written to disk to resolve hard page
faults. This counter is a primary indicator of the kinds of faults that cause system-wide delays.
It is the sum of Memory\\Pages Input/sec and Memory\\Pages Output/sec. It is counted in
numbers of pages, so it can be compared to other counts of pages, such as Memory\\Page
Faults/sec, without conversion. It includes pages retrieved to satisfy faults in the file system
cache (usually requested by applications) non-cached mapped memory files.
In addition to the available system monitoring tools, the c-tree Server supports monitoring server
memory usage using the c-tree Plus SystemConfiguration() API function. See the section
"Monitoring c-tree Server Using SystemConfiguration API" (page 88) for more details.
See Also
 Memory Use of Linux Processes (page 190)
Monitoring Network Usage
The system administrator should know the expected network use by the c-tree Server during
normal operation of the system. Network use should be tracked so that unexpected changes in
network usage can be detected, analyzed, and corrected.
Solaris supports the following utility for monitoring network usage. Other Unix systems support
similar utilities:
 netstat displays the contents of network-related data structures in various formats, depending
on the specified options.
The Windows Performance Monitor utility (perfmon) can be used to network usage. The Network
Interface performance object maintains counters for network usage. The available counters
include the following (descriptions taken from the Performance Monitor’s explanatory text):
 Bytes Received/sec is the rate at which bytes are received over each network adapter,
including framing characters. Network Interface\\Bytes Received/sec is a subset of Network
Interface\\Bytes Total/sec.
 Bytes Sent/sec is the rate at which bytes are sent over each each network adapter, including
framing characters. Network Interface\\Bytes Sent/sec is a subset of Network Interface\\Bytes
Total/sec.
 Output Queue Length is the length of the output packet queue (in packets). If this is longer
than two, there are delays and the bottleneck should be found and eliminated, if possible.
www.faircom.com
All Rights Reserved
86
Since the requests are queued by the Network Driver Interface Specification (NDIS) in this
implementation, this will always be 0.
 Packets Outbound Errors is the number of outbound packets that could not be transmitted
because of errors.
 Packets Received Errors is the number of inbound packets that contained errors preventing
them from being deliverable to a higher-layer protocol.
 Packets Received/sec is the rate at which packets are received on the network interface.
 Packets Sent/sec is the rate at which packets are sent on the network interface.
Other System Monitoring Options
In addition to the system monitoring utilities described in the above sections that are target
specific resource monitoring, there are also other system utilities that can be used to monitor a
variety of system resources.
On Solaris and Unix systems, the sar utility is useful for monitoring system activity, including
system buffer transfer activity, cache hit ratios, system calls, and device activity.
The Windows Performance Monitor includes performance objects such as the Object, Process,
Server, System, and Thread objects that can be used to monitor system resource usage in
specific ways. Also, the Windows Task Manager can be used to monitor system resource usage.
7.2
Monitoring c-treeACE Internal Resource Usage
c-treeACE supports utilities and APIs that can be used to monitor its internal resources (such as
data and index caches, lock table, transaction and file activity). The following sections explain
how to use these utilities and APIs to monitor the server’s internal resources.
Monitoring c-treeACE Using Snapshot Support
The c-treeACE Performance Snapshot capability enables the capture of performance monitoring
data using a combination of configuration file options and calls to the SnapShot() function. The
performance data can be captured automatically at specified intervals or on demand.
Performance data maintained and made available by the server’s snapshot capability includes
the following: File lock statistics, transaction time histogram, transaction commit delay statistics,
transaction log I/O, function timings, data and index cache details, disk read and write statistics,
and communication read and write statistics.
c-treeACE supports the snapshot capability on systems that support 8-byte integers. On systems
that do not support a high-resolution timer, some aspects of the snapshot are not available.
Snapshot Configuration File Options
Server configuration file options can be used to capture automatic system snapshot data.
When SNAPSHOT_INTERVAL <interval in minutes> is specified in the server configuration
file, an automatic snapshot thread performs a system snapshot after each interval. The automatic
system snapshot is written to the c-tree Server’s system event log (SYSLOG) files.
www.faircom.com
All Rights Reserved
87
The following configuration entries can be used multiple times to include snapshot details to for
users and files in the snapshot output. Use a pattern of ‘*’ to activate monitoring for all user ID’s
or files.
SNAPSHOT_USERID <user ID>
SNAPSHOT_FILENAME <file name>
Specifying DIAGNOSTICS SNAPSHOT_SHUTDOWN in the server configuration file causes the
server to log system snapshot details to the file SNAPSHOT.FCS when the server shuts down.
Snapshot API Function Options
The SnapShot() API function can be used to control automatic snapshots, overriding
configuration options (if any), and can capture on-demand server performance data to the
SYSLOG files, to the human-readable SNAPSHOT.FCS file, or as a return to the calling program.
See the c-tree Plus Function Reference Guide for full details on using the SnapShot() API
function.
Monitoring c-treeACE Using ctstat Utility
The ctstat utility is a client utility used to display statistics collected by c-treeACE. Depending on
the specified command-line options, ctstat displays file, system, user, or function timing statistics.
ctstat uses the SnapShot API function to log server statistics to the server’s system event log,
then reads the statistics from the logs and displays them in human-readable format.
See Performance Monitoring Using the ctstat Utility in the c-treeACE server Administrators Guide
(http://docs.faircom.com/doc/ctserver/) for full details on using the ctstat utility.
Monitoring c-treeACE Using SystemConfiguration API
The c-treeACE API function SystemConfiguration() returns an array of LONGs describing the
current configuration, as well as some of the important dynamic aspects of the system such as
the memory usage an the number of files in use. The following sections list
SystemConfiguration() return values relevant to specific types of monitoring such as server lock
table, file usage, and cache usage. For a detailed list of the values returned by
SystemConfiguration(), see the c-tree Plus Function Reference Guide.
Monitoring c-treeACE Memory Use
The SystemConfiguration() API function can be used to display current c-treeACE memory
usage figures as shown in the following table:
Array Subscript
Explanation
cfgMEMORY_USAGE
Current system memory usage.
cfgMEMORY_HIGH
Highest system memory use.
cfgNET_ALLOCS
Current system net allocations.
www.faircom.com
All Rights Reserved
88
Monitoring c-treeACE Lock Table
c-treeACE uses a memory-resident lock table for managing locks on c-tree data records. The
following sections discuss options for monitoring the state of the server’s lock table.
LockDump API Options
The c-tree Plus API function LockDump() creates a diagnostic dump of the c-tree Server internal
lock table. Locks can be dumped for a particular file or user or for all files in the system.
For a c-tree Server with snapshot support enabled, the LockDump() function also logs disk I/O
statistics for each file included in the lock dump. These disk I/O statistics consist of the number of
read and write operations and bytes read and written for each file.
Below is sample lock dump output for the c-tree data file mark.dat:
------------------------------mark.dat>>
0000-00094480x
0000-00094580x
0000-00094200x
0000-00094600x
T013
T014
T010
T012
write/1: W18 W19
write/1
write/1
write/1
cumulative lock attempts: 9462(4731)
blocked: 0(0)
dead-lock: 0
denied: 0
Current file lock count: 4
---------------cumulative I/O: read ops: 76 bytes: 614528
write ops: 38 bytes: 614400
The output shows four write locks held on mark.dat. The log lists the following details for each
lock currently held on a file:
 The record offset of the locked record (0000-00094480x)
 The ID of the thread that is holding the lock (T013)
 The type of lock (write/1)
 The IDs of any threads that are waiting to acquire the lock (W018 W019)
The possible lock types are shown in the following table. Note that the first 5 lock types in the
table are supported only for a c-tree Server built with strict serialization support:
Lock Type
Explanation
SS open
SS (strict serializer) logical Open lock
SS commit intent
SS commit intent lock
SS commit
SS commit lock
NS commit intent
NS (nonstrict serializer) commit intent lock
NS commit
NS commit lock
read
Read lock
write/1
Exclusive write lock
write/2
Exclusive write lock (no aggregate check)
www.faircom.com
All Rights Reserved
89
SnapShot API Options
The SnapShot() function can be used to retrieve lock details. See the discussion of the
SNAPSHOT.FCS file format for details.
SystemConfiguration API Options
The SystemConfiguration() function can be used to display the current number of pending
locks:
Array Subscript
Explanation
cfgNET_LOCKS
Current number of pending locks (system wide).
Monitoring c-tree Client Activity
c-treeACE provides a variety of ways to monitor c-tree client activity. The following sections
discuss the available options.
Server Configuration Options
The following server configuration options can be used to monitor client activity:
 Specifying DIAGNOSTICS LOGON_COMM in the server configuration file causes the server to
write detailed logon status messages to its console. This option is useful for tracking down
the cause of failed client connection attempts.
 Specifying DIAGNOSTICS TRAP_COMM in the server configuration file causes the server to
log all communication messages received from c-tree clients to the file TRAPCOMM.FCS.
This option provides a way to capture the exact sequence of client requests, and if a copy of
the initial data and index files are preserved, the cttrap utility can be used to replay this
TRAPCOMM.FCS log in order to reproduce the original client activity. Note that using this
option may impact server performance.
 Specifying FUNCTION_MONITOR YES in the server configuration file causes the c-tree Server
to display details about each client request to the function monitor window or standard output.
Another variation is to specify FUNCTION_MONITOR <logfile>, which causes the server to
log function details to the file named <logfile>. When function monitor output is directed to a
log file, the function return codes are included, which makes this option useful for tracking
down the occurrence of unexpected c-tree errors. Note that using this option may impact
server performance.
ctadmn Utility Options
The c-tree Server Administration Utility, ctadmn, can be used to monitor c-tree client activity by
following these steps:
1. Start ctadmn. When prompted, enter the user ID of a member of the ADMIN group, the user’s
password, the optional FAIRCOM.FCS file password, and name of the c-tree Server.
2. Select option 4, “Monitor Clients”, from the ctadmn main menu.
www.faircom.com
All Rights Reserved
90
3. Select option 1, “List Attached Clients”, from the Monitor Clients menu. ctadmn displays an
entry such as the following for each connected client:
UserID: GUEST
Task 11
Memory: 25K
Tran Time:
0:01
NodeName:
Communications: F_TCPIP
Open Files: 2
Logon Time:
0:02
Rqst Time:
0:00 InProcess Rqst# 13
TRANEND
The meaning of each field is shown in the following table:
Field
Explanation
UserID
The user ID specified by this client when connecting to the server.
NodeName
The application-assigned node name for this client.
Task
The server-assigned task ID for the server thread servicing this client. Entries
logged by this thread to the server status log include this task ID (for example, “User 11”).
Communications
The communication protocol used by this client.
Memory
The current server memory usage attributed to this client thread.
Open Files
The current number of open files by this client.
Logon Time
The total logon time for this client connection.
Tran Time
The current elapsed transaction time for this client’s currently active transaction.
Watch for unexpected high transaction times.
Rqst Time
If the text to the right of this value reads “InProcess”, this thread is currently
executing a request on behalf of a client and this time is the current elapsed time for
this client’s current request. In this case, a large “Rqst Time” value indicates that the
server is taking a long time to complete this client’s request.
If the text to the right of this value reads “NoRequest”, this thread is waiting for the
next client request and this time is the current elapsed time since the completion of
the previous client request. In this case, a large “Rqst Time” value indicates that it
has been a long time since the server has received a request from this client.
Rqst#
If the text to the left of this value reads “InProcess”, the function number and
function name refer to the c-tree API function currently being executed on behalf of
the client.
If the text to the left of this value reads “NoRequest”, the function number and
function name refer to the c-tree API function that were most recently executed on
behalf of the client.
SystemConfiguration Options
The c-tree Plus SystemConfiguration() API function can be used to monitor c-tree client activity.
SystemConfiguration() returns three values referenced with the following constants used as
subscripts in the output array of LONG values as shown in the following table:
Array Subscript
Explanation
cfgLOGONS
Current number of logons.
cfgUSERS
Maximum number of logons set in server configuration file.
cfgMAX_CONNECT
Maximum number of logons set by server activation.
www.faircom.com
All Rights Reserved
91
Monitoring c-treeACE Transaction Activity
This section discusses the available options for monitoring the c-tree Server’s transaction activity.
The CHECKPOINT_MONITOR server configuration keyword can be used to cause the server to log
the starting and completion times of checkpoint operations to the server status log and the server
console. This option can be used to determine how often checkpoints occur. If checkpoints occur
very frequently, the server’s performance can be affected. In such a situation, the
CHECKPOINT_INTERVAL and LOG_SPACE keywords can be used to reduce the frequency of
checkpoint operations.
SnapShot API Options
The SnapShot() function can be used to retrieve transaction activity details. See the discussion
of the SNAPSHOT.FCS file format for details.
Monitoring c-treeACE Transaction Numbers and Transaction File Numbers
The server assigns a transaction number to each transaction and it assigns a transaction file
number each time a transaction file is modified. The limits for these numbers are very high, so it
should take years to reach them even on a system with heavy traffic. Nonetheless, these
numbers should be monitored to ensure that they do not reach their limits:
1. Transaction numbers can go up to: 1,125,899,906,842,623
2. Transaction file numbers can go up to: 4,294,963,200
Both numbers can be easily monitored by looking at CTSTATUS.FCS. The server prints error
messages to CTSTATUS.FCS well before it reaches limits for these numbers.
The limitation to this method is that it does not give any percentage value or any estimation on
how far away the limit is. The current values of these numbers can be monitored using the ctstat
-vat option. This option is documented c-treeACE Server Administration Guide in the ctstat
Transaction Statistics Example http://docs.faircom.com/doc/ctserver/#60944.htm.
The last two values returned by the ctstat -vat option, tranno (transaction number) and tfil
(transaction file number), indicate the next available numbers. Knowing the max value for these
numbers, it should be quick to calculate the status.
See also:
 6-Byte Transaction Numbers (page 27)
 Transaction Number Limitations (page 27)
 Configurable Transaction Number Overflow Warning Limit (page 29)
 ctstat Transaction Statistics Example http://docs.faircom.com/doc/ctserver/#60944.htm
www.faircom.com
All Rights Reserved
92
Monitoring c-treeACE File Usage
This section discusses options for monitoring c-tree data and index file usage by the c-tree Server
and its clients.
The following server configuration options support monitoring the c-tree Server’s usage of data
and index files:
 DIAGNOSTICS LOWL_FILE_IO is useful in troubleshooting file open, create, close, delete,
and rename errors. This keyword causes the server to log to the server status log,
CTSTATUS.FCS, the filename and system error code for failed file open, create, close,
delete, and rename operations.
 DIAGNOSTICS WRITETHRU causes the c-tree Server to log to the server status log the
names of all PREIMG or non-transaction c-tree data and index files that are opened or
created during server operation without the WRITETHRU filemode in effect.
 DIAGNOSTICS EXTENDED_TRAN_NO causes each physical open of a
non-extended-transaction-number file to be listed in CTSTATUS.FCS. The reason to check
for a file that does not support extended transaction numbers is that if all files do not support
extended transaction numbers, then the exceptions could cause the server to terminate if the
transaction numbers go out of the original 4-byte range and one of these files are updated.
By “all files” we mean superfile hosts and indices; data files are not affected by the
extended-transaction-number attribute.
SystemConfiguration API Options
The c-tree Plus SystemConfiguration() API function can be used to monitor c-tree data and
index file usage by the c-tree Server. SystemConfiguration() returns three values referenced
with the following constants used as subscripts in the output array of LONG values as shown in
the following table:
Array Subscript
Explanation
cfgOPEN_FILES
The number of c-tree Plus files opened by the c tree Server.
cfgPHYSICAL_FILES
The number of physical c-tree Plus files opened by the c-tree Server.
Includes superfile members omitted from cfgOPEN_FILES count.
cfgOPEN_FCBS
Number of c-tree Plus file control blocks in use by the c-tree Server.
Monitoring c-treeACE Dynamic Dumps
c-treeACE logs dynamic dump error messages and error codes to the server status log,
CTSTATUS.FCS. In the event of a failed dynamic dump, examine the server status log.
c-treeACE can be configured to log more detailed dynamic dump progress entries to the server
status log, including an entry for each file included in the dump, by adding DIAGNOSTICS
DYNDUMP_LOG to the server configuration file before starting the server.
www.faircom.com
All Rights Reserved
93
Monitoring c-treeACE Automatic Recovery
If RECOVER_DETAILS YES is present in the server configuration file when the server is started,
the server logs the time spent for each phase of recovery to the server status log. This option
provides a way to more specifically monitor the progress of automatic recovery. The server writes
the entry for each recovery phase upon completion of that recovery phase, so the current
recovery phase can be determined by examining the contents of the server status log.
See the section "Server Startup Hangs or Takes Excessive Time" (page 103) of this document for
more details on monitoring automatic recovery.
Monitoring c-treeACE Cache Usage
The c-treeACE SystemConfiguration() API function can be used to monitor the usage of the
c-tree Server data and index caches. SystemConfiguration() returns nine values referenced
with the following constants used as subscripts in the output array of LONG values an application
can use to capture system-wide cache and buffer statistics, (cache pages hold data record
images and buffers hold index nodes), allowing an application to track the use of these resources.
Array Subscript
Explanation
cfgCACHE_PAGES
Available cache pages
cfgCACHE_PAGES_INUSE
Cache pages in use
cfgCACHE_PAGES_MXUSE
Maximum cache pages used
cfgCACHE_PAGES_DED
Available dedicated cache pages
cfgCACHE_PAGES_DEDINUSE
Dedicated cache pages in use
cfgCACHE_PAGES_DEDMXUSE
Maximum dedicated cache pages used
cfgBUFFER_PAGES
Available index buffers
cfgBUFFER_PAGES_INUSE
Index buffers in use
cfgBUFFER_PAGES_MXUSE
Maximum index buffers used
Note: The dedicated cache pages are a subset of the regular cache pages.
Monitoring c-treeACE Status Log Messages
During server operation, c-treeACE writes messages to the server status log, CTSTATUS.FCS.
The messages the server logs may be informational, warning, or error messages. The system
administrator should monitor the server status log to detect situations in which the server writes
unexpected warning or error messages to the status log.
The ctsysm utility can be used to monitor status log messages. This utility reads a configuration
file containing the possible status log messages and associated actions depending on the context
of the message. As the server logs messages to the status log, the utility examines the messages
and outputs the corresponding message code, which can be matched to the appropriate action, if
any, for the message. For details on using the ctsysm utility to monitor the c-tree Server status
log, see c-treeACE Server Status Monitoring Utility, ctsysm in the c-treeACE System
Administrators Guide (http://docs.faircom.com/doc/ctserver/).
www.faircom.com
All Rights Reserved
94
Monitoring c-treeACE Process State
The state of the c-treeACE process can be monitored using system utilities and c-treeACE
utilities. System utilities commonly available on Unix systems include the following:
 ps lists the current processes on the system. This utility can be used to confirm that the
server process exists and is in a running state.
 truss traces system calls and signals for a command or process. This utility can be used to
determine what operations the server is currently performing.
 pstack prints a hex and symbolic stack trace for each lwp in a process. This utility can be
used to determine what each server thread is currently doing. Also see the proc man page
for details on other process monitoring tools.
 gcore creates a core image of the specified process. This utility can be used to view a
detailed snapshot of the server’s operation at a point in time.
The Windows Performance Monitor and Task Manager can be used to observe the state of the
c-treeACE process and its current activity.
The ctstat utility can be used to monitor server activity. By observing c-treeACE statistics over
time, the server’s activity can be measured. For example, transaction commits, communication
read/write operations, and disk read and write operations can be examined to determine what the
server is currently doing.
The ctadmn utility can be used to monitor client activity. Details can be listed for all client
connections, including current request, elapsed request time, and elapsed transaction time.
Monitoring c-treeACE Server with strace
A trace of the server process can yield valuable information about performance bottlenecks. A
good strategy is to use a utility to monitor the system call times while running a test utility, such as
the cttctx test.
On Linux and some Unix platforms, the strace utility can be used to detail system calls. The -p
flag will attach strace to a running process, which will be c-treeACE Server in this case. This
allows you to monitor a specific instance of c-treeACE Server to analyze performance. Similar
tools are available on other platforms such as Windows and Unix. Some Unix systems provide a
similar utility named truss, although arguments may differ.
Note: The strace utility only attaches to the threads that existed when it was started.
You will need to know the process ID (PID) of the c-treeACE Server thread that will be monitored,
as explained in the sections below. To find the PID, you may need to know the binary name of the
c-treeACE Server:
 The binary name for the ISAM server is ctsrvr for Unix/Linux and ctsrvr.exe for Windows.
 The binary name for the SQL server is ctreesql for Unix/Linux and ctreesql.exe for
Windows.
To run strace on c-treeACE Server, use the following command:
strace -f -p PID -c
 where PID is the c-treeACE Server process ID (the sections below explain how to obtain the
process ID).
www.faircom.com
All Rights Reserved
95
 -f - traces child processes.
 -c - adds call timing information.
This command will run in the background until you press <CTRL>+C, and then it will output the
system call counts and times.
Finding the c-treeACE Server Process ID
To use strace you will need to know the process ID (PID) of the c-treeACE Server thread you
need to monitor. The sections below show several methods of determining the c-treeACE Server
process ID.
Searching CTSTATUS.FCS
You can obtain the c-treeACE Server process ID by looking at the most recent start of c-treeACE
Server within CTSTATUS.FCS. If you have more than one c-treeACE Server running on the
machine, the best way to find the process ID is to look in CTSTATUS.FCS. You can search for
"Process ID:" or simply "ID:" as shown below:
Fri May 8 08:08:00 2015
- User# 00001 Process ID: 18305
Viewing the Process Status (Unix/Linux)
The process status command, ps, shows information about the currently-running processes. That
output can be searched, by piping it to grep, to find the c-treeACE Server process.
For the c-treeACE SQL Server use:
ps -ef | grep ctreesql | grep –v grep
For the c-treeACE ISAM Server use:
ps -ef | grep ctsrvr | grep –v grep
The following snippet shows an example of executing the ps command on a Unix/Linux system
and searching the results for "ctree":
ps -ef | grep ctree
fctech
18305 13447
fctech
18324 13447
6 08:08 pts/4
0 08:08 pts/4
00:00:00 ./ctreesql
00:00:00 grep ctree
In this example, the second row containing "grep" is the grep command, which can be ignored.
The first row is the ctreesql process.
Using Task Manager (Windows)
www.faircom.com
All Rights Reserved
96
On Windows, you can load Task Manager to find the c-tree process.
Monitoring System Call Times
The cttctx test can be used to monitor call times. To see the system call times for the thread that
is running the test, follow these steps:
1. Start c-treeACE Server and note its process ID (see the earlier sections).
2. Run top with the following command-line to see the c-treeACE Server threads:
top -H -p CTREE_SERVER_PROCESS_ID
3. While top is running, start the cttctx test. Note the process ID of the thread that is at the top
of the top list. For example:
PID USER
PR NI VIRT RES SHR S %CPU %MEM
TIME+ COMMAND
7591 fctech
20
0 1095m 33m 3800 D 1.3 0.9
0:00.11 ctsrvr
7567 fctech
20
0 1095m 33m 3800 S 0.7 0.9
0:00.09 ctsrvr
7568 fctech
20
0 1095m 33m 3800 S 0.0 0.9
0:00.00 ctsrvr
7569 fctech
20
0 1095m 33m 3800 S 0.0 0.9
0:00.00 ctsrvr
4. Run strace for process ID of the thread identified in the previous step:
strace -p 7591 -c
When the test finishes, stop strace and save the output. Collect the strace output for all cases of
interest.
Using ctstat to Capture Statistics
The procedures below can be conducted to analyze performance when the system is running
slow:
Note: These procedures will impact performance slightly, so we only recommend doing this on a
limited basis.
1. Use the following command to enable the internal c-treeACE function call to capture metrics.
ctstat -wrktime on -u ADMIN -p ADMIN -s FAIRCOMS
where "FAIRCOMS" should be replaced with the name of your c-treeACE Server.
2. Use this command to log all c-treeACE Server statistics (including function call timings) to the
text file SNAPSHOT.FCS every minute:
ctstat -text -u ADMIN -p ADMIN -s FAIRCOMS -i 60
This command will not return to the command line. Allow it run for at least 10 minutes so you
have several traces to analyze.
To stop execution, press CTRL+C to interrupt the program.
www.faircom.com
All Rights Reserved
97
3. After the test in step 2 is terminated, disable the "wrktime" server metrics using this
command:
ctstat -wrktime off -u ADMIN -p ADMIN -s FAIRCOMS
The SNAPSHOT.FCS file can be analyzed to locate performance problems.
The Windows procdump Utility
The procdump utility on Windows can be set to trigger on a performance counter which might be
handy if the response times are available in that form. The default procdump dump (without
process memory) should be sufficient to see what is going on.
The procdump utility generates stack traces. For generating system call traces, use the Process
Monitor utility. You can find more information by searching Microsoft Technet.
www.faircom.com
All Rights Reserved
98
8.
Troubleshooting and Debugging
8.1
Failures During c-treeACE Startup
This section discusses failures that may occur when starting the c-treeACE.
Server Fails to Start
There are situations in which an attempt to start the c-tree Server process can fail. A failed server
startup can be detected by examining the list of processes running on the system. If ctsrvr (the
name of the server binary) is not shown as a running process after the server is started, the
server startup has failed.
The ps or pgrep utilities can be used on Unix systems to list active processes.
The Windows Task Manager can be used on Windows system to list active processes.
In the event of a failed c-tree Server startup, the server logs error messages to CTSTATUS.FCS
and sometimes to the server console. Check for errors in these locations first in order to
understand the reason the server failed to start. If the c-tree Server has successfully started in the
past, consider what might have changed since the last successful server startup (such as server
configuration file options, server binaries, etc.).
The following are possible causes of a failed server startup:
Unactivated c-tree Server
If the c-tree Server is not pre-activated by FairCom, it must be activated before it is started. If an
unactivated server is started, the server writes the following message to CTSTATUS.FCS and
terminates:
Thu Sep 25 15:42:38 2003
- User# 01SERVER NEEDS ACTIVATION KEY!
Execute 'fcactvat' program first
To resolve this type of failed startup, activate the c-tree Server using the c tree Server Activation
Utility.
Missing or Incorrect Configuration File
The server may fail to start if the server configuration file is missing or contains settings that are
inconsistent with those used previously when starting the c-tree Server. For example, if the server
configuration file specifies a PAGE_SIZE setting that differs from the setting used when the
server created its FAIRCOM.FCS file, the server is unable to open FAIRCOM.FCS and server
startup fails. In this situation, the server logs error details to CTSTATUS.FCS.
To resolve this type of failed startup, review the startup errors logged to CTSTATUS.FCS and
start the server using a server configuration file with the appropriate configuration settings.
www.faircom.com
All Rights Reserved
99
Unrecognized Keyword in Server Configuration File
If the server configuration file used when starting the c-tree Server contains a keyword that is
used incorrectly or is not recognized, the c-tree Server fails to start up. The example below shows
the messages logged to CTSTATUS.FCS when an unrecognized keyword
<unrecognized_keyword> is specified in the server configuration file:
Thu Sep 25 16:45:06 2003
- User# 01DO NOT RECOGNIZE CONFIGURATION KEYWORD...: 2
Thu Sep 25 16:45:06 2003
- User# 01<unrecognized_keyword>: 2
Thu Sep 25 16:45:06 2003
- User# 01O1 M2 L73 F9 P0x (recur #1) (uerr_cod=0)
To resolve this type of failed startup, review the errors logged to CTSTATUS.FCS and make the
appropriate changes to the server configuration file.
Server Fails to Open Server Administrative Files
The c-tree Server will fail to start if it is unable to open its administrative files, which include the
files FAIRCOM.FCS, SYSLOGDT.FCS, and SYSLOGIX.FCS. In this situation, check the server
status log and look for a message such as the following:
Wed Oct 1 12:34:25 2003
- User# 01
Could not initialize server. Error: 14
If the server fails to start up and logs this message to the server status log, attempt to open
FAIRCOM.FCS, SYSLOGDT.FCS, and SYSLOGIX.FCS to determine which of these files failed
to open. The files SYSLOGDT.FCS and SYSLOGIX.FCS are the server’s event logs. If the server
fails to open the files they can be safely deleted if their contents are not of interest, or they can be
rebuilt, or they can be moved out of the server directory and the server will re-create these files
during server startup. The file FAIRCOM.FCS contains user and group definitions. If the sever
fails to open the files and the server’s default user and group account settings have not been
changed, FAIRCOM.FCS can be deleted and the server will re-create it during server startup. If
the server administrator has made changes to the user and group accounts settings, rebuild this
file or restore it from backup.
If the message shown below appears in the server status log, the server was not able to open
FAIRCOM.FCS because the current PAGE_SIZE setting differs from the page size used when
FAIRCOM.FCS was created.
Wed Oct 01 12:46:38 2003
- User# 01
Could not process User/Group Information: 417
To correct this problem, change the PAGE_SIZE setting to the correct value, use the ctscmp
utility to change the page size for FAIRCOM.FCS, or delete FAIRCOM.FCS.
If the server fails to start due to a failure to open its administrative files, consider adding
DIAGNOSTICS LOWL_FILE_IO to the server configuration file. This diagnostic option causes the
server to log messages showing filenames and system error codes for failed file
open/close/delete/create/rename operations to the server status log.
Missing Server Binary or Communication DLLs
The c tree Server can fail to start if the server binary is missing or in the case of the Windows
server if a required communication DLL is missing. If the server binary is missing, the system
www.faircom.com
All Rights Reserved
100
command used to start the server typically outputs a message indicating that the binary was not
found. In the event of a missing communication DLL, CTSTATUS.FCS shows a message such as
the following:
Thu Sep 25 15:15:58 2003
- User# 01
F_TCPIP: 145
Thu Sep 25 15:15:58 2003
- User# 01
Could not establish logon area. Error: 143
To resolve this type of failed startup, review the startup errors reported by the server startup
command or logged to CTSTATUS.FCS and copy the necessary binaries to the server’s working
directory.
Server Cannot Initialize Communication Protocol
If the c-tree Server is unable to initialize its communication subsystem at startup, it will terminate
with an error. Examples of this type of failure include a missing communication DLL (as discussed
above), improper system configuration for the specified communication protocol, or unavailable
communication resources (for example, the TCP/IP port the server is attempting to use is already
in use or otherwise unavailable).
To resolve this type of failed startup, review error messages logged to CTSTATUS.FCS to
determine the reason for the failure. Correct the problem and restart the server.
Missing or Corrupt Server Settings File
Some versions of the c-tree Server are require an encrypted server settings file to exist at startup.
A server that requires a settings file will terminate at startup if the settings file is missing or if the
server cannot read the settings file. In this situation, the server writes one of the following
messages to CTSTATUS.FCS:
Thu Sep 25 16:41:10 2003
- User# 01
The Server's settings file is missing.
It is required to operate this server.
Thu Sep 25 16:42:01 2003
- User# 01
The current Server's settings file is invalid.
Use current FairCom utility to recreate the settings file.
To resolve this type of failed startup, review error messages logged to CTSTATUS.FCS. Make
available to the server a good copy of the encrypted settings file and restart the server.
Automatic Recovery Fails
Each time the c-tree Server starts, it examines its transaction logs to determine whether or not it
needs to perform automatic recovery of TRNLOG files. The server automatically performs
automatic recovery if it determines automatic recovery is required. When automatic recovery is
successful, the server continues its normal startup processing. If automatic recovery fails, the
c-tree Server logs an error message to CTSTATUS.FCS and terminates.
To resolve this type of failed startup, review the error messages logged to CTSTATUS.FCS and
take the appropriate action. See the "Automatic Recovery Fails" (page 126) section in this
chapter for a discussion of specific types of automatic recovery failures and what to do in each
case.
www.faircom.com
All Rights Reserved
101
A Server is Already Running in the Working Directory
Two c-tree Servers cannot be running in the same working directory at the same time.
Note: Here the working directory refers to the directory in which the server stores its transaction
logs and other *.FCS files.
If a server attempts to start in a directory in which another server is already running, the server
fails to start up and logs the following error message to CTSTATUS.FCS:
Thu Sep 25 16:38:15 2003
- User# 01
Is another server running in this workspace?
Thu Sep 25 16:38:15 2003
- User# 01
O1 M99 L54 F537 P1x (recur #1) (uerr_cod=0)
To resolve this type of failed startup, shut down the running server or configure the c-tree Server
to start in a different working directory, then start the c-tree Server.
Dynamic Dump Cannot Be Scheduled
If the server configuration file includes the DUMP keyword, the server opens the specified
dynamic dump script file and attempts to schedule a dynamic dump. If the dump cannot be
scheduled (for example, due to a missing dump script or a dump script with incorrect or
unrecognized keywords), the server logs an error message to CTSTATUS.FCS and shuts down.
Below is an example showing errors logged to CTSTATUS.FCS when a dynamic dump cannot be
scheduled at server startup because the dump script file does not exist:
Thu Sep 25 16:48:43 2003
- User# 01
DD: could not open script file...: 12
Thu Sep 25 16:48:43 2003
- User# 01
my.scr: 12
Thu Sep 25 16:48:43 2003
- User# 01
Could not schedule Dynamic Dump...: 5
Thu Sep 25 16:48:43 2003
- User# 01
my.scr: 5
To resolve this type of failed startup, review the error messages logged to CTSTATUS.FCS to
understand the specific cause of the failure. Correct the problem that prevented the scheduling of
the dynamic dump and restart the server.
Server Startup Terminates Abnormally
In addition to the specific causes of a failed server startup, the c-tree Server may terminate
abnormally at startup for the following reasons:
 The c-tree Server process encounters a fatal exception, causing the system to terminate the
server process. In this case the system may produce a core image of the server process at
the time of the exception. The c-tree Server status log may contain error messages related to
the exception.
 An administrator forcibly terminates the c-tree Server process. In this case, the process is
abruptly terminated and the c-tree Server status log does not show an indication of a
shutdown occurring.
 The system on which the c-tree Server is running terminates abnormally (due to power loss,
operating system exception, or sudden system reboot). In this case, the server process may
be abruptly terminated, which case the status log does not show an indication of a shutdown
occurring.
www.faircom.com
All Rights Reserved
102
 The c-tree Server detects an unexpected internal server error situation known as a catend or
a terr. In these cases, the server status log shows an error message containing details about
the internal server error.
If a server startup terminates abnormally, follow these steps:
1. Examine system logs, application logs, and the server status log to determine the nature of
the abnormal server termination.
a. If a fatal exception terminated the server process, save the core file if it exists.
b. If the server terminated due to a fatal exception or internal c-tree Server error, save a
copy of the server’s *.FCS files, the server configuration file, and if time and disk space
permit save a copy of all data and index files before restarting the c-tree Server. These
files can be used to analyze the abnormal server termination.
c. Consider whether any recent hardware or software changes could explain the reason for
the startup failure (including server configuration file option changes).
d. If the situation that led to the abnormal server termination can be understood by
analyzing the server status log or other system logs, correct the problem that caused the
server to terminate. For example, if the server terminated due to insufficient disk space
which prevented the server from writing to its transaction logs, free up disk space to
ensure the server has enough space for the transaction logs (Caution - but do not delete
active transaction logs before the server performs its automatic recovery).
2. Unlike an abnormal server termination that occurs after the server is operational, an
abnormal server termination at server startup does not require special actions to be taken to
ensure the integrity of PREIMG and non-transaction c-tree data and index files because the
application data and index files will not have been open with active changes.
3. If the abnormal server termination occurred during automatic recovery, the TRNLOG files are
in an unknown state. Automatic recovery must be successfully completed or the TRNLOG
files re-created or restored from backup. See the “Automatic Recovery Fails” topic in the
“Failures During System Recovery” section of this document for details on the steps to follow
if the server terminates abnormally during automatic recovery.
4. If the server can be restarted and automatic recovery completes successfully, clients can
connect to the server and can resume processing.
Server Startup Hangs or Takes Excessive Time
The c-tree Server startup process is usually very fast. The c-tree Server logs a message of the
form shown below to CTSTATUS.FCS when startup is complete and the server is ready for
clients to connect:
c-tree(R) V8.13.826 Server Is Operational
-SN 33333333
If the c-tree Server process appears in the system process list but CTSTATUS.FCS does not yet
show the above message indicating the server is operational, the most likely cause is that the
server is performing automatic recovery and for some reason the recovery is taking a long time.
To determine if the long startup time is due to automatic recovery occurring, check the server
status log. When the server begins automatic recovery, it writes the following message to the
status log:
- User# 01
Beginning automatic recovery process
When the server completes automatic recovery, it writes the following message to the status log:
- User# 01
Automatic recovery completed
www.faircom.com
All Rights Reserved
103
If the server has logged the first message to the status log but not the second, it has begun but
has not yet completed automatic recovery.
If RECOVER_DETAILS YES is present in the server configuration file when the server is started,
the server logs the time spent for each phase of recovery to the server status log. This option
provides a way to more specifically monitor the progress of automatic recovery. Below is an
example showing the order of automatic recovery phases. The server writes the entry for each
recovery phase upon completion of that recovery phase, so the current recovery phase can be
determined by examining the contents of the server status log.
Mon Sep 29 10:14:34 2003
- User# 01
Transaction scan time:
1 seconds.
Mon Sep 29 10:14:34 2003
- User# 01
Beginning automatic recovery process
Mon Sep 29 10:14:34 2003
- User# 01
Index repair time:
0 seconds.
Mon Sep 29 10:14:34 2003
- User# 01
Index composition time:
0 seconds.
Mon Sep 29 10:14:34 2003
- User# 01
Transaction undo time:
0 seconds for
2 transactions.
Mon Sep 29 10:14:34 2003
- User# 01
Vulnerable data time:
0 seconds.
Mon Sep 29 10:14:34 2003
- User# 01
Vulnerable index time:
0 seconds.
Mon Sep 29 10:14:34 2003
- User# 01
Transaction redo time:
0 seconds for 843 transactions.
Mon Sep 29 10:14:34 2003
- User# 01
Automatic recovery completed
Although the current recovery phase and time spent so far during recovery can be determined
using the above approach, the log entries do not indicate how much time remains until recovery is
complete.
If automatic recovery appears to hang or is taking a long time, the two options are to wait until
recovery completes or to abandon recovery and restore TRNLOG data and index files from a
backup. See the "Automatic Recovery Fails" topic in the “Failures During System Recovery”
section of this document for details on these options.
If the server startup is taking a long time or appears to hang and the cause does not appear to be
automatic recovery (based on the status log messages), check the state of the server process
using system utilities as described in the “Monitoring c-tree Server Process State” section. If
necessary, the server can be forcibly terminated and restarted without affecting the state of c-tree
data and index files because the files will not have been open for end user modification at this
point.
Java 1.7 uses large amount of virtual memory at startup
The Server will potentially use a very large amount of virtual memory at startup when it is
configured to use Java version 1.7. This is because the default behavior of the 1.7 JVM (64-bit
JVM on Windows) is to reserve 1/4 of the total physical memory. This does not affect physical
memory usage. When looking at the Windows Committed memory or Virtual memory usage,
ctreesql may show a very large value at startup if the JVM is configured.
http://www.oracle.com/technetwork/java/javase/jdk7-relnotes-418459.html
(http://www.oracle.com/technetwork/java/javase/jdk7-relnotes-418459.html)
www.faircom.com
All Rights Reserved
104
The JVM heap size can be limited with the following Server configuration keyword:
; Limit JVM maximum heap to 256 MB
SETENV DH_JVM_OPTION_STRINGS=-Xmx256m
The maximum heap size should be tuned based on how the Stored procedures are written and
used (256MB should be enough for simple usage). See below for details on Java Tuning.
http://www.oracle.com/technetwork/java/javase/gc-tuning-6-140523.html
(http://www.oracle.com/technetwork/java/javase/gc-tuning-6-140523.html)
8.2
Failures During c-treeACE Operation
This section discusses failures that may occur during c-treeACE operation following a successful
startup.
Clients Cannot Connect to Server
To connect to the c-tree Server, a client calls a c-tree Plus API function such as InitCtree(),
InitCtreeXtd(), InitISAM(), InitISAMXtd(), or CTDBLogon(). A connection attempt may fail for
various reasons. Check the function return code to determine possible causes for the connection
failure. The following table sections lists errors a c-tree Plus API function may return in the event
of a failed connection attempt and describes possible causes and troubleshooting steps for each:
c-tree Error 10: SPAC_ERR
Error description
Memory allocation error during logon.
Possible causes
An attempt to allocate memory during logon failed. The most common cause is a shortage of
system memory.
Troubleshooting steps
Check system memory usage by the c-tree Server and other processes on the system. Free
system memory (for example by stopping unnecessary processes or shutting down and restarting
the c-tree Server) and attempt to logon again.
c-tree Error 84: MUSR_ERR
Error description
Maximum users exceeded.
Possible causes
The c-tree Server enforces a limit on the number of concurrently connected clients. This error
indicates that the maximum number of concurrent connections has been reached.
www.faircom.com
All Rights Reserved
105
Troubleshooting steps
In some cases, it is expected that the maximum number of clients may be logged on. In this
situation, try the operation again after clients have logged off. If reaching the connected user limit
is unexpected, use the ctadmn utility to list the current client connections and to view their
activity. Use ctadmn to determine if there are any inactive client connections that can be
terminated. When the number of connected clients is below the connection limit, try to logon
again. Note, the Server is designed to allow one instance of the user ID “ADMIN” to be able to
connect to the Server even if the maximum number of supported connections has been reached.
Note: A client which belongs to the ADMIN group and which sets the USERPRF_ADMSPCL bit
of the user profile can log onto to the c-tree Server even if the server already has the maximum
permitted number of clients logged on. This capability is useful in situations in which it is
necessary to perform system administration even when the client limit has been reached. The
ctadmn utility automatically uses this feature.
c-tree Error 127: ARQS_ERR
Error description:
Could not send request. A communication error occurred while sending a request to the server.
Possible causes and troubleshooting steps:
The section "Clients Lose Connection to Server" (page 110) describes possible causes and
troubleshooting steps for this error.
c-tree Error 128: ARSP_ERR
Error description:
Could not receive answer. A communication error occurred while receiving a response from the
server.
c-tree Error 133: ASKY_ERR
Error description:
The server could not be located.
Possible causes:
1.
2.
3.
4.
The c-tree Server is not operational.
The specified server name or location is incorrect.
Network connectivity problems prevent the client from connecting to the server.
The client is using a different communication protocol than the server is using.
Troubleshooting steps:
1. Verify that the c-tree Server is operational. Use system utilities to confirm that the server
process is active.
2. Confirm that the server is using the same communication protocol as the client. This can be
determined by examining the server configuration file (ctsrvr.cfg) and the server status log
(CTSTATUS.FCS).
www.faircom.com
All Rights Reserved
106
3. Verify that the server name and location are correctly specified for the communication
protocol the client is using. Note the SERVER_NAME value is case sensitive. If the TCP/IP
communication protocol is being used, be sure the
Machine_Name@Server_NameServer_Name@Machine_Name protocol is being followed.
For example, 128.128.128.128@[email protected].
4. Check the network connectivity. If the server and client reside on separate machines, ping
the server machine from the client machine using the host name or IP address specified
when connecting. Use system utilities to verify that the server is listening for incoming
connections. Try connecting using ctadmn from the server machine and from the client
machine.
5. Add the option DIAGNOSTICS LOGON_COMM to the c-tree Server configuration file and
restarting the server. This option causes the server to write detailed logon status messages
to its console. These messages can help determine at what point the connection attempt
failed. For example, the messages can show whether or not the server was aware of the
client’s connection attempt. Note: tracking of logon details on the client side can be enabled
by compiling the c-tree client library with #define CT_DIAGNOSE_LOGON_COMM enabled.
The client outputs logon messages to standard output.
6. Shut down and restart the c-tree Server to cause it to reinitialize its communication
subsystem.
c-tree Error 150: SHUT_ERR
Error description:
Server is shutting down. The client connected to the server but the server closed the connection.
c-tree Error 162: SGON_ERR
Error description:
Server has gone away. The client connected to the server but the server closed the connection.
c-tree Error 450: LUID_ERR
Error description:
Invalid user ID.
Possible causes:
The specified user ID does not exist.
1. Use the ctadmn utility to list the user IDs recognized by the server.
2. Logon using a valid user ID or create a new user account with the specified user ID.
c-tree Error 451: LPWD_ERR
Error description:
Invalid password.
www.faircom.com
All Rights Reserved
107
Possible causes:
The specified password is invalid for the specified user ID. Note that passwords are
case-sensitive.
To resolve this error, logon using the correct password for the specified user ID or use the
ctadmn utility to change the password to match the specified password.
c-tree Error 452: LSRV_ERR
Error description:
Server could not process user or account information. The c-tree Server encountered an error
when reading the account information for the specified user.
Possible causes:
This logon error points to possible problems with the user account data in the FAIRCOM.FCS
superfile. Depending on the location of the problem, the c tree Server may log one of the
following messages to CTSTATUS.FCS:
User ID file processing error
User/Group file processing error
Valid ID file processing error
Use the ctadmn utility to list the properties for the specified user account. If necessary, change
account properties or delete and re-create the account. If the error persists, using the ctscmp
utility to compact FAIRCOM.FCS may help correct this type of error. Or, if a good backup copy of
FAIRCOM.FCS exists, restoring this file from backup is an option.
c-tree Error 470: LGST_ERR
Error description:
Guest logons disabled.
Possible causes:
The client attempted to logon as guest by specifying a NULL or empty user ID, but guest logons
are disabled. The guest account is disabled unless GUEST_LOGON YES is specified in a server
settings or configuration file (the guest account is also disabled by specifying GUEST_LOGON
NO).
To avoid this error, logon using a non-guest account or reconfigure the c-tree Server to allow
guest access.
c-tree Error 530: LMTC_ERR
Error description:
Client does not match server.
Possible causes:
Some c-tree Servers only accept connections by specially-configured c-tree clients. When a
standard c-tree client attempts to connect to such a server, the server rejects the connection
attempt with c-tree error 530.
www.faircom.com
All Rights Reserved
108
To avoid this error, connect to the server using the appropriate specially-configured c-tree client.
c-tree Error 579: LIVL_ERR
Error description:
Logon interval error. The c-tree Server can be configured to require a user to logon at least once
within a defined time. This ability can be configured on a per-user account basis and on a
system-wide basis if desired. If the user fails to logon at least once within the prescribed time
period, the c-tree Server disables the user account and subsequent logon attempts using that
user ID fail with c-tree error 579.
Possible causes:
A required logon time period is in effect for the specified user account and the user did not logon
at least once within the specified time period.
An administrator can re-enable a user account that the c-tree Server has deactivated due to
exceeding the required logon interval by using the ctadmn utility.
c-tree Error 584: LRSM_ERR
Error description:
Exceeded failed logon limit. The c-tree Server supports setting a limit on the number of
consecutive logon failures due to specifying an invalid password. This limit can be set on a
per-user and on a system-wide basis. If a user exceeds the specified number of consecutive
logon failures, the server disables the user account and subsequent logon attempts using that
user ID fail with c-tree error 584.
Possible causes:
A consecutive logon failure limit is in effect for the specified user account and the user has
exceeded the limit.
An administrator can re-enable a user account that the c-tree Server has deactivated due to
exceeding the failed logon limit by using the ctadmn utility.
c-tree Error 585: LVAL_ERR
Error description:
Logon date exception. The c-tree Server supports setting starting and ending validity dates for
user accounts. An attempt to logon using a user account before its starting validity date or after its
ending validity date fails with c tree error 585.
Possible causes:
A validity period is in effect for the specified user account and the starting validity date has not yet
arrived, or the ending validity date has already passed.
An administrator can change the starting and ending validity dates for a user account using the
ctadmn utility.
www.faircom.com
All Rights Reserved
109
c-tree Error 589: LADM_ERR
Error description:
Member of ADMIN group required.
Possible causes:
A client is attempting to connect to the c-tree Server in an administrative mode (for example,
logging on using ctadmn or logging on in order to shut down the server) but the specified user ID
is not a member of the ADMIN group.
Logon using a user ID that is a member of the ADMIN group, or use the ctadmn utility to add the
specified user ID to the ADMIN group.
c-tree Error 593: XUSR_ERR
Error description:
Non-ADMIN user blocked from logon. The c-tree Server can be put into an operational mode in
which only users that are members of the ADMIN group are allowed to logon. When this mode is
in effect, logon attempts by non-ADMIN users are rejected with c-tree error 593.
Possible causes:
The server administrator has enabled the c-tree Server’s ADMIN group only logon mode using
the c-tree Plus SECURITY API function or using the STARTUP_BLOCK_LOGONS keyword in
the server configuration file.
To resume normal server operation, the server administrator can call the c tree Plus SECURITY
API function with a mode of SEC_BLOCK_OFF.
c-tree Error 609: LTPW_ERR
Error description:
One-use temporary password failure. The c-tree Server supports establishing a one-time
password that another client can use (along with the user ID matching the caller that set the
password) as long as the original caller is still logged on. Once the original caller logs off, the
one-time password becomes invalid. Once the password is used by the subsequent client, the
password is no longer available.
Possible causes:
Either no one-time password is in effect for the specified user ID, or the specified password is
invalid.
Confirm that the client that established the one-time password is already logged on, that a client
has not yet connected using the one-time password, and that the specified password is correct.
Clients Lose Connection to Server
A connected client may lose its connection to the c-tree Server for various reasons. If a client
loses its connection to the server, subsequent calls to c-tree functions that send requests to the
server return an error indicating that the connection has been lost. The topics below list errors a
www.faircom.com
All Rights Reserved
110
c-treeACE API function may return in the event of a lost connection and describes possible
causes and troubleshooting steps for each:
c-tree Error 7: TUSR_ERR
Error description:
Terminate user. The c-tree Server or server administrator has terminated the client’s connection
to the server.
Possible causes:
1. An administrator may have terminated the client connection.
2. The c-tree Server may have terminated the client connection (for example, when the server is
shutting down or when the server aborts a transaction).
Examine CTSTATUS.FCS to determine the reason the connection was terminated. See the
discussion of c-tree error 127 for additional details about reconnecting to the c-tree Server after a
client connection is terminated.
c-tree Error 127: ARQS_ERR
Error description:
Could not send request. A communication error occurred while sending a request to the server.
Possible causes:
1.
2.
3.
4.
The server may have shut down.
The server may have terminated abnormally.
An administrator may have terminated the client connection.
A network error may have occurred that terminated the connection to the server.
1. Verify that the server is operational. Restart the server if it is not operational.
2. When a client loses its connection to the c-tree Server and the server detects the lost
connection, the server aborts the client’s active transaction (if any) and closes any files that
the client had open. If the server is still operational, use the ctadmn utility to confirm that the
server thread for the lost connection has been terminated. If necessary, terminate the old
connection using ctadmn.
3. To determine if the connection was terminated by an administrator, check CTSTATUS.FCS
for messages of the form:
External kill request posted against user #<taskID>
where <taskID> is a server-assigned thread task ID.
1. Attempt to reconnect to the server.
2. If this communication error occurs at logon time, consider using the DIAGNOSTICS
LOGON_COMM server configuration keyword to monitor logon process as described in the
discussion of c-tree error 133.
3. If this communication error occurs frequently without explanation (for example, connections
are lost but the c-tree Server remains active), investigate the possibility of network
connectivity errors.
www.faircom.com
All Rights Reserved
111
c-tree Error 128: ARSP_ERR
Error description:
Could not receive answer. A communication error occurred while receiving a response from the
server.
The possible causes and troubleshooting steps are the same as for error 127.
c-tree Error 150: SHUT_ERR
Error description:
Server is shutting down. The client connected to the server but the server closed the connection.
Possible causes:
The c-tree Server is refusing new connections because it is in the process of shutting down.
Check the status of the c-tree Server process. Restart the c tree Server if necessary. When the
server is operational, retry the connection attempt.
c-tree Error 162: SGON_ERR
Error description:
Server has gone away. The client connected to the server but the server closed the connection.
The possible causes and troubleshooting steps for this error are the same as described for c-tree
error 150.
Number of Active Transaction Logs Unexpectedly Increases
The number of active transaction log files required to support c-tree Server operation is nominally
normally 4. Each time the server creates a new log, it determines whether or not the oldest
existing log can be deleted (or made inactive, if the KEEP_LOGS server configuration option is
specified in the server configuration file). A number of conditions require the server to keep more
than 4 active log files. It is important for the server administrator to detect cases in which the
number of active logs increases significantly and to understand the cause and whether or not
action is required.
When the number of log files is about to increase, the server logs the following message to
CTSTATUS.FCS:
The number of active log files increased to <nlogs>
where <nlogs> is the new number of active logs.
The most important of the situations that require keeping the oldest transaction log active are:
 Increasing CHECKPOINT_FLUSH to delay flushing of buffers associated with committed
transactions:
When creating a new transaction log, the c-tree Server determines the recoverability vulnerability
due to unflushed buffers associated with committed transactions and keeps the required number
of active logs. The following formula can be used to estimate the number of logs required to
support unflushed buffer/cache pages based on server configuration settings.
www.faircom.com
All Rights Reserved
112
Let:
CPF = CHECKPOINT_FLUSH value (defaults to 2)
CPL = number of checkpoints per log (typically 3 and no less than 3)
MNL = minimum number of logs to support unflushed pages
Then:
MNL =
((CPF + CPL - 1) / CPL) + 2, where integer division is used
For example:
CPF=2,
CPL=3 => MNL = 3 (But the server enforces a minimum of 4)
CPF=7,
CPL=3 => MNL = 5
CPF=9,
CPL=3 => MNL = 5
CPF=10, CPL=3 => MNL = 6
 A pending transaction that began several logs ago and still has not committed or aborted:
Unlike CHECKPOINT_FLUSH, which leads to a well-defined limited increase in the number of
active transaction logs, a long uncommitted transaction can lead to an unlimited increase in
transaction logs. For example, if a client begins a transaction and then sits idle while other clients
execute transactions, the other clients’ transaction activity fills the transaction logs. When the
server creates new logs it finds that the idle client’s transaction has not committed. The server
must keep the log in which the idle client’s transaction begin is logged until that client aborts or
commits its transaction. For this reason, it is important to monitor the number of active transaction
logs. In the event of an unexpected long transaction, the ctadmn utility can be used to list
connected clients and their transaction times and to terminate clients as needed.
 Dynamic dumps:
A dynamic dump is similar to the case of a long pending transaction. The dynamic dump must
keep all transaction logs from the dump start time to the dump end time in order to include in the
dump stream file all transaction activity that occurred during the dump. If very large files are
included in the dump, the dynamic dump can take a significant amount of time. Depending on the
amount of transaction activity between the dump start and end times, the number of active logs
that must be kept during a dynamic dump can be large.
The c-tree Server logs to CTSTATUS.FCS an explanation as to the condition that triggered the
increase. When the increase is caused by a pending transaction, the server attempts to identify
the user ID and node name associated with the transaction.
Based on the cause of the increased number of active logs shown in CTSTATUS.FCS, the server
administrator can take the appropriate action, if any. For example, a long pending transaction can
be aborted using the ctadmn utility to terminate the client that began the transaction, or a
dynamic dump can be terminated using ctadmn.
Server Is In A Non-Responsive State
The symptoms of a c-tree Server in a non-responsive state are the following:
 Requests from connected clients hang indefinitely.
 Client connection attempts hang or fail with an error such as c-tree error 133.
A non-responsive server can be detected by monitoring connected clients and looking for client
requests that have not completed within a reasonable timeframe. Note that some c tree API
function calls can be expected to take a significant amount of time (for example, when rebuilding
www.faircom.com
All Rights Reserved
113
a large file or physically closing a file that has many unwritten updated cache buffers). Even
reading a record can take awhile if the call must wait to acquire a lock on the record. The specific
symptoms that indicate a fully non-responsive c-tree Server are that all client requests hang and
new connection attempts may fail.
When the c-tree Server is in a non-responsive state follow these steps to identify the cause and
to correct the problem:
1. The ctadmn utility can be used to monitor the status of client connections, but in the event of
a non-responsive server, ctadmn may be unable to connect to the server or its requests may
also hang. If ctadmn can connect and can list connected clients, it may be possible to use it
to terminate c-tree clients or to shut down the c-tree Server.
2. If ctadmn cannot connect to the server, use system monitoring utilities to determine the state
of the c-tree Server process. Verify that the process is in a running state and if possible use
system utilities to save a core image of the c-tree Server process and stack traces for all the
server threads. See Monitoring c-treeACE in the c-treeACE Server Administrator's Guide
(http://docs.faircom.com/doc/ctserver/) for details about system utilities that can be used to
collect information about the state of the c-tree Server process. Any information that can be
collected about the state of a non-responsive server can be useful in determining the cause
and finding a way to prevent future occurrences of such a problem.
3. To shut down a non-responsive c-tree Server, follow the steps described in the section
Stopping the c-tree Server in the c-treeACE Server Administrator's Guide
(http://docs.faircom.com/doc/ctserver). Shutting down a non-responsive server might require
a hard kill.
Some Clients Are In A Non-Responsive State
A c-tree client can be in a non-responsive state if a server request hangs or takes a long time to
complete. As discussed above, some c tree calls (such as rebuild calls or file close calls that
involve physically closing a file) may take awhile to complete. Calls to read a record with a
blocking lock will hang until the lock can be acquired.
If requests made by one or more clients do not complete in a reasonable timeframe, follow these
steps to identify the cause and to correct the problem:
1. The ctadmn utility can be used to view the current state of the client connections, including
the function name for the current request being processed on behalf of each client and the
current request time.
2. The c-tree Server’s snapshot and lock dump capabilities can be used to collect details about
the state of the c-tree Server. For example, if ctadmn shows one or more clients hanging on
record read operations, use the c-tree Plus API function LockDump() to dump the current
state of the server’s lock table to disk, and examine this log to determine if the read requests
are simply blocking waiting to acquire a record lock. If this is the case, identify from the log
which client currently holds the lock and use ctadmn to view the activity of that client or to
terminate that client if appropriate.
3. If the cause of the long request time cannot be determined using c-tree Server utilities or
c-tree API functions, use system utilities to monitor the server’s system calls and to collect
details about the server process state. Saving a core image and stack traces for the server
threads in this type of situation can help identify the cause of the hanging client requests so
that the problem can be resolved.
4. If necessary, use ctadmn to terminate client connections that are non-responsive. If after
terminating the client connections using ctadmn, the client connections still appear in the list
of connected clients, the c-tree Server may have to be shut down and restarted to clear the
hung connections.
www.faircom.com
All Rights Reserved
114
Errors Occur When Opening c-tree Files
A c-tree data or index file can fail to open for a variety of reasons. This section introduces a
server configuration keyword that can be used to log system error details in the event of failed file
open, create, close, delete and rename operations. The remainder of the section focuses on
specific c-tree errors returned by c-tree file open API functions and ways to resolve the errors.
Enabling Low-Level File I/O Diagnostics
The c-tree Server configuration keyword DIAGNOSTICS LOWL_FILE_IO is useful in
troubleshooting file open, create, close, delete, and rename errors. This keyword causes the
server to log to the server status log, CTSTATUS.FCS, the filename and system error code for
failed file open, create, close, delete, and rename operations. Although client applications have
access to system errors through the c tree global variable sysiocod, it can be useful to have the
server log these errors. For example: An end-user has problems opening a file. The end-user
copied the data file from a CD-ROM to the hard disk leaving the file marked read-only. When the
user attempted to open these files, the open failed with c-tree error 12. Adding the DIAGNOSTICS
LOWL_FILE_IO keyword directed the Server to log the system error code to CTSTATUS.FCS
which helped identify that the file open failed because the file was marked read-only.
c-tree Error 12: FNOP_ERR
Error description:
Could not open file: not there or locked.
Possible causes:
1. The specified filename or path is incorrect (no file by that name exists).
2. The specified file is already open using a file access mode that conflicts with the specified
access mode. For example, if the file is open in EXCLUSIVE mode, attempting to open the
file in SHARED mode fails (and vice-versa).
3. The server does not have the appropriate permission to access the file (for example the file is
marked read-only or system file security attributes are set to disallow access by the user and
group under which the server is running).
1. Verify that the specified filename and path are correct. Note that filenames on some
operating systems are case-sensitive. If using ISAM open functions, it is possible that the
data file open succeeded but an index file open failed. Check the isam_fil global variable to
determine which file open failed. Try opening the data and index files individually using
low-level functions to determine which open fails.
2. Check the c-tree global variable sysiocod. If it is set to -8 (FCNF_COD), this indicates that the
open failed due to conflicting access modes.
3. Check the file permissions to verify that the c-tree Server has the appropriate file access
permissions (read/write access is usually what is required).
4. If the failed open occurs on a superfile member, verify that the member exists using the c-tree
Plus API function GetSuperFileNames() and that the member name is specified exactly as it
appears in the superfile directory index (member names are always case-sensitive).
c-tree Error 14: FCRP_ERR
Error description:
File corrupt at open.
www.faircom.com
All Rights Reserved
115
Possible causes:
The c-tree Server sets an update flag in the header of c-tree data and index files on the first
update to the file after the file is opened. The server resets the update flag when the file is
physically closed (after all updated cache pages for the file are written to disk). When the server
finds the update flag still set when opening the file, the server considers this to mean that the file
was updated but was not properly closed, and so the state of the file is unknown. For example, if
a file is updated and then the server terminates abnormally, the update flag remains set, which
indicates that unwritten updates might not have been written to the file. Error 14 is most likely to
occur for PREIMG and non-transaction files. Because the server’s automatic recovery processes
TRNLOG files in the event of an abnormal server termination, error 14 is not expected for
TRNLOG files unless automatic recovery fails. See the discussion of TRNLOG, PREIMG, and
non-transaction files for full details about caching and the state of files in the event of an
abnormal server termination.
1. If the file is a TRNLOG file, review the sequence of events that led up to the error 14. If the
c-tree Server terminated abnormally, restarting the server should cause automatic recovery
to occur, restoring the TRNLOG files to a consistent transaction state and avoiding the
possibility of error 14 occurring.
2. If the file is a PREIMG or non-transaction file and the server terminated abnormally, error 14
can be avoided by rebuilding the affected files, or re-creating the files and re-loading their
data from an external source, or by restoring backup copies of the files. To avoid data loss
and error 14 for non-TRNLOG files in the event of an abnormal server termination, consider
using the WRITETHRU filemode and WRITETHRU server configuration options. See the
discussion of the WRITETHRU filemode for details.
c-tree Error 417: SPAG_ERR
Error description:
Cache page size error.
Possible causes:
When a superfile is opened, the index node size currently in effect must be the same as the index
node size at the time the superfile was created. This is not usually a problem unless one wishes
to move the file between different environments. Error 417 results if the node size does not
match. By contrast, an ordinary index file can be opened as long as the current node size is at
least as large as the node size at the time the index file was created.
To resolve this error, either:
1. Re-create the superfile using the page size setting currently used by the c-tree Server, or
2. Change the server’s PAGE_SIZE setting to ensure it matches the page size used when
creating the superfile and restart the c-tree Server.
c-tree Error 456: SACS_ERR
Error description:
Group access denied.
Possible causes:
The user that is attempting to open a file is not a member of a group with access to the file.
www.faircom.com
All Rights Reserved
116
Use ctadmn to list the file permissions assigned to the file. To avoid this error, either add the user
to a group that has permission to access the file or change the file permissions to allow the user
to access the file.
c-tree Error 457: SPWD_ERR
Error description:
File password invalid.
Possible causes:
A password is assigned to the file and the file password specified when opening the file is
incorrect.
Specify the correct file password for the file, or use the ctadmn utility to change or reset the file’s
password.
Errors Occur When Reading or Writing c-tree Files
c-tree Error 35: SEEK_ERR
Error description:
Seek error. A file seek operation on a c-tree data or index file failed.
Possible causes:
A file seek operation can fail for various reasons, including disk media errors or an invalid file
descriptor.
In the event of a SEEK_ERR, the c-tree Server logs the following message to CTSTATUS.FCS:
SEEK_ERR...
<filename>
where <filename> is the name of c-tree data or index file for which the seek operation failed.
When a c-tree Plus API function returns c-tree error 35, check the value of the c-tree global
variable sysiocod, which contains the system error code returned by the failed seek operation.
The interpretation of the system error code can explain the cause of the failed seek operation.
c-tree Error 36: READ_ERR
Error description:
Read error. A file read operation on a c-tree data or index file failed.
Possible causes:
A file read operation can fail for various reasons, including disk media errors and inaccessible
files due to locking by external applications.
variable sysiocod, which contains the system error code returned by the failed file read operation.
The interpretation of the system error code can explain the cause of the failed read operation.
www.faircom.com
All Rights Reserved
117
c-tree Error 37: WRITE_ERR
Error description:
Write error. A file write operation on a c-tree data or index file failed.
Possible causes:
A file write operation can fail for various reasons, including disk media errors, insufficient disk
space, and inaccessible files due to locking by external applications.
variable sysiocod, which contains the system error code returned by the failed file write operation.
The interpretation of the system error code can explain the cause of the failed write operation.
c-tree Error 39: FULL_ERR
A FULL_ERR (39) error means a file is at it's capacity size limit, and there's no space available to
add additional records. For a non-HUGE file, this is not easy to resolve. You will need to convert it
to a HUGE file, and rebuild all indexes. The ctcv67 utility helps in this case.
>ctcv67
<file.dat>
<path/to/new/file.da>
H yes
The file will need to be taken offline while conversion takes place. It is a standalone utility, and
can not run while the file remains under server control.
c-tree Error 40: KSIZ_ERR
Error description:
Index node size too large. The c-tree Server was not able to open the specified index file,
superfile, or variable-length data file because the page size used when creating the file is larger
than the server’s current page size. The page size determines the maximum supported index
node size.
Possible causes:
The file was created using a larger PAGE_SIZE setting than the server is currently using. This
situation can arise if the file was created by a server or a standalone c-tree utility that is
configured to use a smaller page size than the server is currently using, or if after the file was
created the PAGE_SIZE setting was changed and the server was restarted.
To resolve this error, either:
1. Re-create the file (by rebuilding or compacting the file) using the page size setting currently
used by the c-tree Server, or
2. Change the server’s PAGE_SIZE setting to ensure it is at least as large as the page size
used when creating the file and restart the c-tree Server.
Note:
A c-tree superfile has stricter page size requirements than a c-tree index has. A
superfile can only be opened by a server who’s PAGE_SIZE exactly matches the page size used
when creating the superfile. See the discussion of c-tree error 417 for details.
www.faircom.com
All Rights Reserved
118
c-tree Plus ODBC Driver
c-tree Plus ODBC Driver users may experience error 40 when an application’s index file is using
a page size larger than allocated by the ODBC driver. To adjust this, access the Windows ODBC
Data Source Administrator.
Note: To configure the 32 bit ODBC driver with 64 bit versions of Windows, you must access the
ODBC Data Source Administrator from the following
directory: %WINDIR%\syswow64\odbcad32.exe
In the ODBC Data Source Administrator window, select the FairCom 32bit driver and click
Configure. When the configuration window is displayed, click the Options button.
The page size used by the driver is calculated by multiplying the Sector Size shown in this
window by 128 bytes. Try increasing the Sector Size from 16 up to 32, then 64. Be sure to close
your ODBC compliant application and reconnect after each change to the ODBC driver
configuration.
If this doesn't work, you may need to rebuild the index files. It's possible a corrupted index file
(typically caused by a system coming down without the files being closed first) could be cause
this error.
c-tree Error 49: FSAV_ERR
Error description:
Could not save file. In some situations, the c-tree Server must ensure that all writes that have
been issued to the filesystem for a c-tree data or index file have been flushed to disk. The server
accomplishes this by issuing a “save” operation on the file, which involves a system call that
forces the filesystem to write to disk all unwritten filesystem buffers for the file. If this flush fails,
the server returns c-tree error 49.
Possible causes:
A file flush operation can fail for a variety of reasons such as a disk media error, insufficient disk
space, or a loss of connectivity to network storage system.
When a save operation fails, the c-tree Server logs the following message to CTSTATUS.FCS:
ctsave failed: system code = <err>
<filename>
lc = <loc>
fd = <fd>
where <err> is the system error code returned by the failed flush call, <loc> is a c tree Server
location code, and <filedesc> is the file descriptor passed to the flush call. Check the
interpretation of the system error code to determine the reason why the flush call failed.
c-tree API Call Fails With Unexpected Error
If a c-tree API function call fails with an error that is not described in this document and the
reason for the error is not clear from the context of the situation, consult the c-tree Plus Function
Reference Guide entry for the c-tree Plus API function that returned the error.
www.faircom.com
All Rights Reserved
119
Server Writes Unexpected Messages to Status Log
During server operation, the c-tree Server writes messages to the server status log,
CTSTATUS.FCS. The messages the server logs may be informational, warning, or error
messages. The system administrator should monitor the server status log in order to detect
situations in which the server writes unexpected warning or error messages to the status log.
The ctsysm utility can be used to monitor status log messages. This utility reads a configuration
file containing the possible status log messages and associated actions depending on the context
of the message. As the server logs messages to the status log, the utility examines the messages
and outputs the corresponding message code, which can be matched to the appropriate action, if
any, for the message. For details on using the ctsysm utility to monitor the c-tree Server status
log, see c-treeACE Server Status Monitoring Utility, ctsysm in the c-treeACE Server
Administrator's Guide (http://docs.faircom.com/doc/ctserver/).
Server Exhibits Atypical Performance
During server operation, the server administrator can use c-tree Server and system monitoring
tools to measure performance properties of the c-tree Server. The application may also provide
tools used to monitor the performance of the system or the database components of the system.
When these system monitoring utilities detect unexpected performance characteristics of the
database components of the system, follow these steps to identify the cause of the unexpected
performance so the problem can be understood and resolved:
1. Identify the nature of the unexpected performance characteristics of the system as
specifically as possible. For example:
a. Can specific application operations or c-tree function calls made by clients be identified
that are performing differently than expected? Application-specific metrics, the ctadmn
utility, the c-tree Server’s snapshot ability, and the function monitor can be used to
identify the specific operations.
b. Does the system exhibit unexpected system or c-tree Server resource usage patterns
(CPU, disk, network usage, etc.) at the time the unexpected performance patterns occur?
Use system and c-tree Server utilities to monitor resource usage and compare to normal
operation. Differences in resource usage from normal operation may provide insight into
the nature of the unexpected performance behavior.
c. Is the unexpected performance behavior occurring consistently, or does it occur only
occasionally? Any pattern that can be identified might help determine the cause of the
behavior.
2. Identify any recent changes to the system that might account for the unexpected performance
characteristics. For example:
a. Has the system load changed (for example are more than the usual number of clients
using the server or are the clients performing different different operations than usual)?
b. Have there been any hardware or software changes (including c-tree Server
configuration option changes)?
Server Exhibits Unexpected Resource Usage
When c-tree Server or system monitoring tools detect unexpected system or server resource
usage, follow these steps to identify the cause of the unexpected resource usage so the problem
can be understood and resolved:
www.faircom.com
All Rights Reserved
120
1. Identify the nature of the unexpected resource usage as specifically as possible. For
example:
a. Is the resource a system resource or a c-tree Server resource? If a system resource, use
system tools to identify the process that is directly responsible for the unexpected
resource usage. If the responsible process is the c tree Server, use application and c-tree
Server monitoring tools to identify whether activity by particular clients accounts for the
change in resource usage. System tools can be used to monitor system calls, dump a
core image of the server, or stack traces for server threads. The ctadmn utility can be
used to terminate clients suspected of contributing to the unexpected resource usage.
b. Does the unexpected resource usage occur consistently, or does it occur only
occasionally? Any pattern that can be identified might help determine the cause of the
behavior.
2. Consider whether any recent changes to the system could account for the unexpected
resource usage. For example:
a. Has the system load changed (for example are more than the usual number of clients
using the server or are the clients performing different different operations than usual)?
Application monitoring tools and the c tree Server’s snapshot ability can help identify
whether the load on the system has changed recently.
b. Have there been any hardware or software changes (including c-tree Server
configuration option changes)?
Dynamic Dump Fails
A dynamic dump backup may fail for various reasons. The following are some possible causes of
a failed dynamic dump:
 The dump script does not exist or is inaccessible.
 The dump script contains invalid options.
 One or more files specified in the dump file list cannot be opened.
 An error occurs when writing the dump stream file (for example, out of disk space or invalid
path specified).
The c-tree Server logs dynamic dump error messages and error codes to the server status log,
CTSTATUS.FCS. In the event of a failed dynamic dump, examine the server status log.
The c-tree Server can be configured to log more detailed dynamic dump progress entries to the
server status log, including an entry for each file included in the dump, by adding DIAGNOSTICS
DYNDUMP_LOG to the server configuration file before starting the server.
Data or Index File Sizes Grow Unexpectedly
The system administrator should monitor the size of c-tree data and index files in order to detect
unexpected increases in file size. Monitoring file sizes helps avoid running out of disk space or
reaching system file size limits and provides useful information in the event of unexpected server
performance behavior or resource usage.
Except for files that are created with deleted space reclamation disabled (using the ctADD2END
extended create mode), c-tree data and index files reuse deleted space. Fixed-length files that
reuse deleted space reuse deleted space with complete efficiency and increase in size only after
all deleted space has been reused.
www.faircom.com
All Rights Reserved
121
Variable-length c-tree data files reuse deleted space by indexing deleted space by size and
storing new variable-length records in the deleted space that most closely matches the size of the
new record. The c-tree Server also coalesces adjacent regions of deleted space in
variable-length files into a single block of deleted space. Note that a variable-length file may
increase in size even if deleted space is available if the available space is not large enough to
store a newly-added record. For this reason, depending on the size of variable-length records and
the order of insertion and deletion operations on variable-length records, deleted space in
variable-length data files can become fragmented over time and the total file size could be larger
than might be expected given the total size of active records in the file.
c-tree index files reuse space made available in index nodes by deleted key values and reuse
nodes that have become empty and are pruned from the tree. A c-tree index file grows only when
a new node is added and no empty nodes remain that can be reused.
Reducing the size of a c-tree data file by removing deleted space from the files can be
accomplished by compacting the data file (which also requires rebuilding the associated indexes).
The c-tree Plus API function CompactIFileXtd() can be used to compact a c-tree data file. Note
that a file must be opened in exclusive mode in order to compact it.
To reduce the size of a c-tree index file by removing deleted nodes, rebuild the index file using
the c-tree Plus API function RebuildIFileXtd(). Note that this function requires exclusive access
to the data file and its associated index files. If index file size is a concern, key compress may
help reduce the overall index size by storing key values in compressed format. See the c-tree
Plus Programmer’s Reference Guide for details on creating an index that contains compressed
keys.
Server Terminates Abnormally
An abnormal server termination is a termination of the c-tree Server process that does not involve
a clean server shutdown. The c-tree Server may terminate abnormally for the following reasons:
 The c-tree Server process encounters a fatal exception, causing the system to terminate the
server process. In this case the system may produce a core image of the server process at
the time of the exception. The c-tree Server status log may contain error messages related to
the exception.
 An administrator forcibly terminates the c-tree Server process. In this case, the process is
abruptly terminated and the c-tree Server status log does not show an indication of a
shutdown occurring.
 The system on which the c-tree Server is running terminates abnormally (due to power loss,
operating system exception, or sudden system reboot). In this case, the server process may
be abruptly terminated, which case the status log does not show an indication of a shutdown
occurring.
 The c-tree Server detects an unexpected internal server error situation known as a catend or
a terr. In these cases, the server status log shows an error message containing details about
the internal server error.
Recovering From Abnormal Server Termination
It is important to understand the reason for the abnormal server termination so that the
appropriate information about the event can be saved and any necessary actions can be taken
www.faircom.com
All Rights Reserved
122
before restarting the c-tree Server. Follow these steps after an abnormal c tree Server termination
occurs:
1. Examine system logs, application logs, and the server status log to determine the nature of
the abnormal server termination.
a. If a fatal exception terminated the server process, save the core file if it exists.
b. If the server terminated due to a fatal exception or internal c-tree Server error, save a
copy of the server’s *.FCS files, the server configuration file, and if time and disk space
permit save a copy of all data and index files before restarting the c-tree Server. These
files can be used to analyze the abnormal server termination.
c. If the situation that led to the abnormal server termination can be understood by
analyzing the server status log or other system logs, correct the problem that caused the
server to terminate. For example, if the server terminated due to insufficient disk space
which prevented the server from writing to its transaction logs, free up disk space to
ensure the server has enough space for the transaction logs (but do not delete active
transaction logs before the server performs its automatic recovery).
2. Determine the status of PREIMG and non-transaction data and index files and restore or
recover these files as needed. PREIMG and non-transaction files are not under full
transaction control, so in the event of an abnormal server termination, these files may be in
an unknown state. Updates that had been written to the server’s cache but not to disk are
lost, data files and index files may be out of sync, and PREIMG files may be in an
inconsistent transaction state.
To determine if a PREIMG or non-transaction file needs to be restored or recovered, open
the file using a standalone (non-client/server) c-tree utility. If the file opens successfully, the
file is in good shape. If the file open fails with c-tree error 14, the file was updated but was not
properly closed and its state is unknown, so the file must be restored or recovered. The
options for restoring or recovering PREIMG and non-transaction files following an abnormal
server termination are the following:
a. Re-create PREIMG and non-transaction files and reload their data from an external
source if available, or
b. Rebuild the files to ensure the data and index files are in sync (although unwritten
updates are still lost), or
c. Restore old copies of the files from backup.
Note: See the discussion of the WRITETHRU filemode and c-tree error 14 for details on the
use of WRITETHRU and server configuration keywords to avoid error 14 for PREIMG and
non-transaction files in the event of an abnormal server termination. Be aware that although
these options provide ways to avoid error 14 in such a situation, it is still possible for
WRITETHRU files to contain data/index inconsistencies or for PREIMG files to be in an
inconsistent transaction state following an abnormal server termination.
3. Recover TRNLOG files using the server’s automatic recovery process. After following the
above steps, TRNLOG files can be recovered by restarting the c-tree Server. The server
detects an abnormal server termination and performs automatic recovery of TRNLOG files,
restoring the TRNLOG files to a consistent transaction state. Upon successful completion of
automatic recovery, the server is fully operational. At this point clients can connect to the
server and can resume their work.
For details on what steps to follow in the event of recovery or restore failures (such as automatic
recovery failing), see the section titled “Failures During System Recovery”.
8.3
Failures During c-treeACE Shutdown
This section discusses failures that may occur during c-treeACE shutdown.
www.faircom.com
All Rights Reserved
123
Server Shuts Down Improperly
This section discusses ways in which a c-tree Server shutdown may fail to complete properly. A
normal c-tree Server shutdown is indicated by the following messages in the server status log:
Fri Sep 26 14:30:08 2003
- User# 12
Server shutdown initiated
Fri Sep 26 14:30:09 2003
- User# 12
Communications terminated
Fri Sep 26 14:30:09 2003
- User# 12
Perform system checkpoint
Fri Sep 26 14:30:09 2003
- User# 12
Fri Sep 26 14:30:09 2003
- User# 12
A normal c-tree Server shutdown operation may not complete properly for the following reasons:
 The server may terminate abnormally at shutdown due to a fatal exception.
 The server may complete its shutdown without successfully terminating all active client
threads.
If the server shutdown terminates abnormally due to a fatal exception, the server does not write
the “Server shutdown completed” message to the server status log. Follow the recovery
procedures described in the section “Recovering From Abnormal Server Termination” (page 122).
If the server shutdown completes without successfully terminating all active client threads, the
server avoids writing a final checkpoint to the transaction logs. This causes the server to perform
automatic recovery on its next startup. The server notes this situation at shutdown by logging the
following message to CTSTATUS.FCS:
Mon Sep 29 16:15:51 2003
- User# 13
Clients active: skipped system checkpoint.
Auto-recovery on next start up
Treat this situation similar to an abnormal server termination, because it is possible that clients
were modifying PREIMG and non-transaction files at the end of server shutdown which could
mean that some updates did not get written to disk. Before restarting the c-tree Server, open
PREIMG and non-transaction files using a standalone utility to determine if they need to be
rebuilt. The server’s automatic recovery ensures that TRNLOG files are in a consistent
transaction state on the next server startup.
Server Shutdown Hangs or Takes Excessive Time
The c-tree Server shutdown process may take a long time for the following reasons:
 The server must write all updated data and index cache pages to disk before shutdown
completes. If the server is configured to use a large cache, there can be many updated cache
pages that must be written to disk at shutdown, which increases the shutdown time.
 The server processes entries in the delete node queue at shutdown. The presence of many
entries in the delete node queue can lead to increased server shutdown time.
 The server allows clients time to recognize that the server is shutting down and to disconnect
from the server. The shutdown time can be long if many clients are connected or if the server
is not able to terminate connected clients.
www.faircom.com
All Rights Reserved
124
Monitoring c-tree Server Shutdown Progress
The progress of the c-tree Server shutdown can be monitored in the following ways:
 Monitoring messages the c-tree Server writes to the server status log during shutdown.
 Monitoring messages the c-tree Server writes to its console or standard output during shut
 Monitoring system resource usage by the c-tree Server during shutdown.
The c-tree Server shutdown is normally accompanied by messages in the server status log such
as the following:
- User# 13
- User# 13
- User# 13
Process delete node Q....
Clients still active.....
Clients shutting down....
These messages indicate the current operation the c-tree Server is performing, such as
processing delete node queue entries, terminating connected clients, and allowing clients time to
shut down.
The server also writes shutdown messages to its console window or standard output. These
messages provide more detailed information than the status log entries, including the remaining
number of delete node queue entries, and the current number of active client threads:
Process delete node Q.......<num_queue> entries.
Clients still active........<num_active>
Clients shutting down.......<num_active>
where <num_queue> is the current number of entries in the delete node queue and
<num_active> is the current number of client threads that are still active.
System utilities can also provide insight into the c-tree Server’s progress during shutdown.
Monitor disk activity on the c-tree data and index files to determine if the server is taking a long
time to shut down because it is flushing data and index cache buffers. Monitor the number of
active server threads to determine how many client threads are still active. See the “Monitoring
c-tree Server Process State” section of this document for additional ways to monitor the state of
the c-tree Server process.
Forcibly Terminating the c-tree Server During Shutdown
If the c-tree Server is taking a long time to shut down or if the server appears to hang during
shutdown, the server process can be terminated using system utilities but be aware of the effect
on c-tree data and index files. Forcibly terminating the c-tree Server process at shutdown
effectively causes an abnormal server termination, which means that unwritten updates for
PREIMG and non-transaction files may be lost and that the server will perform automatic
recovery on its next startup in order to ensure TRNLOG files are in a consistent transaction state.
For details on the state of c-tree data and index files in the event of an abnormal server
termination, see the topic “Server Terminates Abnormally” in the “Failures During c-tree Server
Operation” section of this document.
8.4
Failures During System Recovery
This section discusses failures that may occur during system recovery.
www.faircom.com
All Rights Reserved
125
Automatic Recovery Fails
At startup, the c-tree Server examines the transaction logs to determine whether or not it needs to
perform automatic recovery. If so, the server initiates recovery and when the recovery
successfully completes, the server startup continues as usual. In some cases, however, the
automatic recovery process can fail. For example automatic recovery may fail if:
 The server’s transaction logs are damaged, missing, or inaccessible.
 TRNLOG c-tree data or index files that automatic recovery determines it must process are
damaged, missing, or inaccessible.
 The server configuration file settings are inconsistent with the settings used the last time the
c-tree Server was run.
Recovering from Automatic Recovery Failure
If automatic recovery fails, the c-tree Server logs error messages to its status logs and
terminates. In the event of an automatic recovery failure, proceed as follows:
1. Examine the server status log to determine the type of automatic recovery failure.
2. See the specific failure cases in the following sections for details on each type of recovery
failure and if possible correct the problem. Restart the c-tree Server and allow automatic
recovery to complete successfully.
3. If the automatic recovery failure cannot be corrected, follow these steps to recover or restore
TRNLOG files and to resume c-tree Server operation:
a. If automatic recovery terminated due to a fatal exception and the system generated a
core file, save a copy of the core file for offline analysis.
b. Save a copy of the server’s transaction logs (*.FCS files), the server configuration file,
and if time and disk space permit save a copy of all TRNLOG data and index files. These
files can be examined offline to attempt to identify the cause of the automatic recovery
failure.
c. TRNLOG files that were in use at the time of the abnormal server termination may be in
an unknown state. To determine the state of each TRNLOG file, attempt to open each
TRNLOG file using a c tree file open function. If the file opens successfully, the file is in
good shape and did not need to be processed by automatic recovery. If the open fails
with error 14, the file must be rebuilt, re-created, or restored from backup.
Be aware that restoring only some TRNLOG files from backup may violate transaction
consistency that an application expects to exist among the set of TRNLOG files. If this is
the case, all related TRNLOG files must be treated the same way (all restored from
backup for example).
d. Verify that the server-maintained TRNLOG files FAIRCOM.FCS, SYSLOGDT.FCS, and
SYSLOGIX.FCS can be properly opened. If the files fail to open (for example, with c-tree
error 14 due to the failed automatic recovery) the server will fail to start up.
FAIRCOM.FCS contains the server’s user and group definitions. If FAIRCOM.FCS fails to
open and the server administrator has not changed the default user and group properties,
this file can be deleted and the c-tree Server will re-create it the next time the server
starts up. If the server administrator has defined new users and groups or has changed
default user or group properties, this file must be rebuilt or restored from a backup, or the
user and group account changes must be re-entered.
SYSLOGDT.FCS and SYSLOGIX.FCS contain c-tree Server system event log entries. A
copy of these files can be saved and examined offline if desired and the original copy of
www.faircom.com
All Rights Reserved
126
the files can be removed from the server directory, and the server will re-create these
files the next time it starts up.
e. Delete the transaction logs from the server directory. The transaction logs consist of the
files S0000000.FCS, S0000001.FCS, and all files named L<lognum>.FCS, where
<lognum> is a 7-digit number.
f. Restart the c-tree Server. The server creates a new set of transaction logs and is ready
for operation again.
The following sections discuss specific automatic recovery failure situations and the options that
are available in each case.
c-tree File Open Errors During Recovery
Automatic recovery fails if a TRNLOG file that must be processed during recovery cannot be
opened. See the section titled “Errors Occur When Opening c-tree Files” for possible errors that
may occur when opening c-tree files and what can be done in each case.
A special case that can occur during automatic recovery is that a file cannot be opened because
an application used a c-tree Plus API function to delete or rename the file. In some cases,
automatic recovery does not realize that the file should be expected to be missing for this reason,
and automatic recovery attempts to open the file and fails with c-tree error 12 because a file by
the specified name does not exist.
Note: Creating TRNLOG files as transaction-dependent files (in which file creation and deletion
are guaranteed to be atomic and these events are indicated by transaction log entries) avoids
most occurrences of this type of situation, but does not guarantee that this situation cannot occur.
When this situation occurs, the server logs the following messages to the server status log:
Tue Sep 30 10:44:10 2003
- User# 01
mark.idx: 12
Tue Sep 30 10:44:10 2003
- User# 01
*** Recovery may proceed by adding 'SKIP_MISSING_FILES YES' ***
*** to the server configuration file.
***
Tue Sep 30 10:44:10 2003
- User# 01
Automatic recovery terminated with error: 12
As indicated in the server status log messages, the SKIP_MISSING_FILES server configuration
keyword can be added to the server configuration file in order to avoid this error when a file is
missing during automatic recovery. Because error 12 can occur for other reasons (for example, a
file may be inaccessible to the c-tree Server process due to file permissions or due to an
unavailable volume), confirm that the specified file does not exist and that there is a reasonable
explanation as to why this file does not exist before adding the SKIP_MISSING_FILES option to
the server configuration file and restarting the c-tree Server.
Automatic Recovery Terminates Abnormally
If the c-tree Server process encounters a fatal exception during automatic recovery, causing the
system to terminate the server process, the system may produce a core image of the server
process at the time of the exception. The c-tree Server status log may contain error messages
related to the exception.
In this situation, examine the server status log to see if there are any error messages that point to
the cause of the exception. If the status log shows automatic recovery errors, consult the
www.faircom.com
All Rights Reserved
127
appropriate section above for actions based on the specific error code shown in the status log.
The c-tree Server may be restarted in order to retry automatic recovery, but if the recovery
continues to fail in this manner and the problem cannot be corrected, follow the steps listed in the
"Recovering From Automatic Recovery Failure" (page 126) section.
Automatic Recovery Takes Excessive Time
Automatic recovery may take a long time to complete for the following reasons:
 Server configuration settings such as increasing the log size and checkpoint interval may
require the server to scan a significant amount of log entries and to process a considerable
number of transaction undo and redo operations.
 TRNLOG indexes that do not use the LOGIDX filemode may need to have their tree structure
reconstructed, which can increase recovery time.
In the event of a long automatic recovery, server administrator has the following options:
 Allow automatic recovery to complete (waiting as long as it takes).
 Terminating the server process and restarting recovery (if server configuration settings or
other system properties can be changed that may improve recovery speed).
 Terminating the server process and abandoning recovery (re-creating or restoring TRNLOG
files from backup).
See the "Server Startup Hangs or Takes Excessive Time" (page 103) section for details on
monitoring automatic recovery progress and the “Recovering from Automatic Recovery Failure”
topic above for steps to follow when choosing to abandon automatic recovery and re-create or
restore TRNLOG files.
Dynamic Dump Restore Fails
Restoring files from a dynamic dump stream file may fail for various reasons. Some examples
include:
 The dump restore script is missing.
 The dump restore script contains invalid options or options that are inconsistent with the
c-tree Server settings.
 An error occurs when the dump restore attempts to restore files to the dump time.
 The dump restore is performed in a directory with files that interfere with the restore
procedure (such as existing transaction logs).
When a dump restore operation fails, the ctrdmp utility logs error messages to the file
CTSTATUS.FCS. Check this file for a c-tree error code that explains the cause of the failure and
take the appropriate action. Review the dump restore procedure to ensure that the proper steps
were followed.
Data and index files are dumped to the dump stream file by reading the contents of the file from
disk. Because a file is not instantaneously read in its entirety, a data or index file in the dump
stream file may consist of the file contents as they appear over a period of time. Dump recovery
includes the transaction log activity during the dump time, so that the file can be restored to its
state at the time the dump began. For this reason, if the dump restore successfully extracts files
from the dynamic dump stream file but fails when attempting to restore the files to the dump time,
the restored data and index files are in an unknown state.
www.faircom.com
All Rights Reserved
128
If ctrdmp fails when attempting to restore the files to the dump time and no solution can be
found, the affected data and index files can be rebuilt to ensure the data and index files are in
sync, but the rebuild may fail because the data file may contain a mixture of record images from
different points in time, or the files can be restored from a different backup.
Note: Consider performing dump restore operations offline immediately after the dynamic dump
backup is performed so that dump restore failures can be resolved at backup time rather than at
restore time.
File Rebuild Fails
A file rebuild operation may fail for various reasons. Examples include:
 The IFIL resource in the data file is missing or damaged.
 The data file cannot be opened (for example, if the header of the file is corrupted).
 The rebuild detects illegal duplicate key values.
When a rebuild fails, check the return code of the c-tree API function used to rebuild the file and
consult the c-tree Plus Function Reference Guide entry for that function to determine the
appropriate action.
The ctrbldif utility can be used to rebuild a file that contains a valid IFIL resource. The utility
opens the data file and retrieves the IFIL resource from the file. If the utility cannot read the IFIL
resource, it prompts for the name of a file containing a good copy of the IFIL resource. Consider
saving a copy of the file containing the IFIL resource for use in such a situation.
The ctrbldif utility and c-tree Plus rebuild API functions support an option to handle the presence
of illegal duplicate keys by marking records containing duplicate key values as deleted.
If a file rebuild fails and no solution is found which allows the rebuild to complete successfully,
re-create the file and reload the data from an external source if available, or restore a backup
copy of the file.
File Compact Fails
Like a file rebuild operation, a file compact operation may fail for various reasons. When a file
compact operation fails, check the return code of the c-tree API function used to compact the file
and consult the c-tree Plus Function Reference Guide entry for that function to determine the
appropriate action.
The ctcmpcif utility can be used to compact a file that contains a valid IFIL resource. The utility
opens the data file and retrieves the IFIL resource from the file. If the utility cannot read the IFIL
resource, it prompts for the name of a file containing a good copy of the IFIL resource. Consider
saving a copy of the file containing the IFIL resource for use in such a situation.
The ctcmpcif utility and c-tree Plus compact API functions support an option to handle the
presence of illegal duplicate keys by marking records containing duplicate key values as deleted.
If a file compact fails and no solution is found which allows the compact to complete successfully,
re-create the file and reload the data from an external source if available, or restore a backup
copy of the file.
www.faircom.com
All Rights Reserved
129
8.5
LockDump Output
LockDump() is a low-level c-tree function which creates a diagnostic dump of the c-tree Server
internal lock table. This is useful in development and profiling activities to observe application
locking behavior. The syntax of the function is as follows:
COUNT LockDump(COUNT refno, pTEXT dumpname, COUNT mode)
The possible legal combinations of the LockDump() parameters mode and refno are as follows:
mode
refno
Interpretation
ctLOKDMPfile
ctLOKDMPallfiles
ctLOKDMPdatafiles
ctLOKDMPindexfiles
Dump all locks by file.
Dump all locks on data
files.
Dump all locks on index
files.
Dump locks for file
filno.
filno
ctLOKDMPuser
ctLOKDMPallusers
ctLOKDMPcaller
userno
Dump all locks by user.
Dump locks for user
calling LockDump().
Dump locks for user
userno.
The resulting lock dump output will be found in the file given by dumpname.
In all but one case of the above combinations the caller of LockDump() does not have to have
any files open, although it is no problem if the caller does have files open. In the case of
ctLOKDMPfile/filno, the caller must have opened a file with file number filno. The userno
referenced in the last combination is the thread ID assigned by the c-tree Server. This thread ID
is listed when ctadmn is used to list users logged on to the c-tree Server. In addition to dumping
the location of the lock and the type of lock, users waiting for a lock are also listed.
Limitations
Since dumping all the locks in a very active system with many locks could affect performance, a
c-tree Server will ONLY support the LockDump() call if either of the following conditions is met:
 The configuration file, ctsrvr.cfg, contains DIAGNOSTICS LOCK_DUMP.
 The user calling LockDump() belongs to the ADMIN user group.
Lock Dump Contents
=================================================
All Files Lock Dump at Fri May 04 13:00:12 2007
------------------------------SOMEFILE.FCS>>
0000-013c9a16x T221 write/1: W060 W254 W740 W763 W758
0000-002916abx T758 write/1: W774 W772 W771 W775 W773 W778 W779 W776 W071
cumulative lock attempts: 4002(616)
blocked: 21(0)
dead-lock: 0
denied: 0
Current file lock count: 0
www.faircom.com
All Rights Reserved
130
---------------cumulative I/O: read ops: 0 bytes: 0
.
.
.
.
List of connected clients
------------------------User# 00002: (Node name not set)
User# 00012: (Node name not set)
write ops: 5 bytes: 16768
=================================================
Description
In the example above, The following details can be obtained:
 There are two records with locks held in SOMEFILE.FCS, each listed with it’s locked file
offset value: 0000-013c9a16x and 0000-002916abx.

The thread ID of the users holding the locks (T221 and T758)
 The type of lock: write/1
 A listing of thread IDs waiting for the record lock to be released (for example, W060 W254
W740 W763 W758)
 The waiting thread IDs are further delineated with a prefix indicating the type of lock they are
waiting to obtain: (R)ead or (W)rite locks.
Types of Locks
The possible lock types are shown in the following table.
Lock Type
Value
Explanation
SS open
1
SS commit intent
2
SS commit
3
SS commit lock
NS commit intent
4
NS commit
5
NS commit lock
read
6
Read lock - A read lock requested and held by a user
thread.
write/1
9
Exclusive write lock - A write lock requested and held by a
user thread.
write/2
10
Exclusive write lock (no aggregate check) - An internal
lock very briefly held by the c-tree Server for files under
transaction control. You may occasionally observe these
in a system with a high transaction volume, and these can
be safely ignored.
forcei cmtlok
11
A very briefly held commit read lock enforced by the
c-tree Server. These will only occur when the
COMMIT_READ_LOCK option is enabled in the server
configuration file. These may be occasionally observed in
systems with high transaction volumes.
www.faircom.com
All Rights Reserved
131
Note: The first five lock types listed in the table are only supported with a c-tree Server built with
strict serialization support.
File Lock Info
 cumulative lock attempts xxx (yyy) - Total number of file and (header) lock attempts. The
header locks are internal c-tree Server locks required for critical updates to the file header.
 blocked - Total number of locks and (header locks) that were blocked while another lock was
held. In a high volume system, some blocked lock attempts are expected.
 dead-lock - Total of dead-lock conditions reported for this file. These are generally not
expected, and error DEAD_ERR (86) is returned to the application caller when this condition
is detected. DEAD_ERR is returned when waiting for a write lock would cause a deadlock
condition.
 denied - Total number of locks denied to a caller with error DLOK_ERR (42). A lock is denied
if the record is already locked. Note that blocking locks cause the thread to sleep until the
lock is available, avoiding the DLOK_ERR.
Cumulative I/O
 read ops - Total cumulative read operations for this file.
 bytes - Total cumulative bytes read for this file.
 write ops - Total cumulative write operations for this file.
 bytes - Total cumulative bytes written for this file.
List of connected clients
A list of all connected clients is appended to the end of the lock dump output. This assists the
correlation of known user threads at the application level to threads with potential blocked locks.
 User# - The thread ID of the user as identified by the c-tree Server
 Node Name - The node name of the thread as assigned by the application.
Note: On Windows, the list of connected clients includes the IP address in addition to the user
name and node name.
Types of Locks
Types of Locks
The possible lock types are shown in the following table.
Lock Type
Value
Explanation
SS open
1
SS commit intent
2
SS commit
3
SS commit lock
NS commit intent
4
NS commit
5
NS commit lock
www.faircom.com
All Rights Reserved
132
Lock Type
Value
Explanation
read
6
Read lock - A read lock requested and held by a user
thread.
write/1
9
Exclusive write lock - A write lock requested and held by a
user thread.
write/2
10
Exclusive write lock (no aggregate check) - An internal
lock very briefly held by the c-tree Server for files under
transaction control. You may occasionally observe these
in a system with a high transaction volume, and these can
be safely ignored.
forcei cmtlok
11
A very briefly held commit read lock enforced by the
c-tree Server. These will only occur when the
COMMIT_READ_LOCK option is enabled in the server
configuration file. These may be occasionally observed in
systems with high transaction volumes.
Note: The first five lock types listed in the table are only supported with a c-tree Server built with
strict serialization support.
8.6
How do I clean and reset the transaction numbers for
my files?
FairCom provides the c-tree Clean Transaction Water-Mark utility, ctclntrn, to reset the
high-water mark transaction numbers in your index files.
In the event of an impending transaction number overflow, the server administrator should follow
these steps to restart transaction numbering:
1. Perform a clean c-treeACE shutdown.
2. Delete the transaction logs and housekeeping files: files S0000000.FCS, S0000001.FCS,
D*.FCS, I*.FCS, and L*.FCS.
3. Use the ctclntrn utility to clean all indices (which resets the transaction numbers in the leaf
nodes and index header) used by your application, including your application index files,
superfiles, variable-length data, and c-tree Server files including the following if present:
• FAIRCOM.FCS -- If you are not using any User IDs or passwords other than ADMIN and
GUEST, you can simply delete this file. (If you do delete this file, tc-treeACE will re-create
it with the single user ADMIN and password ADMIN.)
• CTSYSCAT.FCS -- This is only present if you are using c-tree ODBC Drivers.
• SEQUENCEIX.FCS
• SYSLOGIX.FCS
• SYSLOG*.FCS
• ALL c-treeACE SQL Database Dictionaries
 <databasename>.dbs/SQL_SYS/<databasename>.fdd
 ctdbdict.fsd (session dictionary)
4. Restart the c-tree Server.
The server will create new transaction logs and start transaction numbering from 1 again.
www.faircom.com
All Rights Reserved
133
It is important to run ctclntrn on all files. If you miss any files and later open that file with a large
transaction number in its header, the server will again increase its transaction number to that
large value. You will need to repeat this procedure should that occur.
FYI: The ctclntrn utility uses the CleanIndexXtd() c-treeACE function. This function cleans any
leaf nodes of exceptional transaction marks and resets the transaction high-water mark in the
header to zero. This avoids rebuilding the entire index file.
You can use the c-tree High-water Mark Utility, cthghtrn, to verify that the transaction high-water
marks in the files are back to zero, or other reasonably low number.
Tip: The AUTO_CLNIXX YES configuration option can help automate and detect files which
have been missed.
See Also
 ctclntrn Utility - Clean Transaction Mark (http://docs.faircom.com/doc/ctreeplus/#31074.htm)
 cthghtrn - Displays the high-water mark for transactions
(http://docs.faircom.com/doc/ctreeplus/#31083.htm)
 AUTO_CLNIDXX (http://docs.faircom.com/doc/ctserver/#57502.htm)
8.7
Pending File ID Overflow: Error 534 in CTSTATUS.FCS
If c-treeACE automatically shuts down and the following message is found in CTSTATUS.FCS,
the transaction file numbers have been exhausted:
- User# 00018
- User# 00018
Pending File ID overflow: 534
O18 M18 L58 F-1 Pfffff003x (recur #1) (uerr_cod=534)
This can be an issue on older c-treeACE versions (before revision 26980) because they used file
ID numbers each time a c-tree data or index file was physically opened, even if it was just read,
not written. Now c-treeACE uses a file ID number only when a file is physically opened and then
updated.
Follow these steps to get back into operation:
1. Shut down c-treeACE Server cleanly: Verify that CTSTATUS.FCS shows that all connections
were successfully closed and a final checkpoint was written, as indicated by the message
"Perform system checkpoint" in CTSTATUS.FCS.
2. Remove your transaction log files (L*.FCS and S*.FCS files).
3. Restart c-treeACE.
Note: The "Pending File ID Overflow" message is not to be confused with the message "Pending
TRANSACTION # overflow" which has the same error code (534) but has a different cause.
See also Pending File ID Overflow (http://www.faircom.com/wp/file_id/) in the FairCom
Whitepapers.
www.faircom.com
All Rights Reserved
134
8.8
Timeout Error Diagnosis
The question we are trying to answer is what is causing calls to the c-tree Server made by c-tree
client processes to fail with error 808/809? To answer these questions it is helpful to have
answers to the following questions:
 Is there a pattern to the times at which the errors occur?
 Is there a pattern as to which processes encounter the error?
 Are there any factors common to the customer sites that encounter the error (especially
factors that are not present on systems that do not encounter the error)?
 What c-tree function call returned error 808/809? If it's a record read call, that points to record
locking as a likely cause.
Recent Observations
Some of the intervals between recent monitoring log entries are larger than expected (say 16
seconds although lock dumps are being taken every 5 seconds). This raises the questions:
 What could cause the intervals to be unexpectedly large? All the timestamps tell us is that the
time between the taking of the two timestamps is 16 seconds. We don't know where the delay
occurs.
 How can we understand the cause of the delay? If it is the c-tree Server delaying its response
to the client, taking a process stack trace of the c-tree Server will show us where in the code
the threads are blocked. Knowing this, we can come up with ideas as to the cause.
Options to Consider
Understanding the cause of the error using the binaries that are already deployed at customer
sites:
1. Review what we have learned so far.
2. Above all, the most likely cause of errors 808/809 is application lock behavior. This is at least
partly confirmed by specific and documented cases1,2. We should at a minimum attempt to
rule out lock problems first in each case. This can be accomplished with SNAPSHOT.FCS
data at the very least and lock dump data if possible.
Understanding the cause of the error that might require new c-tree Server or client application
binaries:
1. Consider using the blocking lock timeout feature. With the blocking lock timeout, a call to the
c-tree Server that times out on a blocking lock request will fail with error 827, which will make
it very easy to distinguish between delays that involve locking and those that do not. A
pre-production test system is a good candidate for this type of test.
2. The client binary can be modified to produce a server stack trace at the appropriate time.
Consider placing a pstack() call (as well as a Snapshot() and LockDump() calls) in the
c-tree client code immediately before the 808/809 error is returned to obtain a stack trace of
the server in this instant in time. This would prove a strategic time and location to grab the
c-tree Server state.
3. Other ideas?
www.faircom.com
All Rights Reserved
135
Proposed actions
Collect a complete repository of data for occurrences of the error. It is important to collect as
much information about all occurrences of the error 808/809 as possible, so we can look for
patterns. For each occurrence include:
 Customer name/site at which the error occurred
 Version of FairCom/Customer/system software running on the system
 What is the socket timeout value that is in use on the system?
 Relevant software configuration details: ctsrvr.cfg, anything else?
 Relevant information about hardware in use on the system: # of CPUs, disk type, location of
data/index files, transaction logs
 Complete I/O subsystem details. SAN drive manufacturer, configurations, partitioning, RAID
levels, backup methods
 Time and date at which the error occurred
 What processes encountered the error
 What happened next: were processes restarted, and did the condition happen again or was
operation normal after that?
 What monitoring data do we have from both normal operation and the activity at the time the
error occurred? Examples include SNAPSHOT.FCS, lock dump log, application error logs,
CTSTATUS.FCS, c-tree Server process stack traces, any other system logs such as disk
data (sar) or CPU data?
 What analysis have we done on the available data? Did we at least examine
SNAPSHOT.FCS, lock dump log, CTSTATUS.FCS, c-tree Server process stack trace?
 Discuss specific cases, which showed up as errors 808/809 and have been resolved.
8.9
Heap Debugging on Solaris 9+ Operating Systems
You can enable heap debugging for the c-treeACE process by setting these environment
variables before startup.
export LD_PRELOAD=libumem.so.1
export UMEM_DEBUG=default
export UMEM_LOGGING=transaction
This is a low overhead malloc() debugging method, suitable for a production environment
experiencing possible heap corruption. With the above options, it will check some guard zones for
memory overwrites on alloc/free.
It also has many commands when a core generated with libumem is used with the mdb
debugger.
::umem_status and ::umem_verify are useful, and the complete list of dcmds can be found in mdb
by executing:
> ::dmods -l libumem.so.1
man umem_debug has more details.
watchmalloc is another malloc debugging library on Solaris that detects memory overwrites more
reliably, however, runs very slowly and is not useful in a production environment.
www.faircom.com
All Rights Reserved
136
8.10
prstat and Performance Monitoring on Solaris Operating
Systems
The prstat utility can give a view of the c-treeACE process activity including user and system
time and time waiting for locks.
 The following shell script can be used to run prstat on the ctsrvr process at 5-second
intervals. Specify the ctsrvr process id (PID) as the command-line option:
#!/bin/csh
prstat -Lmc -p $1 5 | nawk '$1=="PID" { "date" | getline d ; close("date");
print d} { print $0 }' > ctsrvr_prstat.log
 The pstack utility is very useful for peering into the c-treeACE process. It writes call stacks
for all of the c-treeACE threads. If you can run pstack on the ctsrvr process at times you
observe long response times, it is possible to see exactly what code the threads are
executing, and if they are waiting on any particular resources.
The example below is a script to call pstack. The ctsrvr process ID is the command-line
argument:
#!/bin/csh
date >> ctsrvr_pstack.log
pstack $1 >> ctsrvr_pstack.log
8.11
Using Windows Process Explorer to Obtain Thread Call
Stacks
Process Explorer http://technet.microsoft.com/en-us/sysinternals/bb896653.aspx is a Microsoft
tool useful in viewing the internal properties of a Windows executable process. It can be a very
valuable tool in observing c-treeACE behavior when things are not functioning as expected.
Follow these steps to use this tool in viewing c-treeACE threads in process:
1. Download Process Explorer and install it.
2. Run Process Explorer and select the ctsrvr.exe or ctreesql.exe process. Right-click and
select Properties.
3. Select the Threads tab. Select the thread that is showing the most CPU use and click the
Stack button.
4. Click copy to copy the stack and send the resulting file to FairCom for analysis if requested.
www.faircom.com
All Rights Reserved
137
Here's a screen snapshot showing a typical c-treeACE thread call stack:
8.12
Generating Dump Files on 64-bit Windows
Windows Task Manager can generate dump files, which can be analyzed to help diagnose
software problems. By default, Task Manager creates 64-bit dumps even if the source is a 32-bit
process. This type of dump (a 64-bit dump of 32-bit process) is difficult to debug because only
windbg supports them and not all the functionality is available.
An alternative version of Task Manager, taskmgr.exe, is available in the c:\windows\syswow64
folder. This version creates 32-bit dumps of 32-bit processes, which allows for more thorough
debugging.
Another utility, procdump, will automatically create the preferred dump format for all processes.
To read about this utility and download it, visit:
http://technet.microsoft.com/en-us/sysinternals/dd996900
The usage and parameters are documented at the link provided above. Several parameters
useful for debugging include:
 -c - CPU threshold at which to create a dump of the process.
 -m - Memory commit threshold in MB at which to create a dump of the process.
 -t - Write a dump when the process terminates.
For example, to write up to 3 mini dumps of a process named 'consume' when it exceeds 20%
CPU usage for five seconds:
C:\>procdump -c 20 -s 5 -n 3 consume
www.faircom.com
All Rights Reserved
138
8.13
Transaction Log Increases
The most likely cause is a transaction that has been active for awhile and one or more other
clients are filling transaction logs with their transaction activity. The server must keep the log
containing the transaction begin log entry until the transaction either commits or aborts.
Questions to consider
 Is there more than one client executing transactions?
 Is there one client that has a transaction that doesn't commit for a relatively long time?
Steps to take
1. Look in CTSTATUS.FCS for messages “The number of active log files increased to ...” and
locate the explanation below those messages. It will probably have a message as follows:
Transaction (started in log <log_number>) still pending.
User# <taskid> |<username>|<nodename>|
1. If this is the case, identify what client that is and determine what it is doing. Is it expected that
the client has a transaction that has been pending for so long?
2. If there is a different explanatory message than the above, please send CTSTATUS.FCS to
FairCom support to examine.
8.14
Additional Transaction Log Number Messages
The number of active log files required to support server operation is nominally four (4). A number
of conditions require more active log files. The most important of these are:
 Increasing CHECKPOINT_FLUSH to delay flushing of buffers associated with committed
transactions.
 A pending transaction that began several logs ago, and has not yet committed or aborted.
 Dynamic dumps.
When the number of log files is about to increase, CTSTATUS.FCS receives a message to that
effect. The c-tree Server outputs an explanation as to the condition that triggered the increase.
When the increase is caused by a pending transaction, we attempt to identify the user ID and
node name associated with the transaction.
When the number of log files is not permitted to increase (because of FIXED_LOG_SPACE YES in
the configuration information), and if the need for more logs is caused by a pending transaction,
the server will disconnect the client associated with the transaction. If the following keyword
COMPATIBILITY NO_TRAN_DISCONNECT
is not part of c-tree Server configuration in ctsrvr.cfg, then the server will attempt to disconnect
the client. If the client is not disconnected, and if the client does not make a subsequent server
request, then the pending transaction will eventually lead to the server terminating abruptly with
error L56. The server terminates as it cannot ensure that a commit or abort will be added to the
transaction logs before the log that holds the TRANBEG entry will become inactive. (If the client
makes a server request, it will see the transaction attribute that indicates the need to abandon the
transaction, and the abnormal shutdown will be avoided.)
www.faircom.com
All Rights Reserved
139
8.15
Dynamic Dump Restore FMOD_ERR (48)
The c-treeACE Dynamic Dump feature creates 1 GB file extents by default. For dump backups
that are at or near this extent threshold, some dumps may generate X number of extents some
days, and X-1 on others, depending on the size of the data at the time of the dump.
When restoring these dumps, be sure to not include an extraneous dump file extents that does
not belong to the actual dump being restored. A good check is the physical date and time stamp
of the file extent, and be sure the files belong together as a group.
An easy way to avoid this problem is to disable the file extent feature:
!EXT_SIZE NO
This is a recommended default dump script option.
8.16
FUSE_ERR (22) During Automatic Recovery
Whenever a transaction controlled c-tree file is opened, it is assigned a unique "File Id" which is
used to reference it in the transaction logs. This number is stored as a 4 byte integer. If large
numbers of files are repeatedly opened and closed, the File Ids can be rapidly consumed ,
leading to a "Pending File ID overflow" message logged in CTSTATUS.FCS. This message is
logged every 10,000 file opens. The "File Id" can be reset by shutting down the server cleanly (so
no recovery is needed), and removing the transaction logs composed of the L*.FCS and
S000*.FCS files.
The FUSE_ERR during recovery is indicating that it needs the FILES setting increased to
complete recovery. There is a RECOVER_FILES keyword that controls this specifically.
RECOVER_FILES <number of files | NO>
Newer versions (9.3 and later) only assign "File Id's" when a file is actually updated, and not just
opened and read from, which substantially extends the interval before the next overflow.
8.17
Activation Failures (Error 26) on AIX 6
A previously activated server was found to not be activated with a newly provided activation key.
The fcactvat utility failed with system error 26 "Text file busy or in use".
AIX 6 can cache shared objects, in this case ctreedbs.so, and fcactvat can then not stamp the
binary. An AIX 6 utility, slibclean, is available on that platform that releases the object from the
cache allowing successful stamping.
8.18
Analyzing ctsemrqs() Calls on AIX systems
1. Parameters passed to ctsemrqs() are stored in the r3, r4, and r5 registers.
2. r2 points to the table of contents (TOC). The addresses of c-tree global variables are stored
in the TOC.
If attempting to determine the source line for a ctsemrqs() call in a function that corresponds to a
ctsemrqs() call in the disassembly and the function contains more than one ctsemrqs() call, use
this approach:
Often the first parameter passed to ctsemrqs() is the address of a global variable.
www.faircom.com
All Rights Reserved
140
Check the value that is stored into r3. If it involves r2, then dump the memory given by r2+0xn
and compare it to the addresses of global mutexes that are used in ctsemrqs() calls in the
function.
Note: Some calls like ctmutrqs() are macros that evaluate to ctsemrqs().
(dbx) stop in main
(dbx) run
0x000000010002452c ctsemrqs() + 0x190
0x0000000100040f30 ctwrtlog() + 0x1b80
Display disassembly starting a little before the ctsemrqs call at 0x1b80:
(dbx) listi &ctwrtlog + 0x1b70
0x100040f20 (ctwrtlog+0x1b70) ea220af8
ld
r17,0xaf8(r2)
0x100040f24 (ctwrtlog+0x1b74) 3880ffff
li
r4,-1
0x100040f28 (ctwrtlog+0x1b78) 63e50000
ori
r5,r31,0x0
0x100040f2c (ctwrtlog+0x1b7c) e8710000
ld
r3,0x0(r17)
0x100040f30 (ctwrtlog+0x1b80) 4bfe346d
bl
0x10002439c (ctsemrqs)
Find the offset of the TOC entry that is stored into r3 (by way of r17):
(dbx) print $r2+0xaf8
0x00000001100259f0
Display the address of the global variable:
(dbx) 0x00000001100259f0/llx
0x00000001100259f0: 110275000
Compare to c-tree global variable address:
(dbx) print &ctpchksema
0x0000000110275000
+6716
if (trnactflg) {
+6717 #ifdef MULTITRD
+6718
ctsemrqs(ctpchksema,WAIT,sOWNR SMN(5460));
====
0x000000010002452c
0x000000010003d348
(dbx) listi
0x10003d324
0x10003d328
0x10003d32c
0x10003d330
0x10003d334
0x10003d338
0x10003d33c
0x10003d340
0x10003d344
0x10003d348
ctsemrqs() + 0x190
ctcomexc81() + 0x610
&ctcomexc81 + 0x5e0
(ctcomexc81+0x5ec) 63e40000
(ctcomexc81+0x5f0) 63030000
(ctcomexc81+0x5f4) 4bfe7365
(ctcomexc81+0x5f8) 60000000
(ctcomexc81+0x5fc) 4bffff38
(ctcomexc81+0x600) 3b800001
(ctcomexc81+0x604) 3880ffff
(ctcomexc81+0x608) 63e50000
(ctcomexc81+0x60c) 60780000
(ctcomexc81+0x610) 4bfe7055
ori
ori
bl
ori
b
li
li
ori
ori
bl
r4,r31,0x0
r3,r24,0x0
0x100024690 (ctsemclr)
r0,r0,0x0
0x10003d26c (ctcomexc81+0x534)
r28,0x1
r4,-1
r5,r31,0x0
r24,r3,0x0
r3 is already set.
Look for all references to (r2). Then for each reference, do this to output the address of the global
variable:
set x=$r2+0x1130; &x/llx
(dbx) print &ctpdcmsema
0x0000000110287fe0 = 0x1130(r2) from the above method
(dbx) print &ctpcomsema
0x0000000110272370 = 0x760(r2) from the above method
this code loads r3 with &ctpdcmsema and checks if sOWNR != ctpdcmsema->ownr:
www.faircom.com
All Rights Reserved
141
0x10003d3b4
0x10003d3b8
0x10003d3bc
0x10003d3c0
0x10003d3c4
(ctcomexc81+0x67c)
(ctcomexc81+0x680)
(ctcomexc81+0x684)
(ctcomexc81+0x688)
(ctcomexc81+0x68c)
e8621130
e8630000
80030044
7c070000
4082ff74
ld
ld
lwz
cmp
bne
r3,0x1130(r2)
r3,0x0(r3)
r0,0x44(r3)
cr0,0x0,r7,r0
0x10003d338 (ctcomexc81+0x600)
So the call is either using ctpcomsema or ctpdcmsma. In the stack trace, it is updbuf() that calls
ctcomexc81() so it must be this call:
ctcomexc81(TRN_ADATA,Lhwt tran,(pGENBUF) db thHan);
which means it's ctpdcmsema:
ctmutrqs(ctpdcmsema,sOWNR SMN(6280));
====
0x000000010002452c
0x0000000100031004
(dbx) listi
0x100030ff4
0x100030ff8
0x100030ffc
0x100031000
0x100031004
ctsemrqs() + 0x190
ctabtexc81() + 0x53c
&ctabtexc81 + 0x52c
(ctabtexc81+0x52c) e8621318
(ctabtexc81+0x530) 3880ffff
(ctabtexc81+0x534) 63850000
(ctabtexc81+0x538) e8630000
(ctabtexc81+0x53c) 4bff3399
ld
li
ori
ld
bl
r3,0x1318(r2)
r4,-1
r5,r28,0x0
r3,0x0(r3)
(dbx) print $r2+0x1318
0x0000000110026210
(dbx) 0x0000000110026210/llx
0x0000000110026210: 110288208
(dbx) print &ctpabtsema
+1168
ctsemrqs(ctpabtsema,WAIT,sOWNR SMN(5570));
====
0x000000010002452c
0x0000000100058a90
(dbx) listi
0x100058a80
0x100058a84
0x100058a88
0x100058a8c
0x100058a90
ctsemrqs() + 0x190
ctdwnfil() + 0x338
&ctdwnfil + 0x328
(ctdwnfil+0x328) 63a50000
(ctdwnfil+0x32c) e9e20170
(ctdwnfil+0x330) 3880ffff
(ctdwnfil+0x334) e86f0000
(ctdwnfil+0x338) 4bfcb90d
ori
ld
li
ld
bl
r5,r29,0x0
r15,0x170(r2)
r4,-1
r3,0x0(r15)
0x0000000110025068
(dbx) 0x0000000110025068/llx
0x0000000110025068/llx
(dbx) print &ctpocsema
0x0000000110047548
ctmutrqs(ctpocsema,sOWNR SMN(2905));
if (ctnum->chnacs == 'n') {
====
0x000000010002452c
0x000000010005ba90
ctsemrqs() + 0x190
OPNFILX() + 0x738
www.faircom.com
All Rights Reserved
142
(dbx) listi
0x10005ba80
0x10005ba84
0x10005ba88
0x10005ba8c
0x10005ba90
0x10005ba94
0x10005ba98
0x10005ba9c
0x10005baa0
0x10005baa4
&OPNFILX + 0x728
(OPNFILX+0x728) e9e20170
(OPNFILX+0x72c) 3880ffff
(OPNFILX+0x730) 63050000
(OPNFILX+0x734) e86f0000
(OPNFILX+0x738) 4bfc890d
(OPNFILX+0x73c) 60000000
(OPNFILX+0x740) 3861015c
(OPNFILX+0x744) 38800001
(OPNFILX+0x748) 63050000
(OPNFILX+0x74c) 480112cd
ld
li
ori
ld
bl
ori
addi
li
ori
bl
r15,0x170(r2)
r4,-1
r5,r24,0x0
r3,0x0(r15)
r0,r0,0x0
r3,0x15c(r1)
r4,0x1
r5,r24,0x0
0x10006cd70 (chkfilblk)
0x170(r2) : this is ctpocsema again
+8122
+8123
+8124
+8125
+8126
#ifdef ctFeatFILEBLOCK
if ((rc = chkfilblk(afilnam,1,sOWNR))) {
sysiocod = rc;
====
0x000000010002452c
0x000000010003b0c8
(dbx) listi
0x10003b0b8
0x10003b0bc
0x10003b0c0
0x10003b0c4
0x10003b0c8
ctsemrqs() + 0x190
ictio81x() + 0x640
&ictio81x + 0x630
(ictio81x+0x630) 3880ffff
(ictio81x+0x634) e87e0410
(ictio81x+0x638) 63850000
(ictio81x+0x63c) 7c63c82a
(ictio81x+0x640) 4bfe92d5
li
ld
ori
ldx
bl
r4,-1
r3,0x410(r30)
r5,r28,0x0
r3,r3,r25
(dbx) print &(((CTFILE *)0)->chnary)
0x0000000000000410
So ld r3,0x410(r30) is getting address of chnary.
ctsemrqs(&ctnum->chnary[0]->siosema,WAIT,sOWNR SMN(1320));
====
0x00000001000c2b4c
0x0000000100059b54
8.19
ct_tflstt() + 0x190
ctdwnfil() + 0x13fc
CPUs Report Different Times on Linux, Causing
Unexpectedly Long sleep() Times
On a multi-core system running CentOS Linux, calls to sleep() were observed to take an
unexpectedly long time. It is believed the system time reported by the CPUs varies, as was
confirmed by this experiment:
The Linux taskset utility can be used to run a process on specified CPUs. The date on each CPU
differed:
taskset
taskset
taskset
taskset
-c
-c
-c
-c
0
1
2
3
date
date
date
date
www.faircom.com
All Rights Reserved
143
Mon
Mon
Mon
Mon
Aug
Aug
Aug
Aug
8
8
8
8
11:20:04
11:20:19
11:20:16
11:20:20
CDT
CDT
CDT
CDT
2011
2011
2011
2011
The Hyper-V VM was used in this case and it was found that adding the following boot options
resolved the problem, as described here:
http://hardanswers.net/correct-clock-drift-in-centos-hyper-v
divider=10 clocksource=acpi_pm (for 32bit kernel)
8.20
Prevent FPUTFGET LNOD_ERR Error (50) from
OpenIFile()
A c-treeACE FPUTFGET application reported numerous LNOD_ERR errors (50, Could not lock
node). Changing the fclock setting on the customers computer to a much larger value resolved
this unusual error.
8.21
Troubleshooting Replication Issues
If replication is not working, check the following:
Is replication enabled for the file? Use the ctinfo utility to check this:
ctinfo yourreplicatedfile.dat
ADMIN ADMIN FAIRCOMS
Look for:
Extended File Mode Details:
ctREPLICATE
: file is replicated
1. If replication is not enabled for the file:
a. Check that the REPLICATE option is properly specified in ctsrvr.cfg.
b. Add DIAGNOSTICS REPLICATE to ctsrvr.cfg. When opening a file, a message is logged
if replication cannot be enabled for the file.
2. If replication is enabled for the file:
a. Check that the Replication Agent is running and is properly connected to source and
target
b. Check source server transaction log entries. Use the ctrepd utility and/or Replication
Agent change log (enable the log_change_details option in ctreplagent.cfg).
c. Check the replication exception log for errors:
 Did the Replication Agent open the file on the target server?
 Did applying adds/deletes/updates fail?
If you are using two-way replication or multiple Replication Agents connected to a server, be sure
to set the unique_id option in the Replication Agent configuration file so that each Replication
Agent has its own unique ID.
If you are doing two-way replication between servers on the same machine, use the
REPL_NODEID option in both servers' configuration files to set unique node IDs for the servers.
www.faircom.com
All Rights Reserved
144
If you use localhost or the DNS name for source_server or target_server in
ctreplagent.cfg, you will need to use REPL_NODEID.
8.22
gdb Remote Debugging
This section shows an example of how to remote debug using gdb, the GNU Project Debugger,
on a different system architecture. In this example:
 Host=x86 Linux
 Target =ARM linux
The gdbserver must be compiled and run on the target system. The gdb must be specially
compiled to be aware of the target architecture.
See: https://sourceware.org/ml/gdb/2005-02/msg00074.html
(https://sourceware.org/ml/gdb/2005-02/msg00074.html)
To build gdb with auto-detect host (x86) and ARM-Linux target:
$ cd gdb-6.3
$ ./configure --target=arm-linux
$ make
$ file gdb/gdb
gdb/gdb: ELF 32-bit LSB executable, Intel 80386, version 1 (SYSV), for
GNU/Linux 2.2.5, dynamically linked (uses shared libs), not stripped
$ cd gdb/gdbserver
$ export CC=/usr/local/bin/arm-linux-gcc
$ ./configure --host=arm-linux
$ make
$ file gdbserver
gdbserver: ELF 32-bit MSB executable, ARM, version 1 (ARM), for GNU/Linux
2.4.3, dynamically linked (uses shared libs), not stripped
Copy gdbserver to the target and run your program on the target using TCP/IP. This alternate
syntax can be used for the COM port:
# gdbserver host:2345 ./ctsrvr
On the host, start your special gdb version and issue the following commands:
#local copy of binary to debug
(gdb) file ./ctsrvr
#path to local "root" for resolving system libraries with absolute paths
(gdb) set sysroot /usr/local/opt/crosstool/arm-linux/gcc-3.3.4-glibc-2.3.2/arm-linux
#path to any local copies of libraries using relative paths
(gdb) set solib-search-path
/usr/local/opt/crosstool/arm-linux/gcc-3.3.4-glibc-2.3.2/arm-linux/lib
#attach to remote process host:port
(gdb) target remote ts7200:2345
www.faircom.com
All Rights Reserved
145
8.23
"ctntio error" Entries in Status Log File CTSTATUS.FCS
SYMPTOMS
Entries such as the following line appearing in c-tree Server's status log file CTSTATUS.FCS:
- User# <taskid> ctntio:
|<userid>|<nodename>|:
- User# <taskid> ctntio:
|<userid>|<nodename>|:
read error – O<taskid> bytes=0 pErr=127
161
send error – O<taskid> bytes=0 pErr=128
161
where:
<taskid> is the task ID assigned to the c-tree Server thread that logged the error message
<userid> is the user ID for the thread that logged the error message
<nodename> is the node name for the thread that logged the error message
CAUSE
When a communication error occurs, the c-tree Server logs a ctntio error message in the status
log file CTSTATUS.FCS. The most common cause of the “ctntio: read error” message is that a
client process terminated without first disconnecting from the c-tree Server. A “ctntio: send error”
message can occur if the client process terminates while the c-tree Server is attempting to send a
response to the client process.
One common way that a client process terminates without first disconnecting from the c-tree
Server is that a user turns off his machine without first properly logging out of the application.
The following are other possible causes of ctntio errors in CTSTATUS.FCS:
 Physical network problems
 An overworked network transport layer that is timing out and doing retries
RESOLUTION
When investigating the cause of ctntio errors, first check for the most common cause: a client
process terminated without properly disconnecting from the c-tree Server. Note that the
application can set the node name after connecting to the c-tree Server by calling the
SetNodeName() c-tree API function. Setting a descriptive node name (including details such as
process ID, thread ID and client machine name or IP address) can help you associate ctntio error
messages with the corresponding client process.
If you rule out the most common explanation, check if the client application is also getting errors
such as ARQS_ERR (127), could not send request) or ARSP_ERR (128), could not receive
answer) when calling c-tree functions. In that case, check for possible network problems as
follows:
Ensure the c-tree Server's host machine is not burdened beyond its capacity. Using a more
powerful machine or limiting the number and types of applications on a machine can improve
performance and limit errors at the communication level. Also, ensure no specific application is
over-using resources on the host machine.
If you find that the ctntio errors are due to heavy network activity, increasing the priority of the
c-tree Server's process can eliminate or reduce the occurrence of ctntio errors. This should be
done cautiously as it will affect other applications running on the same machine.
www.faircom.com
All Rights Reserved
146
The error messages in the status log can be turned off, but unless they are an inconvenience, this
is not recommended. The messages serve as a good health check on the state of your network
and may be an early warning of more serious network and system problems. To disable the
messages, add CTSTATUS_MASK VDP_ERROR to the ctsrvr.cfg configuration file and restart the
c-tree Server.
MORE INFORMATION
To provide a little more context, the following a short high level description of how c-tree Server's
client/server communication operates.
The c-tree Server’s communication is initiated by the client process: the client makes the
connection, the client sends the request, and the client normally terminates the connection. The
c-tree Server is only a "listener and responder".
In the c-tree Server process, there is a thread for each client attached to the c-tree Server which
is waiting on a blocking read until the next request from the client. Effectively it waits forever.
If the operating system determines that the communication channel is invalid for whatever reason
(crashed client, broken network connection, overloaded network layer that cannot handle
messages in a timely manner), the blocking read is released. When the blocking reads returns,
the server attempts to read data from the communication channel but there is none. Based on
the error code returned by the socket read operation, the thread can determine if it should retry
the read. If retry is not an option or the maximum number of retries has been reached, the ctntio
read error message is written to the status log file CTSTATUS.FCS and the client session is
marked for termination and cleanup. This is not a fatal error to the c-tree Server since it is able
to abort any open transactions for the user and data integrity is assured. The effect should be
more apparent on the client side because it can make no further requests to the c-tree Server
unless it reconnects.
8.24
"WARNING: ct_lflsema livelock" Entries in Status Log
File CTSTATUS.FCS
SYMPTOMS
Entries such as the following lines appearing in c-tree Server's status log file CTSTATUS.FCS:
WARNING: ct_lflsema livelock
Log flush from buffer overflow. Current LFW Channel block not set: 1
CAUSE
This condition occurs when the COMMIT_DELAY logic is enabled and the c-tree Server is trying to
acquire a lock on the log flush semaphore (ct_lflsema). If a large number of retries does not lead
to either acquisition of the semaphore or the flushing of the log, then a warning is posted in the
status log about a possible livelock problem, and the commit delay logic is automatically disabled.
The consequence of disabling the commit delay logic could lead to a drop of performance.
A possible condition that may trigger a "ct_lflsema livelock" warning, may occur during a log
extension operation of a large transaction log files (L*.FCS). If the operation takes too long to
complete, it may cause an excessive looping that in turn produces the warning situation.
www.faircom.com
All Rights Reserved
147
RESOLUTION
If the cause of the warning is latency during log extension, you have a number of options to
decrease the latency:
 Transaction Log Template feature. With the Transaction Log Template feature enabled, new
empty log templates are created at server startup to serve as a log template. Whenever a
new log is required, the corresponding blank log file is renamed to LXXXXXXX.FCS instead
of being created from scratch.
 Decrease the size of transaction log files using the configuration keyword LOG_SPACE.
 Upgrade the underlying hardware and/or software file system where the transaction log files
are stored.
MORE INFORMATION
It is impossible to know if a livelock detection represents a deadlock scenario, or simply a timing
issue that would have cleared if the limit on the retry loop counter was increased. The limit is set
by a #define and increasing such value requires a customization of the c-tree Server.
For additional information about the Transaction Log Template feature, please read the
Transaction Log Template White Paper.
8.25
Disappearing c-treeACE Core Files on Linux
Uh-oh...it happens. Perhaps you ran shy of memory. Or worse, you violate FairCom’s cardinal
rule of transaction logs: You ran out of drive space. Your c-treeACE process unexpectedly dies.
FairCom asks to see your core file for analysis. You go to look and...it’s NOT THERE!
The Redhat daemon ABRT, Automatic Bug Reporting Tool, (abrtd process) strikes again!
Automatic Bug Reporting Tool (ABRT)
(https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Deployment_
Guide/ch-abrt.html)
This tool, found on modern Redhat Linux systems, sets limits, in addition to ulimits, for core size,
and and other problem application information. You should become familiar with this very useful
utility suite. More importantly, ABRT is integrally tied to the Redhat package management system
for automatic bug reporting. As such, this tool may remove unknown core files as they are
dropped.
Why does the abrtd daemon delete recently created application core dumps?
(https://access.redhat.com/solutions/168603)
Look for messages such as the following in your system logs:
Dec 12 3:19:22 hostname abrtd: Directory 'ctreedbs-13412346-1725' creation detected
Dec 12 3:19:22 hostname abrtd: Executable '/home/FairCom/servers/bin/ace/sql/ctreesql' doesn't
belong to any package
Dec 12 3:19:22 hostname abrtd: Corrupted or bad crash /var/spool/abrt/ctreedbs-13412346-1725
(res:4), deleting
This is the case for applications not installed via the Redhat package management tool. System
administrators should consider adding c-treeACE to the accepted list of applications to monitor.
This is done with the following options In your /etc/abrt/abrt.conf configuration file:
 ProcessUnpackaged = yes/no
www.faircom.com
All Rights Reserved
148
This directive tells ABRT whether to process crashes in executables that do not belong to any
package. The default setting is no.
 SaveBinaryImage = yes/no
This directive specifies whether ABRT's core catching hook should save a binary image to a
core dump. It is useful when debugging crashes which occurred in binaries that were deleted.
The default setting is no.
FairCom advises to also configure your ulimit to allow unlimited core files (-c) (within storage
space availability, of course).
8.26
c-treeACE Memory Use and glibc malloc per-thread
Arenas
During testing and debugging, it has been observed that newer Linux versions have produced
noticeably larger core files than would be expected from memory usage statistics. A core file is
normally close to the size of the process’s working memory space. A bit of research has turned
up a somewhat surprising finding many of our Linux users, glibc users in particular, should be
aware of.
The C runtime (GLIBC >= 2.10) now allocates a new heap for each thread on its first memory
allocation call, and each heap is 64 MB. This behavior can be reproduced with a small test
program. Create a thread and have it sleep without calling malloc(), and process memory use
increases only by the thread’s stack size. However, if your thread calls malloc(), process memory
use increases by about 64 MB. This is by design with newer versions of glibc (>=2.10).
 Malloc per-thread arenas in glibc
(http://journal.siddhesh.in/posts/malloc-per-thread-arenas-in-glibc.html)
 Linux glibc >= 2.10 (RHEL 6) malloc may show excessive virtual memory usage
(https://www.ibm.com/developerworks/community/blogs/kevgrig/entry/linux_glibc_2_10_rhel_
6_malloc_may_show_excessive_virtual_memory_usage?lang=en)
This change was introduced for scalability purposes. Allocating a separate heap for each thread
reduces contention between the threads up to a limited number of threads. The creation of new
heaps is limited to 8 times your CPU core count (64-bit systems) or 2 times your CPU core count
(32-bit systems).
You can modify this behavior via an environment variable visible to your process. Set
MALLOC_ARENA_MAX to 1 before starting c-treeACE, then only one heap is created for your
process, and observed memory use appears as may be expected, that is, process size plus any
memory allocations. This must be done before the first malloc() call.
It is also possible to call mallopt() to change MALLOC_ARENA_MAX directly in your application.
Example:
#include <malloc.h>
...
mallopt(M_ARENA_MAX, 1);
...
FairCom engineers are studying whether to include a c-treeACE configuration option and allow
modifying this value such that it is tunable for specific applications. If performance profiling
indicates appreciable gains can be found, look for this change in a future c-treeACE release. In
www.faircom.com
All Rights Reserved
149
the meantime, you may wish to explore how this impacts your specific c-tree database
applications.
www.faircom.com
All Rights Reserved
150
9.
9.1
c-treeACE SQL Troubleshooting
Java Configuration for c-treeACE SQL Stored
Procedures, Triggers and User Defined Functions
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
9.2
Setting/Enabling Advanced Features in SQL Explorer
c-treeACE SQL provides numerous options for advanced diagnostics. These can be enabled
from your configuration file, built in stored procedures or
The c-treeACE SQL Explorer utility is an extremely useful tool in administering your SQL
databases.
Enable advanced features in c-treeACE SQL Explorer:
1. Right click on SQL Explorer.
2. Choose "Properties".
3. In the "Target" box, after c-treeSQLExplorer.exe, add the "-adv" option as follows:
.../c-treeSQLExplorer.exe -adv
www.faircom.com
All Rights Reserved
151
4. Open c-treeACE SQL Explorer.
5. Click File->Debug Flags.
6. Select one or more of the following:
• sql
• opt
• log error
• display cost
For advanced execution debugging, you may select:
• xec
The java option is internal to stored procedure and triggers handling and is not typically useful
for end users:
• java
c-treeACE SQL Explorer's log (trace file)
You will find the output of c-treeACE SQL logging in the following file, found in the server's
working directory:
c:\Faircom\9.4\...\bin\ace\sql\data: file\sql_server.log
See Also
 Advanced c-treeACE SQL Logging http://docs.faircom.com/doc/sqlops/40862.htm
9.3
SRLSEG not Available in c-treeACE SQL When ROWID
is Used
Only 1 serial segment mode (SRLSEG) is allowed per data file.
ROWID is used by default with c-treeDB and c-treeACE SQL and uses the SRLSEG mode.
SRLSEG also imposes a performance overhead as it is a special index. This mode can be
disabled on a file by file basis at file creation time.
c-treeACE IDENTITY support provides a much enhanced auto-numbering option, while retaining
SRLSEG for ROWID use. From SQL this is easy to include in your tables:
CREATE TABLE mytable (name CHAR(20), age INTEGER, name_id INTEGER IDENTITY(1,1));
Temporarily Disable SRLSEG or IDENTITY
9.4
What are .fdk Files in the SQL_SYS Directory?
c-treeACE SQL maintains the SQL system tables in the <dbname>.dbs\SQL_SYS\<dbname>.fdd
file. This file is a standard c-treeACE superfile; a file containing all of the system tables and
indexes. For example
.\ctreeSQL.dbs\SQL_SYS\ctreeSQL.fdd
There is one .dbs directory and .fdd system table per SQL database.
www.faircom.com
All Rights Reserved
152
When c-treeACE SQL upgrades require changes to the system tables, a conversion automatically
takes place upon server startup, with all databases listed in the session dictionary (ctdbdict.fsd).
The process is as follows:
1. The existing <dbname>.fdd file is copied to <dbname><timestamp>.fdk
2. c-treeACE SQL performs the conversions on <dbname>.fdd
3. A template database, __Master.dbs, database is created and comparisons made for
validation
Each database found is converted in a separate transaction. If the conversion fails for any
reason, for example, an abnormal shutdown of the server, <dbname>.fdk can be copied back to
<dbname>.fdd. Check CTSTATUS.FCS for any reported conditions when updating c-treeACE
SQL.
The following c-treeACE SQL versions require system table upgrades:
 V9.5
 V9.3
 V8.27
Note: To prevent a database conversion, the SQL_OPTION NO_DB_CONVERSION keyword can
be added to the configuration file. This should only be used upon the recommendation of
FairCom support.
9.5
What is __Master.dbs?
__Master.dbs is a template database layout generated by <FC_PRPD_ACE> when it needs to
upgrade existing databases to a new version (e.g., when upgrading from V10 to V11). It is a
template form of the new database format which <FC_PRPD_ACE> uses during the upgrade.
It is automatically removed after the upgrade, although in some situations it may be left behind. If
the server starts and stops correctly, it can be removed.
9.6
Error While Creating SQL Database
While creating a SQL database, it is possible to encounter the following error:
Error while creating the SQL Database: 19
When the ctreesql server is started, it will check for the file ctdbdict.fsd (the session dictionary)
which has a list of all known CTDB and SQL databases. If this file doesn't exist it will be created.
Next, it will check the session dictionary for the SQL_DATABASE specified in ctsrvr.cfg
(ctreeSQL by default). If this database isn't known, the server attempts to create a new one.
This creation operation may fail with error 19, indicating that the database already exists on disk
(but it isn't listed in ctdbdict.fsd).
To use this (or any other) existing database, you can add a reference to ctdbdict.fsd using the
ctsqlcdb.exe command line utility, found in tools\cmdline\admin\client\.
Use the following command to add an existing database named ctreeSQL:
run: ctsqlcdb -add ctreeSQL FAIRCOMS
www.faircom.com
All Rights Reserved
153
If you don't want the database that is on disk, delete the directory ctreeSQL.dbs (or
SQL_DATABASE.dbs for a database called “SQL_DATABASE”), and run the following command
to create a new database named ctreeSQL:
ctsqlcdb -create ctreeSQL FAIRCOMS
You can also use c-treeISAMExplorer to add or create databases by right-clicking on the root of
the tree in the left-hand pane.
9.7
DBLOAD Debugging Help
By setting an environment variable, DBLOAD_DEBUG=Y the c-treeACE SQL dbload utility will
output a large volume of additional internal information useful when debugging usage of the
utility.
9.8
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
www.faircom.com
All Rights Reserved
154
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
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
155
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
156
9.9
Stored Procedure Error: Could not initialize class
sun.util.calendar.ZoneInfoFile
The following Java exceptions can be found when compiling stored procedures or triggers with
Java 1.7 using the ctreeSQLSP.jar file compiled with Java 1.6:
java.lang.AssertionError: Default directory is not an absolute path
java.lang.NoClassDefFoundError: Could not initialize class sun.util.calendar.ZoneInfoFile
Compiling with Java 1.6 resolves the problem.
This has been corrected as of c-treeACE SQL V10.1.
9.10
Stored Procedure Java Class Resolution
Occasionally a stored procedure does not behave as expected. One possible cause can be
improper resolution of the Java class. For example, a custom jar in the CLASSPATH may include
a class using the same name as our stored procedures generate.
The class resolution can be traced using these procedures:
1. Add the followig to ctsrvr.cfg:
SETENV DH_JVM_OPTION_STRINGS=-verbose:class;-verbose:jni
(DH_JVM_OPTION_STRINGS may contain a variety of Java options, for example, you may
be increasing the default Java heap size with -Xmx, etc. Simply add the verbose options to
the string.)
2. Start ctreesql.exe from the command line, and redirect stderr to a file:
ctreesql.exe 1>err.log
3. Connect and call the stored procedure in question (e.g., admin.p_sp_getfddversion()).
www.faircom.com
All Rights Reserved
157
4. Check err.log for the results.
Here is the expected load of procedure in err.log:
[Loaded admin_p_sp_getfddversion_SP from __JVM_DefineClass__]
Here is an unexpected version being loaded from a .class file sitting in the CLASSPATH:
[Loaded admin_p_sp_getfddversion_SP from
file:/Q:/ctreesrc/ipv6/ctreeAPI/bin.sql/data/]
9.11
When do I have to specify the owner of a table?
The answer depends on the SQL owner of the table:
 the user who creates the table owns the table and does not need to specify the owner's name
 users who did not create the table must specify the owner's name
In SQL, any user can create a table within their user space (a "schema"). The user name in
c-treeACE SQL acts as the schema name. If no schema is explicitly specified, the user is the
assumed schema. The user who created the table does not need to specify their own name when
accessing the table.
To access tables outside of your schema, you must have the appropriate privileges (through
GRANT or by being an ADMIN) and you must explicitly specify the owner of the table (the
schema).
Example:
The ADMIN user creates a table called "custmast" and GRANTs SELECT privileges to a user
called JOHNDOE. This allows JOHNDOE to access this table by explicitly specifying
"ADMIN"."custmast" to properly distinguish the correct "custmast" table. (Quotes not necessary in
most cases.)
Imported Tables
With imported tables, the owner defaults to the user who authenticated with the import utility. If
the user has ADMIN privileges, a different owner can be specified with the -o switch. See
ctsqlimp Usage (http://docs.faircom.com/doc/sqlops/#41004.htm) in the c-treeSQL Server
Operations and Utilities Guide.
Setting a Default Schema
To set a default "schema" use the SET SCHEMA statement. If JOHNDOE executes the following,
then "ADMIN".<tablename> will be assumed for tables without an explicit schema for the
remainder of JOHNDOE's session:
SET SCHEMA ADMIN
SET SCHEMA can be called as needed within a session.
www.faircom.com
All Rights Reserved
158
9.12
How do I convert tables in a database to be case
insensitive?
Sometimes you have data and index files that were created with the case-sensitive option and
you want to make them case-insensitive. The SQL_OPTION DB_CASE_INSENSITIVE option
enables case-insensitive comparisons, sorting, and identifiers within a database. This option is a
database-level attribute that is set when a database is created, so it only affects databases that
are created after it is enabled.
Notice that this option does not actually convert your existing tables to be case-insensitive.
Instead it is used in a process of creating new, case-insensitive tables and importing the existing
data into them.
This option affects the key segment definition. An index created in a database that has been
created as case-insensitive uses the USCHSEG segment mode instead of SCHSEG.
How To
If you have data and index files that were created with the case-sensitive option and you want to
use them in a case-insensitive database, follow these steps:
1. Add the SQL_OPTION DB_CASE_INSENSITIVE keyword to ctsrvr.cfg.
2. Use the ctsqlcdb utility to create the new database.
3. Use PUTIFIL() to change your segment modes to case-insensitive segment modes. You will
need to write some code to do this (it is not available in a utility).
4. Rebuild the indices.
5. Use the SQL import utility (ctsqlimp) to import the tables into the new database.
The new database will be case-insensitive.
9.13
Analyzing JVM Memory usage with c-treeACE SQL
Java Stored Procedures
Find the committed and maximum sizes of the JVM heap in your ctreesql process.
1. Run jconsole (found in the JDK's bin directory).
2. In the New Connection dialog box, choose the Local Process entry with the process ID of the
ctreesql process and click Connect.
3. Select the Memory tab and view the Heap Memory Usage chart. What are the values of the
Committed and Max heap sizes that are shown below the graph? In the example below it is
"Committed: 59,072 bytes", which is 59 MB, and "Max: 699,072 kbytes" which is about 699
MB. (Note that even if you click "Perform GC" and the used amount of the heap is reduced,
the committed value, which is the actual memory in use by the JVM and not available for
other purposes, does not change.)
If you find that the JVM is using a significant amount of memory, FairCom recommends setting
smaller initial and maximum JVM heap sizes, with the goal of making more memory available for
c-treeACE SQL use. This is accomplished using the following option in ctsrvr.cfg and restarting
c-treeACE SQL:
SETENV DH_JVM_OPTION_STRINGS=-Xms100m;-Xmx100m
www.faircom.com
All Rights Reserved
159
This example sets initial and maximum heap sizes to 100 MB each. After setting this option and
restarting c-treeACE SQL, run jconsole again and you should expect to see Committed and Max
values are both 100 MB.
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
and memory use. Two options of immediate use are the minimum and maximum size of the
memory heap.
www.faircom.com
All Rights Reserved
160
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)
 -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
www.faircom.com
All Rights Reserved
161
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 154)
9.14
Compiling c-treeACE SQL PHP on Linux/Unix
c-treeACE SQL PHP is provided as a ready to go driver for currently available versions of PHP.
However, PHP regularly advances, and new versions out pace current support quickly. In that
case, you usually have to rebuild the PHP driver to match the specific version of PHP in your
environment.
Usually, you can simply execute our provided build script from the /src directory of your
c-treeACE SQL PHP driver installation:
>
>
>
>
phpize
./configure --make-ctsql
make
make install
However, you may find that the configure scripts don't always match the current autotools version
of your Linux flavor. In that case, you need to regenerate the ./configure script. Consider the
following sequence. Actual steps may differ slightly depending on your autotools version and
Linux flavor. Check with the autotools documentation for details.
>
>
>
>
>
>
>
phpize
libtoolize
aclocal
autoreconf -i
make
make install (optional)
The driver will be in the newly created /modules folder. You are free to copy this to an appropriate
library location in your environment.
Note: You may need elevated privileges to install this into /lib or other system locations.
www.faircom.com
All Rights Reserved
162
10. COBOL Help
10.1
COBOL Compilers Supported by c-treeRTG COBOL
Edition
TESTED AND SUPPORTED
 Veryant isCOBOL
 ACUCOBOL-GT 6
 ACUCOBOL-GT 7
 ACUCOBOL-GT 8
 ACUCOBOL-GT 9
 Micro Focus Visual COBOL
 Micro Focus Net Express
 Micro Focus Server Express 5
 Micro Focus COBOL 4
 Micro Focus Server Express 4
 Cobol-IT
 Fujitsu NetCOBOL for .NET
 Fujitsu NetCOBOL for Windows
 Fujitsu NetCOBOL for Linux
 P3/COBOL
NOT TESTED: LIKELY SUPPORTED
 Fujitsu PowerCOBOL (through EXTFH interface)
NOT TESTED
 Fujitsu COBOL
 CA Realia COBOL
NOT SUPPORTED
 OpenCOBOL
www.faircom.com
All Rights Reserved
163
COBOL Help
10.2
Troubleshooting Data Conversion Errors
The fact that the XDD initially does not contain any error handling information immediately
exposes data conversion errors to a SQL user. This provides the way to begin troubleshooting
data conversion errors and to identify the proper settings to specify in your XDD file.
Checking in c-treeACE SQL Explorer
c-treeACE SQL Explorer and c-treeACE Explorer include a button to simplify the process of
checking for bad records.
To check for bad records in c-treeACE SQL Explorer or c-treeACE Explorer:
1. Select a sqlized table, such as custmast in the image above.
2. Click the Table Records tab.
3. A button labeled Check Bad Records appears at the right of the row of buttons (the image
above shows the Java version of c-treeACE Explorer where the buttons are at the top of the
tab; the .NET version, called c-treeACE SQL Explorer, shows this row of buttons at the
bottom of the tab).
4. Click the button to execute a SQL query to find records that did not sqlized properly.
Checking with a SQL Query
You can use the procedures in this section to identify data-conversion errors and use that
information to fine-tune your XDD files.
If a query fails, it is possible the failure is due to a problem with SQL data conversion.
Troubleshooting this type of error is quite easy with the following steps:
1. Identify the table (in case of a complex query) on which the conversion error occurs by
running the following SQL statement on each table involved in the query:
SELECT * FROM <table>
If none of the queries fail, the original query failure is not due to a conversion problem.
2. Run the following SQL statement to select only the records that do not properly convert:
SELECT * FROM <table> ctoption(badrec)
ctoption(badrec) is a c-treeACE extension to SQL indicating the query should return
only records having conversion errors and expose values that do not properly convert as
NULL.
www.faircom.com
All Rights Reserved
164
COBOL Help
3. Look for NULL values returned from the query in step 2. These are the fields that do not
properly convert. The remaining record values should be sufficient to identify the record that
requires investigation.
The ctoption(badrec) command generates a log file, ctsqlcbk.fcs, in the c-treeACE SQL
Server directory that can be used to determine the exact conversion error and the data causing it.
This file lists all the fields that caused a conversion error exposed in SQL along with the value of
the data that could not be converted. Note that the log contains information for the fields that
result in propagating the conversion error to SQL. It does not log conversion errors that result in a
SQL value because they were already handled successfully following the settings in the XDD.
Each log entry is made of three lines:
1. The first line is similar to the following:
Convert error XXXX on field[YYYY]
Where XXXX is the error code indicating the cause of the conversion error, YYYY is the field
on which the conversion error occurred.
2. The second line contains a message which gives internal information for FairCom technicians
to identify where the error occurs in the code, as well as a message explaining the problem.
3. The third line is a hexadecimal dump of the field content.
For example:
Convert error 4028 on field[FIELD1]
{ctdbStringFormatToDateTime} on 0000000000 failed
00000000
{ctdbStringFormatToDate} on 00000000 failed
3030303030303030
[NormalizeCobolStr] ascii value is not a digit
2020202020202020
[NormalizeCobolStr] ascii value is not a digit
2020202020202020
10.3
Error: Requested def blk is empty
The following message was seen when attempting to connect to c-treeACE SQL after a COBOL
table had been imported with the ctutil -sqlize option:
Error : -17438 "ExecuteReader - CT - Requested def blk is empty"
Along with that, the following message is logged in CTSTATUS.FCS
Mon Oct 1 13:59:43 2012
- User# 00001 LoadSQLSDK: Failed to load SQL callback library libctsqlcbk.so: dynamic linker :
./ctreesql : could not open libctsqlcbk.so
Mon Oct 1 13:59:43 2012
- User# 00001 : PANIC - TPEUTIL LoadSQLSDK callback library load failed PID 20028
A COBOL resource in the file is closely related to the referenced callback routine needed by SQL
for data type conversions.
Configuring the LD_LIBRARY_PATH environment variable to correctly pick up the path to
libctsqlcbk.so for the server process owner should correct this error.
www.faircom.com
All Rights Reserved
165
COBOL Help
www.faircom.com
All Rights Reserved
166
Appendix A.c-treeRTG Errors
The c-treeRTG solution is enabled through a server-side callback module, which implements
c-treeDB callback routines. Errors that occur within these routines generate a standard c-treeDB
error code that is context sensitive to this implementation. Here is a list of possible return codes
from this module, and their meaning in c-treeRTG XDD handling.
Symbolic
Error
Code
Description
CTDBRET_CALLBACK_1
4109
Could not find table info in XML definitions
CTDBRET_CALLBACK_2
4110
Record length does not match XML definitions
CTDBRET_CALLBACK_3
4111
Invalid or corrupted c-treeRTG resource
CTDBRET_CALLBACK_4
4112
Syntax error parsing XML definition file
CTDBRET_CALLBACK_5
4113
No longer used. (Updating records with NULL
fields not supported)
CTDBRET_CALLBACK_6
4114
Could not find field info in XML definitions
CTDBRET_CALLBACK_7
4115
Could not find filter info in XML definitions
CTDBRET_CALLBACK_8
4116
Too many record types
CTDBRET_CALLBACK_9
4117
Error setting filter condition
CTDBRET_CALLBACK_10
4118
Unexpected error during number conversion
CTDBRET_CALLBACK_11
4119
Unsupported CLOB/BLOB definition
CTDBRET_CALLBACK_12
4120
No longer used. (Field length does not match
XML definitions)
CTDBRET_CALLBACK_13
4121
Missing date/time format in XML definitions
CTDBRET_CALLBACK_14
4122
Invalid filter key settings in XML definitions
CTDBRET_CALLBACK_15
4123
No longer used. (Invalid field default settings in
XML definitions)
CTDBRET_CALLBACK_16
4124
Unexpected error in file structure: missing
NULFLD
CTDBRET_CALLBACK_17
4125
Key definition in XML does not match Physical
file
CTDBRET_CALLBACK_18
4126
Missing default for null field
www.faircom.com
All Rights Reserved
167
11. Reference Material
11.1
mtmake Command Line
c-treeACE mtmake Make Utility
The traditional mtmake build utility can still be used to configure your c-treeACE libraries. You will
find this utility in a new location reflecting the easy to use c-treeACE concepts. mtmake, is found
in the /pro directory of your c-treeACE installation.
Note: If you have previously constructed automated build processes you may need to change
some keystroke options passed to mtmake as they have changed.
mtmake Advanced Options
Advanced Options
Many users may not know that mtmake has numerous advanced options to tailor the c-treeACE
libraries for specific needs or exacting size footprints (consider embedded devices). Execute
mtmake with a question mark ("?") for a listing of these advanced options.
> mtmake ?
www.faircom.com
All Rights Reserved
168
Reference Material
A display of options and their descriptions is shown below. Contact FairCom if you have any
questions for how to tailor the c-treeACE libraries for your unique application needs.
11.2
Typical Unix Errors From errno.h Header File
sysiocod errors are system specific, and are reported directly from the operating system. For
WIndows you can use the built-in helpmsg system to obtain the meaning of these errors:
>net helpmsg <msg_no>
From Unix, you need to reference the errno.h header file. Here is a typical file (from AIX) provided
as a handy reference.
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
EPERM
ENOENT
ESRCH
EINTR
EIO
ENXIO
E2BIG
ENOEXEC
EBADF
ECHILD
EAGAIN
ENOMEM
EACCES
EFAULT
ENOTBLK
EBUSY
EEXIST
EXDEV
ENODEV
ENOTDIR
EISDIR
EINVAL
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
Operation not permitted
No such file or directory
No such process
interrupted system call
I/O error
No such device or address
Arg list too long
Exec format error
Bad file descriptor
No child processes
Resource temporarily unavailable
Not enough space
Permission denied
Bad address
Block device required
Resource busy
File exists
Improper link
No such device
Not a directory
Is a directory
Invalid argument
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
www.faircom.com
All Rights Reserved
169
Reference Material
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
ENFILE 23
EMFILE 24
ENOTTY 25
ETXTBSY 26
EFBIG
27
ENOSPC 28
ESPIPE 29
EROFS
30
EMLINK 31
EPIPE
32
EDOM
33
ERANGE 34
ENOMSG 35
EIDRM
36
ECHRNG 37
EL2NSYNC 38
EL3HLT 39
EL3RST 40
ELNRNG 41
EUNATCH 42
ENOCSI 43
EL2HLT 44
EDEADLK 45
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
Too many open files in system
Too many open files
Inappropriate I/O control operation
Text file busy
File too large
No space left on device
Invalid seek
Read only file system
Too many links
Broken pipe
Domain error within math function
Result too large
No message of desired type
Identifier removed
Channel number out of range
Level 2 not synchronized
Level 3 halted
Level 3 reset
Link number out of range
Protocol driver not attached
No CSI structure available
Level 2 halted
Resource deadlock avoided
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
#define ENOTREADY
#define EWRPROTECT
#define EFORMAT
46
47
48
/* Device not ready
/* Write-protected media
/* Unformatted media
*/
*/
*/
#define ENOLCK
49
/* No locks available
*/
#define ENOCONNECT
#define ESTALE
#define EDIST
50
52
53
/* no connection
*/
/* no filesystem
*/
/* old, currently unused AIX errno*/
/* non-blocking and interrupt i/o */
/*
* AIX returns EAGAIN where 4.3BSD used EWOULDBLOCK;
* but, the standards insist on unique errno values for each errno.
* A unique value is reserved for users that want to code case
* statements for systems that return either EAGAIN or EWOULDBLOCK.
*/
#if _XOPEN_SOURCE_EXTENDED==1
#define EWOULDBLOCK
EAGAIN
/* Operation would block
*/
#else /* _XOPEN_SOURCE_EXTENDED */
#define EWOULDBLOCK
54
#endif /* _XOPEN_SOURCE_EXTENDED */
#define EINPROGRESS
#define EALREADY
55
56
/* Operation now in progress */
/* Operation already in progress */
/* ipc/network software */
#define
#define
#define
#define
#define
#define
#define
#define
#define
/* argument errors */
ENOTSOCK
57
/* Socket operation on non-socket */
EDESTADDRREQ
58
/* Destination address required */
EDESTADDREQ
EDESTADDRREQ /* Destination address required */
EMSGSIZE
59
/* Message too long */
EPROTOTYPE
60
/* Protocol wrong type for socket */
ENOPROTOOPT
61
/* Protocol not available */
EPROTONOSUPPORT 62
/* Protocol not supported */
ESOCKTNOSUPPORT 63
/* Socket type not supported */
EOPNOTSUPP
64
/* Operation not supported on socket */
www.faircom.com
All Rights Reserved
170
Reference Material
#define
#define
#define
#define
EPFNOSUPPORT
EAFNOSUPPORT
EADDRINUSE
EADDRNOTAVAIL
65
66
67
68
/*
/*
/*
/*
Protocol family not supported */
Address family not supported by protocol family */
Address already in use */
Can't assign requested address */
#define
#define
#define
#define
#define
#define
#define
#define
#define
/* operational errors */
ENETDOWN
69
/* Network is down */
ENETUNREACH
70
/* Network is unreachable */
ENETRESET
71
/* Network dropped connection on reset */
ECONNABORTED
72
/* Software caused connection abort */
ECONNRESET
73
/* Connection reset by peer */
ENOBUFS
74
/* No buffer space available */
EISCONN
75
/* Socket is already connected */
ENOTCONN
76
/* Socket is not connected */
ESHUTDOWN
77
/* Can't send after socket shutdown */
#define ETIMEDOUT
#define ECONNREFUSED
78
79
/* Connection timed out */
/* Connection refused */
#define EHOSTDOWN
#define EHOSTUNREACH
80
81
/* Host is down */
/* No route to host */
/* ERESTART is used to determine if the system call is restartable */
#define ERESTART
82
/* restart the system call */
/* quotas and limits */
#define EPROCLIM
83
#define EUSERS
84
#define ELOOP
85
#define ENAMETOOLONG
86
/*
/*
/*
/*
Too many processes */
Too many users */
Too many levels of symbolic links
File name too long
*/
*/
/*
* AIX returns EEXIST where 4.3BSD used ENOTEMPTY;
* but, the standards insist on unique errno values for each errno.
* A unique value is reserved for users that want to code case
* statements for systems that return either EEXIST or ENOTEMPTY.
*/
#if defined(_ALL_SOURCE) && !defined(_LINUX_SOURCE_COMPAT)
#define ENOTEMPTY
EEXIST /* Directory not empty */
#else
/* not _ALL_SOURCE */
#define ENOTEMPTY
87
#endif /* _ALL_SOURCE */
/* disk quotas */
#define EDQUOT
88
/* Disc quota exceeded */
#define ECORRUPT
89
/* Invalid file system control data */
/* errnors 90-92 reserved for future use compatible with AIX PS/2 */
/* network file system */
#define EREMOTE
93
#define ESOCKTNOSUPPORT 94
#define EOPNOTSUPP
95
#define EPFNOSUPPORT
96
#define EAFNOSUPPORT
97
#define EADDRINUSE
98
#define EADDRNOTAVAIL
99
#define ENETDOWN
100
#define ENETUNREACH
101
#define ENETRESET
102
#define ECONNABORTED
103
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
Item is not local to host */
Socket type not supported */
Operation not supported on transport endpoint */
Protocol family not supported */
Address family not supported by protocol */
Address already in use */
Cannot assign requested address */
Network is down */
Network is unreachable */
Network dropped connection because of reset */
Software caused connection abort */
www.faircom.com
All Rights Reserved
171
Reference Material
#define
#define
#define
#define
#define
#define
ECONNRESET
ENOBUFS
EISCONN
ENOTCONN
ESHUTDOWN
ENOSYS
104
105
106
107
108
109
/*
/*
/*
/*
/*
/*
Connection reset by peer */
No buffer space available */
Transport endpoint is already connected */
Transport endpoint is not connected */
Cannot send after transport endpoint shutdown */
Function not implemented POSIX */
/* disk device driver */
#define EMEDIA
110
#define ESOFT
111
/* media surface error */
/* I/O completed, but needs relocation */
/* security */
#define ENOATTR
#define ESAD
#define ENOTRUST
112
113
114
/* no attribute found */
/* security authentication denied */
/* not a trusted program */
/* BSD 4.3 RENO */
#define ETOOMANYREFS
115
/* Too many references: can't splice */
#define EILSEQ
#define ECANCELED
116
117
/* Invalid wide character */
/* asynchronous i/o cancelled */
/* SVR4
#define
#define
#define
#define
#define
#define
118
119
120
121
122
123
/*
/*
/*
/*
/*
/*
STREAMS */
ENOSR
ETIME
EBADMSG
EPROTO
ENODATA
ENOSTR
temp out of streams resources */
I_STR ioctl timed out */
wrong message type at stream head */
STREAMS protocol error */
no message ready at stream head */
fd is not a stream */
#define ECLONEME
ERESTART /* this is the way we clone a stream ... */
#define ENOTSUP
124
/* POSIX threads unsupported value */
#define EMULTIHOP
#define ENOLINK
#define EOVERFLOW
125
126
127
/* multihop is not allowed */
/* the link has been severed */
/* value too large to be stored in data type */
#endif /* _ANSI_C_SOURCE */
#endif /* _H_ERRNO */
www.faircom.com
All Rights Reserved
172
Reference Material
11.3
c-treeACE Server Files
We want you to know how easy and simple your c-treeACE Server is to operate and manage. No
registry entries or other system configurations are involved in the installation and maintenance of
your c-treeACE Server. Only a small collection of server maintained "housekeeping" and
transaction log files are used and are located in the server binary directory unless otherwise
directed.
We briefly describe these files here so you can be confident in your knowledge of the c-treeACE
Server installation.
License Object
 ctsrvr-xxxxxxxx.lic - Your License Authorization File assigned with your serial number and
licensed settings. Must be present for server to start. This file replaces prior activation steps.
Status Logs
 CTSTATUS.FCS - c-treeACE Server Status Log File. Text based.
 SYSLOGDT.FCS and SYSLOGIX.FCS - SYSLOG facility security logging data file. These
are c-treeACE data and index files maintainable only by the c-treeACE Server.
User and Group Information
 FAIRCOM.FCS - Maintains c-treeACE User and Group information in a standard c-tree data
file format. Passwords are encrypted to prevent casual inspection. For a higher level of
security, it is recommended to use the ADMIN_ENCRYPT configuration keyword to fully
encrypt this file.
Transaction Logs
 Lxxxxxx.FCS - Transaction Log Files ever increasing in number as a rotating set. A minimum
of four are kept at any given time.
 S0000000.FCS - Transaction Log Start File generated during checkpoints.
 S0000001.FCS - Backup Transaction Log Start File generated during checkpoints.
www.faircom.com
All Rights Reserved
173
Reference Material
 Lxxxxxx.FCT - Transaction Log File template for enhanced performance in creating new
transaction log files.
Housekeeping Files
 D0000000.FCS - Preimage swap file
 D0000001.FCS - Holds queue entries for the space reclamation of deleted superfile members
and recovered variable length data files
 I0000001.FCS - Index of the file IDs currently open with the c-treeACE Server
 I0000002.FCS - c-treeACE Server Transaction Processing Lock File
 DNODEQUE.FCS - Permanent delete node queue file for enhanced performance of the
delete node thread
 sql_server.log - c-treeACE SQL log file used to log SQL specific messages
 ctdbdict.fsd - c-treeDB Database Session File
 ctreeSQL.dbs/SQL_SYS/ctreeSQL.fdd - c-treeACE SQL dictionary file. (c-treeACE SQL
System Tables)
 FREOPENX.FCS - Backup stream files for use when file handles become scarce
11.4
c-treeACE Utilities
A large collection of c-treeACE utilities are available for monitoring and managing your c-treeACE
Server. Here is a quick list of included utilities immediately useful for the most common
administrative tasks.
Graphical Utilities
 c-treeACE Security Admin - An easy to use intuitive interface for managing user, group and
file security information.
www.faircom.com
All Rights Reserved
174
Reference Material
 c-treeACE Monitor - Monitor the activity and health of your c-treeACE Server.
Command Line Utilities
 ctadmn - The Administrator utility is a menu driven utility for performing many common
administrative tasks.
• Add and manage users and groups
• List current logged on users
• Stop the server
• Pause the server for maintenance
• View active files and locks
• Set file passwords
 ctstop - The Stop utility halts server operation.
 ctpass - The Password utility is used to change the password for a c-treeACE Server user
account.
 sa_admin - The Security Administrator utility is used to add and change user and group
security information. Easily create scripts with this utility.
 ctinfo - The information utility provides useful information about c-treeACE files.
 ctstat - The Statistics utility has many options for monitoring the c-treeACE Server. Over 200
metrics are available for monitoring.
 ctdump - The Dynamic Dump utility submits scripts for instructing the c-treeACE Server to
perform live "hot" backups.
www.faircom.com
All Rights Reserved
175
Reference Material
11.5
NULL Handling
NULL fields are used to represent "missing information and inapplicable information." The use of
NULL allows a table to distinguish between an unknown value and a value of 0 or FALSE.
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 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.
The ctdbClearRecord() function handles NULL fields when $NULFLD$ support is available.
11.6
ISAM Parameter Files (Legacy)
The ISAM parameters specify the characteristics of the data files and indices used in an
application program. The parameters are stored in a regular ASCII text file called the ISAM
parameter file. If your application uses the high-level ISAM routines, you must construct an ISAM
parameter file or use the incremental ISAM structures previously defined. Any text editor can be
used to create or modify ISAM parameter files, provided special control characters are not
embedded in the parameter file.
This section deals with the ISAM Parameter File. When using ISAM parameter files, all files in the
parameter file are opened and closed together. With Incremental ISAM structures, the
programmer has individual file open/close control and automatic file definition storage; making
ISAM structures the recommended choice. Some applications work better with Incremental ISAM
Structures. FairCom highly recommends using Incremental ISAM structures.
ISAM Parameter File Organization
The ISAM parameter file is composed of five types of records:
 Initialization Record
 Data File Description Records
 Index File Description Records
 Optional Index Member Records
 Key Segment Description Records
Each parameter file begins with one Initialization Record which specifies, among other things, the
number of data files. Then for each data file there are a group of records beginning with a Data
File Description record. Each Data File Description record specifies the number of indices it uses.
For each of these indices there is a group of records beginning with the Index File Description
record or Index Member record. Each Index File Description record and/or optional Index Member
record is followed by one or more Key Segment Description records.
The overall organization of the records is shown in the following schematic and reflects the
hierarchical relationship among the data files and their corresponding indices:
www.faircom.com
All Rights Reserved
176
Reference Material
Parameter File Organization
Initialization Record
Data File Description Record
First Index File Description Record
First Key Segment Description Record
:::
Last Key Segment Record
Optional Index Member Records
:::
:::
Last Index File or Index Member Record
:::
REPEAT FOR EACH DATA FILE
Parameter File Contents
Each of the fields comprising the parameter file records is separated from neighboring fields by
one or more “white space” characters (blanks, tabs, or new lines). In the following subsections, if
a parameter corresponds to a formal parameter in a c-tree function call, its name is included after
the parameter’s brief description (e.g., bufs in the first position of the initialization record).
Initialization Record
The Initialization Record is made up of four numeric fields:
 Number of index file buffers (bufs)
 Number of indices
 Number of node sectors (sect)
 Number of data files
The first and third parameters correspond to the first and third parameters of the InitCTree()
function, bufs and sect, described earlier. For each index specified in the second parameter,
there is either an Index Description record or an Index Member record. For each data file
specified in the fourth parameter there is a Data File Description record. The Number of Node
Sectors times 128 is the size, in bytes, of the B-Tree nodes. The number of data files specified by
the fourth parameter of the Initialization Record must match exactly the number of Data File
Description Records. However, the number of index files given by the second parameter can be
equal to, OR GREATER than, the actual number of indices. If greater, c-tree reserves extra file
control blocks that your application may use with its own calls to OpenCtFile(), OpenIFile(), or for
more flexible numbering of files in the parameter file.
Data File Description Record
Each Data File Description record is made up of six required fields and two additional fields if
r-tree is to be used:
 Data file number (datno)
www.faircom.com
All Rights Reserved
177
Reference Material
 Data file name (filnam)
 Record length (datlen)
 File size extension parameter (xtdsiz)
File mode (filmod; see c-tree Concepts in the c-treeACE Professional Developers Guide
(http://docs.faircom.com/doc/ctreeplus/))
 Number of associated index files
If RTREE is defined in your library, which is the default in ctopt2.h unless NO_RTREE is defined,
each Data File Description record must have two additional fields:
 Symbolic name (without any spaces) of the first field in the data record
 Symbolic name of the last field in the data record
The first five fields correspond to the parameters of CreateDataFile(). The data file name must
agree with the operating system’s file naming conventions. Usually it can include a disk drive
designation and/or a directory path name. The record length parameter is used only when the file
is created. However, it should be properly maintained since the rebuild utility verifies that the
parameter file value matches the value in the data file header record. filmod specifies:
 the multi-user access to the file
 whether the file is opened permanently or virtually
 whether the data file will have fixed- or variable-length records
 the level of transaction processing
The sixth parameter specifies how many indices will be maintained for the data file. Each such
index will either be a separate c-tree file or a member of an index file. See “CreateIndexFile” and
“CreateIndexMember” in the c-treeACE Professional Developers Guide
(http://docs.faircom.com/doc/ctreeplus/). If RTREE is defined in ctoptn.h, then the seventh and
eighth parameters must be present. If the parameter file is to be used in conjunction with r-tree,
these parameters must match actual entries in the data object definition array, DODA, otherwise
r-tree will report an error. The DODA is described in “Record Schemas” in the c-treeACE
Professional Developers Guide (http://docs.faircom.com/doc/ctreeplus/). If the parameter file is
not actually for use with r-tree, then any arbitrary symbolic names may be used as long as there
are no embedded blanks.
Index File Description Record
Each Index File record has eleven required fields and one additional field if r-tree is to be used:
 Index file number (keyno)
 Index file name (filnam)
 Key length (keylen)
 Key type (keytyp; see c-tree Concepts in the c-treeACE Professional Developers Guide
 Duplicate flag (keydup)
 Number of additional index file members (nomemb)
 File size extension parameter (xtdsiz)
 File mode (filmod; see c-tree Concepts in the c-treeACE Professional Developers Guide
www.faircom.com
All Rights Reserved
178
Reference Material
 NULL key flag
 Empty character
 Number of key segments
If RTREE is defined in ctoptn.h, then one additional parameter is required:
 Symbolic index name
The first eight fields correspond to the parameters of CreateIndexFile(). The index file name
must agree with the operating system’s file naming conventions. Usually, the index name may
contain a disk drive designation and/or a directory path name. The third through seventh
parameters are used at the time the index file is created. However, they should be maintained
carefully since the rebuild utility verifies that the ISAM parameter file values agree with the
corresponding values stored in the index file header record. Remember, if duplicates are allowed,
the last 4 bytes of the key value are reserved for the 4 bytes of the associated data record
position. For example, a key length of 12 bytes combined with duplicate values results in 8 bytes
for the actual key value and 4 bytes for the tie-breaking data record position. Skipping the ninth
and tenth parameters for now (see the term “Null Key Values” below), the eleventh parameter
specifies the number of segments concatenated to form a key value from the data record
contents.
If RTREE is defined in ctoptn.h, the twelfth parameter is required. It is a symbolic name for the
index file. It should start with an alphabetic character and may include upper and lower case
letters, numbers and under scores. It may not include embedded blanks. Unlike the field names in
the Data Description record, these do not, and must not, match entries in the r-tree DODA.
Symbolic names for the data files are not necessary because each data file has a unique name.
Null Key Values
The ninth parameter of the Index File Description record, NULL key flag, determines if NULL or
missing key values will be detected. After the key segments have been concatenated according
to the Key Segment Description records, the NULL key flag parameter determines whether or not
to test for a missing value. If the NULL key flag parameter is zero, no check for a NULL or
missing value is made. If the NULL key flag is set to one, then the resulting key value is
compared with the empty character (tenth parameter). If the key value is composed entirely of
empty characters, then the key value is considered NULL or missing and is not entered into the
index file.
The empty character is expressed in the decimal equivalent of the character. For example, an
ASCII space (0x20) is specified with a value of 32. A NULL byte (0x00) is specified with a value of
zero.
Optional Index Member Record
It is not necessary for each index associated with a data file to be in a separate file. Indices can
be combined in the same physical file. If the nomemb parameter of an Index File Description
Record is greater than zero, the following nomemb Index File Description Records must be
replaced by Index Member Records. For example, if a data file has three indices, and the second
index has an additional member, nomemb equals one, use two Index Description Records and
one Index Member Record.
The Index Member Record is composed of seven required fields and one additional field to be
used with r-tree:
www.faircom.com
All Rights Reserved
179
Reference Material
 Key number (keyno)
 Key length (keylen)
 Key type (keytyp)
 Duplicate flag (keydup)
 NULL key flag
 Empty character
 Number of key segmens
If RTREE is defined in ctoptn.h, each Index Member record needs one additional parameter:
 Symbolic index name
These fields have the same interpretation as the corresponding fields in the Index Description
Record. Index Member records do not include explicit member numbers (membno). The
sequence of Index Member records following an Index File Description record determines the
member number of each Index Member, (the first Index Member record is member number one,
and so on). While a key number (keyno) is specified for each member, there is no freedom in the
keyno value. The keyno specified in each Index Description Record must equal the keyno value
of the host index file plus the member number, or error IMKY_ERR (108) will be raised in
CreateISAM() and OpenISAM().
Key Segment Description Record
Each key value is composed of one or more segments. A segment is simply a sequence of bytes
from specified offset within the data record. Each Key Segment Description record is comprised
of three fields:
 Segment position
 Segment length
 Segment mode
Fixed-Length Parameter File Examples
The contents of ctexam.p will be similar to those shown below.
ISAM Parameter File For Fixed Record Length
18 3 4 1
3
cust.dat
128 4096
0
custnam.idx 24 0 0
6 14 2
30
6 2
121
4 3
1
4 0 0
2
4 1
2
custzip.idx 22 0 0
112
9 2
6
9 2
121
4 3
1
1
0
3
4096
4096
1 1
32
3
0
0
1
1 1
32
3
This parameter file is interpreted as follows. There will be eighteen index file buffers, up to three
index files, 512-byte B-Tree nodes, and exactly one data file.
www.faircom.com
All Rights Reserved
180
Reference Material
The first index is assigned key number 0, and is in the file named custnam.idx which will be
incremented in 4,096-byte chunks. The keys are unique, 24 bytes long and scanned left-to-right.
The keys have three segments: 14 bytes, 6 bytes and 4 bytes long. The first two segments are
converted to upper case, and are made up of the last name and first, respectively. The third
segment is based on the automatic sequence number maintained by c-tree for each data file. The
sequence number ensures that keys, which are otherwise the same, will be stored in order of
entry in the data base.
Note: c-tree automatically places the sequence number in the record at byte offset 121 as
specified by the third segment’s offset value.
The second index is assigned key number 1, and is the first (and only) additional member of
custnam.idx. The keys are unique, 4-byte values. Keys are not checked for missing values (i.e.,
all data records will generate a key value). The key is comprised of one segment treated as an
unsigned integer.
The last index is assigned key number 2, is named custzip.idx and has 22-byte unique keys. The
key segments are made up of the nine character Zip Code, the first 9 bytes of the last name, and
the same automatic sequence number used in the name index.
Note: If more than one index uses the automatic sequence number, all such indices must use the
same sequence number. Otherwise, the results will be unpredictable. The segment length of the
sequence number must be 4.
Note: Each data file, index file, and index file member is assigned a unique number. This is the
number by which the data file and indices are referenced in the c-tree functions. The additional
index members are numbered consecutively based on the host index number.
If RTREE is enabled in ctoptn.h, the preceding parameter file might look as follows:
ISAM Parameter File With RTREE Enabled
18 3 4 1
3
cust.dat
128 4096
0 custnam.idx 24 0 0
6 14 2
30
6 2
121
4 3
1
4 0 0
2
4 1
2 custzip.idx 22 0 0
112
9 2
6
9 2
121
4 3
1
1
0
3 delflag cust_last
4096 1 1 32 3 name_key
4096
0
0
1 numb_key
1 1
32
3 zipc_key
Variable-Length Parameter File Example
The example parameter file for the variable-length example takes advantage of the key
compression and the variable-length fields supported by c-tree. ctvxmg.c contains the source for
the variable-length example, and ctvxam.p is its associated parameter file. The contents of
ctvxam.p will be similar to those shown below (assuming RTREE is not enabled).
ISAM Parameter File For Variable Record Length
18 3 4 1
3
vcust.dat
0
vcust.idx 24
0 15 5
15
4 1
4096 5
2 4096
3
1 0
32
2
www.faircom.com
All Rights Reserved
181
Reference Material
4
5 2
0
4 1
4
0
9 2
9 5
1
4
2
0 0
0
0
1
22 12 1
1
32
2
The important points to note in this example are:
 The last name index (keyno = 0) has a key type of 4 (leading character compression will take
place). Padding compression is not used since the second segment of the key is based on
the Zip Code and will usually be the full length.
 The first segment of the last name index has a mode value of 5. The segment is found in the
zeroth varying length field, right after the fixed-length portion of each data record, not at
absolute byte position zero. It will be padded, if necessary, to 15 bytes, and converted to
upper case.
 The Zip Code index (keyno = 2) has a key type of 12 (both leading character and padding
compression will take place). Since the second segment of this index is based on the last
name, many of the keys should have padding.
The main differences between ctvxam.p and ctexam.p are:
 The data file uses variable-length records, (file mode of 5 specifies virtually opened,
variable-length records, and file sharing in multi-user systems), with a minimum record length
of 15 bytes;
 All the indices have been combined into one physical index file;
 The key segment offsets are modified since all the fixed-length fields have been moved to the
beginning of the record structure.
These examples use a non-zero file size extension parameter. A zero file size extension
parameter means the file grows one record at a time instead of growing in large chunks. The
advantage of growing in chunks is that every time the file is extended, c-tree forces the update of
directory entries associated with the file.
Multiple Data File Parameter Setup
The ISAM parameter file can accommodate more than one data file. The following data show how
a parameter file would look for two data files, each with two index files. Indentation is ignored by
the programs, but is helpful in reading the material.
24 4 4 2
0 VENDOR.DAT 384 8192
2 VENDOR.IDX 14 0
0 10 0
3
6 0
12 6 0
1 INVOICE.DAT 192 8192
4 INVOICE.IDX 16 0
32 6 0
0 6 0
5
10 0
0 6 0
0
1
2
1 8192 0 1
32
1
0
0
0
1
0
1
2
1 8192 0 0
0
2
1
1
32
1
The application using this parameter file refers to the vendor data file, VENDOR.DAT, as file
number 0, and the invoice data file, INVOICE.DAT, as file number 1. Each data file has two
www.faircom.com
All Rights Reserved
182
Reference Material
indices. In both cases, the indices are stored in one physical file. Except for key number 3, which
does not accept duplicates, all the segment lengths sum to 4 bytes less than the actual key
lengths to accommodate the suffixes.
Parameter Files in Client Server Models
Client applications using parameter files to define file definitions must either specify a proper
path, from the c-treeACE Server perspective, to the location of the parameter file or the
parameter file must be located in the c-treeACE Server directory.
Parameter files not containing the optional r-tree parameters must be modified. The parameter
file data description record contains positions for r-tree’s symbolic first and last field name and the
index description record contains a position for the symbolic index name. Since the c-treeACE
Server has RTREE defined, these values must be specified. If r-tree will not be used with the
parameter file, dummy values can be used as placeholders. For example, the sample parameter
file ctmark.p uses the letter ‘d’ as a provisional placeholder for the three r-tree symbolic values.
Refer to ISAM Parameter File System Functions in the c-treeACE Professional Developers Guide
(http://docs.faircom.com/doc/ctreeplus/).
11.7
Prototyping
If your compiler supports function prototyping, we strongly suggest that you use this feature. A
function declaration, or function prototype, establishes the name and return type of a function, as
well as the types and number of arguments to the function. This information enables the compiler
to check the types of the actual arguments when the function is used. If you accidentally use too
few parameters when you invoke a prototype function, your compiler should give you a warning.
With some compilers it is very important that you use prototyping to avoid serious memory
overwrites, for instance, with the Large memory model with the Microsoft C compiler, and
functions that use TEXT pointers. If you do not include a function prototype in your code, the
compiler will have to determine if it should use a 16-bit or 32-bit address for the function
arguments. If it chooses the wrong one, the function may copy the information to the wrong
location in memory. By including the function prototype in your code, you inform the compiler of
the type of parameter that will be used, and the correct address will be passed.
The header file ctdecl.h contains declarations for the commonly used c-tree functions. There are
two sets of declarations: one with prototypes and one without. By default, PROTOTYPE is
defined in ctoptn.h. This will include the prototype definitions. If your compiler does not support
prototyping, remove the PROTOTYPE define from ctoptn.h.
11.8
2xx Internal Error Codes
The internal error codes in the 2xx range should not occur during proper operation of c-treeACE.
Their main function is to help find programming bugs, especially if you modify c-treeACE code.
Our experience shows that almost all occurrences of an internal error are caused by memory
overwrites from the application code.
200
Neither LOW_HIGH nor HIGH_LOW defined in ctoptn.h.
201
Both LOW_HIGH and HIGH_LOW defined in ctoptn.h.
www.faircom.com
All Rights Reserved
183
Reference Material
202
NOTFORCE, FPUTONLY, nor FPUTFGET defined in ctoptn.h.
203
More than one of NOTFORCE, FPUTONLY, and FPUTFGET defined in ctoptn.h.
206
Update flag inconsistency between index file header and buffer status information.
207
Corrupt node found in nodser() function.
208
Updated (but not written) node found in FPUTFGET disk I/O mode.
210
Undefined key type found in compar.
211
Negative number of key values indicated in node.
212
No leaf node found during FirstKey() operation.
213
No leaf node found during LastKey() operation.
214
Corrupt tree found in fndkey().
215
No leaf node found in fndkey().
216
Attempt to save node with negative number of key values.
217
Attempt to transfer key values between buffers for different index files.
218
Corrupt tree found in .
219
No leaf node found in .
220
Corrupt tree found in .
221
No leaf node found in .
222
Undefined file access flag found: filacs member of file control structure must be set ‘y’ (active), ‘v’
(active, temporarily closed), or ‘n’ (inactive).
225
VARLDATA not defined in ctoptn.h. Add VARLDATA option and recompile ctaddk.c.
226
Undefined key segment translation mode.
227
While extending the size of a fixed-length data file, delete flags could not be written into new (but
unused) records at the end of the file.
228
Expected deleted record mark not found while collapsing consecutive deleted areas.
230
B-Tree node has conflicting member number value during write operation.
231
B-tree node has conflicting member number value during read operation.
232
Attempt to expand non-existent compressed key value.
233
Illegal value for key compression bytes.
235
Illegal comparison value during node insert.
236
Illegal key value shift detected with compressed keys.
237
Attempt to get an index node at byte offset zero.
238
Illegal key value shift detected with compressed keys.
239
Variable key expansion request with NO_VARLK.
240
Exceeded maximum b-tree levels. Increase number or size of node sectors, or increase MAXLEV. In
standalone models, may be a symptom of adding index entries sequentially, creating a badly
balanced tree. Compact the index or shift to a client/server model.
www.faircom.com
All Rights Reserved
184
Reference Material
11.9
Internal 749X Error Codes
Most 749X errors are the result of memory corruption on the host machine. These errors are
extremely rare, however, can be serious. In most cases, restarting c-treeACE will clear a transient
memory error. If these errors repeat, please contact your application vendor.
Value
Cause
7490
A request for memory beyond reasonable limits.
7491
Attempting to return memory carrying an unreasonable large length value in its control header.
7492
Encountered an invalid “availability” counter during a sub-allocator get operation.
7493
An invalid “availability” counter while returning a block of memory.
7494
An invalid header pointer for an allocation block.
7495
A list connected with c-tree’s memory sub-allocator has become invalid or corrupted.
7496
Failure in memory swapping operation.
7497
Attempting to return memory carrying a zero length in its control header.
7498
An invalid semaphore owner while getting memory.
7499
An invalid semaphore owner while returning memory.
www.faircom.com
All Rights Reserved
185
12. Operating System Specific
12.1
Microsoft Windows
Installation Error Due to XML Encoding
While installing c-treeACE on Windows, the installation program may report display an alert
reporting an "Unspecified XML file encoding." This error may occur while the installer is
configuring XML files. It is the result of the encoding used in your system's .NET machine.config
file.
The first line of the machine.config file indicates the encoding. An example of UTF-8 is shown
below:
<?xml version="1.0" encoding="UTF-8"?>
The FairCom installer supports the following encodings:
 UTF-8
 UTF-16
 ASCII
 ISO-8859-1 (Latin-1)
If you are using an encoding other than those listed above, you will need to use a .zip file for
installation. The .zip file is available from FairCom.
Windows Vista Network AutoTuning Parameters
The symptoms exist due to the new re-written TCP stack in Windows Vista that aims to take full
advantage of hardware advances such as gigabit networking. Among the new feature in Windows
Vista TCP/IP is Receive Window Auto-Tuning for TCP connections. TCP AutoTuning enables
TCP window scaling by default and automatically tunes the TCP receive window size for each
individual connection based on the bandwidth delay product (BDP) and the rate at which the
application reads data from the connection, and no longer need to manually change
TcpWindowSize registry key value which applies to all connection. Theoretically, with TCP
auto-tuning, network connection throughput in Windows Vista should be improved for best
performance and efficiency, without any registry tweaks. However, this is not always the case,
and may cause some Internet related issues and problems.
A workaround to the above problem is to disable the TCP/IP AutoTuning in Windows Vista.
Disabling auto tuning of TCP Windows Size should not cause any negative effects, only that the
TCP Window Size will always be the default value without ability for optimization to each
connection.
A microsoft TechNet article describing the feature is here:
www.faircom.com
All Rights Reserved
186
Operating System Specific
Microsoft TechNet - Vista Network Performance Improvements
http://technet.microsoft.com/en-us/library/bb878127.aspx
Disable AutoTuning
1. Open an Elevated Command Prompt (see below)
2. Enter the following command to disable auto-tuning
netsh interface tcp set global autotuninglevel=disabled
Enable AutoTuning
If you find disabling auto-tuning doesn’t fix your problem, re-enable it as follows:
1. Open an Elevated Command Prompt
2. Enter the following command to enable auto-tuning
netsh interface tcp set global autotuninglevel=normal
AutoTuningStatus
To view the state of your current TCP parameters, use this command:
netsh interface tcp show global
Elevated Command Prompt
1. Click on the Start button.
2. In the search box, type in “cmd” or “Command Prompt” - Do not press Enter.
3. cmd.exe or Command Prompt will show in the search results (depending on what you
searched for).
4. Right click cmd.exe (or Command Prompt) in the search results and select “Run as
Administrator”.
5. Enter the administrator credentials when prompted.
Configuring 32-bit ODBC Drivers on 64-bit Windows Versions
With 64-bit versions of Windows, the previous 32-bit ODBC Driver Manager is now located in a
different location, and is not used by default. To configure a 32-bit driver on these systems, use
the following steps:
 Execute: %WINDIR%\syswow64\odbcad32.exe
 Create a DSN using the 32-bit version of the Administrator
See Also
 DSN-less ODBC Connections (http://docs.faircom.com/doc/ctpodbc/index.htm#38030.htm).
Connect Microsoft 64-bit SQL Server 2005 to c-treeACE SQL
 First configure your 32-bit driver as described in this article:
Configuring 32-bit ODBC Drivers on 64-bit Windows Versions (page 81)
 Using the SQL Server Import and Export Wizard, you will get a pop-up screen that is asking
for a Data Source.
www.faircom.com
All Rights Reserved
187
 You will not see the 32-bit DSN in the drop down menu. Select ".Net Framework Data
Provider for ODBC". On most systems it's probably the top one in the list, however, you need
to scroll up to see it as the list usually displays in the middle.
 Enter further connection information on the resulting dialog screens.
 Under NamedConnection String there is a field for "dsn". In this field put the name of the DSN
created in Step 1.
 Click on Next and follow the rest of the instructions to copy the desired data.
Slow Windows Network Traffic
Communication with a server on a local network can be substantially slower than expected when
newer Windows computers (Windows Vista and later) attempt to access older Windows
computers. Although the communication works eventually, you may experience slow response
times.
The problem may be due changes in the was the system handles Link Local Multicast Name
Resolution (LLMNR) protocol. LLMNR is based on the Domain Name System (DNS) protocol. It
provides name resolution for addresses on the same local network without the need for a DNS
server.
The multicast used by LLMNR is not supported by all systems. If your network contains a mix of
old and new systems, some systems may be attempting to use a protocol that others do not
support. After a timeout, the computer will use other means to perform the operation, so the
process works...slowly.
Solutions:
1. Disable LLMNR on the newer computers.
2. Avoid a DNS lookup be doing either of the following:
• Specify an IP address in the connection string instead of a domain name.
• Edit the hosts file on the newer machine to include the name and IP address of the older
machine.
3. And, of course, if you can replace the older computers you will eliminate this problem and
possibly improve performance in other areas at the same time.
To turn off LLMNR on a server:
1. From the Windows Start menu, type GPEdit.msc in the search box and press Enter. The
Local Group Policy Editor will appear:
www.faircom.com
All Rights Reserved
188
2. Using the Console Tree on the left, navigate to:
Local Computer Policy > Computer Configuration > Administrative Templates >
Network > DNS Client
3. In the DNS Client folder, double-click Turn off Multicast Name Resolution and set State to
Enabled.
12.2
Linux
CPUs Report Different Times on Linux, Causing Unexpectedly Long sleep()
Times
On a multi-core system running CentOS Linux, calls to sleep() were observed to take an
unexpectedly long time. It is believed the system time reported by the CPUs varies, as was
confirmed by this experiment:
The Linux taskset utility can be used to run a process on specified CPUs. The date on each CPU
differed:
taskset
taskset
taskset
taskset
Mon Aug
Mon Aug
Mon Aug
-c
-c
-c
-c
0
1
2
3
date
date
date
date
8 11:20:04 CDT 2011
8 11:20:19 CDT 2011
8 11:20:16 CDT 2011
www.faircom.com
All Rights Reserved
189
Mon Aug
8 11:20:20 CDT 2011
The Hyper-V VM was used in this case and it was found that adding the following boot options
resolved the problem, as described here:
divider=10 clocksource=acpi_pm (for 32bit kernel)
Compiling c-treeACE SQL PHP on Linux/Unix
c-treeACE SQL PHP is provided as a ready to go driver for currently available versions of PHP.
However, PHP regularly advances, and new versions out pace current support quickly. In that
case, you usually have to rebuild the PHP driver to match the specific version of PHP in your
environment.
Usually, you can simply execute our provided build script from the /src directory of your
c-treeACE SQL PHP driver installation:
>
>
>
>
phpize
make
make install
However, you may find that the configure scripts don't always match the current autotools version
of your Linux flavor. In that case, you need to regenerate the ./configure script. Consider the
following sequence. Actual steps may differ slightly depending on your autotools version and
Linux flavor. Check with the autotools documentation for details.
>
>
>
>
>
>
>
phpize
libtoolize
aclocal
autoreconf -i
make
make install (optional)
The driver will be in the newly created /modules folder. You are free to copy this to an appropriate
library location in your environment.
Note: You may need elevated privileges to install this into /lib or other system locations.
Memory Use of Linux Processes
When examining memory use for a Linux process, there are utilities available in addition to top. A
recommended utility found useful in determining actual memory usage is pmap.
pmap -x <ctree_pid>
Here's top output for a ctreesql process:
PID USER
1493 fctech
PR
17
NI
0
VIRT RES SHR S %CPU %MEM
515m 227m 4836 S 0.0 11.3
TIME+ COMMAND
0:00.28 ctreesql
www.faircom.com
All Rights Reserved
190
Here's pmap output for this process. In this case, the VIRT and RES values shown by top are
close to the Kbytes and RSS values from pmap. The "[ anon ]" mappings are likely to be the most
common ones. c-treeACE allocations from the heap will show up as that type.
1493:
./ctreesql
Address
Kbytes
0000000000400000
4
0000000000600000
4
000000000b8ec000 238152
0000003403e00000
112
000000340401c000
4
000000340401d000
4
0000003404200000
1340
000000340434f000
2048
000000340454f000
16
0000003404553000
4
0000003404554000
20
0000003404600000
8
0000003404602000
2048
0000003404802000
4
0000003404803000
4
0000003404a00000
520
0000003404a82000
2044
0000003404c81000
4
0000003404c82000
4
0000003404e00000
88
0000003404e16000
2048
0000003405016000
4
0000003405017000
4
0000003405018000
16
0000003405200000
28
0000003405207000
2048
0000003405407000
4
0000003405408000
4
0000003405600000
80
0000003405614000
2044
0000003405813000
4
0000003405a00000
84
0000003405a15000
2048
0000003405c15000
8
0000003405c17000
4
0000003405e00000
236
0000003405e3b000
2048
000000340603b000
4
000000340603c000
40
0000003406e00000
628
0000003406e9d000
2044
000000340709c000
8
0000003407200000
84
0000003407215000
2044
0000003407414000
4
0000003407415000
4
0000003407416000
8
0000003408200000
8
0000003408202000
2044
0000003408401000
4
0000003408600000
68
0000003408611000
2048
0000003408811000
4
0000003408812000
4
0000003408813000
8
0000003408a00000
580
RSS
4
4
220112
100
4
4
500
0
16
4
20
8
0
4
4
64
0
4
4
80
0
4
4
4
16
0
4
4
12
0
4
44
0
8
4
20
0
4
0
68
0
8
24
0
4
4
0
8
0
4
20
0
4
4
0
88
Dirty
0
4
220112
0
4
4
0
0
8
4
20
0
0
4
4
0
0
4
4
0
0
4
4
4
0
0
4
4
0
0
4
0
0
8
4
0
0
4
0
0
0
8
0
0
4
4
0
0
0
4
0
0
4
4
0
0
Mode
r-x-rw--rw--r-x-r---rw--r-x-----r---rw--rw--r-x-----r---rw--r-x-----r---rw--r-x-----r---rw--rw--r-x-----r---rw--r-x-----rw--r-x-----rw--rw--r-x-----rw--rw--r-x-----rw--r-x-----r---rw--rw--r-x-----rw--r-x-----r---rw--rw--r-x--
Mapping
ctreesql
ctreesql
[ anon ]
ld-2.5.so
ld-2.5.so
ld-2.5.so
libc-2.5.so
libc-2.5.so
libc-2.5.so
libc-2.5.so
[ anon ]
libdl-2.5.so
libdl-2.5.so
libdl-2.5.so
libdl-2.5.so
libm-2.5.so
libm-2.5.so
libm-2.5.so
libm-2.5.so
libpthread-2.5.so
libpthread-2.5.so
libpthread-2.5.so
libpthread-2.5.so
[ anon ]
librt-2.5.so
librt-2.5.so
librt-2.5.so
librt-2.5.so
libz.so.1.2.3
libz.so.1.2.3
libz.so.1.2.3
libselinux.so.1
libselinux.so.1
libselinux.so.1
[ anon ]
libsepol.so.1
libsepol.so.1
libsepol.so.1
[ anon ]
libglib-2.0.so.0.1200.3
libglib-2.0.so.0.1200.3
libglib-2.0.so.0.1200.3
libnsl-2.5.so
libnsl-2.5.so
libnsl-2.5.so
libnsl-2.5.so
[ anon ]
libcom_err.so.2.1
libcom_err.so.2.1
libcom_err.so.2.1
libresolv-2.5.so
libresolv-2.5.so
libresolv-2.5.so
libresolv-2.5.so
[ anon ]
libkrb5.so.3.3
www.faircom.com
All Rights Reserved
191
0000003408a91000
0000003408c91000
0000003408e00000
0000003408e02000
0000003409001000
0000003409600000
0000003409608000
0000003409807000
0000003409a00000
0000003409a2c000
0000003409c2c000
0000003409e00000
0000003409e24000
000000340a023000
0000003412000000
000000341200d000
000000341220d000
0000003416c00000
0000003416ce6000
0000003416ee5000
0000003416eeb000
0000003416eee000
0000003417000000
000000341704e000
000000341724e000
000000341725c000
000000394a800000
000000394a92d000
000000394ab2c000
000000394ab4d000
000000394ac00000
000000394ac48000
000000394ae48000
00002ab7f38ed000
00002ab7f38ef000
00002ab7f4432000
00002ab7f4632000
00002ab7f4697000
00002ab7f7dba000
00002ab7f82ec000
00002ab7f8b10000
00002ab7f8b1a000
00002ab7f8d19000
00002ab7f8d1a000
00002ab7f8d1b000
00002ab7f8d1c000
00002ab7f8e9c000
00002ab7f8e9d000
00002ab7f901d000
00002ab7f901e000
00002ab7f919e000
00002ab7f919f000
00002ab7fc000000
00002ab7fc0d0000
00002ab800000000
00002ab800024000
00002ab804000000
00002ab804001000
00002ab804181000
00002ab804182000
00002ab804302000
00002ab804303000
2048
16
8
2044
4
32
2044
4
176
2048
8
144
2044
8
52
2048
4
920
2044
24
12
72
312
2048
56
4
1204
2044
132
16
288
2048
24
8
11532
2048
404
56368
5188
8244
40
2044
4
4
4
1536
4
1536
4
1536
4
1536
832
64704
144
65392
4
1536
4
1536
4
1536
0
16
4
0
4
16
0
4
40
0
8
28
0
8
36
0
4
412
0
24
12
8
44
0
12
0
232
0
16
8
52
0
12
8
2836
0
328
660
44
6188
24
0
4
4
0
12
0
8
0
12
0
8
688
0
16
0
0
12
0
12
0
16
0
12
0
0
4
0
0
4
0
0
8
0
0
8
0
0
4
0
0
20
12
8
0
0
8
0
0
0
8
8
0
0
12
8
0
0
324
652
40
6188
0
0
4
4
0
12
0
8
0
12
0
8
688
0
16
0
0
12
0
12
0
16
----rw--r-x-----rw--r-x-----rw--r-x-----rw--r-x-----rw--r-x-----rw--r-x-----r---rw--rw--r-x-----rw--rw--r-x-----rw--rw--r-x-----rw--rw--r-x-----rw--rw--rw--rw--r-x-----r---rw------rw------rw------rw------rw--rw------rw----------rw------rw------rw---
libkrb5.so.3.3
libkrb5.so.3.3
libkeyutils-1.2.so
libkeyutils-1.2.so
libkeyutils-1.2.so
libkrb5support.so.0.1
libgssapi_krb5.so.2.2
libk5crypto.so.3.1
libk5crypto.so.3.1
libk5crypto.so.3.1
libgcc_s-4.1.2-20080825.so.1
libgcc_s-4.1.2-20080825.so.1
libgcc_s-4.1.2-20080825.so.1
libstdc++.so.6.0.8
libstdc++.so.6.0.8
libstdc++.so.6.0.8
libstdc++.so.6.0.8
[ anon ]
libncurses.so.5.5
libncurses.so.5.5
libncurses.so.5.5
[ anon ]
libcrypto.so.0.9.8e
libcrypto.so.0.9.8e
libcrypto.so.0.9.8e
[ anon ]
libssl.so.0.9.8e
libssl.so.0.9.8e
libssl.so.0.9.8e
[ anon ]
libctreedbs.so
libctreedbs.so
libctreedbs.so
[ anon ]
[ anon ]
[ anon ]
libnss_files-2.5.so
libnss_files-2.5.so
libnss_files-2.5.so
libnss_files-2.5.so
[ anon ]
[ anon ]
[ anon ]
[ anon ]
[ anon ]
[ anon ]
[ anon ]
[ anon ]
[ anon ]
[ anon ]
[ anon ]
[ anon ]
[ anon ]
[ anon ]
[ anon ]
[ anon ]
[ anon ]
[ anon ]
www.faircom.com
All Rights Reserved
192
00002ab804483000
00002ab804484000
00002ab804604000
00002ab804605000
00002ab804785000
00002ab804786000
00002ab804906000
00002ab804907000
00002ab804a87000
00002ab804a88000
00002ab804a89000
00002ab804c09000
00002ab804c0a000
00002ab804d8a000
00007ffff783e000
00007ffff79fd000
ffffffffff600000
---------------total kB
12.3
4
1536
4
1536
4
1536
4
1536
4
4
1536
4
1536
4
84
12
8192
-----536032
0
16
0
16
0
16
0
20
4
0
8
0
8
4
44
4
0
-----233324
0
16
0
16
0
16
0
20
4
0
8
0
8
4
44
0
0
-----228496
----rw------rw------rw------rw--rw-s----rw------rw--rw-srw--r-x------
[
[
[
[
[
[
[
[
[
[
[
[
[
[
[
[
[
anon ]
anon ]
anon ]
anon ]
anon ]
anon ]
anon ]
anon ]
shmid=0x3d9f0008 ]
anon ]
anon ]
anon ]
anon ]
shmid=0x3d9f8009 ]
stack ]
anon ]
anon ]
Solaris
Heap Debugging on Solaris 9+ Operating Systems
You can enable heap debugging for the c-treeACE process by setting these environment
variables before startup.
export LD_PRELOAD=libumem.so.1
export UMEM_DEBUG=default
export UMEM_LOGGING=transaction
This is a low overhead malloc() debugging method, suitable for a production environment
experiencing possible heap corruption. With the above options, it will check some guard zones for
memory overwrites on alloc/free.
It also has many commands when a core generated with libumem is used with the mdb
debugger.
::umem_status and ::umem_verify are useful, and the complete list of dcmds can be found in mdb
by executing:
> ::dmods -l libumem.so.1
man umem_debug has more details.
watchmalloc is another malloc debugging library on Solaris that detects memory overwrites more
reliably, however, runs very slowly and is not useful in a production environment.
12.4
AIX
IBM AIX Multicore/CPU Performance Tuning Options
Doubling c-treeACE workload on an IBM AIX system has been observed to more than double
CPU utilization or generate very high CPU utilization. An AIX environment variable can be
changed and the server restarted to compare performance.
The following environment variable is used:
www.faircom.com
All Rights Reserved
193
AIXTHREAD_SCOPE=S
IBM AIX Large Page Support
When running a 64-bit c-treeACE Server on AIX, it was suspected memory pages were being
"stolen" by another process or the file system cache. The key diagnostic indicator in this case
was to monitor RSS memory of the c-treeACE process (ps v PID) and see if it drops at times of
poor performance.
It was found that the c-treeACE executable and/or the system needed to be set for large page
support.
The instructions found on the following pages were followed:
http://dbasrus.blogspot.com/2009/06/size-sometimes-does-matter.html
http://dbasrus.blogspot.com/2009/06/size-sometimes-does-matter.html
http://publib.boulder.ibm.com/infocenter/db2luw/v9/topic/com.ibm.db2.udb.admin.doc/doc/t00104
05.htm
http://publib.boulder.ibm.com/infocenter/db2luw/v9/topic/com.ibm.db2.udb.admin.doc/doc/t00104
05.htm
The following commands were then run as root:
 Enable pinned memory
vmo -p -o v_pinshm=1 -o lru_file_repage=0
 Allocate 256 MB for large page support
vmo -p -o lgpg_size=16777216 -o lgpg_regions=16
 Allow the user account that runs the ctreesql process to lock memory and use large pages
chuser capabilities=CAP_BYPASS_RAC_VMM,CAP_PROPAGATE fctech
 Enable the ctreesql executable to use large pages
ldedit -b lpdata ctreesql
IBM AIX Mutex Performance Tuning Options
There have been sporadic reports of poor c-treeACE performance when running on AIX operating
systems. Symptoms reported include:
 Low disk / CPU utilization at times of poor performance;
 Contention on internal process mutexes as examined from process stack dumps
It may be possible to improve performance, in some cases, by adjusting the AIX environment
variables SPINLOOPTIME and YIELDLOOPTIME, which change mutex behavior.
IBM Infocenter
(http://publib.boulder.ibm.com/infocenter/aix/v6r1/index.jsp?topic=/com.ibm.aix.prftungd/doc/prftu
ngd/thread_tuning.htm)
The above link says that SPINLOOPTIME defaults to 40 and YIELDLOOPTIME defaults to 0.
www.faircom.com
All Rights Reserved
194
Try setting SPINLOOPTIME=650 and YIELDLOOPTIME=10, restart the server and see if this
improves the situation. Further tuning may give greater benefits.
Analyzing ctsemrqs() Calls on AIX systems
1. Parameters passed to ctsemrqs() are stored in the r3, r4, and r5 registers.
2. r2 points to the table of contents (TOC). The addresses of c-tree global variables are stored
in the TOC.
If attempting to determine the source line for a ctsemrqs() call in a function that corresponds to a
ctsemrqs() call in the disassembly and the function contains more than one ctsemrqs() call, use
this approach:
Often the first parameter passed to ctsemrqs() is the address of a global variable.
Check the value that is stored into r3. If it involves r2, then dump the memory given by r2+0xn
and compare it to the addresses of global mutexes that are used in ctsemrqs() calls in the
function.
Note: Some calls like ctmutrqs() are macros that evaluate to ctsemrqs().
(dbx) stop in main
(dbx) run
0x000000010002452c ctsemrqs() + 0x190
0x0000000100040f30 ctwrtlog() + 0x1b80
Display disassembly starting a little before the ctsemrqs call at 0x1b80:
(dbx) listi &ctwrtlog + 0x1b70
0x100040f20 (ctwrtlog+0x1b70) ea220af8
ld
r17,0xaf8(r2)
0x100040f24 (ctwrtlog+0x1b74) 3880ffff
li
r4,-1
0x100040f28 (ctwrtlog+0x1b78) 63e50000
ori
r5,r31,0x0
0x100040f2c (ctwrtlog+0x1b7c) e8710000
ld
r3,0x0(r17)
0x100040f30 (ctwrtlog+0x1b80) 4bfe346d
bl
Find the offset of the TOC entry that is stored into r3 (by way of r17):
(dbx) print $r2+0xaf8
0x00000001100259f0
Display the address of the global variable:
(dbx) 0x00000001100259f0/llx
0x00000001100259f0: 110275000
Compare to c-tree global variable address:
(dbx) print &ctpchksema
0x0000000110275000
+6716
if (trnactflg) {
+6717 #ifdef MULTITRD
+6718
ctsemrqs(ctpchksema,WAIT,sOWNR SMN(5460));
====
0x000000010002452c
0x000000010003d348
(dbx) listi
0x10003d324
0x10003d328
0x10003d32c
0x10003d330
0x10003d334
ctsemrqs() + 0x190
ctcomexc81() + 0x610
&ctcomexc81 + 0x5e0
(ctcomexc81+0x5ec) 63e40000
(ctcomexc81+0x5f0) 63030000
(ctcomexc81+0x5f4) 4bfe7365
(ctcomexc81+0x5f8) 60000000
(ctcomexc81+0x5fc) 4bffff38
ori
ori
bl
ori
b
r4,r31,0x0
r3,r24,0x0
0x100024690 (ctsemclr)
r0,r0,0x0
0x10003d26c (ctcomexc81+0x534)
www.faircom.com
All Rights Reserved
195
0x10003d338
0x10003d33c
0x10003d340
0x10003d344
0x10003d348
(ctcomexc81+0x600)
(ctcomexc81+0x604)
(ctcomexc81+0x608)
(ctcomexc81+0x60c)
(ctcomexc81+0x610)
3b800001
3880ffff
63e50000
60780000
4bfe7055
li
li
ori
ori
bl
r28,0x1
r4,-1
r5,r31,0x0
r24,r3,0x0
r3 is already set.
Look for all references to (r2). Then for each reference, do this to output the address of the global
variable:
set x=$r2+0x1130; &x/llx
(dbx) print &ctpdcmsema
0x0000000110287fe0 = 0x1130(r2) from the above method
(dbx) print &ctpcomsema
0x0000000110272370 = 0x760(r2) from the above method
this code loads r3 with &ctpdcmsema and checks if sOWNR != ctpdcmsema->ownr:
0x10003d3b4 (ctcomexc81+0x67c) e8621130
ld
r3,0x1130(r2)
0x10003d3b8 (ctcomexc81+0x680) e8630000
ld
r3,0x0(r3)
0x10003d3bc (ctcomexc81+0x684) 80030044
lwz
r0,0x44(r3)
0x10003d3c0 (ctcomexc81+0x688) 7c070000
cmp
cr0,0x0,r7,r0
0x10003d3c4 (ctcomexc81+0x68c) 4082ff74
bne
0x10003d338 (ctcomexc81+0x600)
So the call is either using ctpcomsema or ctpdcmsma. In the stack trace, it is updbuf() that calls
ctcomexc81() so it must be this call:
ctcomexc81(TRN_ADATA,Lhwt tran,(pGENBUF) db thHan);
which means it's ctpdcmsema:
ctmutrqs(ctpdcmsema,sOWNR SMN(6280));
====
0x000000010002452c
0x0000000100031004
(dbx) listi
0x100030ff4
0x100030ff8
0x100030ffc
0x100031000
0x100031004
ctsemrqs() + 0x190
ctabtexc81() + 0x53c
&ctabtexc81 + 0x52c
(ctabtexc81+0x52c) e8621318
(ctabtexc81+0x530) 3880ffff
(ctabtexc81+0x534) 63850000
(ctabtexc81+0x538) e8630000
(ctabtexc81+0x53c) 4bff3399
ld
li
ori
ld
bl
r3,0x1318(r2)
r4,-1
r5,r28,0x0
r3,0x0(r3)
0x0000000110026210
(dbx) 0x0000000110026210/llx
0x0000000110026210: 110288208
(dbx) print &ctpabtsema
+1168
ctsemrqs(ctpabtsema,WAIT,sOWNR SMN(5570));
====
0x000000010002452c
0x0000000100058a90
(dbx) listi
0x100058a80
0x100058a84
0x100058a88
0x100058a8c
0x100058a90
ctsemrqs() + 0x190
ctdwnfil() + 0x338
&ctdwnfil + 0x328
(ctdwnfil+0x328) 63a50000
(ctdwnfil+0x32c) e9e20170
(ctdwnfil+0x330) 3880ffff
(ctdwnfil+0x334) e86f0000
(ctdwnfil+0x338) 4bfcb90d
ori
ld
li
ld
bl
r5,r29,0x0
r15,0x170(r2)
r4,-1
r3,0x0(r15)
www.faircom.com
All Rights Reserved
196
0x0000000110025068
(dbx) 0x0000000110025068/llx
0x0000000110025068/llx
(dbx) print &ctpocsema
0x0000000110047548
if (ctnum->chnacs == 'n') {
====
0x000000010002452c
0x000000010005ba90
(dbx) listi
0x10005ba80
0x10005ba84
0x10005ba88
0x10005ba8c
0x10005ba90
0x10005ba94
0x10005ba98
0x10005ba9c
0x10005baa0
0x10005baa4
ctsemrqs() + 0x190
OPNFILX() + 0x738
&OPNFILX + 0x728
(OPNFILX+0x728) e9e20170
(OPNFILX+0x72c) 3880ffff
(OPNFILX+0x730) 63050000
(OPNFILX+0x734) e86f0000
(OPNFILX+0x738) 4bfc890d
(OPNFILX+0x73c) 60000000
(OPNFILX+0x740) 3861015c
(OPNFILX+0x744) 38800001
(OPNFILX+0x748) 63050000
(OPNFILX+0x74c) 480112cd
ld
li
ori
ld
bl
ori
addi
li
ori
bl
r15,0x170(r2)
r4,-1
r5,r24,0x0
r3,0x0(r15)
r0,r0,0x0
r3,0x15c(r1)
r4,0x1
r5,r24,0x0
0x10006cd70 (chkfilblk)
0x170(r2) : this is ctpocsema again
+8122
+8123
+8124
+8125
+8126
#ifdef ctFeatFILEBLOCK
if ((rc = chkfilblk(afilnam,1,sOWNR))) {
sysiocod = rc;
====
0x000000010002452c
0x000000010003b0c8
(dbx) listi
0x10003b0b8
0x10003b0bc
0x10003b0c0
0x10003b0c4
0x10003b0c8
ctsemrqs() + 0x190
ictio81x() + 0x640
&ictio81x + 0x630
(ictio81x+0x630) 3880ffff
(ictio81x+0x634) e87e0410
(ictio81x+0x638) 63850000
(ictio81x+0x63c) 7c63c82a
(ictio81x+0x640) 4bfe92d5
li
ld
ori
ldx
bl
r4,-1
r3,0x410(r30)
r5,r28,0x0
r3,r3,r25
(dbx) print &(((CTFILE *)0)->chnary)
0x0000000000000410
So ld r3,0x410(r30) is getting address of chnary.
ctsemrqs(&ctnum->chnary[0]->siosema,WAIT,sOWNR SMN(1320));
====
0x00000001000c2b4c
0x0000000100059b54
ct_tflstt() + 0x190
ctdwnfil() + 0x13fc
www.faircom.com
All Rights Reserved
197
Activation Failures (Error 26) on AIX 6
A previously activated server was found to not be activated with a newly provided activation key.
The fcactvat utility failed with system error 26 "Text file busy or in use".
AIX 6 can cache shared objects, in this case ctreedbs.so, and fcactvat can then not stamp the
binary. An AIX 6 utility, slibclean, is available on that platform that releases the object from the
cache allowing successful stamping.
12.5
HP-UX
Moving a HP-UX c-treeACE SQL Database to Windows
c-treeACE is a flexible database engine capable of running on many platforms and system
architectures. It is frequently useful to move a database from a Unix based high low architecture
to a Windows low-high Intel architecture. There are a couple issues with doing so:
 File headers
 Binary data
FairCom has long provided utilities for doing such data and index file conversions, namely,
ctunf1. To apply these to a full c-treeACE SQL database, perform the following steps.
1. Shutdown the server. Check for a clean shutdown logged in CTSTATUS.FCS with the final
messages:
- User# 00016
- User# 00016
2. Backup the database directory, making sure to include files ctdbdict.fsd, <dbname>.dbs/*.dat,
<dbname>.dbs/*.idx, and <dbname>.dbs/SQL_SYS/<dbname>.fdd.
3. Copy ctunf1 and convert.sh into the same directory as the server. (See below for convert.sh)
4. Run ./convert.sh <dbname>
5. Copy ctdbdict.fsd and the <dbname>.dbs folder to the windows machine if no errors
occurred.
6. Start the Windows c-treeACE Server process.
7. Use the ctpath utility to change paths from ./<dbname>.dbs/SQL_SYS/ to
.\<dbname>.dbs\SQL_SYS\
8. Use the ctpath utility to change paths from .<dbname>.dbs/ to .\<dbname>.dbs\
convert.sh (page 68)
convert.sh
#!/bin/sh
# usage: convert.sh DATABASE
# runs ctunf1 on a database and session dictionary
# converts from HIGH-LOW to LOW-HIGH ENDIAN-NESS
err(){
echo ERROR converting file $1
echo Check convert.log for error code
exit 1
}
www.faircom.com
All Rights Reserved
198
usage(){
echo usage:
echo convert DATABASE
echo runs ctunf1 on DATABASE and session dictionary
echo converts from HIGH-LOW to LOW-HIGH ENDIANNESS.
exit 1
}
dbname=$1
echo ${dbname}
if [ ! -d ${dbname}.dbs ]; then
echo Database ${dbname}.dbs not found
usage
fi
if [ ! -f ${dbname}.dbs/SQL_SYS/${dbname}.fdd ]; then
echo Database Dictionary not found
exit 1
fi
if [ ! -f ctdbdict.fsd ]; then
echo Session dictionary ctdbdict.fsd not found
exit 1
fi
echo
echo
echo
echo
echo
echo
echo
read
STARTING DATABASE ENDIAN CONVERSION.
ENSURE SERVER WAS SHUTDOWN CLEANLY.
ENSURE DATABASE $dbname HAS BEEN BACKED UP.
THIS UTILITY CONVERTS FILES IN PLACE.
ANY ERROR DURING CONVERSION WILL CORRUPT DATA.
PRESS ctrl-z TO EXIT.
PRESS ENTER TO CONTINUE CONVERSION.
echo CONVERTING DATABASE DICTIONARY
./ctunf1 ./${dbname}.dbs/SQL_SYS/${dbname}.fdd 8 L Y B2 512 >convert.log
if [ $? != 0 ]; then
err ${dbname}.dbs/SQL_SYS/${dbname}.fdd
fi
echo CONVERTING ALL DATA... Please be patient
for i in ./${dbname}.dbs/*.dat
do
if [ $? != 0 ]; then
err $i
fi
done
echo DATA FILE CONVERSION SUCCESS!
echo CONVERTING INDEX FILES
for i in ./${dbname}.dbs/*.idx
do
if [ $? != 0 ]; then
err $i
fi
done
echo INDEX FILE CONVERSION SUCCESS!
www.faircom.com
All Rights Reserved
199
echo CONVERTING Session dictionary
./ctunf1 ctdbdict.fsd 8 L Y B2 512 >>convert.log
if [ $? != 0 ]; then
err ctdbdict.fsd
fi
echo CONVERSION COMPLETE!
exit 0
www.faircom.com
All Rights Reserved
200
13. Function Name Cross Reference
Each c-treeACE function has two names: the full name and the abbreviated name. Full names
are used throughout this manual, and describe the action the function performs. The abbreviated
name is generally shorter and more cryptic. You will see it if you examine the c-treeACE source
code. Prior versions of the c-tree File Handler used the abbreviated names. If you have a
program that worked with older versions of c-tree, you will not have to change the function calls to
the full names. Also included in the table is the function’s API group and a table of API groups.
13.1
Full Names
This table lists the functions alphabetically by the Full Name.
Full Name
Abbreviated Name
Function Type
Abort
TRANABT
Transaction Processing API
AbortXtd
TRANABTX
AddCtResource
ADDRES
Utility API
AddKey
ADDKEY
Low-level Data Manipulation API
AddRecord
ADDREC
ISAM Data Manipulation API
AddVRecord
ADDVREC
AllocateBatch
ALCBAT
ISAM Data Manipulation - Batch API
AllocateSet
ALCSET
ISAM Data Manipulation - Sets API
AvailableFileNbr
AVLFILNUM
Utility API
Begin
TRANBEG
BuildKey
frmkey
ChangeBatch
CHGBAT
ChangeHistory
CHGHST
ChangeISAMContext
CHGICON
ISAM Data Manipulation - Context API
ChangeSet
CHGSET
CleanIndexXtd
CLNIDXX
Utility API
ClearSavePoint
SAVPCLR
ClearTranError
TRANCLR
CloseCtFile
CLSFIL
www.faircom.com
All Rights Reserved
201
Function Name Cross Reference
Full Name
Abbreviated Name
Function Type
CloseIFile
CLIFIL
Initialization API - ISAM
CloseISAM
CLISAM
CloseISAMContext
CLSICON
CloseRFile
CLRFIL
Commit
TRANEND
CompactIFile
CMPIFIL
Utility API
CompactIFileXtd
CMPIFILX
Utility API
cpybuf
cpybuf
Miscellaneous Functions
CreateDataFile
CREDAT
Low-level Data Definition API
CreateDataFileXtd
CREDATX
CreateDataFileXtd8
CREDATX8
CreateIFile
CREIFIL
ISAM Data Definition API
CreateIFileXtd
CREIFILX
CreateIFileXtd8
CREIFILX8
CreateIndexFile
CREIDX
CreateIndexFileXtd
CREIDXX
CreateIndexFileXtd8
CREIDXX8
CreateIndexMember
CREMEM
CreateISAM
CREISAM
CreateISAMXtd
CREISAMX
ctFILELIST
ctFILELIST
Utility API
ctGETHGH
ctGETHGH
ctMBprefix
ctMBprefix
Utility API
CtreeAsynchronous
CTASYNC
Utility API
CtreeCheckPoint
CTCHKPNT
CtreeFlushFile
CTFLUSH
Utility API
CtreeFlushFileXtd
CTFLUSHX
Utility API
CtreeUserOperation
CTUSER
Miscellaneous Functions
ctSETHGH
ctSETHGH
ctThrdAttach
ctThrdAttach
Initialization API - ctThrd API
ctThrdBlockCls
ctThrdBlockCls
www.faircom.com
All Rights Reserved
202
Full Name
Abbreviated Name
Function Type
ctThrdBlockGet
ctThrdBlockGet
ctThrdBlockInit
ctThrdBlockInit
ctThrdBlockRel
ctThrdBlockRel
ctThrdBlockWait
ctThrdBlockWait
ctThrdCreate
ctThrdCreate
ctThrdData
ctThrdData
ctThrdDataSet
ctThrdDataSet
ctThrdDetach
ctThrdDetach
ctThrdExit
ctThrdExit
ctThrdHandle
ctThrdHandle
ctThrdInit
ctThrdInit
ctThrdLIFOWrite
ctThrdLIFOWrite
ctThrdMutexCls
ctThrdMutexCls
ctThrdMutexGet
ctThrdMutexGet
ctThrdMutexInit
ctThrdMutexInit
ctThrdMutexRel
ctThrdMutexRel
ctThrdMutexTry
ctThrdMutexTry
ctThrdQueueClose
ctThrdQueueClose
ctThrdQueueCount
ctThrdQueueCount
ctThrdQueueMlen
ctThrdQueueMlen
ctThrdQueueOpen
ctThrdQueueOpen
ctThrdQueueRead
ctThrdQueueRead
ctThrdQueueReadDirect
ctThrdQueueWrite
ctThrdQueueWrite
ctThrdQueueWriteDirect
ctThrdSemapCls
ctThrdSemapCls
ctThrdSemapGet
ctThrdSemapGet
ctThrdSemapInit
ctThrdSemapInit
ctThrdSemapRel
ctThrdSemapRel
ctThrdSemapTry
ctThrdSemapTry
ctThrdSleep
ctThrdSleep
www.faircom.com
All Rights Reserved
203
Full Name
Abbreviated Name
Function Type
ctThrdTerm
ctThrdTerm
ctu16tou8
ctu16tou8
Utility API
ctu8tou16
ctu8tou16
Utility API
ctVerifyFile
ctVerifyFile
Verifies integrity of a file
ctVERIFYidx
ctVERIFYidx
CurrentFileOffset
GETCURP
CurrentISAMKey
GETCURK
CurrentLowLevelKey
GETCURKL
DeleteCtFile
DELFIL
DeleteCtResource
DELRES
Utility API
DeleteIFile
DELIFIL
DeleteKey
DELCHK
DeleteKeyBlind
DELBLD
DeleteRecord
DELREC
DeleteRFile
DELRFIL
DeleteVRecord
DELVREC
DoBatch
BATSET
DropIndex
ctDROPIDX
EnableCtResource
ENARES
Utility API
EstimateKeySpan
ESTKEY
FirstInSet
FRSSET
FirstInVSet
FRSVSET
FirstKey
FRSKEY
FirstRecord
FRSREC
FirstVRecord
FRSVREC
FreeBatch
FREBAT
FreeBatchNbr
FREBATN
FreeHistory
FREHST
FreeHistoryNbr
FREHSTN
FreeSet
FRESET
FreeSetNbr
FRESETN
www.faircom.com
All Rights Reserved
204
Full Name
Abbreviated Name
Function Type
GetAltSequence
GETALTSEQ
GetConditionalIndex
GETCIDX
GetCtFileInfo
GETFIL
GetCtResource
GETRES
Initialization API - Instance Control
GetCtreePointer
GETCTREE
Utility API
GetCtTempFileName
TMPNAME
Utility API
GetDODA
GETDODA
GetGTEKey
GTEKEY
GetGTERecord
GTEREC
GetGTEVRecord
GTEVREC
GetGTKey
GTKEY
GetGTRecord
GTREC
GetGTVRecord
GTVREC
GetIFile
GETIFIL
GetKey
EQLKEY
GetLTEKey
LTEKEY
GetLTERecord
LTEREC
GetLTEVRecord
LTEVREC
GetLTKey
LTKEY
GetLTRecord
LTREC
GetLTVRecord
LTVREC
GetORDKey
ORDKEY
GetRecord
EQLREC
GetSerialNbr
SERIALNUM
Utility API
GetServerInfo
GetServerInfo
GetServerInfoXtd
GetServerInfoXtd
GetSuperFileNames
GETMNAME
GetSymbolicNames
GETNAM
GetVRecord
EQLVREC
GetXtdCreateBlock
GETXCREBLK
Utility API
GetXtdKeySegmentDef
GETKSEGDEF
www.faircom.com
All Rights Reserved
205
Full Name
Abbreviated Name
Function Type
InitCTree
INTREE
Initialization API - Low-level
InitCTreeXtd
INTREEX
InitISAM
INTISAM
InitISAMXtd
INTISAMX
IOPERFORMANCE
IOPERFORMANCE
Server Administration API
IOPERFORMANCEX
IOPERFORMANCEX
KeyAtPercentile
FRCKEY
LastInSet
LSTSET
LastInVSet
LSTVSET
LastKey
LSTKEY
LastRecord
LSTREC
LastVRecord
LSTVREC
LoadKey
LOADKEY
LockCtData
LOKREC
LockDump
ctLOKDMP
LockISAM
LKISAM
NbrOfKeyEntries
IDXENT
NbrOfKeysInRange
RNGENT
NbrOfRecords
DATENT
NewData
NEWREC
NewVData
NEWVREC
NextCtree
NXTCTREE
NextInSet
NXTSET
NextInVSet
NXTVSET
NextKey
NXTKEY
NextRecord
NXTREC
NextVRecord
NXTVREC
OpenCtFile
OPNFIL
OpenCtFileXtd
OPNFILX
OpenFileWithResource
OPNRFIL
OpenFileWithResourceXt
d
OPNRFILX
www.faircom.com
All Rights Reserved
206
Full Name
Abbreviated Name
Function Type
OpenIFile
OPNIFIL
OpenIFileXtd
OPNIFILX
OpenISAM
OPNISAM
OpenISAMContext
OPNICON
OpenISAMXtd
OPNISAMX
PartitionAdmin
PTADMIN
Utility API
Perform
PERFORM
PermIIndex
PRMIIDX
PermIIndex8
PRMIIDX8
PositionSet
MIDSET
PositionVSet
MIDVSET
PreviousInSet
PRVSET
PreviousInVSet
PRVVSET
PreviousKey
PRVKEY
PreviousRecord
PRVREC
PreviousVRecord
PRVVREC
PutDODA
PUTDODA
PutIFile
PUTIFIL
PutIFileXtd
PUTIFILX
PutIFileXtd8
PUTIFILX8
PutXtdKeySegmentDef
PUTKSEGDEF
ISAM Data Definition
ReadData
REDREC
ReadIsamData
REDIREC
ReadIsamVData
REDIVREC
ReadVData
RDVREC
RebuildIFile
RBLIFIL
RebuildIFileXtd
RBLIFILX
RebuildIFileXtd8
RBLIFILX8
RebuildIIndex
RBLIIDX
RegisterCtree
REGCTREE
ReleaseData
RETREC
www.faircom.com
All Rights Reserved
207
Full Name
Abbreviated Name
Function Type
ReleaseVData
RETVREC
RenameFile
ctRENFIL
RenameIFile
RENIFIL
RenameIFileXtd
RENIFILX
ReReadRecord
RRDREC
ReReadVRecord
REDVREC
ResetRecord
UPDCURI
RestoreSavePoint
TRANRST
ReWriteRecord
RWTREC
ReWriteVRecord
RWTVREC
SA_FILES
SA_FILES
SA_GROUP
SA_GROUP
SA_LOGOF
SA_LOGOF
SA_LOGON
SA_LOGON
SA_USERS
SA_USERS
Security
SECURITY
SetAlternateSequence
SETALTSEQ
SetCallbackOnRebuild
SETCBRBL
Utility API
SetDataFilter
SETFLTR
SetEncryption
ctSETENCRYPT
Utility API
SetFileSegments
ctSETSEG
SETLOGPATH
SETLOGPATH
SetNodeName
SETNODE
SetOperationState
SETOPS
Utility API
SetRecord
SETCURI
SetSavePoint
TRANSAV
SetVariableBytes
SETVARBYTS
StopServer
STPSRV
StopServerXtd
STPSRVX
StopUser
STPUSR
StopUserAsync
STPUSRA
www.faircom.com
All Rights Reserved
208
13.2
Full Name
Abbreviated Name
Function Type
SuperfilePrepassXtd
CTSBLDX
Utility API
SwitchCtree
SWTCTREE
SystemConfiguration
SYSCFG
Utility API
SystemLog
SYSLOG
SystemMonitor
SYSMON
Utility API
TempIIndexXtd
TMPIIDXX
TempIIndexXtd8
TMPIIDXX8
TestFileNbr
TSTFILNUM
Utility API
TestHugeFile
TESTHUGE
Utility API
TransformKey
TFRMKEY
TranformSegment
cttseg
TranformXtdSegment
XFMKSEGDEF
TransactionHistory
CTHIST
UnRegisterCtree
UNRCTREE
UpdateConditionalIndex
UPDCIDX
UpdateCtResource
UPDRES
Utility API
UpdateFileMode
PUTFIL
UpdateHeader
PUTHDR
VDataLength
GTVLEN
VRecordLength
GETVLEN
vtclose
vtclose
Utility API
WhichCtree
WCHCTREE
WriteData
WRTREC
WriteVData
WRTVREC
Abbreviated (short) Names
This table lists the functions alphabetically by the Abbreviated Name.
Abbreviated Name
Full Name
Function Type
ADDKEY
AddKey
ADDREC
AddRecord
www.faircom.com
All Rights Reserved
209
Abbreviated Name
Full Name
Function Type
ADDRES
AddCtResource
Utility API
ADDVREC
AddVRecord
ALCBAT
AllocateBatch
ALCSET
AllocateSet
AVLFILNUM
AvailableFileNbr
Utility API
BATSET
DoBatch
CHGBAT
ChangeBatch
CHGHST
ChangeHistory
CHGICON
ChangeISAMContext
CHGSET
ChangeSet
CLIFIL
CloseIFile
CLISAM
CloseISAM
CLNIDXX
CleanIndexXtd
Utility API
CLRFIL
CloseRFile
CLSFIL
CloseCtFile
CLSICON
CloseISAMContext
CMPIFIL
CompactIFile
CMPIFILX
CompactIFileXtd
cpybuf
cpybuf
Utility API
CREDAT
CreateDataFile
CREDATX
CreateDataFileXtd
CREDATX8
CreateDataFileXtd8
CREIDX
CreateIndexFile
CREIDXX
CreateIndexFileXtd
CREIDXX8
CreateIndexFileXtd8
CREIFIL
CreateIFile
CREIFILX
CreateIFileXtd
CREIFILX8
CreateIFileXtd8
CREISAM
CreateISAM
CREISAMX
CreateISAMXtd
CREMEM
CreateIndexMember
CTASYNC
CtreeAsynchronous
Utility API
CTCHKPNT
CtreeCheckPoint
ctDROPIDX
DropIndex
ctFILELIST
ctFILELIST
Utility API
www.faircom.com
All Rights Reserved
210
Abbreviated Name
Full Name
Function Type
CTFLUSH
CtreeFlushFile
Utility API
CTFLUSHX
CtreeFlushFileXtd
Utility API
ctGETHGH
ctGETHGH
CTHIST
TransactionHistory
ctLOKDMP
LockDump
ctMBprefix
ctMBprefix
Utility API
ctRENFIL
RenameFile
CTSBLDX
SuperfilePrePassXtd
Utility API
ctSETENCRYPT
SetEncryption
Utility API
ctSETHGH
ctSETHGH
ctSETSEG
SetFileSegments
ctThrdAttach
ctThrdAttach
ctThrdBlockCls
ctThrdBlockCls
ctThrdBlockGet
ctThrdBlockGet
ctThrdBlockInit
ctThrdBlockInit
ctThrdBlockRel
ctThrdBlockRel
ctThrdBlockWait
ctThrdBlockWait
ctThrdCreate
ctThrdCreate
ctThrdData
ctThrdData
ctThrdDataSet
ctThrdDataSet
ctThrdDetach
ctThrdDetach
ctThrdExit
ctThrdExit
ctThrdHandle
ctThrdHandle
ctThrdInit
ctThrdInit
ctThrdLIFOWrite
ctThrdLIFOWrite
ctThrdMutexCls
ctThrdMutexCls
ctThrdMutexGet
ctThrdMutexGet
ctThrdMutexInit
ctThrdMutexInit
ctThrdMutexRel
ctThrdMutexRel
ctThrdMutexTry
ctThrdMutexTry
ctThrdQueueClose
ctThrdQueueClose
ctThrdQueueCount
ctThrdQueueCount
ctThrdQueueMlen
ctThrdQueueMlen
ctThrdQueueOpen
ctThrdQueueOpen
ctThrdQueueRead
ctThrdQueueRead
www.faircom.com
All Rights Reserved
211
Abbreviated Name
Full Name
Function Type
ctThrdQueueWrite
ctThrdQueueWrite
ctThrdSemapCls
ctThrdSemapCls
ctThrdSemapGet
ctThrdSemapGet
ctThrdSemapInit
ctThrdSemapInit
ctThrdSemapRel
ctThrdSemapRel
ctThrdSemapTry
ctThrdSemapTry
ctThrdSleep
ctThrdSleep
ctThrdTerm
ctThrdTerm
cttseg
TransformSegment
ctu16tou8
ctu16tou8
Utility API
ctu8tou16
ctu8tou16
Utility API
ctVerifyFile
ctVerifyFile
ctVERIFYidx
ctVERIFYidx
CTUSER
CtreeUserOperation
Utility API
DATENT
NbrOfRecords
DELBLD
DeleteKeyBlind
DELCHK
DeleteKey
DELFIL
DeleteCtFile
DELIFIL
DeleteIFile
DELREC
DeleteRecord
DELRES
DeleteCtResource
Utility API
DELRFIL
DeleteRFile
DELVREC
DeleteVRecord
ENARES
EnableCtResource
Utility API
EQLKEY
GetKey
EQLREC
GetRecord
EQLVREC
GetVRecord
ESTKEY
EstimateKeySpan
FRCKEY
KeyAtPercentile
FREBAT
FreeBatch
FREBATN
FreeBatchNbr
FREHST
FreeHistory
FREHSTN
FreeHistoryNbr
FRESET
FreeSet
FRESETN
FreeSetNbr
www.faircom.com
All Rights Reserved
212
Abbreviated Name
Full Name
Function Type
frmkey
BuildKey
FRSKEY
FirstKey
FRSREC
FirstRecord
FRSSET
FirstInSet
FRSVREC
FirstVRecord
FRSVSET
FirstInVSet
GETALTSEQ
GetAlternateSequence
GETCIDX
GetConditionalIndex
GETCTREE
GetCtreePointer
GETCURK
CurrentISAMKey
GETCURKL
CurrentLowLevelKey
GETCURP
CurrentFileOffset
GETDODA
GetDODA
GETFIL
GetCtFileInfo
GETIFIL
GetIFile
GETKSEGDEF
GetXtdKeySegmentDef
GETMNAME
GetSuperFileNames
GETNAM
GetSymbolicNames
GETRES
GetCtResource
Utility API
GetServerInfo
GetServerInfo
GetServerInfoXtd
GetServerInfoXtd
GETVLEN
VRecordLength
GETXCREBLK
GetXtdCreateBlock
Utility API
GTEKEY
GetGTEKey
GTEREC
GetGTERecord
GTEVREC
GetGTEVRecord
GTKEY
GetGTKey
GTREC
GetGTRecord
GTVLEN
VDataLength
GTVREC
GetGTVRecord
IDXENT
NbrOfKeyEntries
INTISAM
InitISAM
INTISAMX
InitISAMXtd
INTREE
InitCTree
INTREEX
InitCTreeXtd
IOPERFORMANCE
IOPERFORMANCE
www.faircom.com
All Rights Reserved
213
Abbreviated Name
Full Name
Function Type
IOPERFORMANCEX
IOPERFORMANCEX
LKISAM
LockISAM
LOADKEY
LoadKey
LOKREC
LockCtData
LSTKEY
LastKey
LSTREC
LastRecord
LSTSET
LastInSet
LSTVREC
LastVRecord
LSTVSET
LastInVSet
LTEKEY
GetLTEKey
LTEREC
GetLTERecord
LTEVREC
GetLTEVRecord
LTKEY
GetLTKey
LTREC
GetLTRecord
LTVREC
GetLTVRecord
MIDSET
PositionSet
MIDVSET
PositionVSet
NEWREC
NewData
NEWVREC
NewVData
NXTCTREE
NextCtree
NXTKEY
NextKey
NXTREC
NextRecord
NXTSET
NextInSet
NXTVREC
NextVRecord
NXTVSET
NextInVSet
OPNFIL
OpenCtFile
OPNFILX
OpenCtFileXtd
OPNICON
OpenISAMContext
OPNIFIL
OpenIFile
OPNIFILX
OpenIFileXtd
OPNISAM
OpenISAM
OPNISAMX
OpenISAMXtd
OPNRFIL
OPNRFILX
OpenFileWithResourceXt
d
ORDKEY
GetORDKey
www.faircom.com
All Rights Reserved
214
Abbreviated Name
Full Name
Function Type
PERFORM
Perform
PRMIIDX
PermIIndex
PRMIIDX8
PermIIndex8
PRVKEY
PreviousKey
PRVREC
PreviousRecord
PRVSET
PreviousInSet
PRVVREC
PreviousVRecord
PRVVSET
PreviousInVSet
PTADMIN
PartitionAdmin
Utility API
PUTDODA
PutDoda
PUTFIL
UpdateFileMode
PUTHDR
UpdateHeader
PUTIFIL
PutIFile
PUTIFILX
PutIFileXtd
PUTIFILX8
PutIFileXtd8
PUTKSEGDEF
PutXtdKeySegmentDef
ISAM Data Definition
RBLIFIL
RebuildIFile
RBLIFILX
RebuildIFileXtd
RBLIFILX8
RebuildIFileXtd8
RBLIIDX
RebuildIIndex
RDVREC
ReadVData
REDIREC
ReadIsamData
REDIVREC
ReadIsamVData
REDREC
ReadData
REDVREC
ReReadVRecord
REGCTREE
RegisterCtree
RENIFIL
RenameIFile
RENIFILX
RenameIFileXtd
RETREC
ReleaseData
RETVREC
ReleaseVData
RNGENT
NbrOfKeysInRange
RRDREC
ReReadRecord
RWTREC
ReWriteRecord
RWTVREC
ReWriteVRecord
SA_FILES
SA_FILES
SA_GROUP
SA_GROUP
www.faircom.com
All Rights Reserved
215
Abbreviated Name
Full Name
Function Type
SA_LOGOF
SA_LOGOF
SA_LOGON
SA_LOGON
SA_USERS
SA_USERS
SAVPCLR
ClearSavePoint
SECURITY
Security
SERIALNUM
GetSerialNbr
Utility API
SETALTSEQ
SETCBRBL
Utility API
SETCURI
SetRecord
SETFLTR
SetDataFilter
SETLOGPATH
SETLOGPATH
SETNODE
SetNodeName
SETOPS
SetOperationState
Utility API
SETVARBYTS
SetVariableBytes
STPSRV
StopServer
STPSRVX
StopServerXtd
STPUSR
StopUser
STPUSRA
StopUserAsync
SWTCTREE
SwitchCtree
SYSCFG
SystemConfiguration
Utility API
SYSLOG
SystemLog
SYSMON
SystemMonitor
Utility API
TESTHUGE
TestHugeFile
Utility API
TFRMKEY
TransformKey
TMPIIDXX
TempIIndexXtd
TMPIIDXX8
TempIIndexXtd8
TMPNAME
GetCtTempFileName
Utility API
TRANABT
Abort
TRANABTX
AbortXtd
TRANBEG
Begin
TRANCLR
ClearTranError
TRANEND
Commit
TRANRST
RestoreSavePoint
TRANSAV
SetSavePoint
TSTFILNUM
TestFileNbr
Utility API
UNRCTREE
UnRegisterCtree
www.faircom.com
All Rights Reserved
216
13.3
Abbreviated Name
Full Name
Function Type
UPDCIDX
UPDCURI
ResetRecord
UPDRES
UpdateCtResource
Utility API
vtclose
vtclose
Utility API
WCHCTREE
WhichCtree
WRTREC
WriteData
WRTVREC
WriteVData
XFMKSEGDEF
TranformXtdSegment
Function API Listing
This section lists the c-treeACE Function API broken into functional groupings: Initializion,
Definition, Manipulation, and Utility. Each of these grouping has sub-groups as described in the
topics that follow.
Initialization API
The initialization API prepares the environment for c-treeACE operation. Included are the ctThrd,
Instance Control, ISAM Initialization, and Low-level Initialization APIs.
ctThrd API
The c-treeACE ctThrd API is a very thin overlay over the native threading API for each operating
systems. Only systems without native threading use a c-treeACE proprietary threading API.
ctThrdAttach
ctThrdInit
ctThrdQueueRead
ctThrdBlockCls
ctThrdLIFOWrite
ctThrdBlockGet
ctThrdMutexCls
ctThrdQueueWrite
ctThrdBlockInit
ctThrdMutexGet
ctThrdBlockRel
ctThrdMutexInit
ctThrdSemapCls
ctThrdBlockWait
ctThrdMutexRel
ctThrdSemapGet
ctThrdCreate
ctThrdMutexTry
ctThrdSemapInit
ctThrdData
ctThrdQueueClose
ctThrdSemapRel
ctThrdDataSet
ctThrdQueueCount
ctThrdSemapTry
ctThrdDetach
ctThrdQueueMlen
ctThrdSleep
ctThrdExit
ctThrdQueueOpen
ctThrdTerm
ctThrdHandle
www.faircom.com
All Rights Reserved
217
Instance Control API
Similar to the thread API but used only with single-thread models, Instance Control allows and
controls multiple c-treeACE instances within a single application.
GetCtreePointer
RegisterCtree
UnRegisterCtree
NextCtree
SwitchCtree
WhichCtree
ISAM Initialization API
Used to initialize the ISAM level operation of c-treeACE.
CloseIFile
InitISAMXtd
OpenIFileXtd
CloseISAM
OpenISAM
CloseRFile
OpenFileWithResourceXtd
OpenISAMXtd
InitISAM
OpenIFile
Low-level Initialization API
Used to initialize the low-level c-treeACE environment.
CloseCtFile
InitCTreeXtd
InitCTree
OpenCtFile
OpenCtFileXtd
Data Definition API
Used to create and define tables and indices. Divided into ISAM and Low-level APIs.
Used to create and define files for ISAM level use.
CompactIFile
GetDODA
RebuildIFile
CompactIFileXtd
GetIFile
RebuildIFileXtd
CreateIFile
GetXtdKeySegmentDef
RebuildIFileXtd8
CreateIFileXtd
PermIIndex
RebuildIIndex
CreateIFileXtd8
PermIIndex8
RenameIFile
CreateISAM
PutDODA
RenameIFileXtd
CreateISAMXtd
PutIFile
TempIIndexXtd
DeleteIFile
PutIFileXtd
TempIIndexXtd8
DeleteRFile
PutIFileXtd8
TranformXtdSegment
DropIndex
PutXtdKeySegmentDef
www.faircom.com
All Rights Reserved
218
GetConditionalIndex
Used to create and define files for Low-level use.
CreateDataFile
DeleteCtFile
RenameFile
CreateDataFileXtd
GetAlternateSequence
CreateDataFileXtd8
GetCtFileInfo
SetFileSegments
CreateIndexFile
GetServerInfo
SetVariableBytes
CreateIndexFileXtd
GetServerInfoXtd
UpdateFileMode
CreateIndexFileXtd8
GetSuperFileNames
UpdateHeader
CreateIndexMember
Data Manipulation API
Data manipulation functions are used to alter the contents of data and index files. This sections is
divided into ISAM and Low-level functions.
ISAM Manipulation functions are divided into general, Batch, Context, and Set APIs.
AddRecord
GetLTEVRecord
PreviousVRecord
AddVRecord
GetLTRecord
ReadIsamData
CurrentFileOffset
GetLTVRecord
ReadIsamVData
CurrentISAMKey
GetRecord
ReReadRecord
DeleteRecord
GetSymbolicNames
ReReadVRecord
DeleteVRecord
LastRecord
ResetRecord
FirstRecord
LastVRecord
ReWriteRecord
FirstVRecord
LockISAM
ReWriteVRecord
GetGTERecord
NbrOfRecords
SetDataFilter
GetGTEVRecord
NextRecord
SetRecord
GetGTRecord
NextVRecord
TransformKey
GetGTVRecord
PreviousRecord
VRecordLength
GetLTERecord
www.faircom.com
All Rights Reserved
219
Batch API
Manipulate batches of records in a single call.
AllocateBatch
DoBatch
ChangeBatch
FreeBatch
FreeBatchNbr
Context API
Maintain separate positions in a file.
ChangeISAMContext
CloseISAMContext
OpenISAMContext
Sets API
Work with a specified subset of a table’s records.
AllocateSet
FreeSetNbr
PositionSet
ChangeSet
LastInSet
PositionVSet
FirstInSet
LastInVSet
PreviousInSet
FirstInVSet
NextInSet
PreviousInVSet
FreeSet
NextInVSet
Manipulate data and index files at the low level.
AddKey
GetKey
NewData
BuildKey
GetLTEKey
NextKey
ctGETHGH
GetLTKey
PreviousKey
ctSETHGH
GetORDKey
ReadData
CurrentLowLevelKey
GetVRecord
ReadVData
DeleteKey
KeyAtPercentile
ReleaseData
DeleteKeyBlind
LastKey
ReleaseVData
EstimateKeySpan
LoadKey
TransformSegment
FirstKey
LockCtData
VDataLength
GetGTEKey
NbrOfKeyEntries
WriteData
GetGTKey
NbrOfKeysInRange
WriteVData
www.faircom.com
All Rights Reserved
220
Utility Functions
The following functions provide capabilities that do not fit into the categories above. In addition to
general utility functions, Server administration and Transaction Processing control functions are
included here.
AddCtResource
ctu16tou8
SetEncryption
AvailableFileNbr
ctu8tou16
SetOperationState
CleanIndexXtd
DeleteCtResource
SuperfilePrePassXtd
cpybuf
EnableCtResource
SystemConfiguration
ctFILELIST
GetCtResource
SystemMonitor
ctMBprefix
GetCtTempFileName
TestFileNbr
CtreeAsynchronous
GetSerialNbr
TestHugeFile
CtreeFlushFile
GetXtdCreateBlock
UpdateCtResource
CtreeFlushFileXtd
PartitionAdmin
vtclose
CtreeUserOperation
The following utility functions are specific to Client/Server operation.
IOPERFORMANCE
SA_LOGOF
StopServer
IOPERFORMANCEX
SA_LOGON
StopServerXtd
LockDump
SA_USERS
StopUser
Perform
Security
StopUserAsync
SA_FILES
SetNodeName
SystemLog
SA_GROUP
The following utility functions control transaction processing.
Abort
ClearTranError
RestoreSavePoint
AbortXtd
Commit
SETLOGPATH
Begin
CtreeCheckPoint
SetSavePoint
ChangeHistory
FreeHistory
TransactionHistory
ClearSavePoint
FreeHistoryNbr
www.faircom.com
All Rights Reserved
221
www.faircom.com
All Rights Reserved
222
14. Common Entry Point Functions
c-tree Plus offers two calling methods for each function: the traditional c-tree Plus call by function
name in which each operation is called by a separate function, and the common entry point in
which all functions are accessed through the ctree function. For example, AddKey() can be
called in either of these two ways:
AddKey(keyno,target,recbyt,typadd);
ctree(FN_ADDKEY,keyno,target,&recbyt,NULL,NULL,typadd);
Either approach produces the same results, but some developers find the common entry point
approach better suits their approach to programming.
If you are using the c-tree Server, the client side of c-tree Plus uses the common entry point
approach to send the function calls to the c-tree Server. The traditional functions are remapped to
common entry point functions. If you use the common entry point function in your application,
without any traditional functions, your program will not have to link in the remapping code, saving
program memory.
Note:
If the local library support is to be used in conjunction with common entry point, call
ctree_loc() instead of ctree().
Note:
When using common entry point with ctNOGLOBALS defined in ctoptn.h, call
RegisterCtree() before initializing c-tree Plus, (InitISAM(), etc.), because the global structure
must be allocated before c-tree Plus can be initialized. If this is not done, the application will hang
or core dump on the initialization call.
14.1
Forced Single Entry Point Capability
The ctFRCSNG define forces single entry point calls using the regular API. Enabling this define
causes the standard c-tree Plus API (i.e., GetRecord(), AddRecord(), . . .) to be routed through
the c-tree Plus single entry function ctree(). Forcing the single-entry point is used when
developing an interface wrapper from another database. This force single entry point feature is
enabled by adding #define ctFRCSNG to ctoptn.h (see the Quick Start and Product Overview
Guide for information on modifying ctoptn.h) and requires no modification on the part of the
programmer.
14.2
Extended Feature Parameter Blocks
Most of the extended features, such as file security, are passed to ctree as part of a set of
parameter blocks defined in ctparm.h. Any application using the single entry point function,
ctree(), must include ctparm.h. ctparm.h also contains the function numbers (FN_ADDKEY, etc.)
used in the ctree() fn parameter.
The definitions of the parameter blocks are below. They are referenced as parameters in the
function definitions listed at the end of this appendix. Please note the values assigned to the
various character array sizes for the parameter block definitions:
www.faircom.com
All Rights Reserved
223
Common Entry Point Functions
Value
Symbolic Constant
Use (including null terminator)
8
EXZ
Incremental IFIL data and index file name extensions.
10
PWZ
User and file passwords.
16
IDZ
User and Group ID’s.
64
DSZ
Symbolic Field and Index Names.
255
FNZ
File and Server Names.
Logon Block
typedef struct logblk {
COUNT
files;
profile mask
*/
COUNT
ibuffers;
COUNT
dbuffers;
COUNT
nsectors;
COUNT
reservd1;
VRLEN
reservd2;
TEXT
userid[IDZ];
TEXT
userword[PWZ];
TEXT
servname[FNZ];
} LOGBLK;
/* number of files & indices */
/*
/*
/*
/*
/*
/*
/*
/*
# of index buffers
# of data buffers
# of sectors per buffer
reserved
reserved
user id
user password
optional server name
COUNT
userprof;
/* user
*/
*/
*/
*/
*/
*/
*/
*/
The ibuffers, dbuffers, and nsectors members are ignored when connecting to a c-tree Server.
The userid and userword members are ignored in non-server operation. The userprof member
controls performance of automatic TransformKey() on targets sent to ISAM level search
routines. Set userprof to USERPRF_NTKEY to disable the automatic TransformKey(). The
servname member supports multiple c-tree Server environments.
ISAM Block
typedef struct isamblk {
LOGBLK
isamlog;
LONG
permmask;
TEXT
groupid[IDZ];
TEXT
fileword[PWZ];
TEXT
parmname[FNZ];
} ISAMBLK;
/*
/*
/*
/*
/*
login block
*/
CreateISAM permission mask */
CreateISAM Group id
*/
file password
*/
parameter file name
*/
The isamlog member is simply a logon block interpreted as above. The optional permmask and
groupid members are only used by CreateISAM() to set the file permission masks and
passwords. The fileword member is used by CreateISAM() to set the password and by
OpenISAM() to access the file. The parmname member holds the parameter file name.
IFIL Block
typedef struct ifilblk {
LONG
permmask;
TEXT
groupid[IDZ];
TEXT
fileword[PWZ];
TEXT
dataextn[EXZ];
/*
/*
/*
/*
CreateIFile permission mask */
CreateIFile Group id
*/
file password
*/
data extension
*/
www.faircom.com
All Rights Reserved
224
TEXT
pIFIL
} IFILBLK;
indxextn[EXZ]; /* indx extension
ptr_ifil;
/* IFIL pointer
*/
*/
permmask and groupid hold the optional security information assigned at file creation. fileword
holds the optional password assigned at creation or used by a file open. dataextn and indxextn
hold optional file name extensions for the data and index files, respectively. If a file name
extension member begins with a NULL byte, the default extension is used, .dat for data files and
.idx for index files. To signify that no extension should be added, pass the member containing
only blanks and a null terminator. Both file name extension members cannot be blank since the
data file and index must have unique names. ptr_ifil points to a traditional IFIL structure.
Create File Block
typedef struct creblk {
UCOUNT
length;
UCOUNT
extdsize;
COUNT
filemode;
COUNT
keytyp;
COUNT
keydup;
COUNT
member;
LONG
permmask;
TEXT
groupid[IDZ];
TEXT
fileword[PWZ];
TEXT
filename[FNZ];
} CREBLK;
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
record / key length
file extent size
file mode
index key type
index duplicate flag
index member #
permission mask
group id
file password
file name
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
length specifies the record length for data files or the key length for index files. extdsize contains
the file size extension parameter, and filemode contains the file mode. keytyp, keydup, and
member are ignored for data files and represent the key type, key duplicate, and index member
number, respectively, for index files. permmask, groupid, and fileword hold the optional file
security information. Finally, filename contains the file name to be used at create.
Open File Block
typedef struct openblk { COUNT
filemode;
/* file password */
TEXT
filename[FNZ]; /* file name
*/
} OPENBLK;
/* file mode
*/
TEXT
fileword[PWZ];
filemode holds the file mode used at open. fileword contains the optional password, and filename
contains the file name to be used at open.
Key Estimate Block
typedef struct estmblk {
TEXT
key1[MAXLEN]; /* 1st key */
TEXT
key2[MAXLEN]; /* 2nd key */
} ESTMBLK;
The Key Estimate Block is used with the FN_ESTKEY() function, which estimates the number of
key values occurring between key1 and key2.
www.faircom.com
All Rights Reserved
225
14.3
Function Calls
The single entry point calling sequence is based on the following function prototype:
COUNT ctree(COUNT fn, COUNT filno, pVOID ptr1, pLONG plong,
pVOID ptr2, pVRLEN psize, COUNT mode);
fn is the function number, filno is usually a file number, ptr1 and ptr2 point to various types of data
or parameter blocks, plong points to a long integer, psize points to a long integer used to convey
or return the size of an object, and mode is a short integer for various specifications.
Because of the manner in which C functions pass parameters, it is not necessary to supply all
seven parameters all of the time. Generally, you need only supply enough parameters to satisfy
the particular function, BUT you cannot skip parameters.
Note: ctree() always returns an error code. If the traditional function does not return an error
code, a return value is passed back as one of the parameters to ctree().
For example, GetKey() returns a long value corresponding to the record position containing the
target key value. In the traditional c-tree Plus approach, call:
recpos = GetKey(keyno,target);
With the ctree() form, call:
errcod = ctree(FN_EQLKEY,keyno,target,&recpos);
recpos is passed back as an output parameter of ctree(). In the following listing, retval denotes
the parameter that contains the return value of the function. c-tree Plus functions which return an
error code do not use a retval parameter.
Several c-tree Plus functions are listed below with their traditional call by name form and the
ctree(FN_...) form. The extended functions, those that have a suffix of Xtd, use the same single
entry point call as the equivalent standard function. The function numbers are based on the short
function name listed in “Upgrade Previous Editions (page 239,
http://docs.faircom.com/doc/knowledgebase/#28374.htm)”.
COUNT Abort()
ctree(FN_TRANABT)
COUNT AddKey(keyno,target,recbyt,typadd)
ctree(FN_ADDKEY,keyno,target,&recbyt,NULL,NULL,typadd)
COUNT AddRecord(datno,recptr)
ctree(FN_ADDREC,datno,recptr)
COUNT AddCtResource(datno,resptr,varlen)
ctree(FN_ADDRES,datno,resptr,NULL,NULL,&varlen)
COUNT AddVRecord(datno,recptr,varlen)
ctree(FN_ADDVREC,datno,recptr,NULL,NULL,&varlen)
COUNT AllocateSet(numset)
ctree(FN_ALCSET,numset)
COUNT AvailableFileNbr(numfils)
ctree(FN_AVLFILNUM,numfils,retval)
LONG Begin(mode)
ctree(FN_TRANBEG,mode,NULL,&retval)
www.faircom.com
All Rights Reserved
226
COUNT ChangeSet(setnum)
ctree(FN_CHGSET,setnum)
COUNT ClearTranError()
ctree(FN_TRANCLR)
COUNT CloseFile(filno,filmod)
ctree(FN_CLSFIL,filno)
COUNT CloseIFile(ifilptr)
ctree(FN_CLIFIL,0,&ifilblk)
COUNT CloseISAM()
ctree(FN_CLISAM)
COUNT CloseRFile(datno)
ctree(FN_CLRFIL,datno)
COUNT Commit(mode)
ctree(FN_TRANEND,mode)
COUNT CreateDataFile(datno,filnam,datlen,xtdsiz,filmod)
COUNT CreateDataFileXtd(datno,filnam,datlen,xtdsiz,filmod,
permmask,groupid,fileword)
ctree(FN_CREDAT,datno,&createblk)
COUNT CreateIFile(ifilptr)
COUNT CreateIFileXtd(ifilptr,dataextn,indxextn,permmask,groupid,fileword)
ctree(FN_CREIFIL,0,&ifilblk)
COUNT CreateIndexFile(keyno,filnam,keylen,keytyp,keydup,
nomemb,xtdsiz,filmod)
COUNT CreateIndexFileXtd(keyno,filnam,keylen,keytyp,keydup,
nomemb,xtdsiz,filmod,permmask,groupid,fileword)
ctree(FN_CREIDX,keyno,&createblk)
COUNT CreateIndexMember(keyno,keylen,keytyp,keydup,membno)
ctree(FN_CREMEM,keyno,&createblk)
COUNT CreateISAM(filnam)
COUNT CreateISAMXtd(filnam,userprof,userid,userword,servname,
permmask,groupid,fileword)
ctree(FN_CREISAM,0,&isamblk)
pTEXT CurrentISAMKey(keyno,idxval,plen)
ctree(FN_GETCURK,keyno,idxval,NULL,plen)
LONG CurrentFileOffset(datno)
ctree(FN_GETCURP,datno,NULL,&retval)
COUNT DeleteCtFile(filno)
ctree(FN_DELFIL,filno)
COUNT DeleteKey(keyno,target,recbyt)
ctree(FN_DELCHK,keyno,target,&recbyt)
LONG DeleteKeyBlind(keyno,target)
ctree(FN_DELBLD,keyno,target,&retval)
COUNT DeleteRecord(datno)
ctree(FN_DELREC,datno)
www.faircom.com
All Rights Reserved
227
COUNT DeleteCtResource(datno,resptr)
ctree(FN_DELRES,datno,resptr)
COUNT DeleteVRecord(datno)
ctree(FN_DELVREC,datno)
COUNT DoBatch(filno,request,bufptr,bufsiz,mode)
ctree(FN_BATSET,filno,request,NULL,bufptr,&bufsiz,mode)
COUNT EnableCtResource(datno)
ctree(FN_ENARES,datno)
LONG EstimateKeySpan(keyno,idxval1,idxval2)
ctree(FN_ESTKEY,keyno,&estm,&retval)
COUNT FirstInSet(keyno,target,recptr,siglen)
ctree(FN_FRSSET,keyno,target,NULL,recptr,NULL,siglen)
LONG FirstKey(keyno,idxval)
ctree(FN_FRSKEY,keyno,idxval,&retval)
COUNT FirstRecord(filno,recptr)
ctree(FN_FRSREC,filno,recptr)
COUNT FreeSet()
ctree(FN_FRESET)
COUNT GetAlternateSequence(keyno,altseq)
ctree(FN_GETALTSEQ,keyno,altseq)
VRLEN GetDODA(datno,bufsiz,bufptr,mode)
ctree(FN_GETDODA,datno,bufptr,&bufsiz,NULL,&retval,mode)
LONG GetFileInfo(filno,mode)
ctree(FN_GETFIL,filno,NULL,&retval,NULL,NULL,mode)
LONG GetGTEKey(keyno,target,idxval)
ctree(FN_GTEKEY,keyno,target,&retval,idxval)
COUNT GetGTERecord(keyno,target,recptr)
ctree(FN_GTEREC,keyno,target,NULL,recptr)
LONG GetGTKey(keyno,target,idxval)
ctree(FN_GTKEY,keyno,target,&retval,idxval)
VRLEN GetIFile(datno,bufsiz,bufptr)
ctree(FN_GETIFIL,datno,bufptr,&bufsiz,NULL,&retval)
LONG GetKey(keyno,target)
ctree(FN_EQLKEY,keyno,target,&retval)
LONG GetLTEKey(keyno,target,idxval)
ctree(FN_LTEKEY,keyno,target,&retval,idxval)
COUNT GetLTERecord(keyno,target,recptr)
ctree(FN_LTEREC,keyno,target,NULL,recptr)
LONG GetLTKey(keyno,target,idxval)
ctree(FN_LTKEY,keyno,target,&retval,idxval)
COUNT GetRecord(keyno,target,recptr)
www.faircom.com
All Rights Reserved
228
ctree(FN_EQLREC,keyno,target,NULL,recptr)
LONG GetCtResource(datno,resptr,bufptr,bufsiz,resmode)
ctree(FN_GETRES,datno,resptr,&retval,bufptr,&bufsiz,resmode)
LONG GetSerialNbr(datno)
ctree(FN_SERIALNUM,datno,NULL,&retval)
COUNT GetSymbolicNames(filno,nambuf,buflen,mode)
ctree(FN_GETNAM,filno,nambuf,NULL,NULL,&buflen,mode)
COUNT GetTempCtFileName(bufptr,bufsiz)
ctree(FN_TMPNAME,0,bufptr,NULL,NULL,&bufsiz)
COUNT InitISAM(bufs,fils,sect)
COUNT InitISAMXtd(bufs,fils,sect,dbufs,userprof,userid,userword,servname)
ctree(FN_INTISAM,0,&logonblk)
COUNT InitCTree(bufs,fils,sect)
COUNT InitCTreeXtd(bufs,fils,sect,dbufs,userprof,userid,userword,servname)
ctree(FN_INTREE,0,&logonblk)
logonblk is defined above under the discussion of the Logon Block found in CTPARM.H.
LONG KeyAtPercentile(keyno,idxval,fractal)
ctree(FN_FRCKEY,keyno,idxval,&retval,NULL,NULL,fractal)
COUNT LastInSet(keyno,target,recptr,siglen)
ctree(FN_LSTSET,keyno,target,NULL,recptr,NULL,siglen)
LONG LastKey(keyno,idxval)
ctree(FN_LSTKEY,keyno,idxval,&retval)
COUNT LastRecord(filno,recptr)
ctree(FN_LSTREC,filno,recptr)
COUNT LoadKey(keyno,target,recbyt,typadd)
ctree(FN_LOADKEY,keyno,target,&recbyt,NULL,NULL,typadd)
COUNT LockISAM(lokmod)
ctree(FN_LKISAM,lokmod)
COUNT LockCtData(datno,lokmod,recbyt)
ctree(FN_LOKREC,datno,NULL,&recbyt,NULL,NULL,lokmod)
LONG NbrOfKeyEntries(keyno)
ctree(FN_IDXENT,keyno,NULL,&retval)
LONG NbrOfRecords(datno)
ctree(FN_DATENT,datno,NULL,&retval)
LONG NewData(datno)
ctree(FN_NEWREC,datno,NULL,&retval)
LONG NewVData(datno,varlen)
ctree(FN_NEWVREC,datno,NULL,&retval,NULL,&varlen)
COUNT NextInSet(keyno,recptr)
ctree(FN_NXTSET,keyno,recptr)
LONG NextKey(keyno,idxval)
ctree(FN_NXTKEY,keyno,idxval,&retval)
www.faircom.com
All Rights Reserved
229
COUNT NextRecord(filno,recptr)
ctree(FN_NXTREC,filno,recptr)
COUNT OpenCtFile(filno,filnam,filmod)
COUNT OpenCtFileXtd(filno,filnam,filmod,fileword)
ctree(FN_OPNFIL,filno,&openblk)
COUNT OpenFileWithResource(filno,filnam,filmod)
COUNT OpenFileWithResourceXtd(filno,filnam,filmod,fileword)
ctree(FN_OPNRFIL,filno,&openblk,&retval)
openblk is defined above under the discussion of the Open Block found in CTPARM.H.
COUNT OpenIFile(ifilptr)
COUNT OpenIFileXtd(ifilptr,dataextn,indxextn,fileword)
ctree(FN_OPNIFIL,0,&ifilblk)
COUNT OpenISAM(filnam)
COUNT OpenISAMXtd(filnam,userprof,userid,userword,servname,
fileword)
ctree(FN_OPNISAM,0,&isamblk)
COUNT PermIIndex(ifilptr)
ctree(FN_PRMIIDX,0,&ifilblk)
COUNT PositionSet(keyno,recptr,siglen)
ctree(FN_MIDSET,keyno,recptr,NULL,NULL,NULL,siglen)
LONG PreviousKey(keyno,idxval)
ctree(FN_PRVKEY,keyno,idxval,&retval)
COUNT PreviousInSet(keyno,recptr)
ctree(FN_PRVSET,keyno,recptr)
COUNT PreviousRecord(filno,recptr)
ctree(FN_PRVREC,filno,recptr)
COUNT PutDODA(datno,doda,numfld)
ctree(FN_PUTDODA,datno,doda,NULL,NULL,NULL,numfld)
COUNT ReadData(datno,recbyt,recptr)
ctree(FN_REDREC,datno,recptr,&recbyt)
COUNT ReadVData(datno,recbyt,recptr,bufsiz)
ctree(FN_RDVREC,datno,recptr,&recbyt,NULL,&bufsiz)
COUNT RebuildIFile(ifilptr)
COUNT RebuildIFileXtd(ifilptr)
ctree(FN_RBLIFIL,0,&ifilblk)
COUNT ReleaseData(datno,recbyt)
ctree(FN_RETREC,datno,NULL,&recbyt)
COUNT ReleaseVData(datno,recbyt)
ctree(FN_RETVREC,datno,NULL,&recbyt)
COUNT ReReadRecord(datno,recptr)
ctree(FN_RRDREC,datno,recptr)
COUNT ReReadVRecord(datno,recptr,bufsiz)
ctree(FN_REDVREC,datno,recptr,NULL,NULL,&bufsiz)
COUNT ResetRecord(datno,mode)
www.faircom.com
All Rights Reserved
230
ctree(FN_UPDCURI,datno,NULL,NULL,NULL,NULL,mode)
COUNT RestoreSavePoingTRANRST(savpnt)
ctree(FN_TRANRST,savpnt)
COUNT ReWriteRecord(datno,recptr)
ctree(FN_RWTREC,datno,recptr)
COUNT ReWriteVRecord(datno,recptr,varlen)
ctree(FN_RWTVREC,datno,recptr,NULL,NULL,&varlen)
COUNT SetAlternateSequence(keyno,altseq)
ctree(FN_SETALTSEQ,keyno,altseq)
COUNT SetRecord(datno,recbyt,recptr,datlen)
ctree(FN_SETCURI,datno,recptr,&recbyt,NULL,&datlen)
COUNT SetSavePoint()
ctree(FN_TRANSAV,0,&retval2)
retval2 is a short integer in which the save point number is returned.
COUNT SetVariableBytes(filno,pvbyte)
ctree(FN_SETVARBYTS,filno,pvbyte)
COUNT StopUser()
ctree(FN_STPUSR)
COUNT TempIIndex(ifilptr)
ctree(FN_TMPIIDX,0,&ifilblk)
pTEXT TransformKey(keyno,tarptr)
ctree(FN_TFRMKEY,keyno,tarptr)
COUNT UpdateFileMode(filno,filmod)
ctree(FN_PUTFIL,filno,NULL,NULL,NULL,NULL,filmod)
COUNT UpdateCtResource(datno,resptr,varlen)
ctree(FN_UPDRES,datno,resptr,NULL,NULL,&varlen)
VRLEN VDataLength(datno,recbyt)
ctree(FN_GTVLEN,datno,NULL,&recbyt,NULL,&retval)
VRLEN VRecordLength(datno)
ctree(FN_GETVLEN,datno,NULL,NULL,NULL,&retval)
COUNT WriteData(datno,recbyt,recptr)
ctree(FN_WRTREC,datno,recptr,&recbyt)
COUNT WriteVData(datno,recbyt,recptr,varlen)
ctree(FN_WRTVREC,datno,recptr,&recbyt,NULL,&varlen)
www.faircom.com
All Rights Reserved
231
15. Important Technical Updates
Stay up with the latest FairCom information. The following notifications have been found to be
important considerations in many production systems. Please Contact your nearest Faircom
office if you are concerned if any of these may impact your application or have any questions.
Important Updates
 Linux File System Performance and Safety Advisory
(http://docs.faircom.com/wp/linux_change/#cover.htm)
 V11 Critical Updates (http://docs.faircom.com/doc/v11ace/#69144.htm)
 V11 Notable Compatibility Changes (http://docs.faircom.com/doc/v11ace/#63562.htm)
15.1
Highly Concurrent c-treeACE SQL Updates Involving
Floating Point Conversions
1 October 2011
Affected Builds: All c-treeACE SQL builds prior to 110914
Criteria: Highly concurrent c-treeACE SQL insertions involving floating point conversions
Indications: Unexpected KDUP_ERR (2) errors
A potential data integrity issue was identified in FairCom's internal testing that demonstrated a
potential field overwrite that could occur with highly concurrent c-treeACE SQL updates that
include a floating point conversion. Affected field types include:
NUMERIC, NUMBER, DECIMAL, MONEY, (N)CHAR, (N)VARCHAR
A remote possibility exists with multi-threaded c-treeACE SQL applications (excluding JDBC and
ADO.Net) when a floating point value (either a variable in the application using native floating
points or a FLOAT SQL type) requires conversion into an aforementioned c-treeACE SQL type.
A combination of events must take place for this overwrite to occur:
1. Floating point data needs to be assigned to one of the above types,
2. Floating point data needs to be compared with one of the above types,
3. The execution of a SQL statement operation (or function) involving floating points and one of
the above types.
Consider the case of an ODBC driver binding a MONEY column to a SQL_C_DOUBLE type.
When an insert is performed, the C type data undergoes a conversion to an SQL type. During this
conversion, there is a possibility a buffer is not protected from multi-threaded updates.
www.faircom.com
All Rights Reserved
232
Important Technical Updates
Solution: This possibility has been avoided by ensuring proper thread safe C library functions
are used on respective platforms and the buffer used for conversion is properly protected.
FairCom customers on current maintenance can request an updated V9 c-treeACE SQL line at
any time. Please contact your nearest FairCom office
(http://www.faircom.com/company#ContactUs) should you have any concerns that you are
impacted by this update.
15.2
Prevent FPUTFGET Data Corruption with Concurrent
Updates
20 January 2010
Affected Builds: All builds between 050722 through 100120
Criteria: Concurrent FPUTFGET record add/updates to variable length files.
Indications: Unexpected ITIM_ERROR (160) errors
In c-tree multi-user standalone (FPUTFGET) mode, when a process updates a record, increasing
the size of the record, while at the same time another process adds a record, and if there is
deleted space available after the record that is being updated, the update logic could reuse that
space even though the add operation has already used the space for the newly-added record.
This issue only affects the c-tree multiuser standalone mode (FPUTFGET) and does not
affect the c-tree Server.
A code change applied in July 2005 modified previously correct behavior. As a result, the logic in
RWTVREC() that reads the key from the space management index after locking the space that is
a candidate for reuse skips the call to read the key from the space management index. This
omission can cause the update to enlarge the record into space that has been reused by a record
add operation. The ITIM_ERR (160) was observed in that an index key entry pointed to an offset
in the data file that was within another record. That record had been enlarged by an update
operation, and it overwrote a record that was added at the same time the record was updated. A
simple rearrangement of code prevents this behavior.
FairCom customers on current maintenance can request an updated V9 c-treeACE line at any
time. Please contact your nearest FairCom office (http://www.faircom.com/company#ContactUs)
should you have any concerns that you are impacted by this update.
15.3
Potential Variable Length Data Corruption Prevented
During Automatic Recovery
5 October 2009
Affected Builds: All builds prior to 091005
Criteria: Variable Length Files under Transaction Control that have Undergone Automatic
Recovery After a Failed Server Process
Indications: Error 37 during recovery and/or evidence of data or index corruption
www.faircom.com
All Rights Reserved
233
Sometime after automatic recovery on a system where the c-treeACE Server had previously gone
through the process of automatic recovery, data and index files were found to contain unexpected
10-byte headers beginning with 0xfbbf marks. The headers appeared at unexpected locations,
sometimes overwriting data records or index nodes, and sometimes written at the physical end of
the file, preceded by a region of 0x00 bytes.
A second observed symptom was automatic recovery failing with error 37 due to an invalid file
descriptor, as indicated by the following entries in CTSTATUS.FCS:
- User# 00002 trandat: scanning log 815
Wed Sep 23 15:44:25 2009
- User# 00002 WRITE_ERR: ???? at 0:1457a4ex sysiocod=6 bufsiz=10 bytes written=0[0] ioLoc=0: 37
Automatic recovery invalidates the space management index for variable-length data files, and it
queues entries for the space reclamation thread to process. These entries trigger the space
reclamation thread to reconstruct the space management index by physically scanning the
variable-length data files for deleted records and adding keys to the space management index for
each deleted region found in the file.
Changes to the space management index can place entries - with associated file numbers - into
the transaction log. One such entry was written to the server's preImage space, however, not
immediately written to the transaction logs. A later transaction can then commit this entry with a
transaction file number not associated with the original file, as the original file could have been
physically closed and the file number reassigned to another physical file.
Should the server then experience an abnormal failure and automatic recovery takes place, the
entry is processed from the transaction log with a transaction file number associated with the
wrong physical file. An attempt is then made to write this entry to the incorrect file causing either
data to be overwritten, or a failed write due to an invalid file descriptor.
To prevent this behavior, the transaction log entries are now written immediately and directly to
the physical transaction log ensuring a correct associated transaction file number upon recovery.
15.4
Prevent Termination of c-treeACE from LRU Cache
Miss Limitations
4 June 2009
Affected Builds: All V9 lines with build dates prior to 090602
Criteria: c-treeACE Server with DATA_LRU_LISTS or INDEX_LRU_LISTS configurations set
greater than 1
Indications: Server crash after large number of cache misses
When a c-treeACE Server is running with the configuration options DATA_LRU_LISTS or
INDEX_LRU_LISTS set greater than 1, after a large number (2^32, over 2 billion) data or index
cache misses occur, the c-tree Server terminates with an unhandled exception. These options
default to 4 in c-treeACE Version 9. Thus all c-treeACE Version 9 servers are susceptible to this
situation. You can verify these options in the server startup information found in the server status
log file, CTSTATUS.FCS.
www.faircom.com
All Rights Reserved
234
When a cache page is required to hold a page that is not already in cache and multiple data or
index LRU lists are in use, the data and index cache logic increments a variable used to calculate
which data or index LRU list is to be used . However, the variable was declared as a signed long
integer, and after 2^32 increments, became negative, resulting in a negative index offset for an
array of data/index cache LRU list mutexes. Redeclaring the variables as unsigned long integers
resolves this issue.
An immediate fix for anyone with potential to be affected by this Version 9.0 only issue is to
directly specify DATA_LRU_LISTS 1 and INDEX_LRU_LISTS 1 in the c-treeACE configuration
file (ctsrvr.cfg) to avoid this unhandled exception condition. You will need to restart your server to
enable this configuration change.
15.5
Potential c-tree Server Automatic Recovery Failures
with the LOGIDX Feature
22 May 2009
Affected Builds: All V8 and V9 lines that enabled this feature through the use of the LOGIDX file
mode withing the application or through the server configuration keyword FORCE_LOGIDX YES.
This feature was enabled by default for c-treeACE V9 Servers with build dates 080111
through 090126.
Criteria: FORCE_LOGIDX YES enabled in the c-treeACE Server configuration
Indications: Failed recovery
c-treeACE provides a feature called LOGIDX which can allow for quicker automatic recovery time
on server startup should you experience an unexpected failure (for example, a power outage).
This feature can be enabled with a file mode of LOGIDX, or using the FORCE_LOGIDX server
configuration keyword.
Extensive testing identified an isolated possibility of failure during automatic recovery when the
LOGIDX logic is active. The net effect is a possibility for failed recovery in the event the c-tree
Server was not properly shut down. This has been corrected as of V9.1 build 090522.
A simple solution to ensure you will not be impacted by this default setting is to disable the
LOGIDX feature via your server configuration file. Follow these easy steps to perform this
change:
1. Cleanly shut down your c-tree Server. (For example, use the c-tree Server Administrator
utility, ctadmn, or the c-tree Server stop utility, ctstop.)
2. Add or change the following server configuration keyword in your server configuration file,
ctsrvr.cfg:
FORCE_LOGIDX OFF
3. Restart your c-treeACE per your normal operating procedures.
www.faircom.com
All Rights Reserved
235
FairCom customers on current maintenance can request an updated V9 server line at any time.
Please contact your nearest FairCom office (http://www.faircom.com/company#ContactUs)
15.6
Avoid Index Errors Caused by memcpy()
Implementation on Latest Operating Systems
20 December 2011
The latest Linux versions, notably Redhat 6 (RHEL 6) have demonstrated a potential problem
with c-treeACE buffer management functions. The most common symptoms are ITIM_ERR errors
(160) or KDEL_ERR errors (4).
Previously, c-treeACE used a C library memcpy() function in certain buffer management areas.
However, when the source and destination buffer locations overlap, this can cause unexpected
memory corruption issues, and the latest Linux versions appear to exhibit this with greater
frequency. The memmove() function has been utilized in place of the memcpy() function to avoid
this problem. Latest versions of c-treeACE since V9.5 (builds since 110420) incorporate this
change.
In most cases, an updated server in this environment, and a quick index rebuild is all that is
needed. Existing data has been shown to be secure.
15.7
Correct Handling of Segmented Files During Automatic
Recovery
10 June 2009
Affected Builds: All builds prior to 090610
Criteria: Segmented file, Automatic recovery after a failed c-treeACE Server process
Indications: Renamed file segments
During automatic recovery of a failed c-treeACE process, existing file segments were renamed
and thus subsequently not available to the application resulting in apparent missing data. During
recovery, an attempt is made to open all segments of a segmented file found in the transaction
logs. To open the segments, the segment definition resource must be read from the primary
segment. However, an internal file map attribute had not been initialized resulting in a failed call.
This failed call caused the recovery process to believe the additional segments did not exist.
When later attempting to create the file segment, and that segment already existed, c-treeACE
then renamed the segment. The uninitialized attributes are now properly assigned avoiding this
potential incorrect renaming of segmented files.
www.faircom.com
All Rights Reserved
236
15.8
Microsoft Vista Locks Out FPUTFGET
Two independent issues affect FairCom's multi-user standalone operational model (FPUTFGET)
which relies on the underlying operating system to ensure file locking integrity. This contrasts with
FairCom's server-based models where locking is independently and solely maintained by the
c-tree Server. These issues manifest in either of the following scenarios:
1. In environments where all machines accessing the data are using Windows Vista, it is
possible for one c-tree Plus FPUTFGET application to “hang” when obtaining the record lock
already owned by another FPUTFGET process. This impacts database files from many
vendors and a patch from Microsoft is available.
2. In mixed OS environments (Windows XP with Vista for example) indexes can become out of
sync resulting in ITIM_ERR (160) errors or even data corruption. This impacts versions of
c-tree Plus V7 and V8 prior to V8.27 Build 071005 with HUGE files enabled, which is the
default in V8.14 and later. This can also occur when using the c-tree Plus ODBC Driver in
read/write mode and the FPUTFGET model of operation.
Applications using the c-tree Server and c-treeSQL Server are not impacted by these
issues.
Testing your FPUTFGET Application
It is easy to test your c-tree Plus FPUTFGET application for this behavior. The c-tree Plus
example program, ctixmg, provides an easy-to-use application allowing for a simple controlled
test. This example is built when you include samples in your c-tree Plus mtree build.
1. Build ctixmg choosing the multiuser standalone (FPUTFGET) c-tree Plus model.
2. Start two ctixmg instances on two different machines. (Vista to Vista or Vista to XP for
example)
3. B)egin Locking from the first instance of ctixmg.
4. A)dd a record from the first instance of ctixmg and do not E)nd Locking.
5. B)egin Locking on the second instance of ctixmg.
6. Attempt to U)pdate the same record as added in Step 4 from the second instance of ctixmg.
You should receive a DLOK_ERR error (42) from the second instance indicating that the
expected and appropriate locking has taken place. If your application hangs (Vista to Vista), or
the Update succeeds (Vista to XP), then you may require the Windows Vista hotfix and/or a c-tree
Plus update.
What if I am affected?
All FairCom maintenance customers in good standing have been notified of this serious matter. A
c-tree Plus update is available. Now is also a great time to consider FairCom's c-tree Server
technology which does not rely on the operating system to manage locking. With only a few
simple changes, you can be up and running with enhanced speed, performance, huge data
caching, dynamic backups, and the security of knowing your data is intact and secured!
Contact your nearest FairCom office should you have any questions or believe you are impacted
by this potentially serious issue.
www.faircom.com
All Rights Reserved
237
15.9
Transaction Number Rollover
Six-byte transaction numbers allow you to take advantage of a vast volume of available numbers
to greatly increase the life span of your active c-tree data files.
Some transaction-intensive applications using older versions of c-tree have experienced
exhausting these numbers. With faster and faster hardware, and greater volumes than ever, there
are good reasons to migrate to the latest version of c-treeACE Server.
Consider a moderately high volume application with 1000 transactions per second:
Transaction Number Limits
 V6 supports around 1 billion transactions: 1000 tps for ~11.6 days.
 V8 supports 70 x 1012: 1000 tps for ~2000 years.
FairCom has created a comprehensive white paper describing this limitation of four byte
transaction numbers, how to recover when you exhaust your supply of numbers, and how to
convert and take advantage of six byte transaction number support. Download this valuable
resource today! Six Byte Transaction Number Support
http://docs.faircom.com/pdf/6byte_trans.pdf
Contact FairCom http://www.faircom.com/company#ContactUs and put the latest version of
c-treeACE in action today!
Migrate to 6-Byte Transaction #’s in 5 Easy Steps
1. Relink all client applications with c-tree Plus V8 libraries.
2. Install a new c-tree V8 Server or newer using recommended practices.
3. Ensure ALL c-tree Server Transaction Logs (*.FCS) are removed.
Warning: You will lose all User IDs and passwords when FAIRCOM.FCS is deleted. These
can be recreated with the c-tree Server Administration utility, ctadmn.
4. Ensure all data files have an extended header which allows huge file and six byte transaction
numbers. V6 c-tree Plus data files may be converted using the c-tree Plus Conversion utility,
ctcv67. Be sure to observe the note below concerning this standalone application.
5. After starting the new c-tree Server, ensure ALL indices are rebuilt using the c-tree Server.
Remember, existing indexes that have not had an appropriate extended header added will be
rebuilt with the old four byte number support.
Note: You can use rebuild and other standalone programs linked with c-tree V8 as a single-user
library, however be sure the 6 byte transaction number is activated with #define ctFeat6BT in
your ctoptn.h file. It is off by default in this operational model.
www.faircom.com
All Rights Reserved
238
16. Upgrading from Previous Editions
16.1
Steps to Upgrade c-treeACE Server
While FairCom always attempts to maintain backward compatibility whenever possible,
transaction logs from earlier versions are generally not always compatible with newer c-treeACE
Server formats. For example, c-treeACE V9 introduced a change in the transaction log format to
accommodate new capabilities.
Note: Unless otherwise mentioned in the version-specific Update Guides, existing data and index
files are usually not affected by transaction log changes.
Removing Transaction Logs and Upgrading c-treeACE Server
The c-treeACE Server process makes it easy to upgrade c-treeACE Server using your existing
files, as long as you remove prior transaction logs in a safe manner. The step shown below are
appropriate any time you are upgrading c-treeACE Server. Notice that you will shut down your
c-treeACE Server two times during this process (steps 2 and 5) to allow all files to be brought to a
consistent state.
1. Have all clients cleanly exit from the existing your c-treeACE Server.
2. Perform a normal controlled shutdown of the c-treeACE Server using one of the methods
described here, depending upon your installation:
• Server Console Window - From the c-tree Server console window click “Control” and then
click “Shutdown the c-tree(SQL) Server”
• Windows Toolbar - Right-click the c-tree Server icon in the Windows Tooltray and choose
“ShutDown the c-tree Server”
• Windows Service - From the Windows Control Panel, choose “Administrative Tools”, then
choose “Services”. Locate the FairCom c-tree Server in the list of services running on
your machine. Right-click the c-tree Service and choose “Stop”.
• Use the client command line utility, ctadmn, and follow the prompts.
• Use the client command line utility, ctstop.
Remember that the Administrator user ID is "admin" (case insensitive) and the default
password is "ADMIN" (case sensitive). The default c-tree Server name is "FAIRCOMS".
3. Block the ability of any clients to attach to the c-treeACE Server.
4. Restart the existing c-treeACE Server with no clients attached and allow a successful
automatic recovery to take place. This ensures all files are brought to a consistent state in the
event there is any data remaining in the transaction logs.
5. Perform another normal controlled shutdown of the c-treeACE Server (as described
earlier).
6. Remove all existing transaction logs and associated files (L*.FCS, S*.FCS, D*.FCS and
I*.FCS).
www.faircom.com
All Rights Reserved
239
Upgrading from Previous Editions
7. Copy your new c-treeACE executable (ctsrvr.exe or ctreesql.exe) into the existing c-tree
Server directory.
Note: Client compatibility can prevent connections to the new c-treeACE database engine.
It is always advised to use the most recent matching client version with your c-treeACE
server version. Versions 9 and 10 have both introduced backward compatibility changes.
8. Unblock the ability of any clients to attach.
9. Start c-treeACE in your usual manner and begin using your existing data.
FairCom has added logic to c-treeACE to notify you when transaction logs may be incompatible.
Please review the section "Detection of Transaction Log Incompatibilities" in the c-treeACE
Server Administrator’s Guide (http://docs.faircom.com/doc/ctserver/) for details.
Upgrade Notes for Developers
This information is intended as a quick reference to demonstrate how easy it is to move from
previous versions of c-tree database technology to the latest c-treeACE. Because c-treeACE is a
flexible tool that has enjoyed great longevity, it is impossible to anticipate every situation that will
be encountered when upgrading. As always, our outstanding engineering team is ready to assist
at every opportunity. Feel free to contact your nearest FairCom office
(http://www.faircom.com/company#ContactUs) for advice and guidance before migrating your
application. We have helped successfully migrate many original c-tree applications to our very
latest versions, sometimes within minutes.
The following sections provide notes about upgrading from previous releases:
V10 Changes
A few notes about the V10 changes:
 c-treeACE V10.0 brings about major security updates and as such, all prior client/server
connectivity is now incompatible. Note that this impacts previous c-tree Plus ODBC drivers.
See V10 Client/Server Compatibility http://docs.faircom.com/doc/v10ace/58667.htm.
 The SERVER_DIRECTORY keyword is now deprecated in favor of LOCAL_DIRECTORY. See
SERVER_DIRECTORY Deprecated http://docs.faircom.com/doc/v10ace/55521.htm.
 Check the Compatibility section of the V10 Update Guide for other minor release changes.
See V10 Compatibility Notes http://docs.faircom.com/doc/v10ace/55499.htm.
Existing V9 Users
c-treeACE V9 introduces several minor compatibility issues of its own that you should be aware
of when moving forward:
 Extended headers now included by default on all new files created by c-treeACE.
 Commit Read Lock support (http://docs.faircom.com/doc/v9ace/48646.htm) is default and
requires record locks on any update.
 Files created by c-treeACE SQL are HUGE by default
(http://docs.faircom.com/doc/v9ace/48573.htm).
www.faircom.com
All Rights Reserved
240
Existing V8 Users
V8 introduced Memory Files, Queues and Notification, and performance monitoring tools.
 Cleanly shut down any existing V8 Servers and remove remaining transaction logs.
(/ace/product_upgradesteps_t.phpSteps for a Clean Upgrade) V9 introduces a new
transaction log format.
 Store a copy of the V8 dynamic dump restore utility (ctrdmp) with any remaining backup files
in case of future recovery. Consider validating a fresh V9 dump and restore and review your
backup procedures at this time.
Existing V7 Users
V7 introduced HUGE, segmented and partitioned file support, and many new cache options for
performance. V7.12 increased the PAGE_SIZE default from 2048 bytes to 8192 bytes. Keep this
in mind with indexes from previous versions, as the page size is used as the index node size.
Existing V6 Users
V6 introduced updated c-tree Plus file format with extended headers for advanced feature
support.
 Convert your existing V6 data files with the ctcv67 conversion utility
(http://docs.faircom.com/doc/ctreeplus/31078.htm). This utility converts existing c-tree Plus
data files to the extended format introduced in V7. Extended header support offers HUGE file
support and segmented files.
 Use the Xtd8 file creation functions to create new Extended files.
 For data files supporting HUGE file support, remember to update your duplicate index keys in
the IFIL definitions to include an additional 4 bytes for the associated record position.
 Note that the ctreep.h header file automatically includes the ctv6v7.h header.
Existing V4 Users
(V4.1F-V4.3C)
Existing c-tree V4 files require conversion to the updated c-treeACE format. The following steps
outline this process.
 Make a BACKUP of ALL OF YOUR FILES before you begin!
www.faircom.com
All Rights Reserved
241
 Convert your existing data files with the ctcv43 file conversion utility
(http://docs.faircom.com/doc/ctreeplus/31077.htm) and set these converted files aside.
 Use the ctexmc parameter file create utility
(http://docs.faircom.com/doc/ctreeplus/31080.htm) to create empty data and index files from
your existing parameter files. (We do this as the IFIL conversion will require a valid index file
to be in place, even if empty.)
 Copy in your newly converted data files overwriting the empty data files just created by
ctexmc. (Leave the new empty index files in place.)
 Convert your existing parameter files to IFIL structures with ctptoi parameter conversion
utility (http://docs.faircom.com/doc/ctreeplus/31091.htm). This utility will place an IFIL
structure directly into the converted data files.
 Rebuild your index files with the ctrbldif rebuild utility
(http://docs.faircom.com/doc/ctreeplus/31093.htm).
 (Optional) Stamp a DODA structure (data schema) based on the ‘C’ structure definitions into
your data file with the c-treeACE PutDODA() API call. The DODA makes available many
higher level interfaces such as ODBC, c-treeDB, .NET and c-treeACE SQL.
 Include the single c-treeACE ctreep.h header file in your application to replace the previous
numerous c-tree headers:
#include "ctreep.h"
Upgrade Notes for Administrators
This section highlights a few notes about upgrading from previous versions of c-tree database
technology to the latest c-treeACE.
GUI Tools
c-treeACE includes a robust set of tools that feature a graphical user interface (GUI). These tools
are useful to administrators as well as developers.
Some versions of c-treeACE (e.g., V11) include updates to the SQL engine. This may pose
compatibility issues if you attempt to use the new tools with an older c-treeACE server. We do not
recommend connecting new tools to older servers.
Transaction Logs
When upgrading it is advisable to start with new versions of the transaction logs because log
formats can change between releases. See Steps to Upgrade c-treeACE (page 239,
http://docs.faircom.com/doc/knowledgebase/#product_upgradesteps.htm) for information about
removing the old logs so you can start fresh with your new version of c-treeACE.
www.faircom.com
All Rights Reserved
242
More about Upgrading c-treeACE
The same core database technology found in prior c-tree releases powers c-treeACE. With an
emphasis on ease of use and unfettered development, c-treeACE is the same core engine you've
come to depend and rely upon for many years in your existing and successful applications.
There are many ways to move forward with c-treeACE technology from existing applications and
previous versions of c-tree. See which pathway best fits your situation and see how easy it is to
begin using c-treeACE. As c-tree database technology is extremely flexible and has been
deployed in a huge number of diverse applications, there may be subtle issues unique to any
upgrade.
Please don't hesitate to contact your nearest FairCom office
(http://www.faircom.com/company#ContactUs) for assistance. Our experienced engineering team
is always willing to assist in any way possible.
Are you an existing c-tree Server developer?
 Link your existing application to the c-treeACE multithreaded library, mtclient.lib, included in
the /lib directory of your installation.
 Copy or move your existing data and index files to the working directory of the c-treeACE
server area in /bin/ace/isam or /bin/ace/sql. You could also consider the LOCAL_DIRECTORY
configuration keyword to point c-treeACE to your existing data location. Be aware that you
will need to remove existing transaction log files as previous versions of these files are
incompatible with c-treeACE. Follow the steps in this section to ensure a clean start with
c-treeACE.
 Continue using your existing application!
Are you an existing c-tree Plus Standalone developer?
c-treeACE Express is a client-server only package. In many cases, you can easily make your
existing data work with the c-treeACE server and gain all of the benefits of c-treeACE technology.
Dynamic backups, advanced caching, and SNAPSHOT statistics monitoring are just a few of the
great features available with the c-treeACE server engine. To begin using this technology in your
application follow these simple steps:
 Link your existing application to the c-treeACE V9 multithreaded library, mtclient.lib.
 Copy or move your existing data and index files to the working directory of c-treeACE. You
could also consider the LOCAL_DIRECTORY configuration keyword to point c-treeACE to your
existing data location. Be aware that you will need to remove existing transaction log files as
previous versions of these files are incompatible with c-treeACE. Follow the steps in this
section to ensure a clean start with c-treeACE.
 Rebuild indexes to take advantage of larger page sizes. Standalone models default to a 2048
byte index node size, while c-treeACE Servers since V8.14 default to 8192 bytes. Increasing
this allows more keys per node, as well as larger keys, that frequently arise when creating
complex indexes via SQL.
 Switch your initialization to InitISAMXtd() and add the client user name and password to
access the server. Use the Xtd() Function API calls that allow the user credentials and server
name to be specified. You can include these in your standalone builds, as they are simply
ignored in those models.
www.faircom.com
All Rights Reserved
243
 Consider multithreading your application for enhanced scalability and performance.
 Access the power of c-treeACE in your application immediately.
Do you wish to use existing c-tree Plus data with c-treeACE SQL?
 Ensure your data is compatible with c-treeACE SQL. c-treeACE SQL requires proper DODA
and IFIL structures to be present. Use the c-tree Information utility, ctinfo, included with both
c-treeACE PRO and Express to check for the presence of these required resources.
 Use the c-tree SQL Import utility, ctsqlimp, to import your existing data and indexes to
c-treeACE SQL. The following topic, Let Your Existing ISAM Applications Co-Exist With
c-treeSQL (page 244), provides the steps needed for this data access addition.
 Begin using any c-treeACE SQL interface technology with your existing c-tree data!
Let Your Existing ISAM Applications Co-Exist With c-treeSQL
c-treeSQL has been designed from its core to provide as much access as possible to all existing
c-tree Plus data. For most applications, it is as simple as linking the data to the c-treeSQL Server
system tables using the c-treeSQL Table Import Utility, ctsqlimp. Not only does this give you the
ability to view and modify your tables with c-treeSQL, you also retain the ability to continue using
your existing application!
 Advantages: No changes are made to the data and index file definitions, so the existing
c-tree application can access the data without changes to the application.
 Considerations: Some higher-level SQL capabilities that require special internal fields,
indexes, and file modes will not be supported unless the files and applications are adjusted to
provide these requirements.
Example ISAM Application with Proper c-treeSQL Constructs
/* -------------------------------------------------------------------------ISAM to SQL Tutorial
The goal of this tutorial is to introduce the most basic c-tree Plus
ISAM API to accomplish creating and manipulating a table through the
c-tree Server.
From a functional point of view this application will perform the following:
1. Logon onto a session
2. Add 1 table with some fields
3. Populate the table with a few records
4. Display the contents of the table
Once this table has been built, it is also ready to use in c-treeSQL.
Use the c-treeSQL Import Utility, ctsqlimp, to link the table to
your c-treeSQL Server. You will then be able to query your data
through c-treeSQL statements!
This example creates and stores a UUID value for a list of names, and
stores them in a c-tree Plus data file. Several concepts are
demonstrated.
1. How to build an ISAM table compatible with c-treeSQL.
www.faircom.com
All Rights Reserved
244
2. How to create and store a universally unique identifier
(UUID) with c-tree.
3. How to properly construct and use a CT_ARRAY field
for later import to c-treeSQL.
The table consists of 3 fields, a 'pad' field, a GUID field, and
a name field. In this example, the GUID field demonstrates how to
properly use a CT_ARRAY field as a c-treeSQL BINARY field. Notice
in particular, the added four byte length header to the field. While
this value is transparent to the c-treeSQL user, it is imperative
that this header be properly constructed with the correct value to
be imported into c-treeSQL.
-------------------------------------------------------------------------- */
/** Preprocessor definitions and includes **/
#include <stdio.h>
#include <string.h>
#include "ctreep.h "/* All necessary c-tree Plus headers */
#define END_OF_FILE INOT_ERR
/** Global declarations **/
/* Data File Number */
COUNT guid_no;
ISEG guid_seg = {
12,16,INTSEG
};
IIDX guid_idx = {
16, /* Length of index */
0, /* key type */
0, /* Dup Flag */
1, /* NULL key flag */
0, /* Empty Char */
1, /* Number of segments */
&guid_seg, /* Pointer to Segment Array */
NULL, /* Index Name */
NULL, /* Optional Index Name */
NULL, /* Alternate Collating Sequence */
NULL /* Option pointer to pad byte */
};
/* IFIL Definitions */
IFIL guid_dat = {
"GUID8", /* data file name ("dat" is always assumed)*/
-1, /* data file number */
52, /* data record length */
8192, /* data extension size */
ctSHARED, /* data file mode */
1, /* number of indices */
8192, /* index extension size */
ctSHARED, /* index file mode */
&guid_idx, /* pointer to index array */
"Delflag", /* pointer to first field name (r-tree) */
"Buffer" /* pointer to last field name (r-tree) */
};
/* Xtd8 File Definitions - we will use HUGE files in this example */
www.faircom.com
All Rights Reserved
245
XCREblk xcreblk[2] = {
{ ctFILEPOS8 , 0, 0, 0, 0, 1048576},
{ ctFILEPOS8 , 0, 0, 0, 0, 1048576}
};
/* Data Record Definitions */
DATOBJ doda[] = {
{"pad",NULL,CT_FSTRING,8},
{"uuid",NULL,CT_ARRAY,20},
{"name",NULL,CT_FSTRING,24}
};
/* Names for records */
COUNT name_count = 6;
typedef struct {
TEXT *name;
} name_text;
name_text name_list[]= {
(pTEXT) "Craig",
(pTEXT) "Ray",
(pTEXT) "Jeff",
(pTEXT) "Jon",
(pTEXT) "Randal",
(pTEXT) "Marco"
};
/** Function declarations **/
#ifdef PROTOTYPE
VOID initialize(void), define(void), manage(void), done(void);
VOID Add_Records(void), Display_Records(void), Delete_Records(void);
VOID doError(TEXT *);
#else
VOID initialize(), define(), manage(), done();
VOID Add_Records(), Display_Records(), Delete_Records();
VOID doError();
#endif
/************************************************************************
* main() - The main() function implements the concept of *
* "Init, define, manage and you're done..." *
* *
************************************************************************/
#ifdef PROTOTYPE
NINT main (NINT argc, pTEXT argv[])
#else
NINT main (argc, argv)
NINT argc;
pTEXT argv[];
#endif
{
initialize();
define();
manage();
done();
getchar();
exit(0);
}
www.faircom.com
All Rights Reserved
246
/************************************************************************
* initialize() - Perform the minimum requirement of logging onto *
* the c-tree Server *
* *
************************************************************************/
#ifdef PROTOTYPE
VOID initialize(VOID)
#else
VOID initialize()
#endif
{
COUNT retval=0;
#ifdef ctThrds
NINT trc;
#endif
ctrt_printf("INIT\n");
/* Initialize c-tree Plus and log on to Server */
ctrt_printf("\tLogon to Session...\n");
#ifdef ctThrds
if (trc = ctThrdInit(3, 0L, NULL))
{
ctrt_printf("\nERROR-> initialize(): ctThrdInit() \n");
ctrt_printf("\nerror = %d\n", trc);
ctrt_printf("*** Execution aborted *** \nPress Enter key to exit...");
getchar();
exit(0);
}
#endif
if (retval = InitISAMXtd(16, 16, 16, 16, 0, "ADMIN", "ADMIN", "FAIRCOMS"))
doError("initialize(): InitISAMXtd()");
}
/************************************************************************
* define() - Open the data file, if it exists, otherwise create and *
* re-Open the table. *
* *
************************************************************************/
#ifdef PROTOTYPE
VOID define(VOID)
#else
VOID define()
#endif
{
ctrt_printf("DEFINE\n");
/** Open data file **/
ctrt_printf("\tOpen Data File...\n");
if (OpenIFile(&guid_dat))
{
/** Create Data File **/
if (CreateIFileXtd8(&guid_dat, NULL, NULL, 0, NULL, NULL, xcreblk))
doError("define(); CreateIFileXtd8()");
www.faircom.com
All Rights Reserved
247
guid_no = guid_dat.tfilno;
if (PutDODA(guid_no, doda, (UCOUNT) 3))
doError("define(); PutDODA 8()");
CloseIFile(&guid_dat);
doError("define(); Re-OpenIFileXtd8()");
}
}
/************************************************************************
* manage() - This function performs simple record functions of add, *
* delete, and gets *
* *
************************************************************************/
#ifdef PROTOTYPE
VOID manage(VOID)
#else
VOID manage()
#endif
{
ctrt_printf("MANAGE\n");
Delete_Records(); /* delete any existing records */
Add_Records(); /* populate the table with data */
Display_Records(); /* show contents of table */
}
/************************************************************************
* Add_Records() - This function adds records to a table in the *
* database from a static structure called *
* RECORD_DATA *
* *
************************************************************************/
#ifdef PROTOTYPE
VOID Add_Records(VOID)
#else
VOID Add_Records()
#endif
{
VRLEN offset;
TEXT inpbuf[256];
TEXT name_buf[24];
long length = 16;
COUNT i = 0;
#ifdef WIN32
GUID new_uuid;
#else
uuid_t new_uuid;
www.faircom.com
All Rights Reserved
248
#endif
ctrt_printf("\tAdd Records...\n");
/* Add records to table */
for (i=0;i<name_count;i++) {
ctsfill(inpbuf, 0, 256);
ctsfill(name_buf, 0, 24);
strcpy(name_buf, name_list[i].name);
offset = 0;
/* Copy in the first position */
cpybuf(inpbuf, name_buf, 8);
offset += 8;
/* Create a new UUID */
#ifdef WIN32
CoCreateGuid(&new_uuid);
#else
uuid_generate (&new_uuid); */
#endif
cpybuf(inpbuf+offset, &length, 4);
offset += 4;
/* Copy the new UUID into the record buffer */
cpybuf(inpbuf+offset, &new_uuid, sizeof(new_uuid));
offset += sizeof(new_uuid);
/* Copy a name into the record buffer */
cpybuf(inpbuf+offset, name_buf, 24);
/** Add the record **/
if (AddRecord(guid_no, inpbuf))
doError("Add_Records(): AddVRecord()");
} /* End of for loop */
}
/************************************************************************
* Display_Records() - This function displays the contents of a table. *
* FirstRecord(), ctdbNextRecord() fetches a *
* record. Then each field is parsed and displayed. *
* *
************************************************************************/
#ifdef PROTOTYPE
VOID Display_Records(VOID)
#else
VOID Display_Records()
#endif
{
char sName[128];
unsigned char sUUID[16];
unsigned char buffer[256];
COUNT RetVal = 0;
www.faircom.com
All Rights Reserved
249
int i = 0;
int j = 0;
unsigned char buf[40];
ctrt_printf("\tDisplay Records...");
ctsfill(&buffer,0,256);
ctsfill(&sName,0,128);
ctsfill(&sUUID,0,16);
/* Read the first record */
if (FirstRecord(guid_no, &buffer))
doError("Display_Records(): ctdbFirstRecord()");
while (!RetVal)
{
/* Copy the UUID field from the buffer. */
cpybuf(sUUID, buffer+12, 16);
/* Copy the name field from the buffer */
cpybuf(sName, buffer+28, 24);
/* Convert the UUID field to Windows GUID format */
memset(buf, 0, 40);
for( i=0,j=0; i<sizeof(uuid_t); i++ ) {
sprintf( buf+j, "%02X", sUUID[i] );
j += 2;
if( (i==3) || (i==5) || (i==7) || (i==9) ) {
*(buf+j) = '-';
++j;
}
}
strcat(buf, "");
/* print out the record contents */
printf("\n%s\tis associated with GUID of %s\n", sName, buf);
/* Read the next record */
RetVal = NextRecord(guid_no, &buffer);
if (RetVal == END_OF_FILE)
break; /* Last Record */
if (RetVal)
doError("Display_Records(): NextVRecord()");
}
}
/************************************************************************
* done() - This function handles the housekeeping of closing tables *
* and the freeing of associated memory. *
* *
************************************************************************/
#ifdef PROTOTYPE
VOID done(VOID)
#else
VOID done()
#endif
{
www.faircom.com
All Rights Reserved
250
ctrt_printf("DONE\n");
/* Close data file (optional) */
ctrt_printf("\tClose table...\n");
if (CloseIFile(&guid_dat))
doError("done(): CloseIFile()");
/* Logout of session and free memory */
ctrt_printf("\tLogout...\n");
CloseISAM();
#ifdef ctThrds
ctThrdTerm();
#endif
}
/************************************************************************
* Delete_Records() - This function deletes records in a data file. *
* *
************************************************************************/
#ifdef PROTOTYPE
VOID Delete_Records(VOID)
#else
VOID Delete_Records()
#endif
{
COUNT RetVal;
NINT bRecSetEmpty;
TEXT inpbuf[256];
VRLEN len;
len = 256;
bRecSetEmpty = 0;
ctrt_printf("\n\tDelete records...\n\n");
if ((RetVal = FirstRecord(guid_no, &inpbuf)) != NO_ERROR)
{
bRecSetEmpty = 1;
else
doError("Delete_Records(): FirstVRecord()");
}
while (!bRecSetEmpty) /* delete til table empty */
{
if ((RetVal = DeleteRecord(guid_no)) != NO_ERROR)
doError("Delete_Records(): DeleteVRecord()");
len = 256;
if ((RetVal = NextRecord(guid_no, &inpbuf)) != NO_ERROR)
{
bRecSetEmpty = 1;
else
doError("Delete_Records(): NextVRecord()");
}
www.faircom.com
All Rights Reserved
251
}
}
/************************************************************************
* doError() - This function is a common bailout routine. It displays *
* an error message allowing the user to acknowledge before *
* terminating the application *
* *
************************************************************************/
#ifdef PROTOTYPE
VOID doError(TEXT mesg[])
#else
VOID doError(mesg)
TEXT mesg[];
#endif
{
ctrt_printf("\nERROR-> %s \n", mesg);
ctrt_printf("\nisam_err = %d, isam_fil = %d, sysiocod = %d\n", isam_err, isam_fil, sysiocod);
getchar();
exit(0);
}
Table Definition Requirements
To take advantage of the ability to co-exist with c-treeSQL, certain requirements must be met to
ensure compatibility.
 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- treeSQL.
 An ISAM application must use corresponding c-tree Plus data types (as defined in the DODA)
as in the c-tree Plus - SQL data type mapping. For example a CT_CHAR field type is used in
c-treeSQL 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-treeSQL, including the c-treeSQL
ODBC Driver.
CT_ARRAY fields are imported by default as a c-treeSQL Binary field. c-treeSQL expects the
first four bytes of a binary field to specify the length of the field. When you create a table with
c- treeSQL these four bytes are automatically created and maintained for you. When
considering a CT_ARRAY field from c- tree Plus, you must explicitly include these four prefix
bytes and assign the appropriate value. An example of how to properly handle this field is
demonstrated in the example code at the end of this article. Should you have existing
incompatible c-tree Plus CT_ARRAY fields to import into c-treeSQL, please contact your
nearest FairCom office for suggestions and advice. We're here to help you.
 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- treeSQL.
 In order 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 with
www.faircom.com
All Rights Reserved
252
c-treeSQL) have a hidden field, $NULFLD$, which is used to determine if each user-created
field in the record buffer has a NULL value. c-treeSQL requires this capability to implement
constraints. c-treeDB and c-treeSQL will access tables without the $NULFLD$ field, but the
table's fields will always return a non-NULL status.
 In order 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-treeSQL 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.
Adding a DODA to an Existing Data File
To use c-treeSQL Server with existing ISAM files that do not already have a DODA resource, add
a DODA to each file. This is done most easily with a developer-created utility that opens each file
and calls PutDODA to insert the required resource into that file. The utility should accomplish the
following tasks:
 Include a data object definition array (DODA) which is simply an array of DATOBJ structures,
as defined below.
 Open each data file in ctEXCLUSIVE mode.
 Call PutDODA() for each file to insert the corresponding DODA resource.
 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 standard c-tree
Plus data files. DATOBJ is defined as follows:
typedef struct {
pTEXT fsymb; /* ptr to symbol name */
pTEXT fadr; /* adr of field in record buffer */
UCOUNT ftype; /* type indicator */
UCOUNT flen; /* field length */
...
} DATOBJ;
 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;
www.faircom.com
All Rights Reserved
253
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. The field types are described in "Field Types" in
the c-treeACE Programmer’s Reference Guide (http://docs.faircom.com/doc/ctreeplus).
The PutDODA() call inserts the DODA object as a resource into the data file. The function is
declared as follows:
PutDODA (COUNT PUTDODA(COUNT datno,pDATOBJ doda,UCOUNT numfld))
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. See review the PutDODA() function description and Appendix D "Record
Schemes" in the c-treeACE Programmer’s Reference Guide
(http://docs.faircom.com/doc/ctreeplus) for additional details. Call FairCom for assistance if
needed.
Index Definition Requirements
 If an index contains a segment consisting of a "partial field" (i.e., does not use the c-tree Plus
Schema segment modes or the segment starting offset and the segment length are different
from the field starting offset and the field length) c-treeSQL cannot access this index, even
though the index is still properly updated by c-tree. You will need to create a new index in
c-treeSQL composed of the corresponding columns.
 If there is more than one logical index in one physical index file, the DROP INDEX and the
DROP TABLE commands will 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.
For example, if a field is deleted from the table, and this field is part of an index segment that
spans over several fields, c- treeSQL 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
characteristics preventing them from working in the original application.
Example
The following application defines a typical c-tree Plus ISAM data file and index with the proper
IFIL and DODA resources necessary for use with c-treeSQL. In addition, it demonstrates the
proper construction of a CT_ARRAY field to be imported into a c-treeSQL database table as a
BINARY field.
See Example ISAM Application with Proper c-treeSQL Constructs.
After executing this application, run the utility to link the table to c-treeSQL:
www.faircom.com
All Rights Reserved
254
#ctsqlimp isam_table.dat -u ADMIN -a ADMIN
Finally, run the
utility to issue c- treeSQL statements against the table:
#ISQL -u ADMIN -a ADMIN ctreeSQL
ISQ>SELECT * FROM isam_table;
Troubleshooting ISAM to c-treeSQL Problems
The easiest way to avoid common problems when importing c-tree Plus data files into c-treeSQL
is to copy these files into the c-treeSQL database directory, typically located in the c-treeSQL
Server directory. This gives the server direct access to the files. However, it is possible to link any
c-tree Plus data file from any location. c-treeSQL Server access to the file is completely relative.
The most common problem encountered is an FOPN_ERR error (12) from ctsqlimp when
importing the table. In most cases, this is simply the c- treeSQL Server's inability to resolve the
file's relative location from the c-treeSQL dictionary files. The most straightforward way to
address this issue is to specify the full pathname when specifying the data file to import.
For example, to import a c-tree Plus data file existing in another directory different from the
c-treeSQL Server, execute the ctsqlimp command as follows:
#ctsqlimp c:\old_data\datafile.dat -d c-treeSQL -s FAIRCOMS -u ADMIN -a ADMIN
This will link the existing data file in place to the c-treeSQL Server. You can now query, add, and
update the data with standard c-treeSQL statements.
Important!
While you can import data from another c-tree Server location into the c-treeSQL Server, keep in
mind you can only use ONE of the servers to access the data. It is not possible to access a c-tree
data file from multiple c-tree Servers simultaneously. With the c-treeSQL Server this is not a
problem; you can continue to use your existing ISAM application with the new c-treeSQL Server!
Example ISAM Application with Proper c-treeSQL Constructs
/* -------------------------------------------------------------------------ISAM to SQL Tutorial
The goal of this tutorial is to introduce the most basic c-tree Plus
ISAM API to accomplish creating and manipulating a table through the
c-tree Server.
From a functional point of view this application will perform the following:
1. Logon onto a session
2. Add 1 table with some fields
3. Populate the table with a few records
4. Display the contents of the table
Once this table has been built, it is also ready to use in c-treeSQL.
Use the c-treeSQL Import Utility, ctsqlimp, to link the table to
your c-treeSQL Server. You will then be able to query your data
through c-treeSQL statements!
This example creates and stores a UUID value for a list of names, and
stores them in a c-tree Plus data file. Several concepts are
demonstrated.
1. How to build an ISAM table compatible with c-treeSQL.
www.faircom.com
All Rights Reserved
255
2. How to create and store a universally unique identifier
(UUID) with c-tree.
3. How to properly construct and use a CT_ARRAY field
for later import to c-treeSQL.
The table consists of 3 fields, a 'pad' field, a GUID field, and
a name field. In this example, the GUID field demonstrates how to
properly use a CT_ARRAY field as a c-treeSQL BINARY field. Notice
in particular, the added four byte length header to the field. While
this value is transparent to the c-treeSQL user, it is imperative
that this header be properly constructed with the correct value to
be imported into c-treeSQL.
-------------------------------------------------------------------------- */
/** Preprocessor definitions and includes **/
#include <stdio.h>
#include <string.h>
#include "ctreep.h "/* All necessary c-tree Plus headers */
#define END_OF_FILE INOT_ERR
/** Global declarations **/
/* Data File Number */
COUNT guid_no;
ISEG guid_seg = {
12,16,INTSEG
};
IIDX guid_idx = {
16, /* Length of index */
0, /* key type */
0, /* Dup Flag */
1, /* NULL key flag */
0, /* Empty Char */
1, /* Number of segments */
&guid_seg, /* Pointer to Segment Array */
NULL, /* Index Name */
NULL, /* Optional Index Name */
NULL, /* Alternate Collating Sequence */
NULL /* Option pointer to pad byte */
};
/* IFIL Definitions */
IFIL guid_dat = {
"GUID8", /* data file name ("dat" is always assumed)*/
-1, /* data file number */
52, /* data record length */
8192, /* data extension size */
ctSHARED, /* data file mode */
1, /* number of indices */
8192, /* index extension size */
ctSHARED, /* index file mode */
&guid_idx, /* pointer to index array */
"Delflag", /* pointer to first field name (r-tree) */
"Buffer" /* pointer to last field name (r-tree) */
};
/* Xtd8 File Definitions - we will use HUGE files in this example */
www.faircom.com
All Rights Reserved
256
XCREblk xcreblk[2] = {
{ ctFILEPOS8 , 0, 0, 0, 0, 1048576},
{ ctFILEPOS8 , 0, 0, 0, 0, 1048576}
};
/* Data Record Definitions */
DATOBJ doda[] = {
{"pad",NULL,CT_FSTRING,8},
{"uuid",NULL,CT_ARRAY,20},
{"name",NULL,CT_FSTRING,24}
};
/* Names for records */
COUNT name_count = 6;
typedef struct {
TEXT *name;
} name_text;
name_text name_list[]= {
(pTEXT) "Craig",
(pTEXT) "Ray",
(pTEXT) "Jeff",
(pTEXT) "Jon",
(pTEXT) "Randal",
(pTEXT) "Marco"
};
/** Function declarations **/
#ifdef PROTOTYPE
VOID initialize(void), define(void), manage(void), done(void);
VOID Add_Records(void), Display_Records(void), Delete_Records(void);
VOID doError(TEXT *);
#else
VOID initialize(), define(), manage(), done();
VOID Add_Records(), Display_Records(), Delete_Records();
VOID doError();
#endif
/************************************************************************
* main() - The main() function implements the concept of *
* "Init, define, manage and you're done..." *
* *
************************************************************************/
#ifdef PROTOTYPE
NINT main (NINT argc, pTEXT argv[])
#else
NINT main (argc, argv)
NINT argc;
pTEXT argv[];
#endif
{
initialize();
define();
manage();
done();
getchar();
exit(0);
}
www.faircom.com
All Rights Reserved
257
/************************************************************************
* initialize() - Perform the minimum requirement of logging onto *
* the c-tree Server *
* *
************************************************************************/
#ifdef PROTOTYPE
VOID initialize(VOID)
#else
VOID initialize()
#endif
{
COUNT retval=0;
#ifdef ctThrds
NINT trc;
#endif
ctrt_printf("INIT\n");
/* Initialize c-tree Plus and log on to Server */
ctrt_printf("\tLogon to Session...\n");
#ifdef ctThrds
if (trc = ctThrdInit(3, 0L, NULL))
{
ctrt_printf("\nERROR-> initialize(): ctThrdInit() \n");
ctrt_printf("\nerror = %d\n", trc);
getchar();
exit(0);
}
#endif
if (retval = InitISAMXtd(16, 16, 16, 16, 0, "ADMIN", "ADMIN", "FAIRCOMS"))
doError("initialize(): InitISAMXtd()");
}
/************************************************************************
* define() - Open the data file, if it exists, otherwise create and *
* re-Open the table. *
* *
************************************************************************/
#ifdef PROTOTYPE
VOID define(VOID)
#else
VOID define()
#endif
{
ctrt_printf("DEFINE\n");
/** Open data file **/
ctrt_printf("\tOpen Data File...\n");
{
/** Create Data File **/
if (CreateIFileXtd8(&guid_dat, NULL, NULL, 0, NULL, NULL, xcreblk))
doError("define(); CreateIFileXtd8()");
www.faircom.com
All Rights Reserved
258
if (PutDODA(guid_no, doda, (UCOUNT) 3))
doError("define(); PutDODA 8()");
CloseIFile(&guid_dat);
doError("define(); Re-OpenIFileXtd8()");
}
}
/************************************************************************
* manage() - This function performs simple record functions of add, *
* delete, and gets *
* *
************************************************************************/
#ifdef PROTOTYPE
VOID manage(VOID)
#else
VOID manage()
#endif
{
ctrt_printf("MANAGE\n");
Delete_Records(); /* delete any existing records */
Add_Records(); /* populate the table with data */
Display_Records(); /* show contents of table */
}
/************************************************************************
* Add_Records() - This function adds records to a table in the *
* database from a static structure called *
* RECORD_DATA *
* *
************************************************************************/
#ifdef PROTOTYPE
VOID Add_Records(VOID)
#else
VOID Add_Records()
#endif
{
VRLEN offset;
TEXT inpbuf[256];
TEXT name_buf[24];
long length = 16;
COUNT i = 0;
#ifdef WIN32
GUID new_uuid;
#else
uuid_t new_uuid;
www.faircom.com
All Rights Reserved
259
#endif
ctrt_printf("\tAdd Records...\n");
/* Add records to table */
for (i=0;i<name_count;i++) {
ctsfill(inpbuf, 0, 256);
ctsfill(name_buf, 0, 24);
strcpy(name_buf, name_list[i].name);
offset = 0;
/* Copy in the first position */
cpybuf(inpbuf, name_buf, 8);
offset += 8;
/* Create a new UUID */
#ifdef WIN32
CoCreateGuid(&new_uuid);
#else
uuid_generate (&new_uuid); */
#endif
cpybuf(inpbuf+offset, &length, 4);
offset += 4;
/* Copy the new UUID into the record buffer */
cpybuf(inpbuf+offset, &new_uuid, sizeof(new_uuid));
offset += sizeof(new_uuid);
/* Copy a name into the record buffer */
cpybuf(inpbuf+offset, name_buf, 24);
/** Add the record **/
if (AddRecord(guid_no, inpbuf))
doError("Add_Records(): AddVRecord()");
} /* End of for loop */
}
/************************************************************************
* Display_Records() - This function displays the contents of a table. *
* FirstRecord(), ctdbNextRecord() fetches a *
* record. Then each field is parsed and displayed. *
* *
************************************************************************/
#ifdef PROTOTYPE
VOID Display_Records(VOID)
#else
VOID Display_Records()
#endif
{
char sName[128];
unsigned char sUUID[16];
unsigned char buffer[256];
COUNT RetVal = 0;
www.faircom.com
All Rights Reserved
260
int i = 0;
int j = 0;
unsigned char buf[40];
ctrt_printf("\tDisplay Records...");
ctsfill(&buffer,0,256);
ctsfill(&sName,0,128);
ctsfill(&sUUID,0,16);
/* Read the first record */
if (FirstRecord(guid_no, &buffer))
doError("Display_Records(): ctdbFirstRecord()");
while (!RetVal)
{
/* Copy the UUID field from the buffer. */
cpybuf(sUUID, buffer+12, 16);
/* Copy the name field from the buffer */
cpybuf(sName, buffer+28, 24);
/* Convert the UUID field to Windows GUID format */
memset(buf, 0, 40);
for( i=0,j=0; i<sizeof(uuid_t); i++ ) {
sprintf( buf+j, "%02X", sUUID[i] );
j += 2;
if( (i==3) || (i==5) || (i==7) || (i==9) ) {
*(buf+j) = '-';
++j;
}
}
strcat(buf, "");
/* print out the record contents */
printf("\n%s\tis associated with GUID of %s\n", sName, buf);
RetVal = NextRecord(guid_no, &buffer);
break; /* Last Record */
if (RetVal)
doError("Display_Records(): NextVRecord()");
}
}
/************************************************************************
* done() - This function handles the housekeeping of closing tables *
* and the freeing of associated memory. *
* *
************************************************************************/
#ifdef PROTOTYPE
VOID done(VOID)
#else
VOID done()
#endif
{
www.faircom.com
All Rights Reserved
261
ctrt_printf("DONE\n");
/* Close data file (optional) */
ctrt_printf("\tClose table...\n");
if (CloseIFile(&guid_dat))
doError("done(): CloseIFile()");
/* Logout of session and free memory */
ctrt_printf("\tLogout...\n");
CloseISAM();
#ifdef ctThrds
ctThrdTerm();
#endif
}
/************************************************************************
* Delete_Records() - This function deletes records in a data file. *
* *
************************************************************************/
#ifdef PROTOTYPE
VOID Delete_Records(VOID)
#else
VOID Delete_Records()
#endif
{
COUNT RetVal;
NINT bRecSetEmpty;
TEXT inpbuf[256];
VRLEN len;
len = 256;
bRecSetEmpty = 0;
ctrt_printf("\n\tDelete records...\n\n");
if ((RetVal = FirstRecord(guid_no, &inpbuf)) != NO_ERROR)
{
bRecSetEmpty = 1;
else
doError("Delete_Records(): FirstVRecord()");
}
while (!bRecSetEmpty) /* delete til table empty */
{
if ((RetVal = DeleteRecord(guid_no)) != NO_ERROR)
doError("Delete_Records(): DeleteVRecord()");
len = 256;
if ((RetVal = NextRecord(guid_no, &inpbuf)) != NO_ERROR)
{
bRecSetEmpty = 1;
else
doError("Delete_Records(): NextVRecord()");
}
www.faircom.com
All Rights Reserved
262
}
}
/************************************************************************
* doError() - This function is a common bailout routine. It displays *
* an error message allowing the user to acknowledge before *
* terminating the application *
* *
************************************************************************/
#ifdef PROTOTYPE
VOID doError(TEXT mesg[])
#else
VOID doError(mesg)
TEXT mesg[];
#endif
{
ctrt_printf("\nERROR-> %s \n", mesg);
ctrt_printf("\nisam_err = %d, isam_fil = %d, sysiocod = %d\n", isam_err, isam_fil, sysiocod);
getchar();
exit(0);
}
16.2
Upgrading V6 Applications
As always, c-tree Plus is designed for immediate use right out of the box.
Applications written for c-tree Plus V6 that include ctreep.h as required will compile and link
properly right out of the box. Your application will function exactly as before using the latest c-tree
Plus library. ctreep.h automatically includes the ctv6v7.h header (described in “#defines (page
264)”).
Developers wanting to use HUGE, segmented files or other functionality made available with the
Xtd8 file format (see “File Formats” in the c-treeACE Programmer's Reference Guide
(http://docs.faircom.com/doc/ctreeplus/)) first introduced in V7 must also:
 Use the 8-byte file creation functions to create new extended files.
 Change IFIL definitions for indices allowing duplicates to store 8-byte offsets for indices
referencing HUGE files.
 Convert existing data files using the ctcv67 utility.
Note that the ctoptn.h file is now created in a custom.xxx directory where .xxx represents the
operational model. This file was previously created in the custom directory.
Duplicate Keys
For indices associated with Standard data files, a duplicate key length includes 4 bytes for the
associated record position which is used to break ties. If an index is created for a HUGE data file,
then the key length must include 8 bytes for the associated record position.
www.faircom.com
All Rights Reserved
263
#defines
The c-tree Plus #define constants were modified to use a uniform style of ctWXYZ by appending
ct to the beginning of all c-tree Plus defines. For example, TRNLOG is changed to ctTRNLOG.
Two header files, ctv6v7.h and ctv7v6.h, provide compatibility.
Add the ctv6v7.h compatibility header file to applications written for c-tree Plus V6.x to
automatically change the old defines to the new defines to allow the application to be compiled
with the latest version of c-tree Plus.
Add the ctv7v6.h compatibility header file to applications written for the latest version of c-tree
Plus to automatically change the new defines to the old defines to allow the application to be
compiled with c-tree Plus V6.x. This header provides “rename #defines” to set the symbols back
to their V6 convention.
The following defines were changed:
16.3
ADMOPEN
LKSTATE
RESTRED
AG_LOCK
LOGFIL
RESTRED_BLK
AUTOSAVE
LOGIDX
RESTRSV
AUTOTRN
MIRROR_SKP
SAVECTREE
CHECKLOCK
NONEXCLUSIVE
SAVENV
CHECKREAD
OPENCRPT
SHARED
CIPFASE
OVRFASE
SS_LOCK
DEFERCP
PENDERR
SUPERFILE
DELUPDT
PENDREN
SUSPEND
DISABLERES
PENDRNU
TRANDEP_CRE
DUPCHANEL
PERMANENT
TRANDEP_DEL
ENABLE
PREIMG
TRANDEP_SFM
ENABLE_BLK
READFIL
TRNBEGLK
EXCLUSIVE
READREC
TRNLOG
FREE
READREC_BLK
TWOFASE
GETLKISAM
RESET
VIRTUAL
LK_BLOCK
RESTORE
VLENGTH
RESTORE_BLK
WRITETHRU
Converting c-tree V4.1F-V4.3C Applications
The conversion of an existing c-tree V4.3 application program involves two main aspects: file
conversion and program conversion. The files from c-tree V4.3 are not compatible with the c-tree
Plus file format. Programs may be compatible, but many will require some modification.
www.faircom.com
All Rights Reserved
264
Application Conversion Details
 data & index files
Data files are converted using the utility program ctcv43 provided with c-tree Plus. Index files
associated with these data files should then be rebuilt using the c-tree Plus rebuild utility,
ctrbld, or function, RebuildIFile().
Stand-alone index files are converted with the programs ctin43 and ctindx provided with
c-tree Plus. ctin43 must be linked with your V4.3 library. It produces a flat key file for each
index. ctindx is linked with your c-tree Plus library. It creates a c-tree Plus index from the flat
key file produced by ctin43.
 ISAM information
ISAM Parameter files and Incremental ISAM Structures are compatible. The tfilno field has
been added to the IFIL structure. The aidxnam, altseq, and pvbyte fields have been added to
the IIDX structure. See Incremental ISAM Structures in the c-treeACE Programmer's
Reference Guide (http://docs.faircom.com/doc/ctreeplus/) for more information on these
structures.
With parameter files, make sure the RTREE setting in ctoptn.h is correct.
 header info
c-tree Plus applications cannot directly access the index file headers via the(ct_key +
filno)->member reference. Instead, use the GetCtFileInfo() and GetSymbolicNames()
functions, part of the c-tree Plus library, to get the information.
For example, the data record length is accessible with the following expression in c-tree V4.3:
(ct_key + filno)->reclen. In c-tree Plus the record length is returned by the function call
GetCtFileInfo(filno,RECLEN).
GetCtFileInfo() returns a long integer since it is also used to return header values such as
the file size. All references of the form “extern CTFILE *ctnum;” must be removed. If you are
using such a statement, then you must rely on the GetCtFileInfo() and
GetSymbolicNames() functions instead.
 length parms
All length related parameters have become 4-byte values. We now provide function
prototypes which should catch (and/or correct) this change. For example, in
REDVREC(datno,recptr,bufsiz), bufsiz is now a 4-byte quantity.
 Function Returns and Parameter Changes
The following functions have undergone parameter changes between c-tree V4 and c-tree
Plus V6:
Function Name
Function Return
Function Parameters
v4
EQLKEY
POINTER
COUNT keyno, TEXT *target
v10
EQLKEY
LONG
COUNT keyno, pVOID target
v4
GTEKEY
POINTER
COUNT keyno, TEXT *target, TEXT *idxval
v10
GTEKEY
LONG
COUNT keyno, pVOID target, pVOID
idxval
v4
GTKEY
POINTER
COUNT keyno, TEXT *target, TEXT *idxval
v10
GTKEY
LONG
COUNT keyno, pVOID target, pVOID
idxval
www.faircom.com
All Rights Reserved
265
v4
NXTKEY
POINTER
COUNT keyno, TEXT *idxval
v10
NXTKEY
LONG
COUNT keyno, pVOID idxval
v4
REDREC
COUNT
COUNT datno, POINTER recbyt, TEXT
*recptr
v10
REDREC
COUNT
COUNT datno, LONG recbyt, pVOID recptr
v4
frmkey
COUNT
COUNT keyno, TEXT *recptr, TEXT * txt,
POINTER pntr
v10
frmkey
COUNT
COUNT keyno, pTEXT recptr, pTEXT txt,
ctRECPT pntr, VRLEN datlen
v4
LOKREC
COUNT
COUNT datno, COUNT lokmod, POINTER
recbyt
v10
LOKREC
COUNT
COUNT datno, COUNT lokmod, ctRECPT
recbyt
 frmkey
If you use the BuildKey() function, short name frmkey, it now takes an additional parameter
specifying the length, as a 4-byte quantity, of the record buffer from which the key is
extracted. See the function prototype for BuildKey() in CTDECL.H.
 current ISAM record
cur_recno[ ] and cur_image[ ] no longer exist. Also, it is no longer necessary to use two
buffers for record updates, although using two buffers will NOT cause any problem for c-tree
Plus. c-tree Plus maintains the necessary information internally for each user.
To determine the current ISAM record position, use GETCURP(datno) instead of
cur_recno[datno]. To reset the current ISAM record after a successful rewrite, use
UPDCURI(datno,SWTCURI) instead of manipulating cur_recno and cur_image. See the
CTVXMG.C code for an example of this technique. See “ResetRecord” or “CurrentFileOffset”
in the c-treeACE Programmer's Reference Guide (http://docs.faircom.com/doc/ctreeplus/) for
additional capabilities.
To set the current ISAM record to a specified byte position (and/or record image) use
SETCURI(datno,recbyt,recptr,bufsiz), where recbyt is required and specifies the record
position. If non-null, recptr points to a record buffer containing an image of the data record. If
non-zero, bufsiz (a 4-byte value), specifies the length of the record buffer. If recptr is non-null
and bufsiz is passed as 0L, then bufsiz is assumed to be the record length defined for the file
at the time the file was created. For variable length files, this corresponds to the fixed length
portion of the file.
 key segment info
If you have accessed key segment information (such as a segment length or segment mode),
you can now retrieve it via a call to:
ctgetseginfo(keyno,segment_no,mode)
where segment_no is a zero-based segment number, and mode is one of the following:
• ctSEGPOS - segment offset
• ctSEGMOD - segment mode
• ctSEGLEN - segment length
 #includes
Be sure to change the c-tree include files to the following:
www.faircom.com
All Rights Reserved
266
#include “ctreep.h”
Note that ctaerr.h includes the definitions for uerr_cod, isam_err and isam_fil. It is not
necessary to include ctifil.h (as specified in the manual) since it will be included automatically.
 old key types
Key types 1, 2 and 3 have been phased out. They supported integer and floating point keys.
You can use appropriate key segments to support all of these types. Change the key type to
0, unless you desire key compression, and modify your ISAM key segment modes. If your
application only uses the low level functions, you can transform the keys as required using
the TransformSegment() function described in the c-tree Plus Function Reference Guide.
 Lock Table Size
c-tree V4.X utilized an internal lock table that supported 32 concurrent locks by default,
#define MAX_LOCKS 32. To alleviate this artificial lock limit, c-tree Plus dynamically
allocates a lock list instead of a more static lock table. The number of locks available to c-tree
Plus is now constrained by available system memory.
 TRANSACTION
The TRANSACTION() function supported in c-tree V4.3, for purposes of keeping a Server
from shutting down in the middle of an application procedure, now simply returns without
error. It causes no action to be taken.
c-tree Plus supports extensive transaction processing in the Server mode via the Begin(),
Abort(), Commit(), SetSavePoint(), and RestoreSavePoint() functions.
 TFRMKEY
c-tree Plus supports the automatic calling of TransformKey(), short name TFRMKEY(), to
transform target key values used in ISAM level search routines. If you use the traditional
c-tree functions to initialize c-tree Plus, InitCTree(), InitISAM(), OpenISAM(), or
CreateISAM(), then this automatic feature is disabled and your existing application will be
unaffected. If you use the extended forms of these functions (InitCTreeXtd(), InitISAMXtd(),
OpenISAMXtd(), or CreateISAMXtd()), then you must set the userprof parameter to
USERPRF_NTKEY to disable the automatic calls to TransformKey(). Otherwise, your
existing calls will be followed by the automatic calls, which will cause problems.
 FPUTONLY
There is no longer a FPUTONLY disk I/O protocol. c-tree Plus now lets you select on a
file-by-file basis whether or not to force updates directly to disk. OR the ctWRITETHRU
constant (64) into the file mode to get the same affect as the FPUTONLY I/O protocol.
 DOSFLUSH
DOSFLUSH support is being phased-out. As distributed, DOSFLUSH will only become
effective in the FPUTFGET, Standalone Multi-user, configuration. If necessary, add
DOSFLUSH to your CTOPTN.H configuration file. CTOPT2.H contains preprocessor
commands that turn DOSFLUSH off if NOTFORCE is selected.)
Transaction processing provides a much more effective means to ensure the consistency and
completeness of the data.
 r-tree® / d-tree™
Applications using Version 1.1 of the r-tree Report Generator or Version 3.1 of the d-tree
Development ToolBox require updated versions of these development tools.
www.faircom.com
All Rights Reserved
267
16.4
Backward Compatibility
In rare situations, customers may need to move from a newer Server to an older one (e.g., from a
V7.12 Server to a V7.11 Server). To do this, you must follow the following steps:
1.
2.
3.
4.
Shut down the server cleanly
Restart the server with no users or processes attached
Let it perform any automatic recovery
Shutdown the server cleanly the second time
If the above procedure completes successfully, you can remove the *.FCS files without any loss
of data.
If you follow the above procedure and encounter no errors on the console and none are written to
the CTSTATUS.FCS file, you will not lose any data by deleting the files.
www.faircom.com
All Rights Reserved
268
17. Index
#
#defines ................................................................ 264
.
.NET - Removed STRONGSIGN from
assemblies .......................................................... 11
.NET Framework Requirements ............................. 11
.NET Tools for VS2010 - All projects updated to
use .NET Framework v4.0 .................................. 11
2
2xx Internal Error Codes ....................................... 183
6
64-bit Windows Filesystem Behavior...................... 81
6-Byte Transaction Numbers .................................. 27
8
8 Tips for a Fast Data Load .................................... 48
A
A Server is Already Running in the Working
Directory............................................................ 102
Abbreviated (short) Names ................................... 209
Activation Failures (Error 26) on AIX 6 .........140, 198
Adding Transaction Processing .............................. 57
Additional Transaction Log Number Messages.... 139
ADO.NET Entity Framework V2 - V4 Support ........ 12
AIX ........................................................................ 193
Analyzing ctsemrqs() Calls on AIX systems .140, 195
Analyzing JVM Memory usage with c-treeACE
SQL Java Stored Procedures ........................... 159
Application Conversion Details ............................. 265
Automatic Recovery................................................ 43
Automatic Recovery Fails .............................101, 126
Automatic Recovery Takes Excessive Time ........ 128
Automatic Recovery Terminates Abnormally ....... 127
Avoid Index Errors Caused by memcpy()
Implementation on Latest Operating Systems.. 236
B
Background............................................................. 13
Backup and Restore Options for
Non-Transaction Files......................................... 30
Backup and Restore Options for PREIMG Files .... 22
Backup and Restore Options for TRNLOG Files .... 25
Backup and Restore Options for WRITETHRU
Files .................................................................... 33
Backward Compatibility ........................................ 268
Batch API .............................................................. 220
Best Practices ......................................................... 16
Better Performance with NXTVREC() vs
GTVREC()........................................................... 47
C
Caching of Data Records ....................................... 17
Caching of Index Nodes ........................................ 17
Calculating File Storage Space ............................. 51
Calculating Index Sizes ......................................... 51
Calculating Memory Usage.................................... 49
Client/Server .......................................................... 53
Clients Cannot Connect to Server ....................... 105
Clients Lose Connection to Server ...................... 110
COBOL Compilers Supported by c-treeRTG
COBOL Edition ................................................ 163
COBOL Help ........................................................ 163
Common Entry Point Functions ........................... 223
Compiling c-treeACE SQL PHP on Linux/Unix162, 190
Configurable Transaction Number Overflow
Warning Limit ..................................................... 29
Configuration and Tuning ...................................... 78
Configuring 32-bit ODBC Drivers on 64-bit
Windows Versions ..................................... 81, 187
Configuring Caching .............................................. 18
Connect Microsoft 64-bit SQL Server 2005 to
c-treeACE SQL .......................................... 66, 187
Context API .......................................................... 220
Controlling Server Memory .................................... 50
convert.sh ...................................................... 68, 198
Converting c-tree V4.1F-V4.3C Applications ....... 264
Copyright Notice ...................................................... iii
Correct Handling of Segmented Files During
Automatic Recovery ......................................... 236
CPUs Report Different Times on Linux, Causing
Unexpectedly Long sleep() Times ........... 143, 189
Create File Block.................................................. 225
Creating 6-Byte Transaction Number Files ........... 28
Creating and Using LOGIDX Index Files ............... 27
Creating and Using PREIMG Files ........................ 22
Creating and Using TRNLOG Files ....................... 25
Creating Huge Files ............................................... 34
Creating Memory Files ........................................... 37
Creating Mirrored Files .......................................... 41
Creating Non-Transaction Files ............................. 31
Creating Partitioned Files ...................................... 39
Creating Segmented Files ..................................... 35
Creating WRITETHRU Files .................................. 33
ctadmn Utility Options ............................................ 90
ctKEEPOPEN File Mode to Retain Cached
Server Data ........................................................ 66
c-tree API Call Fails With Unexpected Error ....... 119
c-tree Customer Performance Metrics ................... 15
c-tree Error 10
SPAC_ERR ...................................................... 105
c-tree Error 12
FNOP_ERR ..................................................... 115
c-tree Error 127
ARQS_ERR ............................................. 106, 111
c-tree Error 128
ARSP_ERR .............................................. 106, 112
www.faircom.com
All Rights Reserved
269
Index
c-tree Error 133
ASKY_ERR ....................................................... 106
c-tree Error 14
FCRP_ERR....................................................... 115
c-tree Error 150
SHUT_ERR...............................................107, 112
c-tree Error 162
SGON_ERR ..............................................107, 112
c-tree Error 35
SEEK_ERR ....................................................... 117
c-tree Error 36
READ_ERR ...................................................... 117
c-tree Error 37
WRITE_ERR ..................................................... 118
c-tree Error 39
FULL_ERR........................................................ 118
c-tree Error 40
KSIZ_ERR ........................................................ 118
c-tree Error 417
SPAG_ERR ...................................................... 116
c-tree Error 450
LUID_ERR ........................................................ 107
c-tree Error 451
LPWD_ERR ...................................................... 107
c-tree Error 452
LSRV_ERR ....................................................... 108
c-tree Error 456
SACS_ERR....................................................... 116
c-tree Error 457
SPWD_ERR ..................................................... 117
c-tree Error 470
LGST_ERR ....................................................... 108
c-tree Error 49
FSAV_ERR ....................................................... 119
c-tree Error 530
LMTC_ERR....................................................... 108
c-tree Error 579
LIVL_ERR ......................................................... 109
c-tree Error 584
LRSM_ERR ...................................................... 109
c-tree Error 585
LVAL_ERR........................................................ 109
c-tree Error 589
LADM_ERR ...................................................... 110
c-tree Error 593
XUSR_ERR ...................................................... 110
c-tree Error 609
LTPW_ERR ...................................................... 110
c-tree Error 7
TUSR_ERR....................................................... 111
c-tree Error 84
MUSR_ERR ...................................................... 105
c-tree File Open Errors During Recovery ............. 127
c-tree Files to Include in a Dynamic Dump ............. 42
c-tree OLTP Solutions ............................................ 13
c-tree Server V8 Transaction Number
Enhancements ................................................... 28
c-treeACE Architectural Concepts ........................... 1
c-treeACE Database Engine.................................. 71
c-treeACE Memory Use and glibc malloc
per-thread Arenas ............................................ 149
c-treeACE OEM Installation Notes - V9 through
V11 ..................................................................... 71
c-treeACE Server Configuration
Recommendations ............................................. 80
c-treeACE Server Files ........................................ 173
c-treeACE SQL - Microsoft SQL Server
Integration .......................................................... 58
c-treeACE SQL ADO.NET Data Provider .............. 74
c-treeACE SQL JDBC Driver ................................. 77
c-treeACE SQL ODBC Driver ................................ 76
c-treeACE SQL Troubleshooting ......................... 151
c-treeACE Storage System Support ........................ 3
c-treeACE Utilities ................................................ 174
c-treeRTG Errors ................................................. 167
ctThrd API ............................................................ 217
D
Data and Index Caching Options ........................... 16
Data Definition API............................................... 218
Data File Description Record ............................... 177
Data Manipulation API ......................................... 219
Data or Index File Sizes Grow Unexpectedly ...... 121
DBLOAD Debugging Help ................................... 154
Debugging Java Stored Procedures .................... 154
Disappearing c-treeACE Core Files on Linux ...... 148
Duplicate Keys ..................................................... 263
Dynamic Dump Cannot Be Scheduled ................ 102
Dynamic Dump Fails ............................................ 121
Dynamic Dump Restore Fails .............................. 128
Dynamic Dump Restore FMOD_ERR (48) .......... 140
E
Enabling Low-Level File I/O Diagnostics ............. 115
Error
Requested def blk is empty.............................. 165
Error While Creating SQL Database.................... 153
Errors Occur When Opening c-tree Files ............ 115
Errors Occur When Reading or Writing c-tree
Files.................................................................. 117
Example ISAM Application with Proper
c-treeSQL Constructs ...................................... 255
Extended Feature Parameter Blocks ................... 223
External Third-Party Utilities .................................. 44
F
Failures During c-treeACE Operation .................. 105
Failures During c-treeACE Shutdown .................. 123
Failures During c-treeACE Startup ........................ 99
Failures During System Recovery ....................... 125
FairCom Typographical Conventions ...................... xi
File Compact Fails ............................................... 129
www.faircom.com
All Rights Reserved
270
Index
File Migration .......................................................... 53
File Mirroring ........................................................... 40
File Rebuild Fails .................................................. 129
File Rebuilds ........................................................... 46
Fixed-Length Parameter File Examples ............... 180
FORCE_LOGIDX.................................................... 80
Forced Single Entry Point Capability .................... 223
Forcibly Terminating the c-tree Server During
Shutdown .......................................................... 125
Full Names............................................................ 201
Function API Listing .............................................. 217
Function Calls ....................................................... 226
Function Name Cross Reference ......................... 201
FUSE_ERR (22) During Automatic Recovery ...... 140
G
gdb Remote Debugging ........................................ 145
Generating Dump Files on 64-bit Windows .......... 138
H
Hardware Component Sizing .................................. 13
Heap Debugging on Solaris 9+ Operating
Systems ....................................................136, 193
Helpful Examples .................................................... 58
Highly Concurrent c-treeACE SQL Updates
Involving Floating Point Conversions ............... 232
How do I clean and reset the transaction
numbers for my files? ....................................... 133
How do I convert tables in a database to be
case insensitive? .............................................. 159
HP-UX ................................................................... 198
Huge Files............................................................... 34
I
IBM AIX Large Page Support ............................... 194
IBM AIX Multicore/CPU Performance Tuning
Options.............................................................. 193
IBM AIX Mutex Performance Tuning Options ...... 194
IFIL Block .............................................................. 224
Important Technical Updates ................................ 232
Index File Description Record .............................. 178
Initialization API .................................................... 217
Initialization Record .............................................. 177
Installation Error Due to XML Encoding ............... 186
Instance Control API ............................................. 218
Internal 749X Error Codes .................................... 185
ISAM Block ........................................................... 224
ISAM Data Definition API ..................................... 218
ISAM Data Manipulation API ................................ 219
ISAM Initialization API .......................................... 218
ISAM Parameter File Organization ....................... 176
ISAM Parameter Files (Legacy) ........................... 176
J
Java 1.7 uses large amount of virtual memory at
startup ............................................................... 104
Java Configuration for c-treeACE SQL Stored
Procedures, Triggers and User Defined
Functions ......................................................... 151
Java Requirements for c-treeACE SQL ................. 46
Java Version .......................................................... 11
K
Keep a CTUSER Library Open .............................. 70
KEEP_LOGS ......................................................... 80
Key Estimate Block .............................................. 225
Key Segment Description Record........................ 180
L
Large File Support ................................................. 33
Large Page Support to Improve Large Cache
Performance ...................................................... 80
Let Your Existing ISAM Applications Co-Exist
With c-treeSQL ................................................ 244
Linux .................................................................... 189
LockDump API Options ......................................... 89
LockDump Output ................................................ 130
Logon Block ......................................................... 224
Low-level Data Definition API .............................. 219
Low-level Data Manipulation API ......................... 220
Low-level Initialization API ................................... 218
M
Maximum Number of Indices Per Data File ........... 82
Memory Files ......................................................... 36
Memory Use of Linux Processes ......................... 190
Microsoft Vista Locks Out FPUTFGET ................ 237
Microsoft Windows ............................................... 186
Migrating Data Between Platforms and
Operational Models ............................................ 52
Migrating Your Application Between Operational
Models................................................................ 54
Minimum Hardware Requirements for c-treeACE
V10 ..................................................................... 10
Minimum Software Requirements for c-treeACE..... 9
Missing or Corrupt Server Settings File ............... 101
Missing or Incorrect Configuration File .................. 99
Missing Server Binary or Communication DLLs .. 100
Monitoring CPU Usage .......................................... 83
Monitoring c-tree Client Activity ............................. 90
Monitoring c-tree Server Shutdown Progress...... 125
Monitoring c-treeACE Automatic Recovery ........... 94
Monitoring c-treeACE Cache Usage...................... 94
Monitoring c-treeACE Dynamic Dumps ................. 93
Monitoring c-treeACE File Usage .......................... 93
Monitoring c-treeACE Internal Resource Usage ... 87
Monitoring c-treeACE Lock Table .......................... 89
Monitoring c-treeACE Memory Use ....................... 88
Monitoring c-treeACE Process State ..................... 95
Monitoring c-treeACE Server with strace .............. 95
Monitoring c-treeACE Status Log Messages......... 94
Monitoring c-treeACE Transaction Activity ............ 92
www.faircom.com
All Rights Reserved
271
Index
Monitoring c-treeACE Transaction Numbers and
Transaction File Numbers................................... 92
Monitoring c-treeACE Using ctstat Utility................ 88
Monitoring c-treeACE Using Snapshot Support ..... 87
Monitoring c-treeACE Using
SystemConfiguration API.................................... 88
Monitoring Disk Usage ........................................... 84
Monitoring Memory Usage ..................................... 85
Monitoring Network Usage ..................................... 86
Monitoring Performance ......................................... 83
Monitoring System Resource Usage ...................... 83
More about Upgrading c-treeACE ........................ 243
Moving a HP-UX c-treeACE SQL Database to
Windows .....................................................68, 198
mtmake Advanced Options .................................. 168
mtmake Command Line ....................................... 168
Multiple c-treeACE Architecture ............................... 6
Multiple Data File Parameter Setup...................... 182
Multi-User Standalone ............................................ 52
Multi-user Standalone to Client/Server ................... 55
N
Non-Transaction Files ............................................ 29
Notification Example ............................................... 67
NULL Handling ..................................................... 176
Number of Active Transaction Logs
Unexpectedly Increases ................................... 112
O
Open File Block .................................................... 225
Operating System Specific ................................... 186
Optional Index Member Record............................ 179
Other System Monitoring Options .......................... 87
P
Parameter File Contents ....................................... 177
Parameter Files in Client Server Models .............. 183
Partitioned Files ...................................................... 38
Pending File ID Overflow
Error 534 in CTSTATUS.FCS ........................... 134
Platform Support ....................................................... 9
Positioning the c-treeACE in the System
Architecture ........................................................... 4
Potential c-tree Server Automatic Recovery
Failures with the LOGIDX Feature ................... 235
Potential Variable Length Data Corruption
Prevented During Automatic Recovery ............ 233
PREIMG Transaction Files ..................................... 21
Prevent FPUTFGET Data Corruption with
Concurrent Updates.......................................... 233
Prevent FPUTFGET LNOD_ERR Error (50) from
OpenIFile() ........................................................ 144
Prevent Termination of c-treeACE from LRU
Cache Miss Limitations ..................................... 234
Properties of Cached Files ..................................... 18
Properties of LOGIDX Index Files .......................... 26
Properties of Memory Files ..................................... 37
Properties of Non-Transaction Files ...................... 30
Properties of PREIMG Files ................................... 21
Properties of TRNLOG Files .................................. 23
Properties of WRITETHRU Files ........................... 32
Prototyping ........................................................... 183
prstat and Performance Monitoring on Solaris
Operating Systems .......................................... 137
R
Recovering From Abnormal Server Termination . 122
Recovering from Automatic Recovery Failure ..... 126
Reference Material............................................... 168
Relocating Transaction Logs ................................. 81
Restrict Access to c-treeACE Server Files ............ 44
S
Safely Copying c-treeACE Controlled Files ........... 44
Segmented Files .................................................... 35
Selecting c-treeACE Features Used in the
System ............................................................... 16
Server Administration API.................................... 221
Server Advantages vs. Multiuser Standalone.......... 1
Server Cannot Initialize Communication Protocol 101
Server Configuration Options .................... 90, 92, 93
Server Exhibits Atypical Performance ................. 120
Server Exhibits Unexpected Resource Usage .... 120
Server Fails to Open Server Administrative Files 100
Server Fails to Start ............................................... 99
Server Is In A Non-Responsive State .................. 113
Server Shutdown Hangs or Takes Excessive
Time ................................................................. 124
Server Shuts Down Improperly ............................ 124
Server Startup Hangs or Takes Excessive Time . 103
Server Startup Terminates Abnormally ............... 102
Server Terminates Abnormally ............................ 122
Server Writes Unexpected Messages to Status
Log ................................................................... 120
Sets API ............................................................... 220
Setting/Enabling Advanced Features in SQL
Explorer ............................................................ 151
Single c-treeACE Architecture ................................. 5
Single-threaded to Multi-Threaded ........................ 57
Single-User Standalone ......................................... 52
Single-User to Multi-User Standalone or
Client/Server ...................................................... 55
SKIP_MISSING_FILES ......................................... 80
Slow Windows Network Traffic ............................ 188
Snapshot API Function Options............................. 88
SnapShot API Options ..................................... 90, 92
Snapshot Configuration File Options ..................... 87
Solaris .................................................................. 193
Some Clients Are In A Non-Responsive State .... 114
SRLSEG not Available in c-treeACE SQL When
ROWID is Used ................................................ 152
Steps to Upgrade c-treeACE Server.................... 239
Stored Procedure Error
www.faircom.com
All Rights Reserved
272
Index
Could not initialize class
sun.util.calendar.ZoneInfoFile....................... 157
Stored Procedure Java Class Resolution ............. 157
Summary of c-treeACE Features ........................... 41
System Requirements .............................................. 9
SystemConfiguration API Options ....................90, 93
SystemConfiguration Options ................................. 91
WRITETHRU Files ................................................. 31
T
Timeout Error Diagnosis ....................................... 135
Transaction Log Increases ................................... 139
Transaction Number Limitations Prior to V8 ........... 27
Transaction Number Rollover ............................... 238
Transaction Processing API ................................. 221
Transaction-Controlled Files ................................... 20
TRNLOG Transaction Files .................................... 23
TRNLOG Transaction Files with LOGIDX
Indexes ............................................................... 26
Troubleshooting and Debugging ............................ 99
Troubleshooting Data Conversion Errors ............. 164
Troubleshooting Replication Issues...................... 144
Types of Locks...................................................... 132
Typical Unix Errors From errno.h Header File ...... 169
U
Unactivated c-tree Server ....................................... 99
Unrecognized Keyword in Server Configuration
File .................................................................... 100
Upgrade Notes for Administrators ........................ 242
Upgrade Notes for Developers ............................. 240
Upgrading from Previous Editions ........................ 239
Upgrading V6 Applications ................................... 263
Using Java 1.7 or Later on Windows ...................... 10
Using Windows Process Explorer to Obtain
Thread Call Stacks ........................................... 137
Utility Functions .................................................... 221
Utility To Search Logs For Open Transactions ...... 70
V
V10 and V11 Configuration Recommendations ..... 78
Variable-Length Parameter File Example ............ 181
W
What are .fdk Files in the SQL_SYS Directory? ... 152
What is __Master.dbs? ......................................... 153
When do I have to specify the owner of a table? . 158
When to Use 6-Byte Transaction Number Files ..... 28
When to Use Huge Files ......................................... 34
When to Use LOGIDX Index Files .......................... 26
When to Use Memory Files .................................... 37
When to Use Mirrored Files .................................... 40
When to Use Non-Transaction Files....................... 31
When to Use Partitioned Files ................................ 39
When to Use PREIMG Files ................................... 22
When to Use Segmented Files ............................... 35
When to Use TRNLOG Files .................................. 25
When to Use WRITETHRU Files............................ 33
Windows Vista Network AutoTuning Parameters . 186
www.faircom.com
All Rights Reserved
273

Knowledgebase

Transcription

Similar documents

Whitepages Pro Caller Identification API

APIs as a Foundation for Systems of Engagement

OMNITRAC LASER TRACKING SYSTEM

Xfinity Live! 90`s Fest, Saturday, July 19, 2014 | Events | 95.7 BEN

API and Mashup Tooklit - GeoJet Information Solutions

to view the 2014-2015 Annual Report

JAG flocomponents LP

Dilip Jagtap

Quarterly NL May 2010-b