c-treeRTG COBOL Edition

Transcription

User's Guide
User's Guide
V2
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-treeRTG Ready-to-Go Products ...................................................................... 1
1.1
1.2
Documentation Overview ...................................................................................... 2
Key Benefits of c-treeRTG COBOL Edition ........................................................... 3
2.
c-treeRTG COBOL Edition Quick Start .............................................................. 4
3.
ACUCOBOL-GT Setup......................................................................................... 5
3.1
Recompiling the Runtime ...................................................................................... 5
Recompiling the Windows Runtime .................................................................................... 5
Recompiling the Unix Runtime............................................................................................ 6
Adding Support for --setenv Command-Line Argument to Runtime ................................... 8
Troubleshooting .................................................................................................................. 9
3.2
Configuring the Runtime for ACUCOBOL-GT ..................................................... 10
CTREE_LIB Environment Variable ................................................................................... 10
ACUCOBOL-GT Environment Variables .......................................................................... 10
3.3
3.4
Enabling XDDOPEN, XDDCHECK, and XDDCLOSE for Programmatic
SQL Conversion Error Checking ......................................................................... 11
Converting ACUCOBOL Data to c-treeRTG COBOL Edition Data ..................... 12
4.
Micro Focus COBOL Setup .............................................................................. 14
4.1
Configuring the Runtime for Micro Focus ............................................................ 14
Dynamic Redirection ......................................................................................................... 14
4.2
Recompiling Your Application (Optional) ............................................................. 15
Using the CALLFH Compiler Directive.............................................................................. 15
Specifying c-tree as Indexed File Handler at Link Time ................................................... 15
4.3
Configuration Note for Micro Focus on 64-bit AIX ............................................... 15
5.
isCOBOL Setup ................................................................................................. 17
5.1
5.2
Configuring the Runtime for isCOBOL ................................................................ 17
Troubleshooting ................................................................................................... 20
6.
RM/COBOL Setup .............................................................................................. 21
6.1
Installing the RM/COBOL Driver.......................................................................... 21
Installing the RM/COBOL Driver on Windows .................................................................. 21
Installing the RM/COBOL Driver on Linux ........................................................................ 21
6.2
6.3
6.4
6.5
Adjusting the RM/COBOL Configuration File ...................................................... 22
Copying the RM Library to the Local Folder ........................................................ 22
Adjusting the Paths ............................................................................................. 22
Multiple File Systems with RM/COBOL ............................................................... 23
www.faircom.com
All Rights Reserved
iv
c-treeRTG Ready-to-Go Products
6.6
Additional Documentation ................................................................................... 26
7.
c-treeRTG Server Setup .................................................................................... 27
7.1
7.2
7.3
7.4
7.5
c-treeRTG for Windows ....................................................................................... 27
c-treeRTG for Unix .............................................................................................. 27
Shared Memory for c-treeRTG ............................................................................ 27
Runtime Configuration ......................................................................................... 28
Configure the c-treeRTG Server.......................................................................... 29
8.
c-treeRTG Configuration................................................................................... 30
8.1
8.2
8.3
8.4
c-treeRTG Configuration File .............................................................................. 31
Support for Encrypting the Configuration File...................................................... 32
CTREE_CONF Environment Variable ................................................................. 33
CTREE_CONF_DUMP environment variable to specify configuration
dump file .............................................................................................................. 33
c-treeRTG Configuration Tool - RTG Config ....................................................... 34
8.5
Creating a New File (Basic) .............................................................................................. 38
Creating a New File (Advanced) ....................................................................................... 40
Editing a Configuration File ............................................................................................... 42
9.
Data Conversion ................................................................................................ 44
9.1
9.2
RTG Migrate ........................................................................................................ 45
ctmigra ................................................................................................................. 50
10.
c-treeRTG SQL Access ..................................................................................... 54
10.1
10.2
10.3
10.4
10.5
Creating an XDD from an XFD ............................................................................ 55
Creating an XDD from the COBOL Source ......................................................... 56
Creating an XDD Manually .................................................................................. 57
Storing the XDD in the Data File ......................................................................... 58
Defining External Rules ....................................................................................... 59
<XFDrules> root element .................................................................................................. 61
<rule> XFDRules element ................................................................................................. 62
<when> rule element ........................................................................................................ 63
<[Condition]> when elements ........................................................................................... 64
<do> rule element ............................................................................................................. 65
<[Action]> do elements ..................................................................................................... 66
<[Target]> action element ................................................................................................. 67
Rule Examples .................................................................................................................. 68
10.6
XDD File Schema ................................................................................................ 69
<table> root element ......................................................................................................... 71
<key> table element .......................................................................................................... 72
<part> key element ........................................................................................................... 73
<segment> key element .................................................................................................... 74
www.faircom.com
All Rights Reserved
v
<filters> table element ....................................................................................................... 75
<field> filters element ........................................................................................................ 76
<filter> filters element ........................................................................................................ 77
<[Operator]> filter elements .............................................................................................. 78
<field> operator element ................................................................................................... 79
<value> operator element ................................................................................................. 80
<schema> table element ................................................................................................... 81
<field> schema element .................................................................................................... 83
10.7
Type Mapping Table ............................................................................................ 86
Variable-length fields mapped into LONGVAR* SQL field................................................ 86
10.8
10.9
10.10
10.11
10.12
Troubleshooting Data Conversion Errors ............................................................ 87
Viewing Sqlized Tables in c-treeACE SQL Explorer ........................................... 89
Adding SQL Indices to Sqlized Files ................................................................... 90
API for SQL Conversion Error Checking ............................................................. 93
Background Information about Sqlizing ............................................................... 97
Record Structure Definition: The XDD .............................................................................. 97
Data Conversion Considerations ...................................................................................... 99
SQL Considerations ........................................................................................................ 101
11.
Tips for Advanced Sqlizing ............................................................................ 104
11.1
11.2
Step-by-Step Sqlizing Instructions .................................................................... 104
xddgen Techniques ........................................................................................... 106
Using Group Names........................................................................................................ 106
Splitting an OCCURR ..................................................................................................... 107
Combining Multiple XDD Directives ................................................................................ 107
Name Conflicts ................................................................................................................ 107
HIDDEN Directive ........................................................................................................... 108
Multi-Record Example ..................................................................................................... 108
11.3
Source Code ..................................................................................................... 109
SQLIZEEXAMPLE.CBL .................................................................................................. 109
CARDFILE.FD................................................................................................................. 113
CARDFILE.SL ................................................................................................................. 117
rules.xml .......................................................................................................................... 117
12.
Utilities: ctutil, ctcbtran, xddgen, cttrnmod, ctmigra, ctfileid ...................... 118
12.1
ctutil ................................................................................................................... 121
ctutil Notes ...................................................................................................................... 121
ctunload407 to unload data of files affected by error 407 ............................................... 122
ctutil Commands ............................................................................................................. 122
-check .............................................................................................................................. 124
-checkimg ........................................................................................................................ 125
-clone .............................................................................................................................. 126
-compact ......................................................................................................................... 127
www.faircom.com
All Rights Reserved
vi
-compress ....................................................................................................................... 128
-conv ............................................................................................................................... 129
-copy ............................................................................................................................... 130
-cryptconf ........................................................................................................................ 132
-filecopy ........................................................................................................................... 132
-getimg ............................................................................................................................ 133
-info ................................................................................................................................. 134
-make .............................................................................................................................. 135
-makeimg ........................................................................................................................ 136
-load ................................................................................................................................ 137
-loadtext .......................................................................................................................... 138
-param ............................................................................................................................. 139
-profile ............................................................................................................................. 140
-rblimg ............................................................................................................................. 141
-rebuild ............................................................................................................................ 142
-remove ........................................................................................................................... 143
-rename ........................................................................................................................... 144
-segment ......................................................................................................................... 145
-setpath ........................................................................................................................... 146
-sign ................................................................................................................................ 147
-sqlcheck ......................................................................................................................... 147
-sqlinfo ............................................................................................................................. 148
-sqllink ............................................................................................................................. 149
-sqlunlink ......................................................................................................................... 150
-sqlize .............................................................................................................................. 151
-test ................................................................................................................................. 152
-tron ................................................................................................................................. 153
-uncompress ................................................................................................................... 154
-unload ............................................................................................................................ 155
-unloadtext ...................................................................................................................... 156
-upgrade .......................................................................................................................... 157
-xfd2xdd .......................................................................................................................... 158
ctcbtran ........................................................................................................................... 158
12.2
xddgen ............................................................................................................... 160
XDD Directives ................................................................................................................ 161
Syntax for WITH DUPLICATES on RECORD KEY ........................................................ 164
xddgen Configuration File ............................................................................................... 164
Configuration files directory ............................................................................................ 165
xddgen now allows names larger than 31 chars............................................................. 165
Suppress dash or replace with underscore .................................................................... 166
More xddgen enhancements .......................................................................................... 166
12.3
12.4
cttrnmod - Change Transaction Mode Utility ..................................................... 168
ctfileid - Update File IDs .................................................................................... 172
Copying Server-Controlled Files ..................................................................................... 172
www.faircom.com
All Rights Reserved
vii
12.5
12.6
ctclntrn and cthghtrn utilities for managing transaction mark numbers ............. 173
Additional Command-Line Tools ....................................................................... 173
Appendix A. Details about the File System and SQL ............................................ 174
A.1. c-treeRTG File System Details .......................................................................... 174
A.2. The SQL Challenge ........................................................................................... 174
Appendix B. Configuration File Elements .............................................................. 175
B.1. Structure Elements ............................................................................................ 175
<config> .......................................................................................................................... 176
<instance>....................................................................................................................... 177
<redirinstance> ............................................................................................................... 179
<file> ............................................................................................................................... 181
B.2.
Settings Elements ............................................................................................. 183
<automkdir> .................................................................................................................... 184
<batchaddition>............................................................................................................... 185
<bulkaddition> ................................................................................................................. 186
<ctfixed> .......................................................................................................................... 187
<datacompress> ............................................................................................................. 188
<datafilesuffix> ................................................................................................................ 190
<detectlock> .................................................................................................................... 191
<encrypt> ........................................................................................................................ 192
<filecopy> ........................................................................................................................ 193
<filepool>......................................................................................................................... 193
<hugefile> ....................................................................................................................... 195
<ignorelock>.................................................................................................................... 196
<indexfilesuffix> .............................................................................................................. 197
<keycheck> ..................................................................................................................... 198
<keycompress> ............................................................................................................... 199
<log> ............................................................................................................................... 202
<locktimeout> .................................................................................................................. 210
<locktype> ....................................................................................................................... 211
<maxlencheck> ............................................................................................................... 212
<map> ............................................................................................................................. 213
<memoryfile> .................................................................................................................. 216
<normalize> .................................................................................................................... 216
<optimisticadd> ............................................................................................................... 218
<prefetch> ....................................................................................................................... 219
<retrylock> ...................................................................................................................... 222
<runitlockdetect> ............................................................................................................. 223
<skiplock> ....................................................................................................................... 224
<smartcopy> ................................................................................................................... 225
<sqlize> ........................................................................................................................... 226
<temporary> .................................................................................................................... 228
www.faircom.com
All Rights Reserved
viii
<transaction> .................................................................................................................. 229
<trxholdslocks> ............................................................................................................... 230
<writethru> ...................................................................................................................... 231
B.3.
Substitution Specifiers ....................................................................................... 231
Appendix C.
c-treeRTG COBOL Edition Directories ............................................. 232
Appendix D. Sample Programs ............................................................................... 235
D.1. The Samples Directory ...................................................................................... 235
D.2. isCOBOL Samples ............................................................................................ 236
Appendix E.
Connecting to the c-treeRTG Server ................................................. 237
Appendix F.
Transaction Processing Notes .......................................................... 238
Appendix G.
Troubleshooting ................................................................................. 239
Appendix H. Logging & Error Codes ...................................................................... 241
H.1. Improved log output with file names on ERROR entries ................................... 241
H.2. Driver Error Codes ............................................................................................ 242
Appendix I.
XDDCHECK Errors ............................................................................... 245
Appendix J.
c-treeRTG Errors ................................................................................. 246
13.
Index ................................................................................................................. 247
www.faircom.com
All Rights Reserved
ix
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.
The c-treeRTG® product line leverages the technology of the c-treeACE® Advanced Core Engine.
Before explaining the details of installation and configuration, this guide will describe the features
common to the c-treeRTG products.
Because the c-treeRTG products are designed as direct replacements for the native file systems,
they require little or no modifications to your application.
Note: c-treeRTG V2 is based on the latest version of the powerful c-treeACE Server. The version
numbers returned from utilities may reflect the underlying core version number of this server,
which is currently V11.x.
How c-treeRTG Empowers Your Applications
The c-treeRTG products allow you to enhance your existing COBOL applications with little or no
development. The c-treeRTG file system allows direct access to your files. By replacing the native
COBOL file system with a specialized version of the c-treeACE Advanced Core Engine,
c-treeRTG brings many of the benefits of c-treeACE to your COBOL applications:
 Transaction Processing (http://www.faircom.com/products/c-treeace/acid-transactions)
 Client/Server Architecture, Sophisticated Caching & Index Compression
(http://www.faircom.com/ace/ace_caches_t.php)
 Multi-User Performance (http://www.faircom.com/ace/ace_performance_t.php)
www.faircom.com
All Rights Reserved
1
 Cross Platform/Multi-Platform Portability
(http://www.faircom.com/ace/ace_cross_platform_t.php)
 Dynamic Backups (http://www.faircom.com/ace/ace_dynamic_dumps_t.php)
 Granular Cache Support (http://www.faircom.com/ace/ace_caches_t.php)
 Memory Files (http://docs.faircom.com/doc/ctreeplus/#29678.htm)
 Minimal Resource Requirements (http://www.faircom.com/ace/ace_smallfootprint_t.php)
 Developer to Developer Support (http://www.faircom.com/ace/support_t.php)
 SQL Access to Your Data (page 174)
To take advantage of the complete set of features available to c-treeACE developers, you may
need to use the c-treeACE Professional SDK in addition to your COBOL application
development. This allows you to use industry-standard APIs such as .NET, Java or C/C++.
Contact FairCom to explore using c-treeACE Professional.
1.1
Documentation Overview
This manual contains the following chapters to help you get up and running with your c-treeRTG
product:
 Begin by performing the setup procedures for the COBOL compiler you are using:
ACUCOBOL-GT Setup (page 5)
Micro Focus COBOL Setup (page 14)
isCOBOL Setup (page 17)
RM/COBOL Setup (page 21)
 Read the following chapters to get your server set up and configured:
c-treeACE Server Setup (page 27)
c-treeRTG Configuration (page 30)
 To migrate your data into c-treeRTG, read this chapter:
Data Conversion (page 44)
 If you are providing SQL access, read these chapters:
c-treeRTG Data: SQL Access (page 54)
Tips for Advanced Sqlizing (page 104)
 A variety of utilities for migrating and other functions are found here:
Utilities: ctutil, ctcbtran, xddgen, cttrnmod, ctmigra, ctfileid (page 118)
 Useful samples are found here:
Samples (page 235)
 Additional useful information can be found in these chapters:
Troubleshooting (page 239)
Logging & Error Codes (page 241)
www.faircom.com
All Rights Reserved
2
1.2
Key Benefits of c-treeRTG COBOL Edition
c-treeRTG provides many features
for the application developer. The
actual features available may be
limited based on the particular
license you have purchased. The
complete list includes:
 Support for ACUCOBOL-GT
Version 6.1.0 and later and
isCOBOL, including the "I$IO"
call.
 Support for Micro Focus
COBOL and other COBOL
dialects through the standard
Callable File Handler interface
(ExtFH).
 No need to recompile your
application.
 Integrated as an additional file system. The file and path management is transparent for both
Vision and c-treeRTG files. Details for handling c-treeRTG files are specified in the
c-treeRTG configuration file. See c-treeRTG File System Details (page 174) in the c-treeRTG
User's Guide.
 c-treeRTG and other file handlers may co-exist in the same application allowing on-the-fly
data conversion from one file system to another.
 Provides a ctutil utility that implements the same functionality as Vision's vutil utility as well
as importing/exporting ASCII files created with the Btrieve butil utility.
 Native COBOL record support with no SQL record buffer conversion which can slow down
your applications.
 SQL support for native data records, including tables that have multiple schema definitions
(redefined fields) in the same table. See Multiple Record Formats
(http://www.faircom.com/ace/ace_multirecformat_t.php) on the FairCom website.
 The cross-platform nature of the c-treeRTG Server, based on the c-treeACE engine, makes it
easy to provide client/server support across multiple platforms including Windows, Linux,
Solaris, Mac OS X, AIX, HP-UX and others.
 The c-treeRTG Server includes industrial-quality on-line transaction processing
(http://www.faircom.com/products/c-treeace/acid-transactions) (OLTP) features that
guarantee ACID (atomicity, consistency, isolation, durability) properties of transactions that
are transparently (to the application) activated on any table.
www.faircom.com
All Rights Reserved
3
2.
c-treeRTG COBOL Edition Quick Start
This section is designed to get you up and running in a hurry.
The first steps establish c-treeRTG as your file handler. After completing these steps, your
applications will have the benefits of performance and stability provided by c-treeRTG; the final
step adds SQL access to your data:
1.
File Handler Installation
The first step is to install the file handler for the type of COBOL you
are using:
• ACUCOBOL-GT Setup (page 5)
• Micro Focus COBOL Setup (page 14)
• isCOBOL Setup (page 17)
• RM/COBOL Setup (page 21)
2.
c-treeRTG Server Setup
(page 27)
The next step is to install the c-treeRTG server (page 27).
3.
c-treeRTG Configuration
(page 30)
Now it is time to configure c-treeRTG. The c-treeRTG configuration
file allows considerable flexibility to handle even complex
environments, so a graphical Configuration Tool (page 34) is
provided to simplify the process.
4.
Data Conversion (page
44)
Before your application can use c-treeRTG, the data must be
converted. c-treeRTG provides GUI and command-line tools for
data conversion (page 44).
5.
SQL Setup (page 54)
The final step is optional.
It is needed if you want
SQL access to your
COBOL data.
Define the record schema of your data in an XDD file and store it in
the data file. See c-treeRTG SQL Access (page 54).
www.faircom.com
All Rights Reserved
4
3.
ACUCOBOL-GT Setup
This chapter describes how to configure your ACUCOBOL-GT installation to use c-treeRTG
COBOL Edition as file handler.
3.1
Recompiling the Runtime
ACUCOBOL-GT requires the runtime to be compiled with the c-treeACE configuration enabled.
The following steps will guide you through this task.
Recompiling the Windows Runtime
Linking the ACUCOBOL-GT runtime with the c-treeACE client libraries requires a suitable
compiler installed:
 ACUCOBOL-GT 6.X requires Microsoft Visual Studio 6.
 ACUCOBOL-GT 7.X and V8X require Microsoft Visual Studio 2005.
 ACUCOBOL-GT 9.X requires Microsoft Visual Studio 2008.
Follow these procedures:
1. Copy the c-tree module ctreeacu.c into the directory that contains the ACUCOBOL-GT
libraries, for example:
copy win32\Driver\ctree.cobol\Acucobol\ctreeacu.c C:\AcuGT\lib
2. Copy the c-tree utilities and DLLs ctutil.exe and mtclient.dll into the directory that contains the
ACUCOBOL-GT binaries, for example:
copy win32\Driver\ctree.cobol\Acucobol\mtclient.dll C:\AcuGT\bin
copy win32\Driver\ctree.cobol\Acucobol\ctutil.exe C:\AcuGT\bin
3. Open the VC++ project located in the ACUCOBOL-GT lib directory and edit the wrundll
project by adding ctreeacu.c. To add the files, click Project from the menu, select Add to
Project and select item Files.
Locate the ACUCOBOL-GT lib directory and select ctreeacu.c.
• ACUCOBOL-GT 6.X:
Open the Visual Studio 6 workspace: wrun32.dsw
• ACUCOBOL-GT 8.X:
Open the Visual Studio 2005 solution: wrun32.sln
ACUCOBOL-GT 9.X:
Open the Visual Studio 2008 solution: wrun32.sln
4. Edit the ACUCOBOL-GT file system configuration file filetbl.c located in the ACUCOBOL-GT
lib directory, for example: C:\AcuGT\lib.
There are three entries to modify:
www.faircom.com
All Rights Reserved
5
ACUCOBOL-GT Setup
a. The original filetbl.c contains the entry:
#ifndef USE_VISION
#define USE_VISION 1
#endif
Add the following additional define section:
#ifndef USE_CTREE
#define USE_CTREE 1
#endif
b. The original filetbl.c contains the entry:
extern DISPATCH_TBL v5_dispatch,...;
Add the following extern definition:
extern DISPATCH_TBL ct_dispatch;
c.
The original filetbl.c contains the entry:
TABLE_ENTRY file_table[] = {
#if USE_VISION
{ &v5_dispatch, "VISIO" },
#endif /* USE_VISION */
#if USE_CTREE
{ &ct_dispatch, "CTREE" },
#endif /* USE_CTREE */
5. Re-build the ACUCOBOL-GT runtime by building the wrun32.dll library. To build this library,
choose Build from the menu and select Build wrun32.dll.
6. Copy the new wrun32.dll to the directory that contains the ACUCOBOL-GT binaries, for
example C:\AcuGT\bin.
7. Verify the link by running wrun32 –vv. This will return version information on all of the
products linked into your runtime system. Ensure it reports the version of the c-tree interface.
For example:
FairCom c-treeACE version 11.0.xxxxx-yymmdd file system (interface
v11.0.xxxxx-yymmdd)
Recompiling the Unix Runtime
1. Copy the c-tree module ctreeacu.c into the directory that contains the ACUCOBOL-GT
libraries, for example:
cp linux.v2.6.x86.32bit.COBOL/Driver/ctree.cobol/Acucobol/ctreeacu.c
/usr/acucbl810/acugt/lib
2. Copy the c-tree utility ctutil and the libmtclient.so library into the directory that contains the
ACUCOBOL-GT binaries:
www.faircom.com
All Rights Reserved
6
ACUCOBOL-GT Setup
cp
linux.v2.6.x86.32bit.COBOL/Driver/ctree.cobol/Acucobol/libmtclient.s
o /usr/acucbl810/acugt/bin
cp linux.v2.6.x86.32bit.COBOL/Driver/ctree.cobol/Acucobol/ctutil
/usr/acucbl810/acugt/bin
3. Edit the ACUCOBOL-GT file system configuration file filetbl.c located in the ACUCOBOL-GT
lib directory, for example: /usr/acucbl810/acugt/lib.
There are three entries to modify:
a. The original filetbl.c contains the entry:
#ifndef USE_VISION
#define USE_VISION 1
#endif
#ifndef USE_CTREE
#define USE_CTREE 1
#endif
b. The original filetbl.c contains the entry:
extern DISPATCH_TBL v5_dispatch,...;
Add the following extern definition:
extern DISPATCH_TBL ct_dispatch;
c.
The original filetbl.c contains the entry:
TABLE_ENTRY file_table[] = {
#if USE_VISION
{ &v5_dispatch, "VISIO" },
#endif /* USE_VISION */
#if USE_CTREE
{ &ct_dispatch, "CTREE" },
#endif /* USE_CTREE */
NOTE: The c-tree entry must be added below the Vision entry so as to leave the
Vision entry the first one in the file_table[] array.
4. Open the file Makefile located in the ACUCOBOL-GT lib, for example:
/usr/acucbl810/acugt/lib.
Add the c-treeRTG AcuCOBOL source module to the line FSI_SUBS=, for example:
FSI_SUBS= < ... > ctreeacu.c
Note: There may be other items already listed in FSI_SUBS. Leave those in place and only
add ctreeacu.c.
5. Re-build the ACUCOBOL-GT runtime by running make –f Makefile.
www.faircom.com
All Rights Reserved
7
ACUCOBOL-GT Setup
6. Copy the new runcbl file to directory that contains the ACUCOBOL-GT binaries, for example
/usr/acucbl810/acugt/bin. This file needs to have the execute permission set for everyone
who will be using the runtime system.
7. Verify the link by running runcbl –vv. This will return version information on all of the
products linked into your runtime system. Ensure it reports the version of the c-tree interface.
For example:
FairCom c-treeACE version 11.x.xxxxx-yymmdd file system (interface
v11.x.xxxxx-yymmdd)
Adding Support for --setenv Command-Line Argument to Runtime
The ACUCOBOL-GT product allows the user to introduce new command line arguments that can
be passed to the ACUCOBOL-GT runtime. The function exam_args() defined in
ACUCOBOL-GT's interface to C module sub.c is called immediately upon startup and is passed
the command line arguments that were passed to the runtime.
The c-tree module ctreeacu.c contains the function ct_exam_args() that provides support
for --setenv command-line argument. The --setenv command-line argument can be used to set
environment variables once the ACUCOBOL-GT runtime has already been started.
To add support for --setenv command-line argument, edit the sub.c module located in the
ACUCOBOL-GT lib directory, for example: /usr/acucbl810/acugt/lib.
1. Add the ct_exam_args() prototype declaration before exam_args() definition as follows:
int ct_exam_args(int argc, char *argv[]);
int
exam_args(int argc, char *argv[])
{
return 0;
} /* exam_args */
2. Change exam_args() to call ct_exam_args() function as follows:
int
exam_args(int argc, char *argv[])
{
return ct_exam_args(argc, argv);
} /* exam_args */
3. Re-compile the ACUCOBOL-GT runtime as described in Recompiling the Windows Runtime
(page 5) or Recompiling the Unix Runtime (page 6).
Once the ACUCOBOL-GT runtime supports the --setenv command line argument, you can call
the runtime passing --setenv:variable=value, for example:
Windows
wrun32.exe cobol_Tutorial1.acu --setenv:DEFAULT_HOST=CTREE
www.faircom.com
All Rights Reserved
8
ACUCOBOL-GT Setup
Unix
runcbl cobol_Tutorial1.acu --setenv:DEFAULT_HOST=CTREE
Troubleshooting
Common errors and relative solutions are described in the following sections.
Error message: "libctclient.so: cannot open shared object file"
If you receive an error such as:
runcbl: error while loading shared libraries: libctree.so: cannot open
shared object file: No such file or directory
Make sure you have the environment variable LD_LIBRARY_PATH (platform specific) set
appropriately to access the c-treeACE library, for example:
LD_LIBRARY_PATH=/usr/acucbl610/acugt/bin;
export LD_LIBRARY_PATH
www.faircom.com
All Rights Reserved
9
ACUCOBOL-GT Setup
3.2
Configuring the Runtime for ACUCOBOL-GT
This section describes how to configure the recompiled ACUCOBOL-GT runtime to use
c-treeRTG.
CTREE_LIB Environment Variable
Specifies the full path of the c-tree library that ACUCOBOL-GT attempts to load. If CTREE_LIB is
not defined then a library named mtclient.dll (Windows) or libmtclient.so (Unix) is searched in the
path.
Windows
set CTREE_LIB=C:\FairCom\V11.x.x.COBOL\win32\Driver\ctree.cobol\ACUCOBOL\mtclient.dll
Unix
CTREE_LIB=/FairCom/V11.x.x.COBOL/linux.v2.6.x86.32bit/Driver/ctree.cobol/ACUCOBOL/libmtclient
.so
export CTREE_LIB
ACUCOBOL-GT Environment Variables
ACUCOBOL-GT allows a program to interface with more than one external file system in the
same program. To define a file system for use with a particular file, you need to set the
filename_HOST configuration variable.
To specify the indexed file system that the program will use by default, you need to set the
DEFAULT_HOST configuration variable.
For an introduction to ACUCOBOL-GT runtime configuration variables and the configuration file,
see section 2.7, Runtime Configuration, in Book 1 of the ACUCOBOL-GT documentation set.
DEFAULT_HOST
DEFAULT_HOST specifies the default file system to be used for all file I/O. Setting
DEFAULT_HOST to CTREE indicates usage of c-tree while setting it to VISION or leaving it unset
indicates usage of Vision. For example, to make c-tree the default file system, set the
environment variable DEFAULT_HOST as follows:
Windows
set DEFAULT_HOST=CTREE
Unix
DEFAULT_HOST=CTREE;
export DEFAULT_HOST
www.faircom.com
All Rights Reserved
10
ACUCOBOL-GT Setup
filename_HOST
This variable specifies the file system to use for a particular file. For example, if DEFAULT_HOST
is set to VISION, and the file CUSTOMERS is a c-tree file, you could set the environment variable
CUSTOMERS_HOST as follows:
Windows
set CUSTOMERS_HOST=CTREE
Unix
CUSTOMERS_HOST=CTREE;
export CUSTOMERS_HOST
This definition directs the runtime to treat CUSTOMERS as a c-tree file. Note that the file name
may not include any path or directory name and should not include the file extension.
DEFAULT_HOST and filename_HOST are described in detail in Appendix H, Configuration File
Entries, in Book 4 of the ACUCOBOL-GT documentation set.
SET ENVIRONMENT ACUCOBOL-GT Verb
When your program executes, each time a file is opened, the ACUCOBOL-GT runtime checks
filename_HOST and DEFAULT_HOST to determine which file system to use. You can change
the value of these variables, just before you open the file, by including the following:
SET ENVIRONMENT "DEFAULT_HOST" TO value
or
SET ENVIRONMENT "filename_HOST" TO value
3.3
Enabling XDDOPEN, XDDCHECK, and XDDCLOSE for
Programmatic SQL Conversion Error Checking
The XDDOPEN, XDDCHECK, and XDDCLOSE commands make it possible to programmatically
check if there will be any conversion errors accessing a table from SQL (see API for SQL
Conversion Error Checking (page 93) for details). This allows them to be called directly from
ACUCOBOL without the necessity to load the mtclient.dll.
To allow these commands to be called from ACUCOBOL, the following modifications are
necessary:
1. Edit the ACUCOBOL-GT file system configuration file direct.c located in the ACUCOBOL-GT
lib directory, for example: /usr/acucbl810/acugt/lib.
2. Search for the struct DIRECTTABLE LIBDIRECT[] array.
3. Just before the array found in step 1, add these three lines:
extern void* ct_XDDOpen();
extern long ct_XDDCheck();
extern void ct_XDDClose();
4. Within the array elements add the following:
{ ""XDDOPEN"", FUNC ct_XDDOpen, C_pointer},
www.faircom.com
All Rights Reserved
11
ACUCOBOL-GT Setup
{ ""XDDCHECK"", FUNC ct_XDDCheck, C_long},
{ ""XDDCLOSE"", FUNC ct_XDDClose, C_void},
5. Make sure the following line (which is already part of the array) is the last one:
{ NULL,
NULL, 0 }
After performing the above steps, XDDOPEN, XDDCHECK, and XDDCLOSE will be directly
callable from the COBOL application.
See Also
 API for SQL Conversion Error Checking (page 93)
3.4
Converting ACUCOBOL Data to c-treeRTG COBOL
Edition Data
This walkthrough describes how to convert existing COBOL data created with the ACUCOBOL
Vision file system to c-treeRTG COBOL Edition data.
If your COBOL program performs OPEN OUTPUT operations, set the file system to CTREE (see
Runtime Configuration (page 28)) before running your program to create files in c-tree format.
If you cannot create files with your COBOL application, ctutil can use your XFD files to create a
new empty file having the same structure described by the XFD files.
The following steps are used to convert ACUCOBOL Vision files into c-tree files. If you have
already created the c-tree files you can jump directly to step 2:
1. To create an empty file using c-treeRTG COBOL Edition, execute ctutil -make passing the
new file name and the XFD file containing its definition:
ctutil -make myctdata mydata.xfd
This command will create a file named myctdata using the image string obtained from the
mydata.xfd.
2. Dump the existing data from the existing mydata data file created using Vision by using the
vutil32 -unload functionality:
vutil32 -unload mydata mydata.dmp
This command will dump the entire contents of the mydata file to a plain text file called
mydata.dmp
3. Load the dumped data into the file created in step 1 using the ctutil -load functionality:
ctutil -load myctdata mydata.dmp A
This command loads the data from the plain text file called mydata.dmp and writes it to the
mydata c-treeRTG COBOL Edition data file.
4. Now the new c-treeRTG COBOL Edition data file mydata can be read through the c-treeRTG
COBOL Edition SQL engine by running the following command:
ctutil -sqlize myctdata mydata.xfd ADMIN ctreeSQL
This command parses the mydata.xfd file and generates an XDD schema definition on the fly
to be used by the c-treeRTG COBOL Edition engine to import the data file as part of a SQL
database.
www.faircom.com
All Rights Reserved
12
ACUCOBOL-GT Setup
www.faircom.com
All Rights Reserved
13
4.
Micro Focus COBOL Setup
c-treeRTG COBOL Edition supports Micro Focus COBOL and other dialects through the standard
Callable File Handler interface, ExtFH. Please refer to your COBOL runtime documentation to
know how to configure your application to use external file handlers.
4.1
Configuring the Runtime for Micro Focus
This section describes how to instruct the Micro Focus File Handler to dynamically load (page 14)
and use the c-treeRTG COBOL Edition file handler.
Alternatively, you can force programs to always use the c-treeRTG COBOL Edition file handler for
processing all COBOL I/O by compiling your application as described in the section titled
Compiling Your Application (Optional) (page 15).
Dynamic Redirection
At runtime set the DYNREDIR environment variable to point to the c-treeRTG COBOL Edition
driver library as follows:
Windows
set DYNREDIR=CTEXTFH.dll!CTEXTFH
Unix
export DYNREDIR=CTEXTFH.so
When using Micro Focus Visual COBOL for Linux a path can be specified for the DYNREDIR
variable.
export DYNREDIR=/usr/local/lib/CTEXTFH.so
When using DYNREDIR with Micro Focus Visual COBOL it is possible to use redirinstance (page
179) without specifying the library and the func. In this case, the c-treeRTG interface will signal to
the COBOL runtime that it does not handle the files and the runtime falls back to the next
filesystem specified by DYNREDIR.
The client library for Micro Focus is available inside the Driver\ctree.cobol\EXTFH\ folder.
www.faircom.com
All Rights Reserved
14
4.2
Recompiling Your Application (Optional)
There are two methods to instruct Micro Focus COBOL to use the c-treeRTG COBOL Edition file
handler:
 Using the CALLFH Compiler Directive (page 15)
 Specifying c-tree as Indexed File Handler at Link Time (page 15)
Using the CALLFH Compiler Directive
Compile your programs with the directive:
$set callfh"CTEXTFH"
Link the c-treeACE CTEXTFH.lib library to your program objects. For example:
COBOL –d –g myprogram.obj _CLASS+CTEXTFH+COBINTFN
This causes all COBOL I/O operations to be compiled into calls to c-treeRTG COBOL Edition
driver.
Please be aware that the c-treeRTG COBOL Edition driver implements support only for indexed
files. If your application uses other types of files, this approach is not viable. Please consider
using the alternative Dynamic Redirection (page 14) approach instead.
Specifying c-tree as Indexed File Handler at Link Time
To link c-tree as indexed file handler with a COBOL program, you must specify the following flags
on the cob command line:
-m ixfile=CTEXTFH to specify ctree as file handler for fixed record length indexed files
-m ixfilev=CTEXTFH to specify ctree as file handler for variable record length indexed files
This ensures that the necessary external references to the ctree library are included in the
resulting executable file, and that they are used instead of the default Micro Focus File Handler.
Examples
cob -x prog.cbl -m ixfile=CTEXTFH -m ixfilev=CTEXTFH CTEXTFH.so
4.3
Configuration Note for Micro Focus on 64-bit AIX
When configuring c-treeRTG for Micro Focus on 64-bit AIX systems, you will need to use the
following settings:
 The <redirinstance> (page 179) properties in the c-treeRTG configuration file, ctree.conf
(page 31), should be set as follows:
lib="libcobrts64.so" func="EXTFH"
For example:
<redirinstance lib="libcobrts64.so" func="EXTFH">
www.faircom.com
All Rights Reserved
15
...
</redirinstance>
 An AIX environment variable must be set as follows:
LDR_PRELOAD64=$COBDIR/lib/libcobrts64.so
www.faircom.com
All Rights Reserved
16
5.
isCOBOL Setup
Veryant isCOBOL ships with a version of the c-treeRTG file system called “c-treeACE for
isCOBOL” (previously known as “isCOBOL ISAM Server”). This file system can be upgraded to
the full version of c-treeRTG COBOL Edition.
c-treeRTG provides a dynamic link library for supporting isCOBOL. This library allows the
c-treeRTG database engine to handle your program’s files. This chapter describes how to
configure your isCOBOL installation to use c-treeRTG.
5.1
Configuring the Runtime for isCOBOL
Upgrading to c-treeRTG
c-treeRTG includes a client DLL and server software that correspond to the c-tree client and
server that originally shipped with isCOBOL.
Replace the corresponding isCOBOL programs with the c-treeRTG programs listed below:
Windows
Linux/Unix
Client (see note below)
Server Executable (see note
below)
ctree.dll
ctreesql.exe
libctree.so
ctreesql
Folder (in the c-treeRTG
distributable)
Driver\ctree.cobol\iscobol\
Server\sql
Server Library
ctreedbs.dll
ctreedbs.so
Server\sql
Note: If you are usIng isCOBOL ACE Bound Server configuration in conjunction with the
isCOBOL Application Server, you do not need to replace the Client or the Server Executable.
Setting the Configuration File
The iscobol.properties file (located in the etc folder) configures isCOBOL. In addition to setting
isCOBOL properties, this file allows you to configure a considerable number of c-treeRTG
properties. As an alternative to using iscobol.properties to configure c-treeRTG, you can use an
external ctree.conf (page 31) file, which provides more configuration options.
The iscobol.properties file contains an entry, iscobol.ctree.new_config, which allows you
to specify which configuration file to use for c-treeRTG:
 iscobol.ctree.new_config=true - (Default) Use the c-treeRTG properties specified in
the iscobol.properties file.
This mode is required if you are using the file system that ships with isCOBOL.
Note: With this setting, you will not use a ctree.conf file for configuration.
 iscobol.ctree.new_config=false - Use the c-treeRTG properties specified outside of
the iscobol.properties file in ctree.conf.
www.faircom.com
All Rights Reserved
17
isCOBOL Setup
This mode is used if you are using the c-treeRTG Server (page 27).
Note: The c-treeRTG properties specified in the iscobol.properties file will not be used for
configuration.
Note: The c-treeRTG Configuration Tool (page 34) provides an easy, graphical interface for
configuring c-treeRTG. The Configuration Tool uses the ctree.conf file, so you must set
iscobol.ctree.new_config=false to use the tool. See the section titled c-treeRTG
Configuration (page 30) for more about using ctree.conf.
Setting the Default File System
isCOBOL allows a program to interface with more than one external file system. It provides a
mechanism for specifying a default file system and a way to override it on a file-by-file basis so
you can specify a different file system for each file.
Using Configuration Variables
Two configuration variables are provided for configuring the file system:
 iscobol.file.index - To specify the indexed file system that the program will use by
default.
 iscobol.file.index.filename - To define a file system for use with a particular file
(.filename). This setting will override the default file system for the file specified.
For an introduction to isCOBOL runtime configuration variables and the configuration file, see
“Configuration” in User’s Guide of the isCOBOL documentation set.
iscobol.file.index
The iscobol.file.index configuration variable specifies the default file system to be used for
file I/O. Setting this variable to ctree2 sets the file system to c-tree; setting it to jisam (or
leaving it unset) sets the file system to JISAM. For example, to make c-tree the default file
system, set the environment variable iscobol.file.index in one of the following ways:
 In the isCOBOL configuration file (usually iscobol.properties):
iscobol.file.index=ctree2
 In the isCOBOL runtime command line:
iscrun –J-Discobol.file.index=ctree2 PROGRAMNAME
 In the system environment on Windows:
SET file.index=ctree2
 In the system environment on Unix:
file.index=ctree2
export file.index
www.faircom.com
All Rights Reserved
18
isCOBOL Setup
iscobol.file.index.filename
The iscobol.file.index.filename configuration variable specifies the file system to use
for a specified file. It overrides the default file system for the filename indicated. For example, if
the default file system is jisam and the file customers is a c-tree file, you would set the
environment variable iscobol.file.index.customers as follows:
 In isCOBOL configuration file (usually iscobol.properties):
iscobol.file.index.customers=ctree2
 In isCOBOL runtime command line:
iscrun –J-Discobol.file.index.customers=ctree2 PROGRAMNAME
 In system environment, Windows:
SET file.index.customers=ctree2
 In system environment, Unix:
file.index.customers=ctree2
export file.index
Using the SET ENVIRONMENT Verb
When your program executes, each time a file is opened, the isCOBOL runtime checks
iscobol.file.index.filename and iscobol.file.index to determine which file system
to use. You can change the value of these variables before you open the file by including the
following:
SET ENVIRONMENT "file.index" TO value
or
SET ENVIRONMENT "file.index.filename" TO value
Using the CLASS Clause
isCOBOL allows you to associate a file handler in the logical file declaration in the program
source code. The specified file handler will be used for that logical file regardless of the physical
name of the file. The following file declaration makes FILE1 a c-tree file regardless of the value
you may assign to FILE1-NAME before opening FILE1.
SELECT FILE1 ASSIGN TO FILE1-NAME
ORGANIZATION INDEXED
CLASS "com.iscobol.io.DynamicCtree2"
ACCESS DYNAMIC
RECORD KEY FILE1-KEY.
Setting isCOBOL to Use c-treeRTG
To set isCOBOL to use c-treeRTG:
1. Replace the client library as described earlier.
2. Add the following line to the iscobol.properties file (located in “etc” folder) to force it to use an
external configuration file (ctree.conf):
iscobol.ctree.new_config=false
www.faircom.com
All Rights Reserved
19
isCOBOL Setup
False allows ctree.conf to be used; all c-treeRTG properties in the iscobol.properties file will
be ignored.
3. Put the iscobol.properties file in the same directory as the COBOL program, or set the PATH
environment variable to include it, so the isCOBOL runtime can access it.
4. Make sure the isCOBOL runtime is not controlling versions between client and server. Add
versioncheck="no" in ctree.conf as a property:
<instance server="[email protected]" versioncheck="no">
5. To test if isCOBOL is properly set, run the following:
iscrun -J-Discobol.file.index=ctree2 com.iscobol.rts.Version
You will see a message that references the version of FairCom being used:
isCOBOL release 2012 R2 build#705.12-20130110-15175 DB FairCom
c-treeACE;x.x.x.xxxx-xxxxxx;x.x.xxxxx-xxxxxxC/S Version 0020 License
info VERYANT##303564/00599991231
5.2
Troubleshooting
Common errors and their solutions are described below.
Error message: java.lang.UnsatisfiedLinkError
If you receive an error such as:
Exception in thread "main" java.lang.UnsatisfiedLinkError: no ctree in java.library.path
make sure you have the environment variable LD_LIBRARY_PATH (platform specific) set
appropriately to access the c-treeACE library, for example:
LD_LIBRARY_PATH=/opt/isCOBOL/native/lib;
export LD_LIBRARY_PATH
isCOBOL Fails to Run cobol_Tutorial1
The tutorial will fail if you have the following setting in iscobol.properties:
iscobol.io_creates=1
If you ran the tutorial with iscobol.io_creates=1 enabled, comment out that setting and
delete the custmast.dat and custmast.idx files.
www.faircom.com
All Rights Reserved
20
6.
RM/COBOL Setup
c-treeRTG COBOL Edition supports COBOL runtimes that use Btrieve as their underlying file
system by including support for Btrieve commands in the c-treeRTG COBOL Edition driver. This
support allows programs written in RM/COBOL to handle files using c-treeRTG.
This chapter describes how to configure your RM/COBOL installation to use c-treeRTG COBOL
Edition as the file handler.
6.1
Installing the RM/COBOL Driver
RM/COBOL typically calls a Btrieve library. To use the new c-treeRTG Btrieve functions, you will
need to replace the Btrieve library with the c-treeRTG COBOL Edition library, as described below.
Installing the RM/COBOL Driver on Windows
The Windows driver is located at:
Driver\ctree.cobol\rm-cobol\mtclient.dll
To install the driver for RM/COBOL on systems running Windows:
1. Make a backup copy of the original Btrieve library WBTRV32.DLL and save it for
safekeeping.
2. Rename the FairCom c-treeRTG library with the same name as the original Btrieve library
(typically WBTRV32.DLL).
3. Be sure the FairCom c-treeRTG library has precedence over the original Btrieve library in the
PATH environment variable.
Installing the RM/COBOL Driver on Linux
The Linux driver is located at:
driver\ctree.cobol\rm-cobol\libmtclient.so
To install the RM/COBOL driver on systems running Linux:
1. Make a backup copy of the original Btrieve library libpsqlmif.so.8 and save it for safekeeping.
Hint: This may be found in two locations. Look in /usr/local/psql/lib as well as /usr/rmcobol.
2. Rename the c-treeRTG library with the same name as the original Btrieve library
(libpsqlmif.so.8).
3. Be sure the c-treeRTG library has precedence over the original Btrieve library in the
LD_LIBRARY_PATH environment variable.
www.faircom.com
All Rights Reserved
21
RM/COBOL Setup
6.2
Adjusting the RM/COBOL Configuration File
The RM/COBOL-to-Btrieve Adapter program for Linux, librmbtrv.so (Linux) or WBTRV32.DLL
(Windows), is initiated by placing the following configuration record in the RM/COBOL
configuration file (see the EXTERNAL-ACCESS-METHOD configuration record for more
information on specifying keywords) and starting the RM/COBOL runtime system:
EXTERNAL-ACCESS-METHOD NAME=RMBTRV
Notes:
1) Version 7.1 and later of RM/COBOL for Unix and version 7.5 and later of RM/COBOL for
Windows allow a configuration file to be located automatically by the RM/COBOL runtime system,
the compiler, and the recovery utility. If the Automatic Configuration File module, librmconfig.so
(UNIX) or librmcfg.dll (Windows), is present in the RM/COBOL execution directory, it will be
loaded and it will attempt to locate an automatic configuration file. The execution directory on
UNIX is normally /usr/bin; on Windows it is normally C:\Program Files\RMCOBOL.
2) If you want a configuration file to by loaded automatically, you need a file named runcobol.cfg
(for the runtime system), rmcobol.cfg (for the compiler), or recover1.cfg (for the recovery utility) in
the execution directory. If the appropriate file is present, the records in the file will be used to
configure the component being executed.
3) The Windows version of RM/COBOL allows configuration files to be physically attached to
rmcobol.exe, runcobol.exe, and recover1.exe using the Attach Configuration utility
(rmattach.exe). The attached configuration will be processed prior to a configuration file specified
by a command-line option. If automatic configuration finds a configuration file, an attached
configuration is ignored.
Configuration Options
The following option designates a file to be used as the complete runtime configuration or as a
supplement to it and allow suppression of the banner and STOP RUN messages.
Use the C Option to designate a file to be used as the runtime configuration. If the C Option is
specified, any attached or automatic configuration is ignored (not processed). The C Option has
the following format:
C=pathname
6.3
Copying the RM Library to the Local Folder
The RM library must be copied to the local folder where you are running the RM/COBOL runtime.
Place the RM library (for Linux: librmbtrv.so) in the same directory as the RM/COBOL runtime
system (runcobol). Typically, the support module is copied into the execution directory (for Linux:
/usr/rmcobol, /usr/local/bin, or /usr/bin).
6.4
Adjusting the Paths
Linux must be able to locate the various executable files that are required. For this support
module to be loaded properly, you must make sure that you have set the LD_LIBRARY_PATH
environment variable. Add the directory that contains the Pervasive libraries, DSOs (dynamic
shared objects), to LD_LIBRARY_PATH. For example:
export LD_LIBRARY_PATH=/usr/local/psql/lib:/usr/lib
www.faircom.com
All Rights Reserved
22
RM/COBOL Setup
Note that if you logged into the system as "psql" these paths will have already been set. To verify
that the shared object, librmbtrv.so, is being loaded properly by the RM/COBOL runtime, type the
following from the shell command line (for more information about the V Option, see
Configuration Runtime Command Options):
runcobol xxx -v
If the following line is displayed in the RM/COBOL runtime banner, the RM/COBOL-to-Btrieve
Adapter for Linux has been loaded correctly:
$EXEDIR/librmbtrv.so - RM/COBOL Btrieve Adapter - Version n.nn.nn.
6.5
Multiple File Systems with RM/COBOL
The demonstration below shows that it is possible to have an RM/COBOL application that opens
some files with the default file system and some files with c-treeRTG WITHOUT any special
configuration of c-treeRTG.
The attached sample program creates two files: custmast and itemmast. Run it with RM/COBOL
to create the files.
$ runcobol cobol_Tutorial2
INIT
DEFINE
Create table CustomerMaster...
Add records in table CustomerMaster...
Create table ItemMaster...
Add records in table ItemMaster...
MANAGE
Display records...
1000
Bryan Williams
1001
Michael Jordan
1002
Joshua Brown
1003
Keyon Dooling
1
Hammer
2
Wrench
3
Saw
4
Pliers
DONE
Press <ENTER> key to exit . . .
ls *mast*
custmast itemmast
At this point you have an RM/COBOL application that opens multiple files, however you can use
c-treeRTG only on one file.
Create a runcobol.cfg file in the execution directory as follows:
www.faircom.com
All Rights Reserved
23
RM/COBOL Setup
echo EXTERNAL-ACCESS-METHOD NAME=RMBTRV32 CREATE-FILES=YES OPTIONS='T=RMBTRV32.log'
>runcobol.cfg
Install the c-treeRTG library:
cp whatever/libmtclient.so ./libpsqlmif.so.8
export LD_LIBRARY_PATH=.:$LD_LIBRARY_PATH
Configure c-treeRTG to enable logging so we can see that it is working:
echo \<config\>\<log/\>\</config\> >ctree.conf
$ cat ctree.conf
<config><log/></config>
Start the c-treeRTG server and then re-run the program to check that c-treeRTG is called by
noticing the log output with the "missing file" errors (15:12:2):
INIT
DEFINEF7FDFAC0> 20160708T115945 api:0324:ctl_init
INFO client version:11.3.0.11002-160706
id:34
F7FDFAC0> 20160708T115945 api:4473:ctl_setins INFO server version:11.3.0.11002-160706
id:34
F7FDFAC0> 20160708T115945 core:3091:cts_open
ERROR 15:12:2
OPNRFIL(/home/fctech/rtg.rm/160707/bin.mtc32bitdynamic/custmast.dat,129)
F7FDFAC0> 20160708T115945 core:3091:cts_open
ERROR 15:12:2
OPNRFIL(/home/fctech/rtg.rm/160707/bin.mtc32bitdynamic/itemmast.dat,129)
MANAGE
Display records...
1000
Bryan Williams
1001
Michael Jordan
1002
Joshua Brown
1003
Keyon Dooling
1
Hammer
2
Wrench
3
Saw
4
Pliers
DONE
Now remove the custmast file and re-run the program to re-create the custmast.dat file with RTG
(notice the "Create table CustomerMaster..." message):
$ rm custmast
www.faircom.com
All Rights Reserved
24
RM/COBOL Setup
INIT
DEFINEF7F0DAC0> 20160708T120309 api:0324:ctl_init
id:34
F7F0DAC0> 20160708T120309 api:4473:ctl_setins INFO server version:11.3.0.11002-160706
id:34
F7F0DAC0> 20160708T120309 core:3091:cts_open
ERROR 15:12:2
Create table CustomerMaster...F7F0DAC0> 20160708T120309 core:3091:cts_open
F7F0DAC0> 20160708T120309 core:3091:cts_open
ERROR 15:12:2
ERROR 15:12:2
Add records in table CustomerMaster...F7F0DAC0> 20160708T120309 core:3091:cts_open
15:12:2 OPNRFIL(/home/fctech/rtg.rm/160707/bin.mtc32bitdynamic/itemmast.dat,129)
ERROR
MANAGE
Display records...
1000
Bryan Williams
1001
Michael Jordan
1002
Joshua Brown
1003
Keyon Dooling
1
Hammer
2
Wrench
3
Saw
4
Pliers
DONE
Verify that the file is created with c-treeRTG (file name ends with .dat and .idx extension):
$ ls custmast*
custmast.dat custmast.idx
Now re-run the program to check that it works with both the default file system and c-treeRTG:
INIT
DEFINEF7EF3AC0> 20160708T120931 api:0324:ctl_init
id:34
F7EF3AC0> 20160708T120931 api:4473:ctl_setins INFO server version:11.3.0.11002-160706
id:34
F7EF3AC0> 20160708T120931 core:3091:cts_open
ERROR 15:12:2
OPNRFIL(/home/fctech/rtg.rm/160707/bin.mtc32bitdynamic/itemmast.dat,129)
MANAGE
Display records...
1000
Bryan Williams
www.faircom.com
All Rights Reserved
25
RM/COBOL Setup
1001
Michael Jordan
1002
Joshua Brown
1003
Keyon Dooling
1
Hammer
2
Wrench
3
Saw
4
Pliers
DONE
Please notice above that c-treeRTG attempts to open itemmast.dat but it fails with "missing file"
error (15:12:2) so RM/COBOL falls back to use the default file system. You can see that
itemmast was opened because the itemmast records are read and displayed (Hammer, Wrench,
etc.)
6.6
Additional Documentation
 RM/COBOL User’s Guide V7.5 for UNIX and Windows:
http://downloads.microfocus.com/Liant/download/pdf/rmcug75.pdf
 Additional Notes on new editions of RM/COBOL V10.0:
http://downloads.microfocus.com/Liant/download/pdf/rmdrm1001.pdf
www.faircom.com
All Rights Reserved
26
7.
c-treeRTG products use a version of the c-treeACE database engine, the c-treeRTG Server,
which integrates server-side logic to implement many of the product features.
Note: c-treeRTG V2 is based on the latest version of the powerful c-treeACE Server. The version
numbers returned from utilities may reflect the underlying core version number of this server,
which is currently V11.x.
7.1
c-treeRTG for Windows
The c-treeRTG installer for Windows creates a Microsoft Windows service that automatically
starts the database engine at Windows startup. This allows for seamless and unattended
operation. Use the standard Windows service control panels to start/stop and configure various
service options.
VSS Backup - c-treeRTG for Windows supports the Windows Volume Shadow Copy Service
(VSS) Writer for backups. This support is supplied as a dynamic link library
(c-treeACEVSSWriter.dll) that allows Windows VSS Backup to be used. Contact FairCom for
information about using VSS.
7.2
c-treeRTG for Unix
The c-treeRTG tar archive for Unix contains a ready-to-run c-treeACE database engine:
cd /FairCom/Vx.x.x.RTG/<platform>/server/sql
./ctreesql
Feel free to include it along with your /etc/init.d startup scripts for fully unattended operation.
Consult your local Unix administrator for details about specific machine configurations.
7.3
Shared Memory for c-treeRTG
c-treeRTG supports the shared memory communication protocol between clients and servers
residing on the same machine. Shared memory communication generally provides much better
performance for locally running applications.
Note: Shared memory support does not include Linux Kernels 2.4 or Mac OS X systems.
The c-treeACE shared memory communication protocol creates a file used by clients to find the
shared memory identifier for its shared memory logon region, and creates a Unix domain socket
as a file for initial communication between a client and server.
www.faircom.com
All Rights Reserved
27
Configuration
Include the following server configuration in ctsrvr.cfg to enable this support:
COMM_PROTOCOL FSHAREMM
c-treeACE creates the directory /tmp/ctreedbs and the file /tmp/ctreedbs/<servername>.logon.
This file name is determined by the value specified with the SERVER_NAME configuration option.
This file contains an identifier of a shared memory region used for clients to connect. The
following configuration option allows this directory to be directly specified:
SHMEM_DIRECTORY (/doc/ctserver/#57538.htm) <directory_name>
c-treeACE must have sufficient read, write, create, and delete permissions with this directory. The
following server keyword sets the shared memory resource permissions:
SHMEM_PERMISSIONS <permissions>
The default is 660. Caution: A setting of 666 allows access to c-treeACE by any user account,
permitting any user to attach to a shared memory segment and read or write to it, which may
cause a security breach.
By default, a client application must belong to the server owner’s primary group to use shared
memory. This is configurable with the SHMEM_GROUP keyword.
SHMEM_GROUP
<group>
Possible errors indicating problems:
FSHAREMM: Could not get group ID for group <group> for shared memory
FSHAREMM: Failed to set group for LQMSG shared memory region: X
Client Configuration
On Unix/Linux system it is necessary to set the CTREE_SHMEM_DIRECTORY environment
variable. This allows the directory to be dynamically overridden without having to recompile the
client code.
7.4
Runtime Configuration
ACUCOBOL-GT allows a program to interface with more than one external file system in the
same program.
To specify the indexed file system that the program will use, you must set the DEFAULT_HOST
configuration variable. For example, to define a file system for use with a particular file, you set
the filename_HOST configuration variable.
For an introduction to ACUCOBOL-GT runtime configuration variables and the configuration file,
see section 2.7, "Runtime Configuration," in Book 1 of the ACUCOBOL-GT documentation set.
Micro Focus COBOL can be configured to use external file handlers in two different ways: you
can insert the CALLFH directive inside your COBOL program and recompile it, or you can use
dynamic redicrection. Please refer to you Micro Focus COBOL documentation.
www.faircom.com
All Rights Reserved
28
7.5
Configure the c-treeRTG Server
Note: The c-treeRTG server (a specialized version of c-treeACE) is configured separately from
the c-treeRTG client. Client configuration is discussed in the next section, c-treeRTG
Configuration (page 30).
For information about configuring the
c-treeRTG Client, see the c-treeRTG
Configuration (page 30) chapter in this
manual.
For information about configuring the c-treeRTG Server, refer to the
Configuring the c-treeACE Server chapter of the c-treeACE Server
Administrator's Guide (http://docs.faircom.com/doc/ctserver/).
The c-treeRTG Server has a multitude of options for configuring many of the various database
subsystems including:
 Data and index cache control
 Transaction logging features
 Memory files
 Backup scripts
 Diagnostic options
 Operational statistics logging
Unless otherwise instructed, the c-treeRTG Server starts with default settings for all configurable
parameters. The c-treeRTG Server takes configuration instructions from a configuration file,
ctsrvr.cfg, placed in the c-treeRTG Server directory. When the c-treeRTG finds a ctsrvr.cfg file, it
uses all the specified configuration values.
c-treeRTG is delivered with appropriate settings for the server. If you want to change these
settings, the ctsrvr.cfg file can be edited using the c-treeACE Config Manager, located in:
FairCom\vX.X.X.RTG\<platform>\Tools\gui\c-treeConfigManager.exe (where
FairCom\vX.X.X.RTG\<platform>\ is the installation directory).
For more information, refer to Configuring the c-treeACE Server in the c-treeACE Server
www.faircom.com
All Rights Reserved
29
8.
The c-treeRTG file system is designed for easy configuration and requires little if any ongoing
maintenance. The c-treeRTG database engine uses a client/server architecture. The c-treeRTG
Server is a specialized version of c-treeACE, which is configured separately from the c-treeRTG
client. Client configuration is discussed in this section. A graphical Configuration Tool (page 34) is
provided to simplify the process.
Information about configuring the c-treeRTG
Client is provided in this chapter in this
manual.
For information about configuring the c-treeRTG Server, refer to
Configure the c-treeRTG Server (page 29) in this book and the
Configuring the c-treeACE Server chapter of the c-treeACE Server
Configure while You Migrate
If you migrate your data using the RTG Migrate graphical tool, you can create a basic
configuration file in the final step of the wizard, as described in RTG Migrate (page 45).
Much of the information you need for configuring your system is entered when you migrate your
data. If your system has additional considerations that dictate a more complex configuration file
(such as files that need to be treated specially, multiple clients, servers, etc.), this chapter will
explain how to edit the configuration file to make adjustments.
If you create a configuration file when you migrate your data, you can skip the Basic
Configuration wizard and edit the resulting file as described in Editing a Configuration File
(page 42).
www.faircom.com
All Rights Reserved
30
8.1
c-treeRTG Configuration File
The configuration of c-treeRTG is controlled by an XML file called ctree.conf by default. Because
it is an XML file, it uses the same syntax for both Windows and Unix.
The c-treeRTG Configuration Tool (page 34) is provided to greatly simplify configuration. To get
the most out of your c-treeRTG system, it is important to know its layout and to understand the
c-treeRTG configuration options available. In this way, your system can be configured to best suit
your needs.
Configuration File Format
The XML configuration file uses a tree structure that follows the hierarchy of parent/child
relationships described below:
 <config> (page 176) - The <config> element is the root of the XML configuration file. As the
root element, it is the parent of the child elements below it. It is used as a container for all the
other elements. It does not have any attributes.
• Settings Elements (page 183) - The <config> root element may contain zero or more
global settings, which apply to the entire hierarchy unless overridden at a lower level. The
settings elements configure the desired settings, such as turning data compression on or
off.
• <instance> (page 177) - The <config> root element can contain zero or more
<instance> elements.
Each <instance> element represents a connection to the c-treeRTG server. When
creating a new instance, you will need to supply the server name, user name, password,
etc., which are attributes of the element. (If no <instance> element is present in the
configuration file, the system will use a default of <instance server="FAIRCOMS">.)
Settings applied within the <config> root element apply to all <instance> elements within
the root element.
 Settings Elements (page 183) - Within each <instance> element there can be zero or
more settings elements. Each settings element specifies an optional configuration
setting, such as turning data compression on or off, which applies only to its parent
instance.
 <file> (page 181) - Within an <instance> element there can be zero or more <file>
elements. Each <file> element specifies the configuration for one or more files
identified by a name and/or dir (directory) attribute. Wildcard file matching rules (page
182) can be used.
 Each <file> element can have multiple attributes (e.g., name) and settings elements
(e.g., compression, encryption, transaction processing).
Structure Elements, Settings Elements, and Attributes
The <config> root element (page 176), the <instance> (page 177) (and<redirinstance> (page
179)) elements, and the <file> element (page 181) are called Structure Elements because they
define the architectural structure of your particular c-treeRTG system.
Most structure elements have attributes that provide details to describe the element (e.g., a file
element uses a name or directory attribute to specify one or more files).
www.faircom.com
All Rights Reserved
31
The structure elements may contain Settings Elements (page 183). These elements configure the
desired settings for their parent structure element. For example, a <file> element may use a
<datacompress> settings element to turn data compression on or off for certain files (which are
specified by attributes of the <file> element).
Remember: The configuration file is a hierarchy, so settings made a higher level (closer to the
root) can be overridden by settings applied to an individual child element. Settings specified by
Option Elements in a child element overwrite the values inherited from higher levels in the
hierarchy. The following rules apply:
 Settings applied within an <instance> or <file> element apply only to that element.
 Settings applied within an <instance> or <file> element override settings inherited from higher
levels in the hierarchy.
 Settings applied within an <instance> element apply to all <file> elements specified within
that element.
Setting elements can be specified as children of <config>, <instance>, and <file> but
actually apply only to file elements if a setting element is not specified as a child of file.
c-treeRTG considers file extensions to be part of file name. If you want to override the suffix, use
the <datafilesuffix> (page 190) configuration option.
If no file paths are specified, the LOCAL_DIRECTORY setting in ctsrvr.cfg comes into play. This
implies that ctree.conf takes precedence over ctsrvr.cfg.
See Also
 For an example of a configuration file, with explanations of the elements and a picture of how
it is depicted in the Configuration Tool, see The c-treeRTG Configuration Tool (page 34).
 To check the syntax of your configuration file, see ctutil -test (page 152).
 For definitions of the elements, see Configuration File Elements (page 175).
 For Micro Focus on 64-bit AIX, see Configuration Note for Micro Focus on 64-bit AIX (page
15).
8.2
Support for Encrypting the Configuration File
It is possible to prevent the user from seeing the user password in ctree.conf by using
configuration files that are encrypted. The typical configuration files in XML format can be
encrypted using the ctutil command -cryptconf (page 132). Usage:
ctutil -cryptconf
config_file output_file
Notice: For security reasons, FairCom does not provide a way to decrypt an encrypted
configuration file. Hence, it is advisable to maintain a “clear text” version of ctree.conf in a safe
place for future reference.
See
 -cryptconf (page 132)
www.faircom.com
All Rights Reserved
32
8.3
CTREE_CONF Environment Variable
The CTREE_CONF environment variable specifies the full path to the configuration file. If
CTREE_CONF is not defined, c-treeRTG searches for a file named ctree.conf in the current
directory (the directory of execution of the user application that loads c-treeRTG).
Windows
set CTREE_CONF=C:\MyConfigFiles\my.ctree.cobol.conf
Unix
CTREE_CONF=/etc/MyConfig/my.ctree.cobol.conf
export CTREE_CONF
8.4
CTREE_CONF_DUMP environment variable to specify
configuration dump file
The CTREE_CONF_DUMP environment variable allows the c-treeRTG configuration to be saved to
a specified file in XML format. If the value of this environment variable is a file name, c-treeRTG
dumps its configuration in XML format to the specified file after c-treeRTG has been initialized
with a ctree.conf or iscobol.properties configuration.
This feature can be used as a way to migrate the isCOBOL configuration options related to
c-treeRTG from iscobol.properties format to ctree.conf format.
www.faircom.com
All Rights Reserved
33
8.5
c-treeRTG Configuration Tool - RTG Config
The c-treeRTG Configuration tool, RTG Config, provides a graphical interface for configuring the
c-treeRTG products. This tool helps you to edit the XML file, ctree.conf, which is used to
configure these products. It also tests ctree.conf for correctness, so you can use it to find any
problems with a ctree.conf you have edited by hand.
The RTG Config tool, RTGConfig.jar, is located in the Tools\guitools.java\ directory.
The ctree.conf file consists of a collection of elements nested in a hierarchy. The <config>
element is the root of the hierarchy. It will have one or more <instance> elements below it. Both
<config> and <instance> can have other elements beneath them (e.g., <file>). Options (such as
data compression) can be applied to elements in the tree. The tool displays descriptions of the
selected elements and options. (For more complete definitions of the elements, see Configuration
File Elements (page 175). For more about the file format see c-treeRTG Configuration File (page
31)).
The Configuration Tool depicts the XML hierarchy as a tree. The tree is composed of:

Elements (e.g., config, instance, file, etc.) are depicted as folders. These elements
define the basic structure you will configure. Each configuration file has a single <config>
element with at least one <instance> under it. See Structure Elements (page 175).

Attributes (e.g., name) are depicted as red dots (a summary of attributes also appears
after the name of each element). They are details that further describe an element (e.g., a file
element is specified with a name or directory attribute).

Options (e.g., datacompression) are depicted as blue dots. They are optional settings
that can be applied to an element. See Settings Elements (page 183).
www.faircom.com
All Rights Reserved
34
You can click the + or - buttons next to each branch to expand or collapse it. The tool bar
provides Expand Tree
and Collapse Tree
buttons to quickly hide or show all details.
The Show Attributes button allows you to hide or display attributes to simplify viewing the tree.
The image above depicts the following XML configuration file, ctree.conf (data compression will
be active for all the specified instances but not for the third instance ("FAIRCOM3") which
specifies its own datacompress setting):
<?xml version="1.0" standalone="yes"?>
XML header.
<config>
This is the root element; all of the other elements and settings
are subordinate to it.
This option element is immediately under the root level, so it
applies compression to all elements (unless it is overridden at
a lower level).
This structure element specifies an instance of a connection to
a c-treeRTG server, called FAIRCOMS, specified by the
server= attribute.
This structure element uses the name= attribute to specify the
CUSTORDR file, which is on the FAIRCOMS c-treeRTG server
because this element is a child of that instance.
The end of the FAIRCOMS instance.
<datacompress>yes</datacompress>
<instance server="[email protected]">
<file name="CUSTORDR"/>
</instance>
<file name="ITEMMAST"/>
An instance of a connection to a c-treeRTG server called
FAIRCOM2.
This structure element specifies the ITEMMAST file on the
FAIRCOM2 c-treeRTG server.
www.faircom.com
All Rights Reserved
35
</instance>
The end of the FAIRCOM2 instance.
This structure element specifies an instance of a connection to
a c-treeRTG server called FAIRCOM3.
<datacompress>no</datacompress>
This settings element turns off compression for its parent
instance, FAIRCOM3.
<file name="CUSTMAST"/>
This structure element specifies the CUSTMAST file on the
FAIRCOM3 c-treeRTG server.
</instance>
</config>
The end of the FAIRCOM3 instance.
The end of this configuration file.
For more about the file format, see c-treeRTG Configuration File (page 31).
Configuration Tool Menus
The following menus are provided:
File
 New (Basic) - Create a simple configuration file.
 New (Advanced) - Create a new configuration file (see below).
 Open - Opens a configuration file.
 Save - Saves the current configuration file.
 Save As - Allows the current configuration file to be saved under a new name.
 Exit - Closes the tool and exits.
Actions
 Remove Item - Removes the selected item from the configuration file.
Help
 About - Displays information about the version of the tool.
Tool Bar
The following controls are provided in the tool bar:

New File (Basic) - See Creating a New File (Basic) (page 38). Create a basic
configuration file. The Basic Configuration window will appear so you can create a new
configuration file.

New File (Advanced) - See Creating a New File (Advanced) (page 40). Create a new
configuration file.

Open a File - Opens a configuration file.

Save Current File - Saves the current configuration file.

Expand Tree - Expands the display of the tree to show all branches so that the full
contents of the file can be seen. You can click the - buttons next to each branch to collapse it.
www.faircom.com
All Rights Reserved
36

Collapse Tree - Collapses the display of the tree to show all branches so that only the
top level of the file can be seen. You can click the + buttons next to each branch to expand it.

- Use this button to display or hide the attributes of the elements. Showing
attributes depicts attributes as separate items in the tree; hiding them can make it easier to
see the entire tree.
Creating/Editing Your Configuration File
The RTG Config tool provides two ways to create your configuration file:
 Basic Configuration - This simple, two-step wizard guides you through the configuration
process to get started in a hurry. Fill in the fields to create a configuration file that connects to
a single c-treeRTG server. If you require a more advanced configuration, you can start with
the Basic Configuration wizard and then use the RTG Config to edit the file. See Creating a
New File (Basic) (page 38).
 Advanced Configuration - The RTG Config allows you to create and edit a configuration
file. Selecting File > New (Advanced) (or clicking on the corresponding hot button), clears
any entries shown in the RTG Config tree view (and prompts you to save changes, if any)
and starts a new configuration. You can then add the elements required for your
environment. See Creating a New File (Advanced) (page 40).
See also
 Editing a Configuration File (page 42)
www.faircom.com
All Rights Reserved
37
Creating a New File (Basic)
The Basic Configuration wizard allows you to configure your system in a hurry. This wizard will
help you create a configuration file for a system that connects to a single c-treeRTG server. It
offers a rich set of options, so it may be all you need to get going.
If your system is more advanced, for example if it connects to multiple c-treeRTG servers, you
can start with the Basic Configuration wizard and then edit the results in the RTG Config tree
window (or you can simply start with New File (Advanced)). If you created a basic configuration
file when you migrated your data with the RTG Migrate tool, you can skip the Basic Configuration
wizard and edit the resulting file as described in Editing a Configuration File (page 42).
To create a new configuration file using the Basic Configuration wizard:
1. Select File > New (Basic) or click the New File (Basic) hot button:
If you have unsaved changes in the configuration shown in the tree, you will be prompted to
save them.
The Basic Configuration wizard will appear:
2. Fill in the fields listed in this dialog. The first tab, called Create Instance, is where define your
connection to the c-treeRTG server.
Instance - These fields define how you log onto the c-treeRTG server:
Server - Specifies the server name and the host name of the c-treeRTG to connect to. The
format can be one of the following syntaxes:
servername
servername@hostname
www.faircom.com
All Rights Reserved
38
servername@IPaddress
If the host name or the IP address is omitted, host name defaults to localhost.
User - Specifies the c-treeRTG user name.
Password - Specifies the c-treeRTG user password.
Instance Global Options - These fields define attributes that apply to this entire connection
to the c-treeRTG server. Many options are available, including transaction processing,
encryption, compression, logging, and file name suffixes. The options provided here
correspond to the configuration Settings Elements (page 183) defined later in this manual.
3. The Files / Directories Maps tab allows you to enter more information about the location of
your files.
Notice that these fields accept wildcards. See Wildcard File Matching Rules (page 182) and
File Matching Precedence (page 183).
4. Click Create to save your file. A file dialog will allow you to select a folder and file name for
the configuration file.
The new configuration file will be displayed in the RTG Config showing the instance you created.
You may now add elements as described in the later sections, Editing a Configuration File
(page 42).
www.faircom.com
All Rights Reserved
39
Creating a New File (Advanced)
To create a new configuration file:
1. Select File > New (Advanced) or click the New File (Advanced) hot button:
If you have unsaved changes in the configuration shown in the tree, you will be prompted to
save them.
A new configuration will be created in the tree with a single root element, <config>.
2. Each configuration file requires at least one <instance> element. You will need one instance
for each connection to a c-treeRTG server.
To add a new instance, right-click on the <config> root element and select Add New
Element > Instance. The New Instance dialog appears so you can enter the basic
information needed for specifying the c-treeRTG server.
Note: If your environment includes more than one c-treeRTG server, you will need to create
an instance for each one. Each instance will be directly under the root <config> element. To
add another instance, right-click the <config> element and select Add New Element >
Instance.
3. Fill in the fields listed in this dialog:
www.faircom.com
All Rights Reserved
40
Server - Specifies the server name and the host name of the c-treeRTG to connect to. The
format can be one of the following syntaxes:
servername
servername@hostname
If the host name or the IP address is omitted, host name defaults to localhost.
User - Specifies the c-treeRTG user name.
Password - Specifies the c-treeRTG user password.
Connect - Choose the desired setting to indicate whether to connect to c-treeRTG at runtime
initialization or wait for the first OPEN operation.
• Not Set - Use the default value.
• Yes - Connect at runtime initialization.
• No - Connect during the first OPEN operation. This is the default value.
Versioncheck - Choose the desired setting to indicate whether to check that the c-treeRTG
version matches the c-treeRTG version.
• Not Set - Use the default value.
• Yes - Turn on version matching check. Versions must match exactly otherwise an error is
returned at runtime initialization.
• No - Turn off version matching check. This is the default value.
4. A file dialog will allow you to select a folder and file name for the configuration file.
The new configuration file will be displayed in the RTG Config showing the instance you created.
You may now add elements as described in the subsequent sections, Editing a Configuration
File (page 42).
www.faircom.com
All Rights Reserved
41
Editing a Configuration File
The configuration file consists of a collection of elements and attributes nested in a hierarchy. The
hierarchy is depicted by the tree displayed in the Configuration Tool. The tool allows you to edit
the tree by adding and removing elements and attributes. The tool displays information about the
selected elements and attributes.
To add an element to the file:
1. Select an existing element in the file. The new element will be placed under the selected
element (e.g., the selected element will be the parent of the new element: if you select
<config>, the new element will be a child of <config>; if you select <instance>, the new
element will be a child of <instance>).
2. Right-click on the selected element and select Add New Element from the menu that
appears.
3. Select the desired element from the list of valid elements that appears.
The list shows only elements that can be used at the selected location in the tree. This
implies that the list will be different depending on the element selected in step 1.
4. The new element will be placed in the tree.
5. The new element will be given a default value. A list labeled Name and Value is shown in the
right side of the tool. Edit the value in that list to set the desired value.
www.faircom.com
All Rights Reserved
42
To add an attribute to an element:
1. Select an existing element in the file. The new attribute apply to the selected element (e.g.,
the selected element will be the parent of the new attribute).
2. Right-click on the selected element and select Add New Attribute from the menu that
appears.
3. Select the desired attribute from the list of valid attributes that appears.
The list shows only those attributes that can be used at the selected location in the tree, so
the list will be different depending on the element selected in step 1.
4. The new attribute will be placed in the tree under the selected element.
5. The new attribute will be given a default value. A list labeled Name and Value is shown in the
right side of the tool. Edit the value in that list to set the desired value.
To remove an element from the file:
1. Right-click on the element.
2. Select Remove Item from the menu that appears.
To check the syntax of your configuration file and see if it can connect to the server, see ctutil
-test (page 152).
www.faircom.com
All Rights Reserved
43
9.
Data Conversion
Migrating Your Data to c-treeRTG COBOL Edition
Before your application is ready to use c-treeRTG COBOL Edition, the data must be converted to
a format that can be used by c-treeRTG. This is a one-time process that must be done before you
can use c-treeRTG.
c-treeRTG provides a GUI tool to aid in migration, RTG Migrate (page 45), as well as a
command-line utility, ctmigra (page 50).
SQL Access
If you will be accessing your data using SQL, you will need to see c-treeRTG SQL Access (page
54).
Configuring Your System
You can create a basic configuration file when you migrate your data with the RTG Migrate tool.
This is done in the final step of the wizard, as described in RTG Migrate (page 45).
Much of the information you need for configuring your system is entered when you migrate your
data, so the configuration file you create may handle your environment with no changes. If you
have additional considerations that dictate a more complex configuration file, such as files that
need to be treated specially, multiple clients, servers, etc., you will need to edit the resulting
configuration file as described in Editing a Configuration File (page 42).
www.faircom.com
All Rights Reserved
44
Data Conversion
9.1
RTG Migrate
The RTG Migrate tool provides a graphical interface to help you migrate data into c-treeRTG
applications by reading records from an external database and writing them to c-treeRTG files.
This tool provides functionality similar to the command-line version, ctmigra (page 50).
The RTG Migrate tool, RTGMigrate.jar, is located in the Tools\guitools.java\ directory. Use the
RTGMigrate.bat batch file to run this utility.
Note: This utility requires a c-treeRTG DLL located in the driver directories (for example,
Driver\ctree.cobol.extfh). If you know the path to this directory, you can add it to your PATH
environment variable. The RTGMigrate.bat batch file correctly sets the path for you and runs the
utility.
You will see four tabs in the RTG Migrate tool, which correspond to the four steps in migration:
 One - Source Environment - Allows you to prepare for the migration.
 Two - Source Files - Indicates the source of the data you will be migrating to c-treeRTG.
 Three - Destination - Indicates the destination of the migrated data, which must be
accessible to the c-treeRTG system.
 Four - Migrate - Begins the migration process.
One - Source Environment
The first tab of the RTG Migrate tool (shown above) is where you prepare for the migration. The
controls are grouped by function:
www.faircom.com
All Rights Reserved
45
Data Conversion
Migration Origin
 Select original environment - Select ExtFH for Micro Focus and other compilers that use
this file system or select PSQL / BTRV for Btrieve files. The Check Library button tests the
presence of the native library to convert data from the original format to the c-treeRTG
format.
 Select the source base directory of the source files - Enter the directory that contains the
source files or click the three dots to navigate to it.
 Optional Btrieve owner name - If you are migrating from Btrieve files (PSQL / BTRV) to
indicate the owner.
After entering the information in the fields, click the Next button to advance to the next tab.
Two - Source Files
Use this tab to select the data files to be migrated. The data will be read out of these files and
copied to the destination you specify in the next tab. The original files will not be altered in the
process.
Do not specify index files because they will be created as part of the migration.
The file system is shown in the tree view on the left. Click to the notes to expand them and click
on the files to select the ones to be migrated.
File Filter
The field labeled File Filter allows you to specify a mask using wildcards. Click Apply to apply
changes to the mask.
www.faircom.com
All Rights Reserved
46
Data Conversion
Click the Next button to advance to the next tab.
Three - Destination
Destination
 Index Filename Extension - Enter the suffix of the destination index file name (default:
.idx).
 Index Filename Extension Mode - Select Append to if you want the extension entered to
be appended to the file name or select Replace to have it replace an extension already in the
file name.
 Replace Existing Files - Select whether or not to overwrite existing files.
 Destination Base Path - Enter the path to the destination root directory. Migrated files and
directories will be placed under this directory on the destination host. This path can be
relative to the c-treeRTG LOCAL_DIRECTORY or it can be an absolute path.
 Encryption, Compression, Transaction - You can also set other parameters.
www.faircom.com
All Rights Reserved
47
Data Conversion
Resulting Directory
The Resulting Directory layout shows indexes with their names and it highlights conflicts.
c-treeRTG Server Connection Information
The destination server is the server to which the migrated files will be copied.
 Server Name, User Name, Password - Enter the login information for the destination server.
 Test Connection - The Test Connection button in the c-treeRTG RTG Migrate tool allows
you to check the configuration by pinging the server.
Note: If you see an error message "Could not find RTG library" it is because the proper driver
directory (e.g., Driver\ctree.cobol\extfh) is not in the path. A batch file, RTGMigrate.bat, will
run the utility without having to set the PATH environment variable.
Click the Next button to advance to the next tab.
Four - Migrate
Migration
 Batch Size - Enter the number of records to read/write in batches. This setting may affect the
speed of the conversion by grouping the records into batches that will be inserted into the
database together. Increasing the size of the batches reduces the number of inserts and
speeds performance, as long as system resources (e.g., memory) permit.
www.faircom.com
All Rights Reserved
48
Data Conversion
 Log File - Enter the name of the file to log additional information. To redirect log to stderr,
enter a dash (-).
 Script Name - If you want to create a script that can be run later, enter a file name for the
script here and click the Create Script button.
 Create Script - Click this button if you want to create a file containing a script that can be run
later. The file name will be the name entered in Script Name. The script will contain the
ctmigra command with the appropriate command-line parameters based on the options you
have entered in this tool.
 Configuration Filename - If you want to create a basic configuration file containing the
information you have entered in this wizard, enter a file name in this field and click the Create
Conf. File button.
 Create Conf. File - Click this button if you want to create a basic configuration file containing
the information you have entered in this wizard. The file name will be the name entered in
Script Name. This configuration file can be edited in the RTG Config tool if you need to
further refine your configuration for your environment.
Click Migrate to begin migration. Alternatively, you can use the Create Script button to create a
script that can be used later with the ctmigra utility.
You can click Stop Migration at any time to halt the operation.
www.faircom.com
All Rights Reserved
49
Data Conversion
9.2
ctmigra
ctmigra is a general purpose data migration utility for converting non-c-tree data for use with
c-treeRTG. It can be used with multiple external data types, including COBOL and Btrieve data
files. For certain data types, such as Btrieve, this also requires access to your original external
libraries used to access incoming source files in their native format, and ctmigra has ability to link
with these libraries as required.
ctmigra migrates data by reading records from existing external tables and writing them to
c-treeRTG files. Supported interfaces include ExtFH, providing access to Micro Focus COBOL
files, and BTRV, providing access to Btrieve files. It also supports other file handlers.
ctmigra is located in the tools\cmdline directory of your c-treeRTG installation. A graphical
interface version RTG Migrate (page 45) is also available providing similar functionality in an
easy to view window. You'll find this in your tools/guitools.java of your c-treeRTG installation.
ExtFH support has been improved in the latest version of ctmigra. With this support, ctmigra
provides an easy way to migrate data from compilers that use ExtFH into an application that uses
c-treeRTG.
Updates include:
 support for mapped names in ExtFH redirinstances
 check for source file not found
 display of error message when library cannot be loaded
How to Use
Usage of c-treeRTG ctmigra depends on your native data file types and your platform.
Usage
ctmigra btrv|extfh [OPTIONS] SOURCE DEST
where:
 SOURCE - name of the file to be copied.
 DEST - name of the file to which it will be copied.
Options for c-treeRTG Files
 -n SERVERNAME or --dest-server=SERVERNAME where SERVERNAME is the name of the
destination c-treeACE Server
 -u USERID or --dest-user=USERID where USERID is the user name of the destination
c-treeACE Server
 -p PASSWORD or --dest-password=PASSWORD where PASSWORD is the user password
of the destination c-treeACE Server
 -I STRING or --dest-idx-suffix=STRING where STRING is the suffix of destination index file
name
 -N SERVERNAME or --source-server=SERVERNAME where SERVERNAME is the name of
the source c-treeACE Server
www.faircom.com
All Rights Reserved
50
Data Conversion
 -U USERID or --source-user=USERID where USERID is the user name of the source
c-treeACE Server
 -P PASSWORD or --source-password=PASSWORD where PASSWORD is the user
password of the source c-treeACE Server
 -i STRING or --source-idx-suffix=STRING where STRING is the suffix of source index file
name
 -l FILE or --log=FILE where FILE is the name of the file to log additional information. To
redirect log to stderr use - as FILE
 -b RECORDS or --batch-size=RECORDS where RECORDS is the number of records to read
/ write in batches
 -a (--append-ext) appends index extension instead of replacing data extension.
 -o OWNER (--owner=OWNER) specifies the BTRV file owner (can be used if you
encountered an error 51 when attempting to migrate).
 -r (--replace) instructs ctmigra to replace the existing destination file (V11 and later).
External Library Configuration for Native File Access
For certain data types, such as BTRV, original external libraries are required to access native
data formats.
 -s LIBRARY!FUNCTION or --source-lib=LIBRARY!FUNCTION where LIBRARY is the
external dynamically loadable library and FUNCTION is the interface entry-point function to
handle the source file
 -d LIBRARY!FUNCTION or --dest-lib=LIBRARY!FUNCTION where LIBRARY is the external
dynamically loadable library and FUNCTION is the interface entry-point function to handle the
destination file
Note: Current usage options are always available when no command-line options are supplied.
Alternative Usage
In some cases, ctmigra can be used with existing local c-treeRTG configuration files. For
example:
ctmigra btrv|extfh -c CONFIG_FILE SOURCE DEST
where:
 SOURCE - name of the file to be copied
 DEST - name of the file to which it will be copied
 -c CONFIG_FILE or --config=CONFIG_FILE where CONFIG_FILE is a valid c-treeRTG
configuration file.
BTRV Conversion Example
To copy and convert data from BTRV files into c-treeRTG, use ctmigra as shown below:
Windows x86
ctmigra.exe btrv –s WBTRV32.DLL S:\Data.PSQL\MYFILE D:\Data.RTG\MYFILE.dat
www.faircom.com
All Rights Reserved
51
Data Conversion
Windows x64
ctmigra.exe btrv –s w64btrv.dll S:\Data.PSQL\MYFILE D:\Data.RTG\MYFILE.dat
Unix/Linux
./ctmigra btrv –s libpsqlmif.so /data.psql/myfile /data.rtg/myfile.dat
Micro Focus COBOL Example
To copy and covert data from Micro Focus COBOL tables into c-treeRTG, use ctmigra as
follows:
ctmigra extfh -s C:\MICROFOCUS\lib\MFFH.DLL!MFFH S:\Data.MF\MYFILE D:\Data.RTG\MYFILE.dat
To use ctmigra with Unix-based Micro Focus libraries be sure and pre-load them with the
LD_PRELOAD environment variable or an alternative mechanism.
For example, on an AIX 64-bit platform (this is all on a single command line):
LDR_PRELOAD64=libcobrts64.3.so:libcobcrtn64.3.so:libcobmisc64.3.so ctmigra extfh -s
libcobrts64.3.so!EXTFH /data/mf/myfile /data/rtg/myfile.dat
For example, on a Linux 32-bit platform (this is all on a single command line):
LD_PRELOAD=libcobrts.so:libcobcrtn.so:libcobmisc.so ctmigra extfh -s libcobrts.so!EXTFH
/data/mf/myfile /data/rtg/myfile.dat
Potential Errors and Troubleshooting
BTRV Error: -7
Your native source library is likely not available. Check the path to
your native data file handling library and be sure it is specified with
the --source-lib= option.
BTRV Error: 53
Attempted to open a non-BTRV file via a BTRV interface.
This can possibly happen when you load a 32-bit BTRV DLL with a
64-bit version of the tool, or vice versa.
Error messages displayed by the c-treeRTG ctmigra utility have been enhanced as follows:
 It now displays actual file names instead of $SOURCE$ and $DEST$.
 It now displays an error message if the source or destination c-tree Servers are not running
(c-tree error 133).
 It now displays an error message if the user/password is not correct (c-tree error 450/451) or
GUEST logon is disabled (c-tree error 470).
 It now displays an error message if c-tree Server is not valid due to OEM version
incompatibility (c-tree error 530).
 It now displays an error message if the specified external library cannot be loaded.
Behavior Change: This modification changes the behavior of the ctmigra tool.
www.faircom.com
All Rights Reserved
52
Data Conversion
New c-treeRTG V2 Options
New options have been added to the ctmigra command-line utility and the RTG Migrate tool.
These options allow you to set encryption, data compression, and transaction support in the
destination c-tree files.
ctmigra Usage:
 -e, --encrypt=CIPHER - Encrypt destination file with CIPHER algorithm.
 -z, --datacompress=TYPE[;LEV][;STR] - Compress destination data file with TYPE algorithm.
 -t, --transaction=no|yes|logging - Create destination data file with or without transaction
support.
These three options enable the following configuration options on the destination file
(corresponding to -e, -z, and -t respectively):
<encrypt type="CIPHER">
<datacompress type="TYPE"= level="LEV" strategy="STR">
<transaction logging="no|yes">
ctmigra --quiet and --verbose options to select output information
These options for the ctmigra command-line utility suppress all output (--quiet or -q) or select the
information to be sent to stdout (--verbose=LEVEL or -v). The --verbose parameter is a bitmask
which can combine the following values:
1 - show message about final result
2 - show percentage progress
4 - show time spent in migration phases (read, write, finalize)
For example, to display everything, use --verbose=7, which is 1+2+4. If not specified, the
--verbose level is 3 (1+2).
The --quiet option is identical to --verbose=0.
www.faircom.com
All Rights Reserved
53
10. c-treeRTG SQL Access
c-treeRTG offers more than just a high-performance file system. The c-treeRTG SQL database
engine opens a new and efficient method to access your data from many other applications via
SQL. By avoiding the overhead imposed by many hybrid SQL implementations, c-treeRTG gives
you the most direct access available.
COBOL and Btrieve data files do not explicitly define a record schema, which is mandatory for
SQL. If you want to provide SQL access to this data, you will need to define the record schema
through an XDD (eXternal Data Definition) file. The XDD is an external XML file that is stored as a
special resource within the data file created through the processes described in this chapter.
FYI: If your data file contains more than one record schema (REDEFINES), c-treeRTG provides
an ability to define multiple record schemas, each of which will appear to SQL as a virtual table.
See the c-treeDB Virtual Tables (http://docs.faircom.com/wp/mrt/#cover.htm) technical white
paper on the FairCom website.
The procedures in this chapter are optional: they are needed only if you want SQL access to your
COBOL data. There are two main parts to this process:
1) Create an XDD
First, you will define the record schema of your data with an XDD file. The method you will use
depends on the compiler you are using:
 Creating an XDD from an XFD (page 55): If your compiler can create an XDD, you can
generate the XDD from it.
 Creating an XDD from the COBOL Source (page 56): If your COBOL compiler does not
provide an XFD, you can generate the XDD from COBOL source.
 Creating an XDD Manually (page 57): If you do not have an XFD or source, you can
manually create an XDD. Users of c-treeRTG BTRV Edition who desire SQL access to their
data will need to use these procedures.
2) Store the XDD in the data file (page 58)
Next, you will store the XDD in the file and link it to the c-treeACE SQL dictionaries using ctutil
-sqlize.
Note: In some cases, these procedures will not produce the desired results because your data
may be structured in a way that cannot be interpret correctly. In those situations, you will need to
add directives to your copybook to handle the data. If the procedures in this chapter are not able
to sqlize your data as expected, see Tips for Advanced Sqlizing (page 104).
www.faircom.com
All Rights Reserved
54
c-treeRTG SQL Access
10.1
Creating an XDD from an XFD
If your COBOL compiler can provide an XFD, it can be used to
create the XDD required for sqlizing your data.
If your COBOL compiler cannot provide an XFD, see the section
Creating an XDD from COBOL Source (page 56).
If your compiler can create an XFD, you can generate the XDD from
it using ctutil -xfd2xdd (page 158) or ctutil -sqlize (page 151).
Use the ctutil utility with the -xfd2xdd (page 158) parameter to
create a valid XDD file starting from an XFD file, which can the
generated by COBOL compilers such as ACUCOBOL.
You can specify a rules file to fine-tune the creation of the XDD, as described in Defining
External Rules (page 59).
If you need to further fine-tune the XFD, it can be edited with an XML editor before it is stored in
the data file.
If you use ctutil -xfd2xdd (page 158) to create the XDD, follow the procedures in the section titled
Storing the XDD in the Data File (page 58) to prepare your data file for SQL access.
www.faircom.com
All Rights Reserved
55
10.2
Creating an XDD from the COBOL Source
If you do not have an XFD, c-treeRTG allows you to create the XDD
from your COBOL source code. The XDD is generated from COBOL
source code using xddgen (page 160). This command-line utility
analyzes the COBOL program to determine the schema. You will
specify the COBOL program file as input. A variety of other
parameters allow you to specify the dialect of COBOL
(ACCUCOBOL, Micro Focus, IBM, etc.), source format (free or
fixed), directories, and other options.
The section titled Tips for Advanced Sqlizing (page 104) explains
the process using a tutorial provided with c-treeRTG. It provides
step-by-step instructions to guide you through the process.
After creating the XDD, use the procedures in the section titled Storing the XDD in the Data File
(page 58) to prepare your data file for SQL access.
www.faircom.com
All Rights Reserved
56
10.3
Creating an XDD Manually
If you do not have access to an XFD or to your COBOL source,
c-treeRTG allows you to create an XDD manually.
Users of c-treeRTG BTRV Edition who do not have a DDF can use
these procedures if they desire SQL access to their data.
The XDD file can be created using any XML editor.
To manually create an XDD, you will need to know the structure of
your data. You will then need to translate that structure into an XDD.
The XDD is explained in the section titled XDD File Schema (page
69).
After creating the XDD, use the procedures in the section titled Storing the XDD in the Data File
(page 58) to prepare the data file for SQL access.
www.faircom.com
All Rights Reserved
57
10.4
Storing the XDD in the Data File
After creating an XDD, the information in that file will need to be
stored in the data file.
Use the ctutil -sqlink (page 149) command to make an existing data
file accessible from SQL by linking the file name to the c-treeACE
SQL dictionaries.
After You Have Sqlized
After you have stored the XDD in the data file, you have finished
sqlizing and you are ready to take it for a test spin. Experiment with
some sample data to see if the process yielded the expected results.
Be aware of two factors that may affect the results:
 Some COBOL fields do not translate well to SQL. For example a text field may be used to
store a date in a human-readable format that has no meaning to SQL.
 Some COBOL programing practices, such as REDEFINES, do not lend themselves to
relational access.
c-treeRTG provides tools to help you fine-tune your installation to overcome these problems. In
particular, review these sections:
 Troubleshooting Data Conversion Errors (page 87)
 Tips for Advanced Sqlizing (page 104) (COBOL only)
You will find an abundance of useful information in this guide, such as c-treeRTG Errors (page
246), API for SQL Conversion Error Checking (page 93) (COBOL only), XDD File Schema (page
69), and Background Information about Sqlizing (page 97).
www.faircom.com
All Rights Reserved
58
10.5
Defining External Rules
When generating a XDD file from an XFD file, it is useful to have an automated method for
altering the resulting XDD to better fit user requirements (e.g., to add defaults, hide fields, etc.).
The "rules file" provides an automated method to control the process using rules saved in XML
format.
The rules file must be specified when using the ctutil -sqlize option or the ctutil -xfd2xdd option
to generate an XDD.
XFDRules
XML rules files have the following structure:
<XFDrules>
<rule>
<when> OPTIONAL
<"condition"> </"condition">
...
More <"condition"> elements
...
</when>
<do>
<"action">
<"target"> </"target">
...
More <"target"> elements
...
</"action">
...
More <"action"> elements
...
</do>
</rule>
...
More <rule> elements
...
</XFDrules>
Example 1
Here is an example demonstrating all hidden fields, as it deletes all the attributes
hidden="true".
<rule sequence="1">
<when>
<field hidden="true"/>
</when>
<do>
<delete>
</delete>
</do>
</rule>
Example 2
COBOL types mapped to date, datetime, or time may cause conversion issues if the COBOL data
cannot be properly represented by a type of date, datetime, or time. Hence it may be useful to
www.faircom.com
All Rights Reserved
59
have a rule to set fields to NULL when a conversion error occurs on the schemas having a field
mapped to a date, datetime, or time field. Here is a rule to do that for date fields:
<rule sequence="2">
<when>
<field dbtype="date"/>
</when>
<do>
<set>
<schema OnConvertError="null"/>
</set>
</do>
</rule>
www.faircom.com
All Rights Reserved
60
<XFDrules> root element
This is the root element used to contain all the rules to apply to the XDD file.
<XFDrules>
</XFDrules>
Elements
Element
Description
<rule> (page 62)
Define one rule, this element can be repeated to define multiple rules.
www.faircom.com
All Rights Reserved
61
<rule> XFDRules element
The rule tag defines a rule to be applied to the XDD file.
There must be at least 1 rule element. In case of multiple rule elements, they define multiple
rules. All of the rules defined will be checked, and, if the <when> condition is satisfied, applied in
defined ascending numeric sequence.
<XFDrules>
<rule>
</rule>
<XFDrules>
Elements
Element
Description
<when> (page 63)
Defines the condition when to apply the current rule. This element is
optional and if missing the rule will always be applied. This can only be
specified once.
<do> (page 65)
Defines the action to apply to the XDD file. This element can only be
defined once.
Mandatory Attributes
Attribute
Description
sequence
Defines the numerical order of the defined rules. The rules will be
evaluated and applied in the specified order.
Optional Attributes
Attribute
Description
debug
The name of the file containing information about rule matching and
execution. If the file exists, the output will be appended. The file will be
created in the current directory if the path is not specified along with this
attribute.
See Also
 <XFDrules> (page 61)
www.faircom.com
All Rights Reserved
62
<when> rule element
The optional <when> element is used to specify the criteria identifying if the rule should be
applied or not. If there is no when tag then the rule always applies.
<XFDrules>
<rule>
<when>
</when>
</rule>
</XFDrules>
Elements
Element
Description
Condition (page 64)
Defines the condition when to apply the current rule. This element can
be specified only once for each rule.
See Also
 <rule> (page 62)
www.faircom.com
All Rights Reserved
63
<[Condition]> when elements
The condition elements are used by the <when> element to identify when the current rule will be
applied. A condition rule is satisfied if all the specified attributes match the matching element of
the XDD file:
 <table> condition is satisfied if all attributes specified in the rule condition matches the
<table> tag of the XDD file.
 <schema> condition is satisfied if all attributes specified in the rule condition matches the
<schema> tag of the XDD file.
 <field> condition is satisfied if all attributes specified in the rule condition matches the <field>
tag of the XDD file.
The condition elements are mutually exclusive and contain the attributes of the element with the
same name as the XDD file.
If more condition elements are specified the current rule will be applied if all the conditions are
satisfied:
 <table> used to describe a condition to verify on the <table> element (page 71) of the XDD
file.
 <schema> used to describe a condition to verify on all the <schema> elements (page 81) of
the XDD file.
 <field> used to describe a condition to verify on all the <field> elements (page 83) (children of
the <schema> element (page 81) element) of the XDD file.
<XFDrules>
<rule>
<when>
<"Condition">
</"Condition">
</when>
</rule>
</XFDrules>
Attibutes
 For <table> condition element attributes refer to the attributes list of the <table> element
(page 71) of the XDD file.
 For <schema> condition element attributes refer to the attributes list of the <schema>
element (page 81) of the XDD file.
 For <field> condition element attributes refer to the attributes list of the <field> element (page
83) (children of the <schema> element (page 81) element) of the XDD file.
See Also
 <when> (page 63)
www.faircom.com
All Rights Reserved
64
<do> rule element
The <do> element describes the action to apply by this rule. If a <when> element (page 63) is
also specified the action will be applied only if all the Condition elements (page 64) are verified.
<XFDrules>
<rule>
<do>
</do>
</rule>
</XFDrules>
Elements
Element
Description
Action (page 66)
Defines which action the rule will execute. This element can be defined
multiple times to specify different actions.
See Also
www.faircom.com
All Rights Reserved
65
<[Action]> do elements
The action elements define which action to execute for the current rule. If a <when> element
(page 63) is also defined, the actions will be executed only if all conditions are verified.
There are 4 different types of action elements:
 <add> This action adds new attributes to the matching element in the XDD file. The attributes
will be added only if they do not exist.
 <set> This action changes the value of the attributes to the matching element in the XDD file.
If the specified attributes do not exist they will be added.
 <modify> This action changes the value of the attributes to the matching element in the XDD
file. The attributes will be changed only if they exist.
 <delete> This action removes an existing attribute to the matching element in the XDD file.
<XFDrules>
<rule>
<do>
<"Action">
</"Action">
</do>
</rule>
</XFDrules>
Elements
Element
Description
Target
Defines the target to identify which element the rule touches. This
element can be specified multiple times to apply more changes in the
XDD file.
See Also
 <do> (page 65)
www.faircom.com
All Rights Reserved
66
<[Target]> action element
Target elements are used by the <do> elements to identify which element the rule touches.
The target elements are mutually exclusive and contain the attributes of the element with the
same name of the XDD file.
More target elements can be specified:
 <table> used to describe a change to make on the <table> element (page 71) of the XDD file.
 <schema> used to describe a change to make on one of the <schema> element (page 81) of
the XDD file.
 <field> used to describe a change to make on one of the <field> element (page 83) (children
of the <schema> element (page 81) element) of the XDD file.
<XFDrules>
<rule>
<do>
<"Action">
<"Target">
</"Target">
</"Action">
</do>
</rule>
</XFDrules>
Attibutes
 For <table> target element attributes please refer to the attributes list of the <table> element
(page 71) of the XDD file.
 For <schema> target element attributes please refer to the attributes list of the <schema>
element (page 81) of the XDD file.
 For <field> target element attributes please refer to the attributes list of the <field> element
(page 83) (children of the <schema> element (page 81) element) of the XDD file.
See Also
 <do> (page 65)
 <"Action"> (page 66)
www.faircom.com
All Rights Reserved
67
Rule Examples
The example below shows the following rules, which will be applied in the order shown below
(based on "sequence="):
 When the field type="NumUnsigned", add bindefault="all-spaces".
 When the field dbtype="date", add field cbdefault="0".
 When the field name="CUSTOMER_ID", set field onConvertError="null".
 When the field dbtype="date", add field cbdefault="0" onConvertError="null" and add field
format="YYYYMMDD" cbdefault="0" onConvertError="error".
<rule sequence="100">
<when>
<field type="NumUnsigned"/>
</when>
<do>
<add>
<field bindefault="all-spaces"/>
</add>
</do>
</rule>
<when>
</when>
<do>
<add>
<field cbdefault="0"/>
</add>
</do>
</rule>
<when>
<field name="CUSTOMER_ID"/>
</when>
<do>
<set>
<field onConvertError="null"/>
</set>
</do>
</rule>
<when>
</when>
<do>
<add>
<field cbdefault="0" onConvertError="null"/>
</add>
<add>
<field format="YYYYMMDD" cbdefault="0" onConvertError="error"/>
</add>
</do>
</rule>
www.faircom.com
All Rights Reserved
68
10.6
XDD File Schema
The XDD file is an XML file used to define the indices and various record schemas present in a
data file. You should have a working knowledge of XML and a solid knowledge of the data
structure to manually create an XDD.
The following sections describe the various tags needed to compose a complete XDD file.
Remember that XML tags and their attributes are case-sensitive.
XDD File Structure
The example below shows the basic structure of an XDD. The elements listed are defined in
more detail in the sections that follow.
<table>
<key>
<part> </part>
...
More <part> elements
...
</key>
<filters>
<field> </field>
...
More <field> elements
...
<filter>
<"Operator">
<field> </field>
<value> </value>
</"Operator">
</filter>
...
More <filter> elements
...
</filters>
<schema>
<field> </field>
...
More <field> elements
...
</schema>
...
More <schema> elements
...
</table>
See Also
 <table> root element (page 71)
 <key> table element (page 72)
 <part> key element (page 73)
 <segment> key element (page 74)
 <filters> table element (page 75)
 <field> filters element (page 76)
www.faircom.com
All Rights Reserved
69
 <filter> filters element (page 77)
 <[Operator]> filter element (page 78)
 <field> operator element (page 76)
 <value> operator element (page 80)
 <schema> table element (page 81)
www.faircom.com
All Rights Reserved
70
<table> root element
The <table> element is the top level (root) element describing the table schema. It defines the
record length and the table name.
The table element can be easily defined from the information about the data structure contained
in the FILE SECTION of the COBOL source. The maxRecLen and the minRecLen attributes are
the same in the case of fixed length records and are equal to the sum of the lengths of all fields.
When a variable length record is defined, the minRecLen and maxRecLen attributes can be
extracted from the RECORD CONTAINS clause of the COBOL source FILE SECTION.
<table>
</table>
Elements
Element
Description
<key> (page 72)
Defines one key. This element can be repeated to define multiple
indices.
<filters> (page 75)
Defines the filters to separate the records between the various record
schemas. This element will be defined once if needed.
<schema> (page 81)
Defines a single record schema with its fields, this element can be
repeated to define different record schemas.
Attribute
Description
maxRecLen
Defines the maximum record length in bytes.
minRecLen
Defines the minimum record length in bytes (9 bytes for huge files; 5
bytes for non-huge files).
Optional Attributes
Attribute
Description
name
The name of the physical file without extension.
www.faircom.com
All Rights Reserved
71
<key> table element
The <key> element specifies the definition of one index present in the data file. All the information
specified must match the IFIL index definitions of the c-tree file.
The <key> element can be defined from the information contained within the COBOL
FILE-CONTROL section combined with the specifications of the RECORD definition from the
COBOL source. The duplicate attribute will always be false for the RECORD KEY. For the
ALTERNATE KEY, the duplicate attribute will be true if the alternate key accepts duplicates
(WITH DUPLICATES) otherwise false. The segCount clause is the number of the fields
composing every key.
<table>
<key>
</key>
</table>
Elements
Element
Description
<part> (page 73)
Describes one of the fields composing the key. This element must be
repeated to define all the fields composing the key.
Optional Attributes
Attribute
Description
duplicate
Indicates whether the index can contain duplicates. Allowed values are
"false" if the index cannot contain duplicates, "true" otherwise. The
default value is "false"
primary
Indicates whether the index will act as the table SQL primary key. Set
this attribute to "true" to use the index as a SQL primary key. Please
note that only one primary key is allowed for each table. The default
value is "false."
See Also
 <table> (page 71)
www.faircom.com
All Rights Reserved
72
<part> key element
The <part> elements of a key are used to enumerate the fields composing the key.
<table>
<key>
<part>
</part>
</key>
</table>
Attribute
Description
offset
A number defining the offset of the first byte composing the field.
size
A number defining the size in bytes of the field.
Optional Attributes
Attribute
Description
name
A string defining the field name. It should match field names defined in
the <field> (page 83) children elements of <schema> (page 81)
elements.
See Also
 <key> (page 72)
www.faircom.com
All Rights Reserved
73
<segment> key element
The <segment> elements of a key are used to enumerate the segments composing the key.
These elements are optional (not used by SQL). They are used to be able to create another table
with exactly the same structure.
<table>
<key>
<segment>
</segment>
</key>
</table>
Attribute
Description
offset
A number defining the offset of the first byte composing the segment.
size
A number defining the size in bytes of the segment.
See Also
 <key> (page 72)
www.faircom.com
All Rights Reserved
74
<filters> table element
The filters element is used to specify how records will be filtered between the various record
schemas, as SQL tables may only have one record schema defined per table. This element can
be avoided if the COBOL data file contains just one record schema.
The filters can be defined into a COBOL source from the $XFD WHEN clauses. The field element
will be defined by all the fields called from all the $XFD WHEN clauses from the COBOL source.
<table>
<filters>
</filters>
</table>
Elements
Element
Description
<field> (page 76)
This element is used to enumerate the fields used to filter records.
<filter> (page 77)
Defines the method to filter records.
See Also
www.faircom.com
All Rights Reserved
75
<field> filters element
The <field> element (children of the <filters> element (page 75)) is used to define a field which
will be used during filtering operations.
<table>
<filters>
<field>
</field>
</filters>
</table>
Attribute
Description
name
A string defining the field name. It should match field names defined in
the <field> (page 83) children elements of <schema> (page 81)
elements.
offset
A number indicating the offset of the first byte composing the field.
size
A number indicating the size in bytes of the field.
type
A string defining the data type. Please refer to the type mapping table
(page 86).
See Also
 <filters> (page 75)
www.faircom.com
All Rights Reserved
76
<filter> filters element
The <filter> element defines the rule identifying records belonging to a schema. The filter element
will contain only one of the operator elements specified below. Every filter element should match
with a $XFD WHEN clause.
<table>
<filters>
<!-field tags>
<filter>
</filter>
</filters>
</table>
Operator Elements
Element
Description
<eq> (page 78)
If this tag is used the filter will be based on an equal comparison.
<neq> (page 78)
If this tag is used the filter will be based on a not equal comparison.
<lt> (page 78)
If this tag is used the filter will be based on a less than comparison.
<lte> (page 78)
If this tag is used the filter will be based on a less than or equal
comparison.
<gt> (page 78)
If this tag is used the filter will be based on a greater than comparison.
<gte> (page 78)
If this tag is used the filter will be based on a greater than or equal
comparison.
<other> (page 78)
If this tag is used the filter will match any record not matching other any
filter.
<always> (page 78)
If this tag is used the filter will always match.
Attribute
Description
number
An increasing number to uniquely identify filters.
table
The name of the SQL table which will be generated by this filter rule. It
requires a <schema> element (page 81) with the same name.
See Also
 <filters> (page 75)
www.faircom.com
All Rights Reserved
77
<[Operator]> filter elements
The operator elements are used by filter elements to describe how the operator will be used to
apply the filter. The operator elements are mutually exclusive and contain the same attributes.
The operator elements are:
 <eq> used to describe filtering using an equal operator
 <neq> used to describe filtering using an not equal operator
 <lt> used to describe filtering using a less than operator
 <lte> used to describe filtering using a less than or equal operator
 <gt> used to describe filtering using a greater than operator
 <gte> used to describe filtering using a greater than or equal operator
 <other> used to describe the default case filter (matches when no other filter matches)
 <always> used to describe a "match-all" filter
Elements
Element
Description
<field> (page 79)
The string representing the name of the field involved in the filter.
<value> (page 80)
The value that will be used for the comparison with the field values.
www.faircom.com
All Rights Reserved
78
<field> operator element
The content of the <field> element (children of one of the Operator elements (page 78)) defines
the name of the field involved in the filtering operation.
www.faircom.com
All Rights Reserved
79
<value> operator element
The content of the <value> element defines the value used by the Operator element (page 78) to
make the comparison with the value of the field specified into the <field> element (page 79)
(Children of the Operator elements (page 78)).
www.faircom.com
All Rights Reserved
80
<schema> table element
The schema describes a schema belonging to the data file; more schemas can be defined if the
table contains more than one record schema. If multiple schemas are defined, a <filters> (page
75) declaration is required.
Elements
Element
Description
<field> (page 83)
Describes one of the fields comprising the current schema.
Attribute
Description
name
The name to assign to the current schema. This name will map a SQL
table containing all the records selected by this schema.
Optional Attributes
Attribute
Description
filter
Specifies which filter to use to generate the current schema, use one of
the filter numbers defined in the <filters> element (page 75)
size
The record length for the current schema specified in number of bytes.
onConvertError
Specifies the default action to take when a value cannot be converted
into SQL readable data.
If "error" is specified an error will be returned and the selected table
records will not be shown unless the field content matches the bindefault
or cbdefault (see <field> schema element (page 83)) in which case the
value will be replaced with SQL null value.
If "null" is specified, the values that cannot be converted will be
replaced with SQL null value.
If "strict" is specified, an error will be returned and the selected table
records will not be shown.
www.faircom.com
All Rights Reserved
81
Attribute
Description
typemap
Specifies the method of COBOL numeric type mapping. COBOL
numeric types are mapped into specific TINYINT, SMALLINT,
INTEGER, or BIGINT types instead of NUMERIC whenever precision
and scale allow. By using native machine types instead of a proprietary
numeric type, this alternative mapping reduces handling overhead.
• If 0 is specified (default), original type mapping is used for backward
compatibility with previously linked tables.
• If 1 is specified, smart type mapping is used and these COBOL types
are mapped to matching integer types:
NumSigned
NumSignSep
NumSepLead
NumLeading
SignedComp2
SignedComp3
Comp2
NumUnsigned
Comp3
Comp6
JustAN (right-justified strings) are mapped to varchar. Left-side spaces
are considered padding and are trimmed so they do not appear in SQL.
Note: To take advantage of smart type mapping on existing imported
tables, it is necessary to relink the tables to SQL.
www.faircom.com
All Rights Reserved
82
<field> schema element
The <field> element (a child of the <schema> element (page 81)) describes one of the fields
composing the schema. Several attributes of this element (listed below under Mandatory
Attributes) are required.
Attribute
Description
name
A string value representing the field name. This will be the field name
used by the SQL engine.
size
The number of bytes composing the field.
type
A string defining the data type containing. Please refer to the type
mapping table (page 86).
Optional Attributes
Attribute
Description
scale
Used only by numerical field types, specifies the scale of the numeric
values.
digits
Used only by numerical field types, specifies the number of digits of the
numeric values.
dbtype
Used to force the SQL type to DATE, DATETIME or BIT. The admitted
values are:
"date" mapping into DATE or DATETIME depending on format attribute.
"boolean" mapping into BIT. At least one of cbtrue or cbfalse
attributes must be specified.
format
Only for date types. Used to describe how the date will be written into
COBOL data file. Use the date-format-string used in $XFD.
hidden
Normally used for the filler fields. Instructs the SQL engine to hide the
current field.
www.faircom.com
All Rights Reserved
83
Attribute
Description
bindefault
bindefault and cbdefault are mutually exclusive: use one or the
other, but not both.
bindefault indicates the binary value to write to disk when writing a
record with null values from SQL.
This option provides more flexibility than cbdefault because it is
binary instead of a string.
This value can either be specified as a hexadecimal string filling the
entire buffer (e.g., bindefault="\x00\x01") or it can be one of the
following predefined values:
low-value - Fills the field with COBOL LOW-VALUE.
high-value - Fills the field with COBOL HIGH-VALUE.
all-spaces - Fills the field with space characters.
For example, to fil lthe field with the COBOL LOW-VALUE:
bindefault="low-value"
When using the hexadecimal string it is possible to specify multiple
occurrences of the same byte using \x[#of occurrences]00
For example, for 12 occurrences of \x20 (space):
bindefault="\x[12]20"
When OnConvertError (see below) is set to “error”, the error is
propagated to SQL and the query fails unless the field content matches
the bindefault in which case the value will be exposed in SQL as
NULL. For more details see SQL/COBOL Data Conversion (page 99).
cbdefault
Mutually exclusive with bindefault (use one or the other, but not
both).
cbdefault indicates the value to write to disk when writing a record
with NULL values from SQL.
This value is the logical value to assign to the field (as a programmer
would write it in a COBOL program). It is always specified as a string in
the XDD file (use bindefault if a binary value is required). The SQL
engine converts it into the proper representation for the field type before
using it. For example, in the case of a PIC 9(4) COMP-6, which
indicates a 4-digit number stored in 2 bytes as an unsigned packed, a
cbdefault="15" will be interpreted as a COMP-6 representing the
number 15 (\x00\x15 in hex).
When OnConvertError (see below) is set to “error”, the error is
propagated to SQL and the query fails unless the field content matches
the cbdefault in which case the value will be exposed in SQL as
NULL. For more details see SQL/COBOL Data Conversion (page 99).
onConvertError
Specifies the action to take when this field value cannot be converted
into SQL readable data.
If "error" is specified an error will be returned and the selected table
records will not be shown unless the field content matches the
bindefault or cbdefault in which case the value will be replaced
with SQL null value.
If "null" is specified the values that cannot be converted will be
replaced with SQL null value.
If "strict" is specified an error will be returned and the selected table
records will not be shown.
If "value:?" (where ? is the wanted value in SQL) is specified the value
that cannot be converted will be replaced with the specified value
www.faircom.com
All Rights Reserved
84
Attribute
Description
onSignError
Used to force the sign of the field value in case it cannot be converted
from the data on disk. The admitted values are:
"+" Forces to positive sign
"-" Forces to negative sign
offset
The zero-based integer value indicating the distance in bytes of the field
from the beginning of the record.
cbtrue
The value used in a COBOL program that matches the BIT value 1 in
SQL.
cbfalse
The value used in a COBOL program that matches the BIT value 1 in
SQL..
julianBase
Only for date types. Used to set the base date for Julian dates. The
Julian date base must be specified using the YYYYMMDD format. It
defaults to 17000301 (March 1st, 1700).
Specifying the bindefault attribute
As described in the table above the value of bindefault attribute must be specified as hexadecimal
values, specifying the x character before the hexadecimal code of any byte composing the value.
There is also a way to repeat the same character an arbitrary number of times by specifying the
number inside square brackets as shown in the example below:
bindefault="\x[4]00"
This example repeats the hexadecimal code 004 times.
www.faircom.com
All Rights Reserved
85
10.7
Type Mapping Table
To define an XDD file requires defining the data type of each column of the original data file. The
following table describes the accepted XDD data types:
Type to be used in the XDD field
specification
Type description
NumUnsigned
ASCII string representing an unsigned number
NumSignSep
ASCII string representing a signed number with trailing
separate sign.
NumSigned
ASCII string representing a signed number with trailing sign
NumSepLead
ASCII string representing a signed number with leading
separate sign
NumLeading
ASCII string representing a signed number with leading sign
Alphanum
ASCII string
Float
Float or Double values
CompSigned
Signed computational
CompUnsigned
Unsigned computational
PackedPositive
Packed string representing a positive number
PackedSigned
Packed string representing a signed number
PackedUnsigned
Packed string representing an Unsigned number
BinarySigned
Integer number represented in binary signed format (big
endian)
BinaryUnsigned
Integer number represented in binary unsigned format (big
endian)
NativeSigned
Integer number represented in native O/S binary signed
format
NativeUnsigned
Integer number represented in native O/S binary unsigned
format
See also <schema> table element (page 81).
Variable-length fields mapped into LONGVAR* SQL field
Support has been added for mapping COBOL fields into LONGVAR* SQL fields.
The XDD has been expanded as follows:
1. New dbtype possible values:
• BLOB: Indicates a variable-length binary object with length depending on a field value.
• CLOB: Indicates a variable-length text object with length depending on a field value.
2. New <field> attribute sizefield to be used in conjunction with dbtype BLOB or CLOB and
having size = "0"
www.faircom.com
All Rights Reserved
86
For an XDD field to be mapped into a LONG VARCHAR or LONG VARBINARY, the following
conditions must be met:
1. The field definition must have:
size="0"
sizefield="X" where "X" is a valid field containing the number of bytes (we suggest
this field to be hidden, but this is not mandatory)
dbtype="clob" or dbtype="blob"
2. At maximum, 1 field mapped to a BLOB or CLOB type.
3. It must be the last field in the record buffer.
If one (or more) of the above condition is not met, an error CTDBRET_CALLBACK_11
("Unsupported clob/blob definition") is returned.
10.8
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.
www.faircom.com
All Rights Reserved
87
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.
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
www.faircom.com
All Rights Reserved
88
10.9
Viewing Sqlized Tables in c-treeACE SQL Explorer
c-treeRTG opens your COBOL and Btrieve data to the world of SQL access. FairCom knows you
will want to monitor and manage this data—and that means seeing it the way it appears to SQL
applications. FairCom's c-treeACE SQL Explorer and c-treeACE Explorer are graphical tools that
allow you to view and manipulate your data, providing comprehensive management capabilities.
c-treeACE SQL Explorer and c-treeACE Explorer are client tools designed to interact with
c-treeRTG Servers through the TCP/IP SQL port. Using the SQL language, they give you access
to all the items in your c-treeRTG database. They also provide the ability to execute single SQL
statements and SQL scripts including options for viewing the execution plans.
Tables that were sqlized have slightly different properties from tables that were creative natively
in SQL. c-treeACE SQL Explorer and c-treeACE Explorer show sqlized tables in a different color
with a jagged "S" (or lightning bolt) to indicate they were sqlized. The custmast table in the
image above is a sqlized table.
When you right-click on a tables that was sqlized, the context menu will display a special set of
options, as shown in the image above. Some options available to regular tables, such as Alter
Table, Clone, and Constraints, are disabled because they are not available for sqlized tables.
www.faircom.com
All Rights Reserved
89
10.10 Adding SQL Indices to Sqlized Files
In release V2, c-treeRTG takes a giant stride in its SQL capabilities by allowing you to create a
SQL index on your COBOL tables. You can execute CREATE INDEX on imported tables or you
can use the graphical tools, c-treeACE SQL Explorer and c-treeACE Explorer.
Performance of SQL Queries
A practical use of this feature is in handling COBOL indices that do not translate well to SQL. In
some cases, the index is imported into SQL by sqlize with limited functionality, so it can be used
only to perform searches using the "=" and the "<>" (not equal) operators. In a small number of
cases, the index cannot be sqlized at all.
These cases may impact the performance of SQL queries on those fields. This issue is now
easily addressed: simply create SQL indices where needed to speed up queries. It is not
necessary to replace every COBOL index, simply replace those that are needed to speed up your
SQL queries.
Note: A SQL index cannot be created on certain COBOL data types: date, time, datetime
(timestamp), and bit (Boolean).
The presence of a SQL index will better optimize some queries. As a side effect, the index returns
rows sorted in logical order as opposed to binary order as is the case for COBOL indices.
www.faircom.com
All Rights Reserved
90
To create a new index for a table, click the table name to see the group labeled
Indexes,
right-click on the group, and select Create from the context menu. The following window will
appear for creating the new index definition including defining index columns (segments):
Create Definition Controls
 UNIQUE - Check this option if you don't want your index to contain duplicate values.
 Index Name - Enter the name to be assigned to the new index.
 Table Name - This box will display the table name receiving the new index. If you access this
dialog from a specific table, the table name will be displayed read-only. If you access this
dialog from the Index group under a user, select the table from the drop-down list.
 Storage_Attributes “Partition” - This check box adds STORAGE_ATTRIBUTES
"PARTITION" to the SQL statement. This creates the index as the partition index to the table
enabling multiple table partitions.
Column Definitions
Use the controls in the Columns group to define the columns composing your new index. New
lines can be added by filling the line marked with the asterisk:
 Column - Click inside the Column drop-down list to select the column name to be included in
your new index. If your index will be built over multiple columns, continue this process until all
columns are listed.
 Desc - Check this box if you want the column to be sorted in descending order. Otherwise an
ascending sort is the default.


- Use this button to move a column up the index column list. Note, the column in the top of
this list will appear first (to the left) within the index.
- Use this button to move a column down the index column list.
To delete an index column: Select the row header that contains the column to be deleted and
then press the Delete key on your keyboard.
www.faircom.com
All Rights Reserved
91
Resulting Statement
The Resulting Statement window will show the CREATE statement to be executed for building
the new index. Once your index is completely defined, press the Create button to create your
index and remember to check Result in the left corner of the status bar at the bottom of the
window for either Success or an error message. Once you see Success in the status window,
click on exit to return to the main window.
You can save the CREATE statement shown in the Resulting Statement window by clicking Save
Statement or using the File menu or pressing CTRL+S.
Finishing Up
Save Statement - Click this button if you want to save the SQL statement so you can execute it
at a later time.
Create - Click this button to create the index.
Exit - Click this button to close this dialog.
Alter Table Callbacks Allow Better Control
The following callbacks allow better control during Alter Table operations:
1. A new field callback was added. This callback is called by ctdbAddSegment for those fields
that have been remapped to a different field type using a field callback.
2. Alter Table logic has been enhanced to call the "alter table callback" at the beginning of the
Alter Table and at the end and once the action to be carried out is determined.
The "time" when the callback is called can be determined by looking at the new CTDBTABLE
alter_time member. The action to be performed is accessible and modifiable in the
callback code by using the alter_action member of CTDBTABLE.
3. During the Alter Table execution it is possible that the table will be closed and re-opened. In
such cases the following callbacks are called when needed:
_OnTableGetSchema
_OnTableGetDoda
_OnTableGetExtInfo
www.faircom.com
All Rights Reserved
92
10.11 API for SQL Conversion Error Checking
It is possible to programmatically check if there will be any conversion errors accessing a table
from SQL. Three functions, exported by mtclient.dll, provide functionality to verify if a record
buffer will generate any conversion error when accessed through SQL.
This checking capability requires an XDD file. It verifies if a record buffer generates any errors
when converted into SQL. It considers all the error handling specified in the XDD (as opposed to
the SQL "badrec" approach that logs any error, even the ones that are handled).
ACUCOBOL users can call these commands from their programs. See Enabling XDDOPEN,
XDDCHECK, and XDDCLOSE for Programmatic SQL Conversion Error Checking (page 11).
A sample program using ACUCOBOL is provided (samples\acucobol\XDDcheck\xddchk.cbl). It
shows how to write a simple COBOL program that takes advantage of this new functionality by
performing a table scan to verify that all records can be converted to SQL. The sample is for
ACUCOBOL only. It assumes that SQL conversion error checking has been enabled in the
runtime as explained in Enabling XDDOPEN, XDDCHECK, and XDDCLOSE for Programmatic
SQL Conversion Error Checking (page 11).
www.faircom.com
All Rights Reserved
93
ct_XDDOpen
Declaration
cbDLLexport pVOID ct_XDDOpen(COUNT signconv, TEXT text[CT_PATH_LEN])
This function accepts:
 signconv: the numeric format to be used; the value must be one of the value specified as
sign conventions defined in ctcbxdd.h
 text: the name of XDD file to open and use
Description
This function returns a VOID pointer holding to be used on calls to other functions, NULL in case
of error.
The function opens and parses the XDD file and prepares all the information required to perform
the buffer checking.
Return Values
Value
Symbolic Constant
Explanation
0
NO_ERROR
Successful operation.
See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.
See Also
 Enabling XDDOPEN, XDDCHECK, and XDDCLOSE for Programmatic SQL Conversion
Error Checking (page 11)
www.faircom.com
All Rights Reserved
94
ct_XDDCheck
Declaration
cbDLLexport LONG ct_XDDCheck( pVOID hdl, pUTEXT buffer, LONG buflen, pTEXT msg, pLONG offset, pLONG
size, pLONG type)
hdl: the handle returned by a ct_XDDOpen call
buffer: pointer to the buffer to be analized
buflen: significant len of the buffer
msg: pointer to a 256 bytes buffer for error message description
offset: pointer to a 4 bytes variable where the logic stores the offset of the first field having a
problem
size: pointer to a 4 bytes variable where the logic stores the size of the first field having a
problem
type: pointer to a 4 bytes variable where the logic stores the type of the first field having a
problem (value as defined by the enum in ctcbxdd.h)
Description
This function returns 0 if no error is encountered. It returns an error code (enum
XDD_CONV_RET value) in case of an error.
The function checks the buffer for conversion from COBOL to SQL based on the XDD
specifications. It stops at the first error and returns information about the error. In case of
multi-record table, it scans through all the possible schema that apply to the buffer.
Return Values
Value
Symbolic Constant
Explanation
0
NO_ERROR
See Also
www.faircom.com
All Rights Reserved
95
ct_XDDClose
Declaration
cbDLLexport VOID ct_XDDClose( pVOID hdl)
hdl: the handle returned by a ct_XDDOpen call
Description
This function frees the memory allocated to the XDD handler and "closes" the XDD checking
session for the specific XDD.
Return Values
Value
Symbolic Constant
Explanation
0
NO_ERROR
See Also
www.faircom.com
All Rights Reserved
96
10.12 Background Information about Sqlizing
Record Structure Definition: The XDD
To provide simultaneous access to the data
through COBOL and SQL, c-treeRTG maps
COBOL types into SQL types (and vice versa).
c-treeRTG must know the structure of the
records so it can provide the SQL schema
required for this mapping.
COBOL does not provide information about the
record structure required by SQL. However,
some COBOL compilers can generate XFD files
which define this record structure.
When an XFD is available: ctutil
c-treeRTG provides a command-line switch to
the ctutil (page 121) utility to convert XFD files
into an XDD (eXtended Data Definition) file. This
file is in XML format and contains information
about the data and index structures including:
index definitions, record schemas, default field
values, null field handling (an undefined concept
in COBOL), behavior of data conversion errors,
etc.
During the conversion from XFD to XDD, ctutil
also accepts a “rule file” that contains
instructions to customize the generated XDD file for specific needs or to add information that the
XFD does not contain (such as default values for fields).
When an XFD is not available: xddgen
For those compilers that do not provide a means to generate an XFD file, we provide the
OpenCOBOL-based xddgen, which can create an XDD from the COBOL source code. See the
xddgen (page 160) chapter for more information.
Merging the XDD with the data file
The information contained in the XDD is stored directly in the data file itself with no effect on
COBOL or Btrieve access to the data. The XDD file is embedded into the data file using the
ctutil -sqlinfo (page 148) switch. After adding the XDD information to the data file, the
ctutil -sqllink (page 149) switch is used to make it immediately accessible through SQL.
Indices
Any operation performed through SQL or from the application uses and maintains existing indices
for the best performance. Because of the nature of some COBOL types encoding, an index may
not sort as an end user expects. c-treeACE SQL can still take advantage of these indices to
retrieve records while not using them for sorting. This architectural limitation does not have
www.faircom.com
All Rights Reserved
97
significant impact in practice because the SQL engine is able to build temporary index files on the
fly when necessary and use dynamic index techniques.
Multiple Record Types
A common habit for COBOL programmers is to use redefines so that, depending on some
criteria, records interpreted using a particular schema. The XDD file contains information about
the different available schemas and their criteria. SQL takes advantage of this information by
presenting each schema as a separate table (named as defined in the XDD file). Select
statements on one of these tables display only records matching the COBOL criteria. Inserts into
these tables are checked for matching criteria. See the c-treeDB Virtual Tables
(http://docs.faircom.com/wp/mrt/#cover.htm) technical white paper on the FairCom website.
www.faircom.com
All Rights Reserved
98
Data Conversion Considerations
As described earlier, data is stored in its “native” (COBOL) format. To share data between
COBOL and SQL, the SQL engine performs data conversion between COBOL and SQL data
types on-the-fly as the fields are accessed.
The XDD file is the source of information about all the operations that need to be performed when
bridging SQL and COBOL data.
There are two sides of conversion:
 From SQL to COBOL when writing (e.g. INSERT INTO, UPDATE statements)
 From COBOL to SQL when reading (e.g. SELECT).
We will begin by describing the SQL-to-COBOL conversion because there are significant
concepts to understand that affect the COBOL-to-SQL side.
SQL to COBOL
Converting from SQL to COBOL, there are a few situations where determining what the COBOL
record buffer should contain is difficult if not impossible. Typical situations are the following:
Null Values
In SQL it is possible to set fields to “NULL” indicating “missing information or inapplicable
information” or “lack of a value.” The same concept does not exist in COBOL where any field has
a value. When a field is set to NULL by SQL, the conversion logic needs to know what value to
store in the field. In COBOL there is no standard discipline for “uninitialized fields” (for example, in
a table of “people,” the date of death is unknown while the person is alive). The field may contain
a high-value, a low-value, spaces, zeros or even garbage; every application has its own
discipline, which may be different on different fields.
To address this issue, the XDD file allows you to specify a “bindefault” or a “cbdefault” attribute
for the field, which will be written to disk in place of a SQL NULL. Essentially, “bindefault” is a
binary value to replace a SQL NULL and “cbdefault” is a COBOL value to replace a SQL NULL
(see <field> schema element (page 83)).
 If the XDD file DOES NOT specify a “bindefault” or a “cbdefault” attribute for the field, it is
linked in SQL as NOT NULL, meaning that SQL will refuse any statement setting the field to
NULL.
 If the XDD file DOES specify a “bindefault” or a “cbdefault” attribute for the field, the field is
linked as “nullable”, SQL will allow setting it to NULL and conversion logic stores the specified
default value in the COBOL record.
In this second case, it is worth noticing that if the default value set in the XDD is a valid value for
the field type (e.g., 0 for numeric types) when reading the record, it will be converted into that
value in SQL and not NULL as it was set. If the value is not a valid value (e.g., spaces for numeric
types), a conversion error will occur when reading the record but the engine automatically
handles it (unless the XDD specifies otherwise, as explained later) and exposes the value as
NULL in SQL, as expected.
www.faircom.com
All Rights Reserved
99
Hidden Fields
The XDD file may specify that some of the fields are hidden to SQL, which is to say that SQL is
not aware of them. This occurs for “filler” fields or for redefines where a portion of the record is
not redefined or simply because the person who generated the XDD decided not to expose some
field (and so the information it contains) to SQL.
When updating an existing record, hidden fields are not a problem, because when performing an
update, the engine will convert and store only fields that are set by the update; the portion of the
record belonging to hidden field is left untouched.
When inserting a new record, hidden fields are a problem: SQL does not pass any value to store
in these fields, because the SQL engine does not know they exist. However, the portion of the
record belonging to these fields must be set. The engine sets it to the “default” value specified in
the XDD for the specific hidden field which is consistent with the approach taken for NULL values.
However, if the default value is not specified a CTDBRET_CALLBACK_18 (Missing default for
null field) error occurs.
Unsigned Fields
Unsigned COBOL types are mapped into SQL types, which are signed. SQL itself does not check
for negative values, which are not acceptable values for the COBOL data types. If the XDD has
defined a field as unsigned, attempting to set it to a negative value causes a
CTDBRET_UNDERFLOW error, which is a common situation of out-of-the-box.
Inline Redefines
It is possible for the XDD file to specify that the redefines are “expanded” as further fields in the
same table instead of creating a separate SQL table. In this case, attempting to add a new record
(i.e., INSERT INTO) fails with error CTDBRET_NOTYET (Not yet implemented).
COBOL to SQL
When converting data from COBOL to SQL there may be situations where the content of the
record cannot be interpreted and/or cannot be mapped into a SQL value.
One typical situation is a PIC 9(3) containing three spaces. The conversion does not know what
the space is or how to interpret it. It cannot tell if the content is garbage or if it was set on
purpose.
Another common situation occurs with dates, where it happens that although the field content is
clear it does not map into a valid SQL value. For instance a PIC 9(10) mapped into a date value
may have its value set to 0, which is a good numeric value, but not a valid date!
A third common scenario is due to the fact that in COBOL there are different conventions on how
to represent numeric data in the record on disk. In particular, programs have different conventions
on how the sign for signed numeric values is encoded. The SQL engine must know which
convention is in use and the data on disk must adhere to that convention, otherwise a conversion
error occurs.
The XDD file contains information on how to handle conversion errors at the “schema” level (for
the whole table) or at “field” level (just for a single field) by setting the “onConvertError”
attribute.
www.faircom.com
All Rights Reserved
100
onConvertError
When a conversion error occurs the engine determines what to do based on the
onConvertError setting for that specific field. If the onConvertError for the field missing, it
uses the one set on the schema or, when that is missing, it uses the default. The possible
behaviors are:
 "strict" - No action is taken, the error is propagated to SQL and the query fails. This behavior
is very strict but very safe. It is good for fields where the value is expected to always be a
valid value, such as the fields composing the main index of the table.
 "null" - The values that cannot be converted are exposed in SQL as NULL. This is very
convenient in those cases where the field contains garbage for whatever reason. It is also
convenient when there is no way to handle the conversion error differently without touching
the data. However this setting makes it impossible for SQL to use any index on the fields to
which it applies.
 "error" - The error is propagated to SQL and the query fails unless the field content matches
the bindefault or cbdefault (see <field> schema element) in which case the value will be
exposed in SQL as NULL. This is the default behavior when onConvertError is not
specified. It is very convenient as is it a good compromise between the “strict” and the “null”
approaches. It is similar to “strict” with only one precise exception for values that SQL would
store in the record when setting the field to NULL.
 "value:?" (where ? is the wanted value in SQL) - The values that cannot be converted are
exposed in SQL as the specified value. This is similar to the “null” approach but it exposes
the content as the specified value instead of as NULL. It has the same pros and cons as the
“null” approach.
XDD files that are automatically generated do not contain any onConversionError setting and
do not contain any default value. Hence human intervention is required, at least initially, to
properly set it up. Once properly set up and verified that conversion errors are properly handled
as desired, it is possible to automate the XDD modification using the rule file, see Define External
Rules (page 59).
SQL Considerations
FairCom c-treeRTG allows the same data files to be accessed by both SQL and ISAM interfaces
(e.g., COBOL). This provides a truly flexible development environment allowing you to choose
exactly the techniques that best suit their needs for performance and data integrity.
The SQL support provided by c-treeRTG is targeted at the most important SQL functionality, such
as reading and writing records using SQL queries, user-defined functions, stored procedures &
triggers, views, and joins (including joining a SQL-created table with an ISAM table). There are
multiple considerations on SQL tables that are important for you to keep in mind.
Please note c-treeACE provides full, industry-standard SQL. You can create a database that is
accessed exclusively through SQL and it will not experience the limitations listed below. The
limitations discussed below arise when accessing data from both SQL and ISAM interfaces (e.g.,
COBOL) on files created through ISAM. Due to the high flexibility of ISAM contrasted with the
discipline of SQL, some SQL features cannot be expected to work in this environment. The next
sections list important considerations to keep in mind when developing applications using both
ISAM and SQL to access the same data.
www.faircom.com
All Rights Reserved
101
Note: Additional considerations apply if you use the c-treeACE Professional Developer's Kit to
expose your ISAM data through SQL, giving you full read, write, insert, and delete access to the
data. Please contact FairCom (http://www.faircom.com/company#ContactUs) for a complete list
of supported functionality.
Common Issues
The following issues are important to keep in mind when developing c-treeACE or c-treeRTG
applications that use both ISAM and SQL to access the same data files created through the ISAM
interface.
Limitation
Table definitions are done through ISAM; any changes to the table
definitions must be done through ISAM. This implies:
• You cannot execute Alter Table over an ISAM data file.
• Referential Integrity cannot be defined across ISAM tables.
Consideration
Not all ISAM indices are fully usable in SQL. In particular, some indices
do not collate as SQL mandates and therefore cannot be used by SQL
for sorting or to perform searches depending on the collation.
This does not limit functionality, however it may impact performance.
In such a case it is now possible create a new index from SQL that
satisfies all SQL needs and apply to both SQL and COBOL/BTRV
access.
Has
Workaround
ISAM files are not portable among different endianess, even if you are
using portable data types.
You can use the FairCom ctunf1 utility to convert endianess before
moving between a big-endian and a little-endian system.
In addition, keep in mind that SQL triggers are applicable at the SQL level only. NoSQL APIs
(e.g., ISAM, CTDB, COBOL, JTDB, etc.) cannot invoke a SQL trigger. This is not a limitation
specific to c-treeACE and c-treeRTG: a trigger is a SQL concept that is not supported by ISAM.
c-treeRTG SQL Support
The c-treeRTG products allow your COBOL data to be exposed through SQL, giving you full
access to read, write, insert, and delete records. This support is targeted at the most important
SQL functionality, which includes:
 Reading and writing records using SQL queries
 User-defined functions
 Stored procedures
 Triggers
 Views
 Joins (including joining a SQL-created table with an ISAM table).
www.faircom.com
All Rights Reserved
102
The topics listed in Common Issues (page 102) are important to remember when developing
c-treeRTG applications that use both ISAM and SQL to access the same data files. In addition,
keep the following in mind:
 A table created through SQL cannot be accessed using c-treeRTG ISAM drivers for COBOL
and Btrieve.
 SQL triggers are applicable at the SQL level only; your COBOL program cannot invoke a
SQL trigger.
 Referential integrity is applicable at the SQL level only; no check is performed to ensure
referential integrity.
 If transactions are disabled on COBOL files, this creates additional considerations to
accessing these files at the SQL level: rollbacks do not affect these files; isolation of
transaction is not provided; etc.
www.faircom.com
All Rights Reserved
103
11. Tips for Advanced Sqlizing
This section examines directives you may need to place in the copybook to handle certain
situations. Depending on the structure of your data, you may need to use some of these
techniques to sqlize your files.
The xddgen utility prepares your COBOL data for SQL access by reading your program to
determine relationships in the data (similar to a SQL schema). Using this information, c-treeRTG
maps the data for SQL access on-the-fly. Your COBOL program will continue to access the same
data, with no changes.
The xddgen utility may be able to sqlize your data without any modifications to your copybook. In
certain situations, your data may be structured in a way that xddgen cannot interpret correctly. In
those situations, you will need to add directives to your copybook to tell xddgen how to handle
the data. You will not need to restructure your data or rewrite your program. Adding these
directives does not cause any compilation issue to your application because they are comments
for the COBOL language.
The code used in these examples is provided in the Sqlize Tutorial:
<install directory>\<platform>\Driver\ctree.cobol\tutorials\Sqlize\
• SQLIZEEXAMPLE.CBL - An example COBOL program
• Tutorial.sql - A SQL file for creating and populating the CARDFILE database used by this
tutorial.
• CARDFILE.FD - The file descriptor used by the tutorial.
• CARDFILE.SL - A select statement used by the tutorial.
• rules.xml - An XML file containing the rules for sqlizing.
Note: The Sqlize Tutorial COBOL source code is compatible with the Micro Focus ACUCOBOL
compiler, Veryant isCOBOL, and Micro Focus starting with Visual COBOL 2010 release. Please
check with FairCom regarding future support for other COBOL compilers.
See also
 xddgen (page 160)
11.1
Step-by-Step Sqlizing Instructions
This section provides step-by-step instructions for sqlizing your data based on the Sqlize Tutorial
(Driver\ctree.cobol\tutorials\sqlize\). It assumes you have already set up the environment where
you will run the COBOL application using c-treeRTG.
The process of sqlizing consists of three major steps for the end user (the tutorial below includes
extra steps for clarity):
1. Extract the XDD from COBOL (step 2 in the tutorial below).
www.faircom.com
All Rights Reserved
104
Tips for Advanced Sqlizing
2. Sqlize it using ctutil (step 4 in the tutorial below).
3. Use SQL to access the database (step 6 in the tutorial below).
The SQLIZEEXAMPLE program prints out information about membership cards satisfying a
partial card number request. The program itself can create the required file if the file does not
exist, however it does not populate the file.
1. Compile the SQLIZEEXAMPLE.CBL program:
iscc SQLIZEEXAMPLE.CBL
2. Extract the XDD from SQLIZEEXAMPLE.CBL by running xddgen:
C:\FairCom\vx.x.x.RTG\winX64\Tools\cmdline\XDDGEN\xddgen.exe
SQLIZEEXAMPLE.CBL
3. Create empty c-treeRTG files using either the COBOL program or the XDD.
a. You can execute the COBOL program one time to create the COBOL files (.DAT and
.IDX):
iscc -ze SQLIZEEXAMPLE.CBL
b. Or you can use the XDD to create the file, using ctutil -make:
ctutil.exe -make CARDFILE CARDFILE.xdd
4. Sqlize it, using ctutil –sqlize and the XDD:
ctutil.exe -sqlize CARDFILE CARDFILE.xdd ADMIN ctreeSQL -rule=rules.xml
5. Populate the table using the SQL script Tutorial.sql:
isql.exe -s Tutorial.sql -u ADMIN -a ADMIN ctreeSQL
6. Run the COBOL program again and count the records. You can now use SQL to query the
multi-record data.
www.faircom.com
All Rights Reserved
105
A few tips:
 Use the ACUCOBOL compiler option -f4 to automatically generate an XFD file. In many
cases, c-treeRTG can use this information to automatically sqlize the table upon creation.
 The c-treeRTG ctree.conf file allows automatic sqlizing with the <sqlize> configuration
option as long as a valid COBOL XFD or c-treeRTG XDD file is available. Uncomment this in
the provided ctree.conf file for Tutorial1.
 You’ll find compiler specific directives (*>>XDD WHEN) in the CARDFILE.FD source module.
Review this module which provides a modestly complex usage of COBOL redefines, resulting
in multiple SQL “tables” from a single COBOL table. Be sure to run xddgen over this module
to create a valid XDD file.
11.2
xddgen Techniques
This section demonstrates techniques you may need to use so that xddgen can map your
COBOL data to SQL.
In many cases xddgen can sqlize your data without any modifications to your copybook. In some
situations, the structure of your data will dictate adding directives to your copybook to tell xddgen
how to handle the data. You will not need to restructure your data nor will you need to rewrite
your application. All you will need to do is add certain directives to the file, which xddgen will read
when it sqlizes your data.
The program used in this tutorial lists and counts all credit card holders within a file whose credit
card numbers are similar to a sequence provided by the user. Once it processes the whole file, it
displays the total count. You must provide a number between 1 and 10 digits. The program
always considers only the initial digits of the number.
The main file of this tutorial is CARDFILE, a file that contains records of a reward membership
card for customers. This tutorial will take you through the copybook, CARDFILE.FD, and explain
how directives can be added to tell xddgen how to handle certain data structures.
Using Group Names
A directive is used here to force c-treeRTG to use the name of the group CARD-TITLE-NUMBER
instead of the subfields when building the SQL table. By default xddgen always expands the field
belonging to groups and shows them in the SQL structure. However there are cases where this is
not the desired behavior.
*>>XDD USE GROUP
10 CARD-TITLE-NUMBER.
15 CARD-TITLE-NUMBER-1 PIC 9(4).
10 CARD-TITLE-NUMBER-X REDEFINES CARD-TITLE-NUMBER
PIC 9(10).
10 CUSTOMER-NUMBER
PIC 9(4).
10 ELITE-MEMBER-TYPE
PIC X.
88 CARD-GOLD
VALUE "G".
88 CARD-PLATINUM
VALUE "P".
88 CARD-SILVER
VALUE "S".
www.faircom.com
All Rights Reserved
106
Splitting an OCCURR
The first elements of the record are actually a split of the OCCURR GROUP-TITLE-INFO that
follows it, but with each field identified separately. This is included in this tutorial to demonstrate a
possible solution to use fields within an OCCURR as indices of a file in SQL. Without this split,
c-treeRTG would not be able to properly identify the field CARD-FAMILY-NUMBER-1 in order to
build a SQL index using it. This is needed only in cases where you need a sub-group of an
OCCURR to be used as a SQL index. Notice that this would not be required if this file would be
accessible only by COBOL programs.
*>>XDD USE GROUP
10 CARD-FAMILY-NUMBER-1.
15 CARD-LABEL-NUMBER-1
15 CARD-MAIN-NUMBER-1
15 CARD-NUMBER-CRC-1
*>>XDD DATE = YYMMDD
10 EMISSION-DATE-1
PIC 9(4).
PIC 9(8).
PIC 9(2).
PIC 9(6)
COMP-6.
Combining Multiple XDD Directives
The example below shows how to combine multiple XDD directives into a single line. In this
example, we combined USE GROUP to force SQL to use the name of the group as the SQL field
and a specific format to display this field as a date as two digits for year, two for month, and two
for day. Many other formats available; please refer to the documentation for other options.
*>>XDD USE GROUP
*>>XDD DATE=YYMMDD
10 VALID-UNTIL-DATE-1 PIC 9(6) COMP-6.
Name Conflicts
OCCURs are handled automatically by c-treeRTG when converting this table into SQL.
c-treeRTG automatically expands every OCCURR into multiple fields, using numbered
extensions such as "_1", "_2" and so on. Because we are not explicitly using the groups for field
naming in this example, the final fields to be displayed in SQL will be the most internal ones. After
sqlizing this table, you can view it in SQL Explorer to see the following fields:
CARD_LABEL_NUMBER_1
CARD_MAIN_NUMBER_1
CARD_NUMBER_CRC_1
CARD_LABEL_NUMBER_2...
www.faircom.com
All Rights Reserved
107
This might cause some field name conflicts, depending on how your fields are named in COBOL.
In this example, if we had named VALID-UNTIL-DATE-1X without the final X, a conflict would
happen and you would not be able to sqlize.
10
GROUP-TITLE-INFO OCCURS 2 TIMES.
*>>XDD USE GROUP
*>>XDD NAME=CARD_FAMILY_NUMB
15 CARD-FAMILY-NUMBER.
20 CARD-LABEL-NUMBER
20 CARD-MAIN-NUMBER
20 CARD-NUMBER-CRC
PIC 9(4).
PIC 9(8).
PIC 9(2).
*>>XDD USE GROUP
*>>XDD NAME=EMISSION
15 EMISSION-DATE
PIC 9(6)
*>>XDD USE GROUP
*>>XDD NAME=VALID_UNTIL
*>>XDD DATE=YYMMDD
15 VALID-UNTIL-DATE
PIC 9(6)
COMP-6.
COMP-6.
HIDDEN Directive
The example below shows the usage of HIDDEN as a directive that will instruct SQL to not
display this field, considering that this is just a filler placeholder used to align the fields between
two different REDEFINES. With this directive, this field will simply not be displayed.
*>>XDD HIDDEN
10 RESERVED
PIC X(4).
Multi-Record Example
This is an example of using multiple records with SQL. Notice that CARD-TABLE-PLATINUM
redefines a previous record structure, but it includes additional fields. This means that this table
has two different types of records, with different sizes. c-treeRTG can handle this properly, as
long as you indicate the rules that the SQL server needs to use to decide which record belongs to
which table. To do this, use the following XDD directive:
*>>XDD WHEN ELITE-MEMBER-TYPE != "P" TABLENAME="REGULARMEMBERS"
05 CARD-TABLE.
This will instruct c-treeRTG to create two separate SQL tables representing each separate set of
records, depending on the condition that has been established for values within each record.
Notice that physically there is still a single COBOL file which allows you to run your COBOL
programs with no modification. c-treeRTG handles this dynamically, building SQL tables as if they
were actually views, and updating the indices in accordance with the file definition.
www.faircom.com
All Rights Reserved
108
In this example, we are forcing c-treeRTG to create a separate table to represent Platinum
members. This SQL table includes some additional fields that are not displayed for the regular
table.
*>>XDD WHEN ELITE-MEMBER-TYPE="P" TABLENAME="PLATINUMMEMBERS"
05 CARD-TABLE-PLATINUM REDEFINES CARD-TABLE.
10 GROUP-TITLE-INFO-PLT OCCURS 3 TIMES.
15 CARD-FAMILY-NUMBER-PLT.
20 CARD-LABEL-NUMBER-PLT
PIC 9(4).
20 CARD-MAIN-NUMBER-PLT
PIC 9(8).
20 CARD-NUMBER-CRC-PLT
PIC 9(2).
*>>XDD DATE=YYMMDD
15 EMISSION-DATE-PLT
PIC 9(6) COMP-6.
*>>XDD DATE=YYMMDD
15 VALID-UNTIL-DATE-PLT
PIC 9(6) COMP-6.
10 GROUP-REWARDS-POINTS.
15
TOTAL-POINTS
PIC 9(8).
*>>XDD DATE=YYMMDD
15
EXPIRATION-DATE
PIC 9(6)
COMP-6.
*>>XDD DATE=YYMMDD
15
LAST-TRANS-DATE
PIC 9(6)
COMP-6.
05
05
11.3
CARD-GROUP-NUMBER
CARD-EMBOSS-FLAG
PIC 9(4).
PIC X(1).
Source Code
The listings for the COBOL program and its copybook are included in this section.
SQLIZEEXAMPLE.CBL
IDENTIFICATION DIVISION.
PROGRAM-ID. SQLIZEEXAMPLE.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
COPY "CARDFILE.SL".
DATA DIVISION.
FILE SECTION.
COPY "CARDFILE.FD".
WORKING-STORAGE SECTION.
01
01
WS_CARDFILE_STATUS_CODE
PIC XX.
WS_CARDFILE_STATUS_CODE_85 PIC X(14).
01
01
WS_CRED_NUM_X PIC X(20).
WS_CRED_NUM_X_2 PIC X(10).
www.faircom.com
All Rights Reserved
109
01
01
01
WS_VALID_CRED_NUM PIC S9(2) COMP.
WS_LEN_CRED_NUM
PIC S9(2) COMP.
WS_COUNT
PIC 9(4).
01
01
01
WS_TOTAL_RECORDS PIC 9(8) VALUE ZEROS.
WS_DATA_REMAINS_SWITCH
PIC X(2)
WS_VALID_CARDS
PIC 9(4).
01
WS_DISP_X
VALUE SPACES.
PIC X(47).
LINKAGE SECTION.
SCREEN SECTION.
PROCEDURE DIVISION.
DECLARATIVES.
CARDHERROR SECTION.
USE AFTER ERROR PROCEDURE ON CARDFILE.
ERROR-ROUTINE.
IF WS_CARDFILE_STATUS_CODE = "35"
OPEN OUTPUT CARDFILE
CLOSE CARDFILE
OPEN INPUT CARDFILE
ELSE
CALL "C$RERR" USING WS_CARDFILE_STATUS_CODE_85
DISPLAY 'ERROR ON FILE:'
DISPLAY WS_CARDFILE_STATUS_CODE_85
DISPLAY "Press enter to exit:"
ACCEPT WS_CRED_NUM_X
STOP RUN
END-IF.
END DECLARATIVES.
MAIN SECTION.
MAIN-PARA.
MOVE ZERO TO WS_VALID_CARDS.
MOVE ZERO TO WS_TOTAL_RECORDS.
MOVE ZERO TO WS_VALID_CRED_NUM.
DISPLAY ""
DISPLAY "|--------------------------------------------|"
DISPLAY "|
Please visit us on
|"
DISPLAY "|
www.FairCom.com
|"
DISPLAY "|
c-treeACE SQL
|"
DISPLAY "|
FairCom Corporation
|"
DISPLAY "|
6300 West Sugar Creek Drive
|"
DISPLAY "|
Columbia, MO 65203
|"
DISPLAY "|--------------------------------------------|"
DISPLAY "|
This program lists and counts
|"
DISPLAY "|
all credit card holders within a file
|".
DISPLAY "|
whose credit card numbers are similar
|".
DISPLAY "|
to a sequence provided by the user.
|".
DISPLAY "|
Once it processed the whole file
|".
DISPLAY "|
it displays the total counting number. |".
DISPLAY "|--------------------------------------------|"
DISPLAY ""
PERFORM UNTIL WS_VALID_CRED_NUM = 1
www.faircom.com
All Rights Reserved
110
DISPLAY "Please provide a number to search for:"
DISPLAY "XXXXXXXXXX
(1-10 digits)"
MOVE 0 TO WS_CRED_NUM_X
MOVE 0 TO WS_COUNT
MOVE 0 TO WS_LEN_CRED_NUM
INSPECT WS_CRED_NUM_X REPLACING
ALL LOW-VALUE BY SPACE
INSPECT WS_CRED_NUM_X
TALLYING WS_COUNT FOR TRAILING SPACE
COMPUTE WS_LEN_CRED_NUM =
LENGTH OF WS_CRED_NUM_X - WS_COUNT
IF WS_LEN_CRED_NUM <= 10 THEN
IF WS_LEN_CRED_NUM > 0 THEN
MOVE 1 TO WS_VALID_CRED_NUM
ELSE
DISPLAY ""
DISPLAY "ERROR: INVALID INPUT!"
DISPLAY "Insert at least 1 digit."
DISPLAY ""
END-IF
ELSE
DISPLAY ""
DISPLAY "ERROR: INVALID INPUT!"
DISPLAY "Greater than 10 digits."
DISPLAY ""
END-IF
END-PERFORM.
OPEN I-O CARDFILE.
READ CARDFILE NEXT
AT END MOVE 'NO' TO WS_DATA_REMAINS_SWITCH
END-READ.
PERFORM PROCESS-RECORDS
UNTIL WS_DATA_REMAINS_SWITCH = 'NO'.
PERFORM PRINT_SUMMARY.
CLOSE CARDFILE.
010-PROCESS.
GOBACK.
PROCESS-RECORDS.
MOVE CARD-RECORD-NUMBER TO WS_CRED_NUM_X_2.
MOVE WS_CRED_NUM_X_2(1:WS_LEN_CRED_NUM)
TO WS_CRED_NUM_X_2.
IF WS_CRED_NUM_X_2 = WS_CRED_NUM_X
ADD 1 TO WS_VALID_CARDS
IF WS_VALID_CARDS = 1 THEN
DISPLAY ""
DISPLAY "|--------------------------------------------|"
DISPLAY "|CARD NUMBER | NAME
|"
END-IF
MOVE "| " TO WS_DISP_X
MOVE CARD-RECORD-NUMBER TO WS_DISP_X(3:10)
MOVE " | " TO WS_DISP_X(13:5)
MOVE CARD-CUSTOMER-NAME TO WS_DISP_X(18:28)
MOVE "
|" TO WS_DISP_X(43:4)
www.faircom.com
All Rights Reserved
111
DISPLAY WS_DISP_X
END-IF.
ADD 1 TO WS_TOTAL_RECORDS.
READ CARDFILE NEXT
AT END MOVE 'NO' TO WS_DATA_REMAINS_SWITCH
DISPLAY "|--------------------------------------------|"
DISPLAY ""
END-READ.
PRINT_SUMMARY.
DISPLAY "TOTAL NUMBER OF CARDS MATCHING:".
DISPLAY WS_VALID_CARDS.
DISPLAY "TOTAL NUMBER OF RECORDS READ:"
DISPLAY WS_TOTAL_RECORDS.
DISPLAY "Press enter to exit:"
DISPLAY "|--------------------------------------------|"
DISPLAY "| Thank you for trying our SQLIZE Tutorial |"
DISPLAY "|
Please visit us on
|"
DISPLAY "|
www.FairCom.com
|"
DISPLAY "|--------------------------------------------|"
.
www.faircom.com
All Rights Reserved
112
CARDFILE.FD
*
*
*
*
*
This file is intended to be used as a tutorial
for c-treeRTG COBOL Edition developers to learn
about the multiple ways that a file descriptor
is mapped into a SQL table within c-treeACE SQL.
All copyrights belong to FairCom, Corp.
*
*
*
*
**********************************************************
The main file of this tutorial is CARDFILE, a file that
contains records of a reward membership card for customers.
**********************************************************
FD CARDFILE.
01 CARDRECORD-MASTER.
05 CARDRECORD-KEY.
10 CARD-RECORD-NUMBER
PIC 9(10).
10 CARD REDEFINES CARD-RECORD-NUMBER.
15 CARD-1
PIC 9(6).
15 CARD-2
PIC 9(4).
*
**********************************************************
*
-----------------> TUTORIAL HINT <----------------------*
*
By default xddgen expands the innermost fields.
*
The "USE GROUP" directive is used here to force xddgen,
*
when building the SQL table, to consider the entire
*
CARD-TITLE-NUMBER group as one field instead of expanding
*
its subfields. In this case we want to expose it and not
*
its children.
*
*
**********************************************************
*>>XDD USE GROUP
10 CARD-TITLE-NUMBER.
10 CARD-TITLE-NUMBER-X REDEFINES CARD-TITLE-NUMBER
PIC 9(10).
10 CUSTOMER-NUMBER
PIC 9(4).
10 ELITE-MEMBER-TYPE
PIC X.
88 CARD-GOLD
VALUE "G".
88 CARD-PLATINUM
VALUE "P".
88 CARD-SILVER
VALUE "S".
***********************************************************
* CARD IDENTIFICATION DEFINITION
***********************************************************
***********************************************************
* -----------------> TUTORIAL HINT <----------------------*
* This is an example of the usage of multi-record with SQL.
* You can notice that CARD-TABLE is redefined later in this
* file by CARD-TABLE-PLATINUM which includes additional fields.
* This means that this table in COBOL has two different types
* of records, with different size. c-treeRTG can handle this
* properly, as long as you indicate what are the rules that
* the SQL server needs to use to decide which record belongs
* to which table. To do this, you use the following XDD directive:
* *>>XDD WHEN ... TABLENAME=...
* This will instruct c-treeRTG to create two separate SQL tables
* representing each separate set of records, depending on the
* condition that has been established for values within each
* record.
www.faircom.com
All Rights Reserved
113
* Notice that physically there is still a single COBOL file
* which allows you to run your COBOL programs with no modification.
* c-treeRTG handles this dynamically, building SQL tables as
* if they were actually views, and updating the indices in
* accordance to the file definition.
* In this example, we are forcing c-treeRTG to create two tables
* one for regular members ad one for Platinum members.
***********************************************************
*>>XDD WHEN ELITE-MEMBER-TYPE != "P" TABLENAME="REGULARMEMBERS"
05 CARD-TABLE.
***********************************************************
* -----------------> TUTORIAL HINT <----------------------*
* There are at maximum three copies of each membership card
* assigned to different family member, of which the first one
* is only assigned while the other two are optionally assigned.
* We needed to build an index on CARD-FAMILY-NUMBER of the
* first copy of the card. Therefore instead of coding a
* OCCURS 3, we explicitly add fields for the first card copy and
* coded a OCCURS 2 for the rest.
***********************************************************
*>>XDD USE GROUP
10 CARD-FAMILY-NUMBER-1.
15 CARD-LABEL-NUMBER-1
PIC 9(4).
15 CARD-MAIN-NUMBER-1
PIC 9(8).
15 CARD-NUMBER-CRC-1
PIC 9(2).
10 EMISSION-DATE-1
PIC 9(6)
COMP-6.
***********************************************************
* -----------------> TUTORIAL HINT <----------------------* The example below shows how to combine multiple XDD directives
* into a single line. In this example, we combined USE GROUP
* to force SQL to use the name of the group as the SQL field
* and a specific format to display this field as a date
* as YMD. There are multiple other formats available, please
* refer to the documentation for other options.
***********************************************************
*>>XDD USE GROUP
*>>XDD DATE=YYMMDD
10 VALID-UNTIL-DATE-1 PIC 9(6) COMP-6.
***********************************************************
* -----------------> TUTORIAL HINT <----------------------* Here is the OCCURS 2 we talked about earlier.
* OCCURS are handled automatically by c-treeRTG when converting
* this table into SQL. xddgen automatically expands every
* occurr into multiple fields, using numbered extensions such
* as "_1", "_2" and so on.
* Therefore the fields would be named as follows
* CARD_FAMILY_NUMBER_1
* EMISSION_DATE_1
* VALID_UNTIL_DATE_1
* CARD_FAMILY_NUMBER_2
* EMISSION_DATE_2
* The first three fields cause a field name conflict, with the
* some fields previously defined in the structure (the three fields we
* specified outside the occurs at lines 57, 63, 76).
* This field name conflict does not allow the table to be "sqlized"
* since field names must be unique.
www.faircom.com
All Rights Reserved
114
* The solution to this is to use the *>>XDD NAME directive to assign
* a different name for SQL to the conflicting fields.
* the result of the directive below is the following fields:
* EMISSION_DATE_1
* CARD_FAMILY_NUMB_1
* EMISSION_1
* VALID_UNTIL_1
* CARD_FAMILY_NUMB_2
* EMISSION_2
* VALID_UNTIL_2
***********************************************************
10 GROUP-TITLE-INFO OCCURS 2 TIMES.
*>>XDD USE GROUP
*>>XDD NAME=CARD_FAMILY_NUMB
15 CARD-FAMILY-NUMBER.
20 CARD-LABEL-NUMBER
PIC 9(4).
20 CARD-MAIN-NUMBER
PIC 9(8).
20 CARD-NUMBER-CRC
PIC 9(2).
*>>XDD USE GROUP
*>>XDD NAME=EMISSION
15 EMISSION-DATE
*>>XDD USE GROUP
*>>XDD NAME=VALID_UNTIL
*>>XDD DATE=YYMMDD
15 VALID-UNTIL-DATE
PIC 9(6)
PIC 9(6)
COMP-6.
COMP-6.
***********************************************************
* -----------------> TUTORIAL HINT <----------------------* The example below shows the usage of HIDDEN as a directive
* that will instruct SQL to not display this field.
* With this directive, this field will simply not be displayed.
***********************************************************
*>>XDD HIDDEN
10 RESERVED
PIC X(4).
***********************************************************
* -----------------> TUTORIAL HINT <----------------------* Fillers are hidden by default so there is no need to use
* directives here.
***********************************************************
10 FILLER
PIC X(10).
***********************************************************
* -----------------> TUTORIAL HINT <----------------------*
* Here it comes the platinum member table we described above
***********************************************************
*>>XDD WHEN ELITE-MEMBER-TYPE="P" TABLENAME="PLATINUMMEMBERS"
05 CARD-TABLE-PLATINUM REDEFINES CARD-TABLE.
10 GROUP-TITLE-INFO-PLT OCCURS 3 TIMES.
15 CARD-FAMILY-NUMBER-PLT.
20 CARD-LABEL-NUMBER-PLT
PIC 9(4).
20 CARD-MAIN-NUMBER-PLT
PIC 9(8).
20 CARD-NUMBER-CRC-PLT
PIC 9(2).
*>>XDD DATE=YYMMDD
15 EMISSION-DATE-PLT
PIC 9(6) COMP-6.
*>>XDD DATE=YYMMDD
www.faircom.com
All Rights Reserved
115
10
15 VALID-UNTIL-DATE-PLT
GROUP-REWARDS-POINTS.
15
TOTAL-POINTS
*>>XDD DATE=YYMMDD
15
EXPIRATION-DATE
*>>XDD DATE=YYMMDD
15
LAST-TRANS-DATE
05 CARD-GROUP-NUMBER
05 CARD-EMBOSS-FLAG
*>>XDD USE GROUP
05 CARD-CUSTOMER-NAME.
10 CARD-CUSTOMER-LAST
10 CARD-CUSTOMER-FIRST
10 CARD-CUSTOMER-M
05 CARD-ADDRESS.
10 CARD-STREET
10 CARD-STREET-2
10 CARD-CITY
10 CARD-STATE
10 CARD-ZIP
05 CARD-CUSTOMER-SEX
88 CARD-MEMBER-MAL
88 CARD-MEMBER-FEM
*>>XDD DATE=YYYYMMDD
05 CARD-CUSTOMER-BIRTH-DATE
PIC 9(6) COMP-6.
PIC 9(8).
PIC 9(6)
COMP-6.
PIC 9(6)
COMP-6.
PIC 9(4).
PIC X(1).
PIC X(30).
PIC X(20).
PIC X(1).
PIC X(40).
PIC X(40).
PIC X(15).
PIC X(2).
PIC 9(5)
COMP-6.
PIC X(1).
VALUE "M".
VALUE "F".
PIC 9(8)
COMP-6.
www.faircom.com
All Rights Reserved
116
CARDFILE.SL
*
*
*
*
*
This file is intended to be used as a tutorial
for c-treeRTG COBOL Edition developers to learn
about the multiple ways that a file descriptor
is mapped into a SQL table within c-treeACE SQL.
All copyrights belong to FairCom, Corp.
SELECT
CARDFILE
ASSIGN TO "CARDFILE"
ORGANIZATION IS INDEXED
ACCESS MODE IS DYNAMIC
RECORD KEY IS
CARDRECORD-KEY
ALTERNATE RECORD KEY IS
SPLIT-KEY-NAME-1 =
CARD-CUSTOMER-NAME,
CARD-GROUP-NUMBER
WITH DUPLICATES
SPLIT-KEY-NAME-2 =
CARD-GROUP-NUMBER,
CARD-TITLE-NUMBER,
CARD-FAMILY-NUMBER-1
WITH DUPLICATES
CARD-EMBOSS-FLAG
WITH DUPLICATES
FILE STATUS IS WS_CARDFILE_STATUS_CODE.
rules.xml
<XFDrules>
<when>
</when>
<do>
<add>
<field bindefault="all-spaces"/>
</add>
</do>
</rule>
</XFDrules>
www.faircom.com
All Rights Reserved
117
12. Utilities: ctutil, ctcbtran, xddgen, cttrnmod,
ctmigra, ctfileid
The c-treeRTG products provide several utilities that you will need. These utilities are located in
the same directory as the sample programs.
Utilities for data migration:
 ctmigra (page 50) - Migrates data into c-treeRTG applications by reading records from an
external database and writing them to c-treeRTG files. Located in tools\cmdline under your
c-treeRTG installation directory.
RTG Migrate (page 45), - This GUI-based migration utility can be found in tools/guitools.java.
Other common utilities are available for various c-treeRTG tasks are located in tools\cmdline
under your c-treeRTG installation directory:
 ctutil (page 121) - A general purpose c-treeRTG file maintenance utility. Use ctutil to
examine files, extract data records, change maximum record sizes, and rebuild corrupted
indices. Much of ctutil's functionality is comparable to Vision's vutil utility for a familiar feel,
however, many additional c-treeRTG extensions and features have been added.
A pre-configured version of ctutil is provided with each c-treeRTG supported flavor of
COBOL and found in Driver/ctree.cobol/<flavor> folder.
 ctcbtran (page 158) - When ctutil is renamed ctcbtran, it functions as an ad-hoc utility to
turn on/off transaction processing. Review the ctutil -tron option for details.
 xddgen (page 160) - Generates c-treeRTG XDD files directly from COBOL source code. This
feature is especially useful when native COBOL XFD files are not available, or you need
advanced handling of COBOL table structures.
Find xddgen in Tools\cmdline\XDDGEN of your c-treeRTG installation.
 cttrnmod (page 168, http://docs.faircom.com/doc/ctreeplus/#49162.htm) - Allows an
advanced user to change transaction status of a c-treeACE data file and its associated index
files.
cttrnmod can be found in the \Tools\cmdline of your c-treeRTG installation.
 ctfileid (page 172) - Provides a convenient and safe way to update the fileid parameter of the
file header.
c-treeRTG also includes a set of graphical utilities, such as the migration and configuration tools
described elsewhere in this book. For descriptions of the other graphical utilities, see the help
files included with the tools or FairCom GUI Tools (http://docs.faircom.com/doc/JavaTools/)
on the website.
www.faircom.com
All Rights Reserved
118
Utilities: ctutil, ctcbtran, xddgen, cttrnmod, ctmigra, ctfileid
More Command-Line Utilities
c-treeRTG includes a large set of command-line utilities in the tools\cmdline directory of your
c-treeRTG installation. For complete descriptions of these utilities, see the Command-Line Tools
(http://docs.faircom.com/doc/cmdline/#cover.htm) book on the FairCom website.
 ctadmn - Server Administrator Utility used by the Server Administrator to manage users,
groups, and files.
 ctclntrn - Clean Transaction Mark “cleans” the high-water transactions marks within a
c-treeACE index.
 ctdump - Dynamic Dump Utility provides an administrator a safe, secure method of backing
up data while c-treeACE is operational.
 ctfdmp - Forward Dump Utility to restore data to a given time following a ctrdmp restore.
 ctfilblkif - Block or unblock a specified c-treeACE file.
 ctfileid - Update File ID utility provides a convenient and safe way to update the fileid
parameter of the file header.
 ctflvrfy - Index Verify utility allows the user to verify an index and, optionally, inspect it at a
low-level.
 cthghtrn - Displays the high-water mark for transactions.
 ctidmp - Examine Dump Files lists the contents of a dynamic dump file or a specific extent of
a dump broken into multiple files.
 ctldmp - Transaction Log Dump performs a partial dump of the transaction logs to assist the
developer in problem resolution.
 ctmigra - A data migration utility for converting non-c-tree data for use with c-treeRTG.
Described in the c-treeRTG User Guide.
 ctpass - Password Utility to allow users to change their password.
 ctquiet - Quiesce c-treeACE Utility allows an administrator to quiet the server from a script.
 ctrdmp - Forward Dump Utility to restore data to a given time following a ctrdmp restore.
 ctsqlcdb - c-treeACE SQL Database Maintenance Utility.
 ctsqlutl - c-treeACE SQL Maintenance Utility to perform maintenance on the c-treeACE SQL
Server.
 ctstat - Statistics Monitoring Utility to display statistics and provide real-time monitoring of
critical c-treeACE operations.
 ctstop - Server Stop Utility to shut down c-treeACE Server.
 ctsysm - Server Status Monitoring Utility monitors error, warning, and informational
messages logged to the server status log.
 cttrap - Communications Trap Playback utility "plays back" a TRAP_COMM log file.
 cttrnmod - Change Transaction Mode Utility allows an advanced user to change the
transaction status of a c-treeACE data file and its associated index files.
 ctunf1 - File Reformatting Utility reformats a file IN PLACE provided the new alignment
restriction does not cause the data record contents to become misaligned.
 ctvfyfil - File Verify Utility
 ctvfyidx - Index Verify Utility checks the integrity of an index file.
 dbdeploy - Utility to deploy stored procedures, user-defined functions, and triggers.
www.faircom.com
All Rights Reserved
119
 dbdump - Data Unload Utility writes the data in a database to a file.
 dbload - Data Load Utility loads records from an input data file into tables of a database.
 dbschema - Schema Export Utility generates c-treeACE SQL statements to recreate the
specified database elements and data.
 isql - Interactive SQL utility provides an industry-standard "command processing" interface to
the c-treeACE SQL Database Engine.
 sa_admin - Command-line security administration utility.
www.faircom.com
All Rights Reserved
120
12.1
ctutil
ctutil provides functionality to perform maintenance tasks on indexed files. Users of Vision
COBOL will recognize it as the c-treeRTG counterpart of the Vision vutil utility. BTRV users may
find it useful for importing data.
ctutil allows you to examine files, extract data records, change the maximum record size, and
rebuild corrupted indices. The functions are designed to allow you to specify all possible task
parameters up front, such that the utility can run unattended or with a minimum of user
interaction.
Beyond the functionality mentioned above, ctutil is important in many aspects of c-treeRTG
operation, including preparing data for SQL access (page 54) and importing BTRV data. See
ctutil Commands (page 122) for a listing of ctutil commands organized by type.
Usage
ctutil [-c config_file] [-s] command ...
 -c config_file - specify a c-tree configuration file to bypass default CTREE_CONF
 -s - superuser mode allows the utility to open a file marked as corrupted (ctOPENCRPT
c-tree file mode)
 -l (lower case "L") - dump the configuration in XML format before the actual ctutil output (V2
and later).
Return Code
The ctutil command returns 0 if the operation was successful or a positive number if it failed.
ctutil Notes
CTUTIL uses stdout to output data and stderr to output the program status. If you do not want to
see the status message "Operation completed successfully" you can redirect the stderr stream:
$ ctutil >/tmp/output.txt 2>/tmp/error.txt
In the example below, if you want to redirect both stdout and stderr you could use the following:
$ ctutil -info /usr/tree/r1/sc0001/LP/LNFILE >/usr/tmp/km.txt 2>&1
Please notice that “2>&1” means “redirect stderr (stream 2) to stdout (stream 1).” ctutil uses
stdout to output data and stderr to output the program status.
If you want to know if the ctutil command was successful despite the output, you can check the
return value of ctutil.
Unix:
$ ctutil >/tmp/output.txt 2>/tmp/error.txt
$ [ $? -eq 0 ] && echo OK
Windows:
C:\> ctutil >/tmp/output.txt 2>/tmp/error.txt
C:\> @if errorlevel 0 echo OK
www.faircom.com
All Rights Reserved
121
ctunload407 to unload data of files affected by error 407
Support has been added to the c-treeRTG ctutil utility to open files affected by error 407 so it can
export data from a file that has a damaged resource chain. This support requires ADMIN
permission and the OPENCRPT file mode. To use this functionality, ctutil must be renamed to
ctunload407. The ctunload407 utility functions similar to ctutil -unload except that it
automatically connects as ADMIN (with the default ADMIN password) and enables the
<allowcorrupt> setting.
ctutil Commands
Available ctutil commands are listed in the following sections.
Information options
 -info file [-x] (page 134)
 -param file (page 139)
 -profile file (page 140)
Maintenance options
 -make file xfd_file (page 135)
 -copy source_file dest_file (page 130)
 -clone source_file dest_file
 -filecopy
source_file dest_file [-overwrite]
 -rename source_file dest_file (page 144)
 -remove file (page 143)
 -upgrade source_file [dest_file] (page 157)
Consistency options
 -check file [-x] [-k=index] (page 124)
 -rebuild file [-purgedups] [-delidx] (page 142)
 -compact file [-purgedups] [-delidx] (page 127)
Definition options
 -setpath file (page 146)
 -tron file T|P|F|W (page 153)
 -segment file max_file_size max_segments (page 145)
 -conv file convention_ID (page 129)
 -compress file (page 128)
 -uncompress file (page 154)
String image options
 -getimg file (page 133)
 -makeimg file image_string (page 136)
www.faircom.com
All Rights Reserved
122
 -checkimg file image_string (page 125)
 -rblimg file image_string (page 141)
 -addimg
file image_string
Import/export options
 -load file seq_file [-b|t|p] [-v[2|4|8][n|x]] [-r|s] [-rs=recsiz] (page 137)
 -unload file seq_file [-b|t|p] [-v[2|4|8][n|x]] (page 155)
SQL options
 -sqlinfo file [xdd_file [convention_ID]] (page 148)
 -sqllink file admin_password database_name (page 149)
[-symb=table_name] [-prefix=table_prefix]
[-owner=user_name] [-public[=ro]]
 -sqlunlink file admin_password database_name (page 150)
[-owner=user_name]
 -sqlize file xfd_file admin_password database_name (page 151)
[-conv=convention_ID] [-rule=rules_file]
 -xfd2xdd xfd_file [-rule=rules_file] (page 158)
 -sqlcheck
file xfd_file
 -ddf2xdd (for use with c-treeRTG BTRV Edition)
Miscellaneous options
 -cryptconf config_file output_file (page 132)
 -test [config|connect] (page 152)
www.faircom.com
All Rights Reserved
123
-check
Tests a file for internal consistency.
Usage
ctutil -check
file_name [-x] [-k=index]
where:
 file_name - File name without extension
 -x - Perform extended tests matching records with keys
 -k=index - Perform tests only on specified index
For very large files with many indexes, you may want to consider using the -k option to validate
only a single index.
www.faircom.com
All Rights Reserved
124
-checkimg
Compares a file with a definition string.
Usage
ctutil -checkimg
file_name
image_string
where:
 image_string - File definition string
www.faircom.com
All Rights Reserved
125
-clone
Create an empty copy of an existing file.
Usage
ctutil -clone
source_file dest_file
where:
 source_file - Source file name without extension
 dest_file - Destination file name without extension
www.faircom.com
All Rights Reserved
126
-compact
Removes the deleted records of a file.
Usage
ctutil -compact file_name [-purgedups] [-delidx]
where:
 -purgedups - Purge duplicate records from data file
 -delidx - Force the deletion of the index file before rebuilding
www.faircom.com
All Rights Reserved
127
-compress
The ctutil -compress command adds data compression to an existing file. The compression type,
level, and strategy are retrieved from settings documented for the <datacompress> (page 188)
option in the c-treeRTG COBOL Edition configuration file.
Usage
To compress the contents of file:
ctutil -compress
file_name
where:
 file_name - File name without extension.
See Also
-uncompress (page 154)
www.faircom.com
All Rights Reserved
128
-conv
The -conv option defines the numeric storage convention for a file.
Usage:
ctutil -conv
file convention_ID
where:
 file - File name without extension
 convention_ID - Numeric storage convention ID. The ID is one of the following:
A ACUCOBOL-GT
B MBP COBOL
D Data General
I IBM
M Micro Focus
N NCR COBOL
R Realia COBOL
V VAX COBOL
www.faircom.com
All Rights Reserved
129
-copy
Copies a file record-by-record creating a new file based on the configuration settings.
Usage
ctutil -copy
source_file
dest_file
where:
Notes:
-copy vs -filecopy
The -copy option creates a copy of a file by building it record-by-record, which creates a new file
based on the configuration settings. The -filecopy (page 132) option makes an exact copy of the
source file, which can be faster than the -copy option.
The difference between these options is that the -copy option creates the destination file based
on the configuration setting while the -filecopy option creates an exact copy of the source file.
Both approaches have limitations and advantages:
 -filecopy is faster than -copy and provides an exact copy of the file.
 -copy may be helpful when you need to change file characteristics.
For example, suppose you use <keycompress> in your ctree.conf file to compress keys and you
need to disable it for a specific file. You could add a specific <file> section in your ctree.conf
that removes the <keycompress> setting from the destination file and then simply run ctutil
-copy. The ctree.conf would look as shown below:
<config>
<instance>
<file> 
<keycompress>yes</keycompress>
</file>
<file name="*_nocompress"> 
<keycompress>no</keycompress>
</file>
</instance>
</config>
Run ctutil -copy making sure to use the correct ctree.conf:
ctutil -c ctree.conf -copy myfile myfile_nocompress
The resulting destination file myfile_nocompress will have all data records from the source file but
its keys will be not compressed.
www.faircom.com
All Rights Reserved
130
ctutil -copy vs Dynamic Dump
The recommended alternative to the ctutil -copy operation is the "Dynamic Dump" backup and
restore option using the ctdump utility. (See Dynamic Dump
(http://www.faircom.com/doc/ctserver/#8376.htm) in the c-treeACE Server Administrator's Guide).
If your files are under transaction processing control (TRNLOG), the Dynamic Dump (utility name
is ctdump) is preferable because the ctdump utility uses transaction processing control if the
data file is TRNLOG enabled. This has the advantage that the data file and any associated
indices are guaranteed to be in a consistent state, even if the file is updated during the backup
process.
The ctutil -copy operation is not under TRNLOG control, therefore it is possible to end up with an
index file that is inconsistent with the data file (for example, if a file is updated during the copy
operation).
If a data file is not under TRNLOG control, the Dynamic Dump offers one advantage over ctutil
-copy: The !PROTECT and !PROTECT_LOW keywords can be used in a Dynamic Dump backup
script to instruct the system not to allow any file updates while each non-TRNLOG file is being
backed up. (See Dump Files Without Transaction Control
(http://www.faircom.com/doc/ctserver/#8387.htm) in the c-treeACE Server Administrator's Guide).
See also:
-filecopy (page 132)
www.faircom.com
All Rights Reserved
131
-cryptconf
Encrypt the ctree.conf configuration file.
Usage:
ctutil -cryptconf
config_file output_file
where:
 -cryptconf - Encrypt the ctree.conf configuration file
 config_file - Name of the configuration file to be encrypted (typically ctree.conf)
 output_file - Name of the encrypted output file
See
 Support for encrypting configuration file (page 32)
-filecopy
Perform a physical file copy.
Usage:
ctutil -filecopy source_file dest_file [-overwrite].
Notes:
The command is not dependent on the configuration file, thus a ctutil -filecopy command will
always perform a physical file copy independently from the configuration settings (as opposed to
the -copy (page 130) option).
The ctutil -filecopy does not overwrite existing files unless the -overwrite option is specified.
See also:
 <filecopy> (page 193)
 -copy (page 130)
www.faircom.com
All Rights Reserved
132
-getimg
Displays the definition string of a file.
Usage
ctutil -getimg file_name
where:
See Also
 -rblimg (page 141)
www.faircom.com
All Rights Reserved
133
-info
Displays information about a file, including the file's WRITETHRU file mode. and the Max Length
for variable-length files.
Usage
ctutil -info
file_name [ -x ]
where:
 -x - Display extended information. (optional)
www.faircom.com
All Rights Reserved
134
-make
Creates a file using XFD definitions.
Usage
ctutil -make file xfd_file
where:
 file - File name to create without extension
 xfd_file - Path to XFD file containing file definitions
www.faircom.com
All Rights Reserved
135
-makeimg
Creates a file from a definition string.
Usage
ctutil -makeimg file_name
image_string
where:
www.faircom.com
All Rights Reserved
136
-load
Imports data from a sequential file. The ctutil -load command reads a sequential file and writes
the records in it to a c-tree file.
Usage
ctutil -load file_name seq_file [-b|t|p] [-v[2|4|8][n|x]] [-r|-s] [-rs=reclen]
where:
 seq_file - Path to the source file.
 -b - Indicates a binary sequential format is used.
 -t - Indicates a line sequential format (records separated by new-line character).
 -p - Indicates an ASCII file created by the BTRV BUTIL -save command.
 -v - Indicates variable-length format (record data is preceded by record length) and is
optionally followed by a 2 or 4 or 8 that indicates the size of the record length field that
precedes the record data and by a n or x to indicate if the record length is represented in
native (n) or big-endian (x) format.
 -r - Replace any existing record that returns 'duplicate key' error.
 -s - Skip any existing record that returns 'duplicate key' error.
 -rs=recsiz - Record size of the sequential file (required only if the record size of the
destination file differs from that of the sequential file).
The command assumes that the record size of the sequential file is the same as the c-tree file. If
they differ, the -rs option is used to specify the record size of the sequential file.
See Also:
 -unload (page 155)
www.faircom.com
All Rights Reserved
137
-loadtext
Imports data from a text file.
Note: This command has been replaced by the -t option of the -load (page 137) command.
www.faircom.com
All Rights Reserved
138
-param
Displays the c-tree parameter definition of a file.
Usage
ctutil -param
file_name
where:
www.faircom.com
All Rights Reserved
139
-profile
Displays information about a file.
Usage
ctutil -profile
file_name
where:
www.faircom.com
All Rights Reserved
140
-rblimg
Rebuilds a file using a definition string (e.g., created by the -getimg option).
Usage
ctutil -rblimg
file_name
image_string
where:
www.faircom.com
All Rights Reserved
141
-rebuild
Rebuilds the indices of a file.
Usage
ctutil -rebuild file_name [-purgedups]
where:
 -purgedups - Purge duplicate records from data file
 -delidx - Force the deletion of the index file before rebuilding
www.faircom.com
All Rights Reserved
142
-remove
Removes a file.
Usage
ctutil -remove
file_name
where:
www.faircom.com
All Rights Reserved
143
-rename
Renames or moves a file.
Usage
ctutil -rename
source_file
dest_file
where:
www.faircom.com
All Rights Reserved
144
-segment
Enables file segmentation on a file.
Usage
ctutil -segment
file_name
max_file_size
max_segments
where:
 max_file_size - Maximum file size for single file segment
 max_segments - Maximum number of file segments
Note: Keep max_segments as low as possible to optimize performance.
www.faircom.com
All Rights Reserved
145
-setpath
Updates the path of a file. The c-tree files contain information about the file including the path
location of the file itself. After copying a file to a location other than the creation directory, it is
necessary to reset the file path information according to the new file location.
Usage
ctutil -setpath
file_name
where:
www.faircom.com
All Rights Reserved
146
-sign
The -sign option is synonymous with the -conv (page 129) option to store the sign-storage
convention ID in a file.
See:
 -conv (page 129)
-sqlcheck
This ctutil option verifies that the data is correct in sqlized tables:
ctutil -sqlcheck
The ctutil command -sqlcheck option is used ot verify that data in a file is compatible with SQL
definitions. The command scans all records of the given file using the primary key index and
stops at the first conversion error encountered showing an error message, the record number,
schema and field name of the incorrect data.
Usage:
ctutil -sqlcheck
file xdd_file [-conv=convention_ID]
The -sqlcheck option checks SQL definitions against data in a file. Valid parameters are:
 xdd_file - Path to a data definition file in XML format
 convention_ID - Optional numeric storage convention ID:
A - ACUCOBOL-GT (default)
B - MBP COBOL
D - Data General
I - IBM
M - Micro Focus
N - NCR COBOL
R - Realia COBOL
V - VAX COBOL
Example:
The usage and output of the command is as follows:
C:\>ctutil -sqlcheck filecompa filecompa.xdd -conv=A
ctutil Version 11.2.0.5893-160315
Initialized from (ctree.conf)
Checking filecompa...
ascii value is not a digit. Record#: 8 Schema#: 0 Field: NS
Operation completed successfully.
www.faircom.com
All Rights Reserved
147
-sqlinfo
Stores or retrieves SQL definitions to or from a file.
Usage
ctutil -sqlinfo
file [xdd_file [convention_ID]]
where:
 xdd_file - Path to a data definition file in XML format
 convention_ID - Optional numeric storage convention ID:
A ACUCOBOL-GT (default)
B MBP COBOL
D Data General
I IBM (Also applies to many RM COBOL numeric types)
M Micro Focus
N NCR COBOL
R Realia COBOL
V VAX COBOL
www.faircom.com
All Rights Reserved
148
-sqllink
Makes an existing file accessible from SQL by linking the file name to the c-treeACE SQL
dictionaries.
Usage
ctutil -sqllink file_name admin_password database_name
[-symb=table_name] [-prefix=table_prefix] [-owner=user_name] [-public[=ro]]
where:
 admin_password - c-treeRTG ADMIN password
 database_name - Database name to be associated with the file
 symb=table_name - Optional table name to use when adding file to a database
 prefix=table_prefix - Optional prefix for table or symbolic name
 owner=user_name - Optional user name to assign table ownership
 public[=ro] - Optionally grant public access permissions, read-only when =ro is used
Note: This is an administrative operation and therefore must be performed with caution. Do not
attempt to use this operation on a file that is open.
Error Logging
When the ctutil -sqllink or ctutil -sqlize procedure or an automatic "sqlize" by the COBOL driver
fails, the logic logs an error messages that could help identifying issues. The ctsqlcbk.FCS file on
the client will have information about the nature of the error.
www.faircom.com
All Rights Reserved
149
-sqlunlink
Removes a file from the c-treeACE SQL dictionaries such that it is no longer accessible from
SQL.
Usage
ctutil -sqlunlink file_name admin_password database_name
[-symb=table_name] [-prefix=table_prefix] [-owner=user_name]
where:
 admin_password - c-treeRTG ADMIN password
 database_name - Database name to remove the file (table) from
 symb=table_name - Optional table name to use when adding file to a database
 prefix=table_prefix - Optional prefix for table or symbolic name
 owner=user_name - Optional user name to assign table ownership
www.faircom.com
All Rights Reserved
150
-sqlize
Performs all necessary operations to make a file accessible from c-treeACE SQL. In fact it groups
a number of operations which can be executed separately helping the user to make the file
accessible from c-treeACE SQL using only one command. The sqlize option accepts XFD or XDD
files as input.
Usage
ctutil -sqlize file xfd_file admin_password database_name
[-conv=convention_ID] [-rule=rules_file]
where:
 xfd_file - Path to a XFD or XDD file
 admin_password - c-treeACE Server ADMIN password
 database_name - Database name to add the file to
 -symb=table_name - Optional table name to link file to database
 -prefix=table_prefix - Optional prefix for table name
 -owner=user_name - Optional user name to assign table ownership
 -public[=ro] - Optionally grant public access permissions; read-only when =ro is used
 -conv=convention_ID - Optional numeric storage convention ID:
A - ACUCOBOL-GT (default)
B - MBP COBOL
D - Data General
I - IBM (Also applies to many RM COBOL numeric types)
M - Micro Focus
N - NCR COBOL
R - Realia COBOL
V - VAX COBOL
 -rule=rules_file - Optional path to rules file - see Define External Rules (page 59)
Error Logging
When the ctutil -sqllink or ctutil -sqlize procedure or an automatic "sqlize" by the COBOL driver
fails, the logic logs an error messages that could help identifying issues. The ctsqlcbk.FCS file on
the client will have information about the nature of the error.
www.faircom.com
All Rights Reserved
151
-test
A new -test option has been added to the c-treeRTG ctutil command to check the configuration
and connections to servers. This option can be used to check the configuration and, optionally,
the connection to servers. The syntax is:
ctutil -test [config | connect]
where config and connect are optional.
 Running ctutil -test with no option, or with the config option, checks the configuration.
 Running ctutil -test connect checks that all servers defined in the configuration (with the
<instance server> attribute) are reachable.
www.faircom.com
All Rights Reserved
152
-tron
Sets the file mode for a file.
Usage
ctutil -tron file_name T|P|F|W
where:
 T - Enable full transaction processing control (ctTRNLOG c-tree file mode). This mode is
recommended for most applications and it is required to take full advantage of c-treeRTG
advanced features.
Note: By default, c-treeRTG files are created as ctPREIMG. When enabling full transaction
control on these default files, no rebuild of the indices is necessary.
It is necessary to also adjust the ctree.conf file to enable full transaction logging for the file(s)
affected. For example,
<file name="CUSTMAST" dir=".">
<transaction logging="yes">yes</transaction>
</file>
 P - Enable logical transaction processing control without logging (ctPREIMG c-tree file
mode). This is the default mode and is indicated where both transaction atomicity and high
performance are required. By suppressing transaction logging it is possible to achieve high
data throughput at the expense of data recoverability. This mode is recommended in
environments protected from system crashes or cases in which data integrity/recoverability is
not an issue.
 F - Asynchronous writes. This mode should only be used on files which data integrity is not
critical as data recovery is not guaranteed in case of a system crash.
 W - Synchronous writes (ctWRITETHRU c-tree file mode). This mode is indicated where
transaction processing may not be suitable yet data safety remains critical.
See also ctcbtran (page 158).
www.faircom.com
All Rights Reserved
153
-uncompress
The ctutil -uncompress command removes data compression from an existing file.
Usage
ctutil -uncompress file_name
where:
See Also
-compress (page 128)
www.faircom.com
All Rights Reserved
154
-unload
Exports data from a COBOL data file to a sequential file. If the COBOL file is encrypted, ctutil
returns error 33: Operation not allowed. File is encrypted.
Usage
ctutil -unload file_name seq_file [-b|t|p] [-v[2|4|8][n|x]]
where:
 seq_file - Path to the destination file.
 -b - Indicates a binary sequential format is used.
 -t - Indicates a line sequential format (records separated by new-line character).
 -p - Indicates an ASCII file to be used by the BTRV BUTIL -load command.
 -v - Indicates variable-length format (record data is preceded by record length) and is
optionally followed by a 2 or 4 or 8 that indicates the size of the record length field that
precedes the record data and by a n or x to indicate if the record length is stored in native (n)
or big-endian (x) format.
See Also:
 -load (page 137)
www.faircom.com
All Rights Reserved
155
-unloadtext
Exports data from a COBOL data file to a text file. If the COBOL file is encrypted, ctutil returns
error 33: Operation not allowed. File is encrypted.
Note: This command has been replaced by the -t option of the -unload (page 155) command.
www.faircom.com
All Rights Reserved
156
-upgrade
In V2 and later, a new switch is available for the ctutil command to upgrade data files:
ctutil -upgrade
This option upgrades the file to the current configured format. With this switch it is possible to
take an existing data file and upgrade it to the latest format.
Usage:
ctutil -upgrade
source_file [dest_file]
 source_file - Source file name without extension.
 dest_file - Destination file name without extension.
This capability gives the customer a tool to upgrade an existing file to match the current settings
in ctree.conf and/or the current c-treeRTG file format. This switch makes it possible to upgrade an
existing data file to the latest format. For example, it would be used if a revision changed the file's
physical layout (e.g., altering the header).
www.faircom.com
All Rights Reserved
157
-xfd2xdd
Transforms an XFD file version 4, 5, and 6 into SQL information that can be used by the -sqlinfo
(page 148) option.
Usage
ctutil -xfd2xdd
xfd_file
[-rule=rules_file]
where:
 xfd_file - Path to a XFD file
 rule=rules_file - Optional path to rules file
The ctutil -xfd2xdd utility (as well as the xddgen utility) mark the first index as the primary in the
XDD definition so that this key becomes the primary key for SQL.
Note: The SQL Information will be written to standard output. Redirect standard output to a new
file to obtain the XDD file.
ctcbtran
The ctutil utility can be renamed to ctcbtran. In this case, it functions as an ad-hoc utility to turn
on/off transaction processing. The parameter is the name of a file that contains a list of files to
modify (one file name per line).
Notice that the utility functions similar to ctuitl -tron except that the parameter is the name of a file
listing the files to modify instead of the name of the table to modify.
Usage
ctcbtran list_file T|P|F|W
 list_file - specify the name of a file that contains a list of files to be modified, one file name per
line. Specify the file names as you would when passing a file name to ctuitl -tron.
 T - Enable full transaction processing control (ctTRNLOG c-tree file mode). This mode is
recommended for most applications and it is required to take full advantage of c-treeRTG
advanced features.
 P - Enable logical transaction processing control without logging (ctPREIMG c-tree file
mode). This is the default mode and is indicated where both transaction atomicity and high
performance are required. By suppressing transaction logging it is possible to achieve high
data throughput at the expense of data recoverability. This mode is recommended in
environments protected from system crashes or cases in which data integrity/recoverability is
not an issue.
 F - Asynchronous writes. This mode should only be used on files which data integrity is not
critical as data recovery is not guaranteed in case of a system crash.
 W - Synchronous writes (ctWRITETHRU c-tree file mode). This mode is indicated where
transaction processing in not suitable yet data safety is still critical.
Example
ctcbtran myfiles
www.faircom.com
All Rights Reserved
158
The myfiles file would list the files to be modified with one file name on each line, for example:
datafile01
datafile02
datafile03
See also -tron (page 153).
www.faircom.com
All Rights Reserved
159
12.2
xddgen
xddgen is used to generate XDD files directly from COBOL source code. Because xddgen must
analyze the program to create the XDD, it needs a full COBOL program as input.
Usage
xddgen [options] file...
Options:
 --help Display this message
 --version, -V Display compiler version
 -std=<dialect> Compile using a config file (config/<dialect>.conf) for a specific dialect (see
xddgen Configuration File (page 164)):
acu ACUCOBOL-GT
acu-Ds ACUCOBOL-GT using the -Ds switch
cobol2002 COBOL 2002
cobol85 COBOL 85
ibm IBM Compatible
mvs MVS Compatible
bs2000 BS2000 Compatible
mf Micro Focus Compatible
default When not specified
• When -std is not specified, config/default.conf is used.
 -free Use free source format
 -fixed Use fixed source format (default)
 -o <directory> Place the output into <directory>
 -I <directory> Add <directory> to copy/include search path
 -conf=<file> User defined dialect configuration. See -std=
 --list-reserved Display reserved words
 --list-intrinsics Display intrinsic functions
 --list-mnemonics Display mnemonic names
 -save-temps(=<dir>) Save intermediate files (default current directory)
Some elements of COBOL FD statements require special consideration when generating the
XDD. In particular:
Redefines
Fields contained in a redefining item occupy the same positions as the fields being redefined.
The XDD generator needs to select just one of the field definitions; by default it takes the fields in
the item being redefined.
www.faircom.com
All Rights Reserved
160
Multiple record definition
The same rule applies to multiple record definitions which are redefinitions of the entire record
area, so again this leads to multiple definitions for the same data area. In this case the XDD
generator picks the first definition.
Group items
By default never included in an XDD as they result in multiple names for the same data items.
FILLER Data Items
In a COBOL FD, FILLER data items are placeholders however they take space on the record
area. FILLER items are not uniquely named, so when generating the XDD they get renamed to
have a unique name and by default are marked as “hidden fields”.
Occurs
An OCCURS clause requires special handling because there must be a unique name to each
database column. The XDD generator accomplishes this by expanding the OCCURS items and
appending sequential index numbers to the items named in the OCCURS.
Primary Key
The xddgen utility (as well as ctutil -xfd2xdd) mark the first index as the primary in the XDD
definition so that this key becomes the primary key for SQL.
See Also
 XDD Directives (page 161)
 xddgen Configuration File (page 164)
XDD Directives
Directives are comments that can be placed into an FD in your COBOL source code. You can
add directives to your COBOL source to override default mapping behaviors or map a field to a
different name. Directives apply to the next field and up to 4 directives per field can be specified.
For compatibility with existing ACUCOBOL-GT source code, xddgen accepts the following $xfd
and *>>XFD directives:
DATE, HIDDEN, NAME, USE GROUP, WHEN, ALPHA, BINARY, COMMENT
Syntax
*>>directive_name parameters
Note: For fixed syntax, the directive must start at column 8.
Supported Directives
XDD HIDDEN
Use the HIDDEN directive to hide the subsequent field in the SQL structure.
www.faircom.com
All Rights Reserved
161
Syntax
*>>XDD HIDDEN
XDD NAME
Use the NAME directive to assign a database field name to the subsequent field.
Syntax
*>>XDD NAME = field
XDD USE GROUP
Use the USE GROUP directive to enter a group item into the database as a single field, instead
of using the elements contained in the group. It implies that the resulting field is alphanumeric.
Syntax
*>>XDD USE GROUP
XDD DATE
Use the DATE directive to expose the subsequent field in SQL as a time/date/timestamp field in
SQL. The date_format is mandatory and represents the description of the desired date format for
the XDD file.
Syntax
*>>XDD DATE = date_format
where
 date_format - A description of the desired date format. The date format is composed of
characters from the following list:
M - Month (01–12)
Y - Year (two or four digits)
D - Day of month (01–31)
J - Julian day (00000000–99999999)
E - Day of year (001–366)
H - Hour (00–23)
N - Minute
S - Second
XDD WHEN
Use the WHEN directive when you want to include multiple record definitions or REDEFINES in
the XDD. The WHEN directive is used to force certain columns of data to be available that
wouldn't be available otherwise. Use the WHEN directive if you want a user to be able to access
all the data in the COBOL file in a way that is understandable.
WHEN declares that the field (or subordinate fields, if it is a group item) immediately following the
directive must appear as a column (or columns) in the indexed file database table when the
condition is satisfied.
Syntax
*>>XDD WHEN field operator value
or
www.faircom.com
All Rights Reserved
162
*>>XDD WHEN field operator value TABLENAME = tablename
where
 field - Specifies the name of a data item that corresponds to a field.
operator - Specifies the operator to use for comparison between the field value and the literal
value.
Supported operators:
= equal
!= not equal
> greater than
< less than
>= greater or equal than
<= less or equal than
 value - An alphanumeric literal specifying the value to compare with or OTHER which
requires the = (equal) operator and matches when no other condition match.
 tablename - The name of the table exposing the fields.
The WHEN directive supports complex expressions containing multiple AND and OR operations
and parentheses to group sub-expressions for proper order of evaluation.
The maximum length of the expression is 1024 characters (no need to split the line). For
example:
*>>XDD WHEN (fld1 = "abac" or fld1 = "default") and (fld2 < 15 or fld2 > 123) and fld4 != "12"
If you have need for an existing $XFD WHEN directive in place and would like a different WHEN
directive in effect (for example, complex directives were not supported with old ACUCOBOL-GT
versions) a *>>WHEN directive immediately following a $XFD WHEN directive overrides it. This is
a useful method to have an original $XFD WHEN in place for other file systems and *>>WHEN
directives for c-tree specific usage.
Multiple schemas can be defined with the same definition but different records and mapping to
different SQL tables by specifying multiple WHEN directives having different tablename settings
on the same field.
For example, your application may use a single table containing customers and suppliers with a
TYPE field indicating if an entry is for a customer or for a supplier. It may be desirable to map this
table into two SQL tables; one for supplier and one for customers. In such a case it is possible to
have two WHEN directives on the same level 01 field (in this example) with the proper condition
and two different table names.
Nested WHEN directives are not explicitly supported.
XDD WHENFULL
Use the WHENFULL directive in the FD or COBOL source when you want to include multiple
record definitions or REDEFINES that also redefine the indexed fields. This directive is very
similar to the WHEN directive.
The WHENFULL directive can only be used before an 01 level definition and the 01 level entry
must contain the whole record definition (including indexed fields). WHENFULL is applicable only
for 01 level definitions that redefine the entire record.
www.faircom.com
All Rights Reserved
163
It is possible to nest WHEN directives within a WHENFULL directive.
XDD FILLER
This directive forces the following field to be considered to be a FILLER.
Syntax
*>>XDD FILLER
Syntax for WITH DUPLICATES on RECORD KEY
In most COBOL compilers it is possible to specify WITH DUPLICATES on the RECORD KEY, but
xddgen did not allow this (it failed with a syntax error). The xddgen syntax has been expanded
to support duplicates on the record key in addition to the support for duplicates on alternate keys.
A record key that allows duplicates cannot be marked as primary key in SQL.
xddgen Configuration File
The -std=<dialect> parameter for xddgen determines which configuration file controls the
conversion. The conf directory contains one configuration file for each value of <dialect> (e.g., for
ACUCOBOL, specify -std=acu when running xddgen acu.conf is used). The file default.conf is
used if -std= is not specified.
You can make customized copies of these files and give them new names. Use those names
when running xddgen. For example, you could make a copy of acu.conf and call it myacu.conf.
Use xddgen -std=myacu to use this file.
Configuration Options
 comp-1-16bit-signed-binary - When set to yes, COMP-1 and COMP-2 are mapped as
per the ACUCOBOL definition.
When using xddgen to create an XDD file for an FD containing a COMP-1 field, the correct
mapping depends on the COBOL compiler being used. It should be mapped into a Float for
most compilers. However, the ACUCOBOL compiler defines COMP-1 as a 16-bit signed
integer, so it should be mapped to BinarySigned. To achieve this, use the following
configuration property:
comp-1-16bit-signed-binary: yes
 sign-trailing-separate - The ACUCOBOL -Ds compiler switch causes numbers to
have separate leading sign by default (when no COMP specification is in place). This option
defaults to no (0). Setting it to yes invokes TRAILING SEPARATE. The configuration file
named acu-Ds.conf enables this flag (use -std=acu-Ds).
 binary-size - Defines the allocated bytes according to PIC:
Value:
'2-4-8'
'1-2-4-8'
signed
-----1 - 4
5 - 9
10 - 18
1 - 2
3 - 4
5 - 9
unsigned
--------
bytes
----2
4
8
1
2
4
www.faircom.com
All Rights Reserved
164
'1--8'
10
1
3
5
7
10
12
15
17
-
18
2
4
6
9
11
14
16
18
1
3
5
8
10
13
15
17
-
2
4
7
9
12
14
16
18
8
1
2
3
4
5
6
7
8
 binary-byteorder - Determines the byte-order. Can be set to native (to use the
byte-order of the original) or big-endian (to force big-endian byte order).
 suppress-dash-in-field-names - When set to yes, dashes are eliminated from the file
name rather than being substituted. The default, no, causes dashes to be substituted with
underscores.
Configuration files directory
The xddgen configuration files can be loaded from the config directory under the xddgen
executable directory. This allows calling xddgen from any directory without worrying about
copying the config sub-directory.
A number of xddgen behaviors are controlled by configuration files. The default configuration file,
default.conf, can be modified using either the -std or the -conf command-line switches:
 When -std=AAA is used, the configuration file name is AAA.conf.
 When -conf is used, the configuration file name is the exact name passed in with no changes.
If no path or a relative path is specified, it will be based on the current working directory.
When -conf is not used, the file is loaded from a directory using the following criteria:
1. If the environment variable COB_CONFIG_DIR is specified, that is the only directory that will
be considered.
else
2. The search for the configuration file will include the config directory under the current working
directory (i.e. the directory where xddgen is launched).
3. If #2 fails, the search for the configuration file will include the config directory under the
xddgen installation path (i.e., the directory where xddgen is located).
The above criteria are also used to locate "included" configuration files (one configuration file can
include another and overwrite some of the values specified).
xddgen now allows names larger than 31 chars
The xddgen utility is now able to generate the XDD if a field name was larger than 31 characters
to allow more flexibility in generating the XDD. Two new configuration entries have been added to
accommodate this situation:
1. user-defined-names-len (defaults to 31) - Can be any number between 31 and 64. It
determines the number of significant chars in fields and table names.
2. check-redefinition (defaults to yes) - If yes, check for field names redefinitions that
would cause having multiple SQL fields with the same name and if so, error out.
www.faircom.com
All Rights Reserved
165
The behavior when names larger than user-defined-names-len is encountered has been
changed so that, instead of generating an error, it produces a warning and truncates the name to
the maximum allowed length.
Suppress dash or replace with underscore
A boolean xddgen configuration behavior allows suppressing the dash character ("-") when it is
present instead of substituting it with an underscore ("_"). The default is no, which preserves the
past behavior in which a dash is substituted with an underscore.
suppress-dash-in-field-names
 no (default) - Dashes are substituted with underscores.
 yes - Dashes are eliminated from the file name rather than being substituted.
Example:
You can create a new configuration file and set this feature as desired. When you run xddgen,
the -std= switch can be used to point to the new configuration file:
1. Copy the configuration file specified by the xddgen -std=<dialect> configuration switch. For
example, if -std=mf, make a copy of the configuration file mf.conf found in the conf directory.
2. Rename the configuration file copied in step 1.
3. Add (or change) for setting for suppress-dash-in-field-names: yes
4. Run xddgen -std=<new_name> replacing <new_name> with the new configuration file name
assigned in step 2.
More xddgen enhancements
Several enhancements have been made to the latest version of xddgen:
Generate an XDD for EXTERNAL files
Support was added xddgen to generate an XDD for files defined as EXTERNAL. By default,
xddgen does not generate XDD files for external files, but it is now possible to change the
xddgen configuration file follows to instruct xddgen to generate XDD files for EXTERNAL files:
# If yes, generates xdd file also for "external files"
# Value: 'yes', 'no'
consider-external-file: yes
Now when an external file is ignored, xddgen generates a warning message to inform about it.
Key based on a redefine
The xddgen utility used to return an error if a key was based on a redefine of a field or, in case of
split keys, if one of the specified fields was a redefine. Now the logic has been changed to allow
these conditions and produce a warning indicating the situation.
It is possible to change the behavior from the default of generating a warning to the old behavior
of getting an error (or even to allow it without any warning) by changing the xddgen configuration
entry:
www.faircom.com
All Rights Reserved
166
# behaviour when a key is based on a redefine of a field.
# Value: 'ok', 'error', 'warning'
key-on-redefines: warning
Rationalized xddgen behavior on error
If an error occurs while generating an XDD, the XDD will not be generated (although other XDDs
may be generated). The xddgen utility will always return a value different than 0 on the
occurrence of an error. This implies it is sufficient to check the return code to see if something
failed during xddgen execution.
www.faircom.com
All Rights Reserved
167
12.3
cttrnmod - Change Transaction Mode Utility
cttrnmod allows an advanced user to change the transaction status of a c-treeACE data file and
its associated index files. The utility can also be used to display the transaction status of a c-tree
data file and its associated indices.
It is expected only advanced database administrators will run this utility.
Usage
cttrnmod (set <tranmode>|get) (-d <database>|-f <filelist>)
[-u <userid>] [-p <password>] [-s <servername>] [-n <sect>]
Where
 set <tranmode> - Set the transaction mode to one of the following:
• T - Full Transaction Control
• P - Partial Transaction Control (No Recoverability)
• N - No Transaction Control (No Recoverability)
repl=on - Enable replication (requires full transaction control).
repl=off - Disable replication.
The following extended header attributes may also be set:
• {+,-}R - {Enable,Disable} Restorable deletes
• {+,-}C - {Enable,Disable} Transaction controlled deletes
• {+,-}A - {Enable,Disable} Auto transaction switching.
 get - Display the current transaction mode.
 -d or -f - Operate on all files in the database or all listed files:
• -d <database> - Operate on all files in the c-tree database <database>.
• -f <filename> - Operate on all files listed in the file <filelist>.
 -u <userid> - Specify c-tree user ID.
 -p <password> - Specify c-tree user password.
 -s <servername> - Specify c-treeACE Server name to connect to. Default: FAIRCOMS
 -n <sect> - Specify node sector size. Default: 64 (PAGE_SIZE=8192)
The files to change are specified by either the -d <database> option or the -f <filelist> option. The
-d <database> option specifies the name of a c-tree database -- when this option is specified, the
utility operates on all files referenced in that database (excluding SQL system data and index
files). The -f <filelist> option specifies the name of a text file containing names of c-tree data files,
one per line -- when this option is specified, the utility operates on all files specified in that text
file.
Note: Indices created with ctPREIMG or ctTRNLOG are physically structured differently than
indices that do not support transactions. Thus a non-tran index cannot be converted to
transaction control, and must be rebuilt after the conversion. If an index file is created ctPREIMG
or ctTRNLOG, it can be accessed in all transaction and non-transaction access modes.
www.faircom.com
All Rights Reserved
168
Important Performance Considerations
When turning transaction processing off for a file, it is possible to take an even larger
performance hit under specific c-treeACE Server configurations. Be sure to remove or comment
out the line COMPATIBILITY FORCE_WRITETHRU from your c-treeACE Server configuration file
ctsrvr.cfg. While this option provides only the safest of data integrity for your non-transaction
processing controlled files, it forces an enormous performance penalty for doing so. This keyword
has historically been included by default with most c-treeACE Server installations.
Example
The following example demonstrates turning off transaction control for all c-tree data files and
their associated index files in the rdsdb database:
# cttrnmod set N -d rdsdb
Setting transaction mode to NON_TRAN for files in database rdsdb...
Tranmode
-------NON-TRAN
NON-TRAN
NON-TRAN
NON-TRAN
NON-TRAN
NON-TRAN
NON-TRAN
NON-TRAN
NON-TRAN
NON-TRAN
Filemode
-------0x0000
0x0000
0x0000
0x0000
0x0000
0x0000
0x0000
0x0000
0x0000
0x0000
Filename
-------.\rdsdb.dbs\admin_deptbl.dat
.\rdsdb.dbs\admin_deptbl.idx
.\rdsdb.dbs\admin_dept_multi_ndx.idx
.\rdsdb.dbs\admin_dept_ndx.idx
.\rdsdb.dbs\admin_emptbl.dat
.\rdsdb.dbs\admin_emptbl.idx
.\rdsdb.dbs\admin_emp_no_ndx.idx
.\rdsdb.dbs\admin_emptbl1.dat
.\rdsdb.dbs\admin_emptbl1.idx
.\rdsdb.dbs\admin_emp_no_ndx1.idx
VERIFYING No Transaction Control...
VERIFY succeeded
3 Data Files Updated
0 Errors
The following example demonstrates reading the transaction status of the data and index files in
the rdsdb database:
# cttrnmod get -d rdsdb
Reading transaction mode for files in database rdsdb...
Tranmode
-------ctTRNLOG
ctTRNLOG
ctTRNLOG
ctTRNLOG
ctTRNLOG
ctTRNLOG
ctTRNLOG
ctTRNLOG
ctTRNLOG
ctTRNLOG
Filemode
-------0x0031
0x0031
0x0031
0x0031
0x0031
0x0031
0x0031
0x0031
0x0031
0x0031
Filename
-------.\rdsdb.dbs\admin_deptbl.dat
.\rdsdb.dbs\admin_deptbl.idx
.\rdsdb.dbs\admin_dept_multi_ndx.idx
.\rdsdb.dbs\admin_dept_ndx.idx
.\rdsdb.dbs\admin_emptbl.dat
.\rdsdb.dbs\admin_emptbl.idx
.\rdsdb.dbs\admin_emp_no_ndx.idx
.\rdsdb.dbs\admin_emptbl1.dat
.\rdsdb.dbs\admin_emptbl1.idx
.\rdsdb.dbs\admin_emp_no_ndx1.idx
www.faircom.com
All Rights Reserved
169
ctTRANMODE Control (c-treeACE V11 and c-treeRTG V2 and later)
When using the Transaction Control utility, cttrnmod, to disable transaction support on a file with
extended file mode ctTRANMODE, the utility could report that after successfully disabling
ctTRNLOG, the file still has ctTRNLOG set. This is expected for a file with the ctTRANMODE bit
set when using a TRANPROC c-tree application.
cttrnmod has been updated to disable ctTRANMODE and ctPIMGMODE bits when it sets a file
to no-transaction support. It was also modified to support explicitly enabling or disabling one of
these bits (depending on the file mode that is in effect at the time).
Replication
New replication actions have been added to the cttrnmod utility for flexible control of replication
attributes.
 cttrnmod now displays replication state for a data file
 cttrnmod can change a file's replication state with the repl option
Note: Replication requires that the data file has a unique index and that the data and index files
are using full (ctTRNLOG) transaction control.
Examples
1. Enable full transaction logging on files:
# cttrnmod set T -f files.txt -u ADMIN -p ADMIN -s FAIRCOMS
Setting transaction mode to ctTRNLOG for files listed in file
files.txt...
Replicate
---------
Tranmode
--------
Filemode
--------
Filename
--------
NO
ctTRNLOG
ctTRNLOG
0x0032
0x0032
ctreesql.dbs\admin_t.dat
ctreesql.dbs\admin_t.idx
ctTRNLOG
0x0032
ctreesql.dbs\admin_t_ti.idx
Note the "Replicate" column for current replication state information.
2. Enable replication on files:
# cttrnmod set repl=on -f files.txt -u ADMIN -p ADMIN -s FAIRCOMS
Enabling replication for files listed in file files.txt...
Replicate
---------
Tranmode
--------
Filemode
--------
Filename
--------
YES
ctTRNLOG
ctTRNLOG
0x0032
0x8032
ctreesql.dbs\admin_t.dat
ctreesql.dbs\admin_t.idx
ctTRNLOG
0x8032
ctreesql.dbs\admin_t_ti.idx
www.faircom.com
All Rights Reserved
170
Note: If cttrnmod is used to disable full transaction logging for a file, it also disables replication
for that file.
www.faircom.com
All Rights Reserved
171
12.4
ctfileid - Update File IDs
The Update File ID utility, ctfileid, provides a convenient and safe way to update the fileid
parameter of the file header. See the section Copying Server Controlled Files (page 172) in the
c-treeACE Programmer's Reference Guide (http://www.faircom.com/doc/ctreeplus/29354.htm) for
details for when this may be necessary. The file is opened exclusively, ensuring that the server
does not have it open. The syntax for this utility is shown below:
ctfileid
file [-ioq] [-n <size>] [-s <svn>] [-u <uid>] [-p <upw>]
 -i - Also update indices related to data file.
 -o - Force open of corrupted files (ctOPENCRPT).
 -q - Quiet (do not output to stdout).
 -s <server name> - c-treeACE Server name.
 -u <user ID> - User name.
 -p <user password> - User password.
Note: ctfileid.c is located in ctree\samples\special\utils and replaces the previous informal and
undocumented utilities, updateid.c and newid.c.
Standalone Usage
An additional option is available to set the node size in standalone mode:
 -n <size> - Set node size (stand-alone only).
Copying Server-Controlled Files
When a file open is attempted, c-treeACE 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. For example, consider the situation where
independent clients operate from different drive or path mappings.
Fri Aug 20 07:56:17 2014
- User# 00021
Matching file IDs: ./data/\ctreeSQL.dbs\custmast.dat <>
/data/\ctreeSQL.dbs\custmast.dat
Fri Aug 20 07:56:17 2014
- User# 00021
Reassigning file ID ...
Fri Aug 20 07:56:17 2014
- User# 00021
/data/\ctreeSQL.dbs\custmast.dat
If two different files have the same file ID, (a 12-byte value comprised of a Server ID, a time
stamp, and a transaction log sequence number), problems will arise as the second file would not
actually be opened. The ID is constructed such that no two files can have the same ID unless
someone copies one file on top of another. See the warning 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-treeACE Server configuration file:
www.faircom.com
All Rights Reserved
172
MONITOR_MASK
MATCH_FILE_ID
Warning: Do NOT copy, move, or delete files controlled by the server while the server is
operational!
As discussed above, copying a file to a new name is typically the only way the file ID’s can
match. The Update File ID utility (page 172), ctfileid, is available to update the file ID number
should this become absolutely necessary. This utility should only to be run on a file when the
server is stopped.
12.5
ctclntrn and cthghtrn utilities for managing transaction
mark numbers
The following utilities are provided in c-treeRTG:
 ctclntrn - “Cleans” the high-water transactions marks within a c-treeACE index.
 cthghtrn - Displays the high-water transaction marks within an index file. This utility would
typically be used when the c-treeACE Server transaction mark number gets too large
These utilities appear in the tools\cmdline folder.
For complete descriptions of these utilities, see the Command-Line Tools
(http://docs.faircom.com/doc/cmdline/#cover.htm) book on the FairCom website.
12.6
Additional Command-Line Tools
More command-line tools are available in c-treeRTG V2. By popular demand, the following tools
have been added in this release:
 ctidmp.exe - Lists the contents of a dynamic dump file or a specific extent of a dump broken
into multiple files. (Compile and link with c-treeACE Standalone Single-user TRANPROC
library.)
 ctpass.exe - Allows users to change their password.
 ctsysm.exe - Monitors error, warning, and informational messages logged to the server
status log, CTSTATUS.FCS. Allows monitoring by an automated external process, such as
the Tivoli monitoring system from IBM.
 cttrap.exe - Plays back a TRAP_COMM log file.
 ctclntrn - “Cleans” the high-water transactions marks within a c-treeACE index.
 cthghtrn - Displays the high-water transaction marks within an index file. This utility would
typically be used when the c-treeACE Server transaction mark number gets too large.
For detailed information, see the Command-Line Tools
(http://docs.faircom.com/doc/cmdline/#cover.htm) guide on the FairCom website.
www.faircom.com
All Rights Reserved
173
Appendix A.Details about the File System and SQL
A.1.
c-treeRTG File System Details
The c-treeRTG file system links directly into your application's runtime, giving existing
applications immediate access to c-treeACE database technology without the need of
recompiling. c-treeRTG replaces the original file system. It intercepts calls for storing and
retrieving records and takes advantage, when requested, of indexes over the record buffers.
An important consideration in a client/server architecture is the time spent in client/server
communication (in contrast to the direct disk access of other file-systems). With this in mind,
FairCom's engineers customized a special edition of the c-treeACE database engine, c-treeRTG
Server, incorporating the functionality required of the file system. The thin client sends requests
directly to the server, reducing network traffic and time spent in communication.
Transactions are another advantage of running c-treeRTG. It is suggested that customers with
production databases keep transaction logs on another disk sub-system. If a disk failure occurs in
the primary data subsystem, the logs remain available. Once the main subsystem is repaired (or
a backup server is found), the logs can be rolled forward into a restored copy of the database.
In addition, c-treeRTG transparently allows read/write access to data from your application
through SQL and other FairCom interfaces such as ODBC, JDBC, and ADO.NET drivers.
A.2.
The SQL Challenge
c-treeRTG provides simultaneous access to data using SQL in addition to COBOL or Btrieve
direct record file I/O routines. The nature of data and record definitions (which may have
redefines) used in these languages does not fit into a traditional relational (SQL-based) model of
table and record definitions, which poses a unique challenge.
Some products require a non-SQL solution for the original application and relational database for
SQL. You must batch copy records into the relational database, resulting in out-of-sync data.
The FairCom approach is different. Our engineering team implemented the required
ACUCOBOL-GT and ExtFH interfaces through our ISAM technology. These interfaces parallel
the COBOL approach to indexed files without the complications of SQL table remapping. From
the application's point of view, c-treeRTG provides a more advanced “native” file system with no
limitations for the programmer. In addition, the interface between the c-treeACE SQL engine and
the native data allows simultaneous read/write access through standard SQL.
The advantage is that the original application has direct access to the data with no added
complexity. While some data conversion is required for SQL access, the FairCom SQL approach
is far simpler and more efficient than the remapping required by other implementations.
Learn more at c-treeRTG (http://www.faircom.com/products/c-treertg) on the FairCom website.
www.faircom.com
All Rights Reserved
174
Appendix B.Configuration File Elements
The following sections describe the elements of a c-treeRTG configuration file. The configuration
file is an XML file that contains two types of elements:
 Structure Elements - These elements define the structure of the system, such as the server
to connect to and any files that need special treatment. They include the <config> root
element (page 176), the <instance> (page 177) and<redirinstance> (page 179) elements,
and the <file> element (page 181).
 Settings Elements - Each of the Structure Elements can have one or more Setting
Elements, which specify the settings to be applied to the Structure Element, as explained in
Settings Elements (page 183).
See Also
 c-treeRTG Configuration (page 30) - An explanation of configuring your system.
 c-treeRTG Configuration File (page 31) - An overview of the Structure Elements and Settings
Elements defined in this section.
 The c-treeRTG Configuration Tool (page 34) - An example of a configuration file created with
the Configuration Tool, which is an excellent starting point for understanding how to use the
Structure Elements and Settings Elements. This tool also tests ctree.conf for correctness, so
it should tell you if there is any problem with a ctree.conf you have edited by hand.
B.1.
Structure Elements
The Structure Elements define the architecture of the system. They consist of the following
elements:
 the <config> root element (page 176)
 the <instance> (page 177) and <redirinstance> (page 179) element
 the <file> element (page 181)
The settings applied to these elements to configure their behaviors are called Settings Elements
(page 183).
See Also
 c-treeRTG Configuration (page 30)
www.faircom.com
All Rights Reserved
175
<config>
<config> is the root element of the XML configuration file. It does not have any attributes and it's
used only as a container of all other configuration elements.
www.faircom.com
All Rights Reserved
176
<instance>
The instance element specifies instance-wide configurations for the client/server driver. Each
instance represents a connection to the c-treeRTG server.
If ctree.conf has no instance defined, it will default to going to default server:
FAIRCOMS@localhost
Attributes
Attribute
Description
Default value
server
Specifies the server name and the host name of the
c-treeRTG to connect to. The format can be one of the
following syntaxes:
servername
servername@hostname
If the host name or the IP address is omitted, host
name defaults to localhost.
FAIRCOMS
user
Specifies the c-treeRTG user name.
""
password
Specifies the c-treeRTG user password.
""
connect
Indicates whether to connect to c-treeRTG at runtime
initialization or wait for the first OPEN operation.
It accepts the following values:
no
• "yes" : Indicates to connect at runtime initialization.
• "no" : Indicates to connect during the first OPEN
operation. This is the default value.
versioncheck
Indicates whether to check that the c-treeRTG driver
version matches the c-treeRTG server version. This
option is turned off by default.
It accepts the following values:
no
• "yes" : Turn on version matching check. Versions
must match exactly otherwise an error is returned at
runtime initialization.
• "no" : Turn off version matching check. This is the
default value.
name
Specifies the name of the instance to identify COBOL
connections in CTADMN and other tools. Two
substitution specifiers can be used to set the <instance
name=""> attribute:
""
• %p Expands to process ID of the instance affected
by configuration
• %t Expands to thread ID of the instance affected by
configuration
Example
<instance server="[email protected]" user="admin" password="ADMIN" connect="yes"
versioncheck="no">
...
</instance>
www.faircom.com
All Rights Reserved
177
Dynamically Setting Attributes
Environment Variables
The <instance> attributes server, user, and password can be set dynamically through
environment variables. The syntax is the same as described in Substitution Specifiers (page 231)
topic:
%(ENV) expands to the value of the environment variable ENV.
Any environment variable can be used. Simply specify its name in place of ENV in %(ENV).
For example:
<instance server="%(SERVNAME)@%(HOSTNAME)" user="%(USERNAME)" password="%(PASSWORD)"/>
Only server, user, and password can be set using environment variables.
Password
If a password is not specified in the configuration file through the <instance password> attribute, it
is possible to specify the password in the URL that it is used to open the file.
For example, if the ctree.conf contains the following <instance> definition:
<instance server="servname@hostname" user="username"/>
any connection would fail if username password has been set in c-tree Server because the
<instance> does not have a password attribute. But opening the file with the following URL would
specify the password and therefore be able to connect:
ctree://username:password@hostname:servname/dir/filename
Warning: It is never advisable to send passwords "in the clear" (where they are visible), such as
in a URL. This feature is provided only for environments where security is not an issue, such as a
test environment.
www.faircom.com
All Rights Reserved
178
<redirinstance>
The <redirinstance> element defines an alternative instance. Each instance represents a
connection to the c-treeRTG server. This element is used when you need to specify
instance-wide configuration options for files that should be handled by an external file system
instead of the c-treeRTG file system. It accepts two attributes: lib and func, which specify the
library and function to be used as an external file system.
This element is used if you have an older COBOL compiler that supports ExtFH for only a single
external file system, and you need to use multiple file systems. For example, if you are already
using an ExtFH for certain files, you can use the <redirinstance> element to redirect those files to
that file system.
The <redirinstance> element supports BTRV as well as ExtFH. When using BTRV, the
<redirinstance> does not need to specify the func= attribute; it only needs the lib= attribute.
Note: If you are using a compiler that natively supports multiple external files systems (e.g., Micro
Focus 4 and later), use the functionality provided by the compiler to redirect.
Attributes
Attribute
Description
Default value
lib
Specify the file name of the library (e.g., DLL) to be
called. Use the complete path with no extension.
""
func
Specify the name of the function to be called.
""
Example 1 - COBOL
Setting <redirinstance> to use a function called mFFH in the cobmffh.so.2 library under
Unix/Linux:
<redirinstance lib="cobmffh.so.2" func="mFFH" >
...
</redirinstance>
Example 2 - BTRV
Setting <redirinstance> for the 32-bit BTRV DLL under Windows:
<redirinstance lib="WBTRV32.DLL">
...
</redirinstance>
Example 3 - BTRV
Setting <redirinstance> for the 64-bit BTRV DLL under Windows:
<redirinstance lib="w64btrv.dll">
...
</redirinstance>
Example 4 - BTRV
Setting <redirinstance> to use the libpsqlmif.so.8 library under Unix/Linux:
<redirinstance lib="libpsqlmif.so.8">
www.faircom.com
All Rights Reserved
179
...
</redirinstance>
Example 5 - BTRV
Setting <redirinstance> to use a function called MFFH in MFFH.DLL under Windows:
<redirinstance lib="MFFH.DLL" func="MFFH">
...
</redirinstance>
Notes:
For additional information, see Configuration Note for Micro Focus on 64-bit AIX (page 15) and
Dynamic Redirection (page 14).
www.faircom.com
All Rights Reserved
180
<file>
The file element specifies file-wide configurations. It is used to delimit options to a specific file
identified by the name attribute or to all the files contained in a directory identified by the dir
attribute.
The name and dir setting may contain the * wildcard to match multiple files with a single <file>
section. The file matching rules that apply when the wildcard * is used are described in Wildcard
File Matching Rules (page 182) and File Matching Precedence (page 183).
Attributes
Attribute
Description
Default Value
name
Specifies the string to match the file name portion of the
file path passed by the COBOL application.
N/A
dir
Specifies the string to match the directory portion of the
file path passed by the COBOL application. If attribute
name is also specified, the options applies to the files
that match both the directory and the name.
N/A
casesensitive
Specifies if the file name and/or file dir attributes should
be matched against the file path considering case
sensitivity.
yes (file and
directory
names are
case-sensitive)
priority
Specify the priority of this entry. Accepted values range
from -32767 to +32767.
0*
type
Specify the file organization. Valid values are:
*
•
•
•
•
•
I - Indexed file
R - Relative file.
L - Line sequential file
S - Record sequential file
* - Any file type (this is the default)
* For the "matching all file rules" (a rule matching all files in all directories) the default priority is
32767.
Example
<file name="CUSTMAST" dir=".">
...
</file>
To turn off case sensitivity (the example below would match CUSTMAST, custmast, CustMast,
etc.):
<file name="CUSTMAST" dir="." casesensitive="no">
</file>
See Also
 Wildcard File Matching Rules (page 182)
 File Matching Precedence (page 183)
www.faircom.com
All Rights Reserved
181
Wildcard File Matching Rules
c-treeRTG allows wildcard file matching. The only wildcard character is: *
The wildcard character can be placed at the beginning of a string, at the end of a string, or both. It
is basically a way to say:
 string* - Match names that begin with the given string.
 *string - Match names that end with the given string.
 *string* - Match names that contain the given string.
The file matching rules are not the same as those for Windows. For example, *.* matches any
file name containing a "." but it does not match names without a dot (e.g., it matches
"customer.dat" but not "customers").
Wildcard matching does not distinguish between file names and extensions. For example, cust*
matches customers.dat because the wildcard character can match multiple characters in the
file name as well as the extension.
Wildcard
Description
Example
Matches
Does NOT match
string*
The file or
directory begins
with the specified
string and can
end with anything.
cust*
(names that
begin with
"cust")
cust
customer
customers
customers.dat
cust.dat
newcustomer
(does not begin
with "cust")
*string
The file or
directory ends
with the specified
string and can
begin with
anything.
*customer
(names that end
with
"customer"
with no
extension)
customer
newcustomer
customer.dat
(the entire file
name, including
extension, must
end with
"customer")
*string*
The file or
directory contains
the specified
string and can
begin and end
with anything.
*cust*
(Names that
contain "cust")
customer
newcustomer.d
at
*.*
(Names that
contain a dot:
".")
customer.dat
customer
(name does not
contain a dot: ".")
Summary of Wildcard Rules
If the name/dir setting does not contain a *, the <file> options apply to the files that match exactly
the name/dir setting.
If the name/dir setting begins with a *, the <file> options apply to the files for which name/dir ends
with the string on the right of the *. For example: <file name="*mast"> matches file name
"custmast" but does not match file name "master".
If the name/dir setting ends with a *, the <file> options apply to the files for which name/dir begins
with the string on the left of the *. For example: <file name="mast*"> matches file name
"master" but does not match file name "custmast".
www.faircom.com
All Rights Reserved
182
If the name/dir setting begins with a * and ends with a *, the <file> options apply to the files
which name/dir contains the string enclosed between the * and *. For example: <file
name="*mast*"> matches file name "master" and file name "custmast".
If the name/dir setting contains only a *, the <file> options apply to all files.
File Matching Precedence
When multiple <file> tags are specified in ctree.conf, a file name may match more than one
tag. The following file precedence rules determine which one is actually applied:
In case a file matches multiple
<file> rules:
In case of matching priorities:
A specific type matching rule (i.e., I, R, L, or S) takes
precedence over the * (unspecified) type.
In case of multiple rules with the
same type:
An exact match has precedence over any wildcard match. For
example, file name "custmast" matches
<file name="custmast"> and does not match
<file name="cust*">.
In case of multiple wildcard
matches:
The rule with the most matching characters takes precedence:
For example, file name "custmast" matches
<file name="cust*"> and does not match
<file name="*ast">.
In case both name and dir are
specified:
In case the sum of matching
characters is equal:
In case the lengths of the settings
are equal
B.2.
A <file> rule with higher priority takes precedence over one
with lower priority.
The sum of the matching characters of both name and dir
setting is considered.
The rule with the longest matching characters takes
precedence: For example, file name "custmast" matches
<file name="cust*" dir="data"> and does not match
<file name="*mast" dir= ".">.
Alphabetical order is used: For example, file name "custmast"
matches <file name="cust*" dir="."> and does not
match <file name="*mast" dir= ".">.
Settings Elements
The Settings Elements apply the settings that you use to configure a Structure Element (the
<config> root element (page 176), the <instance> (page 177) and<redirinstance> (page 179)
elements, and the <file> element (page 181)). These elements configure c-treeRTG behavior.
See Also
 c-treeRTG Configuration (page 30)
www.faircom.com
All Rights Reserved
183
<automkdir>
The automkdir option indicates whether to automatically create missing directories when creating
new files. If this option is set to yes, any missing directory of the file path is automatically created.
If this option is set to no, an error is returned if the file path does not exist. This option is disabled
by default.
Accepted Values
Value
Effect
Synonyms
yes
Missing directories are automatically created.
y, true, on, 1
no
An error is returned if path does not exist. This is the
default value.
n, false, off, 0
Example
<automkdir>yes</automkdir>
www.faircom.com
All Rights Reserved
184
<batchaddition>
The batchaddition option enables batch record writes to improve performance of consecutive
record additions. This is achieved by caching the records being added in the client side before
they are sent in one batch operation to the server to be written to disk. The records are sent to
the server after a given number of records (specified by the records attribute) have been added or
when the file is closed. Since the records are actually written when they are sent to the server, a
duplicate key error is returned by the operation that triggered the batch write operation. For this
reason, batchaddition is recommended only for specific operations such as data import where
duplicate errors are not expected. It is important that COBOL applications performing
batchaddition check the status of CLOSE operations to detect possible errors writing records.
Writing records in batches improves performance of large record additions in environments where
client and server reside on different systems connected with a network. In such environments any
request from the client to the server is sent over the network which is generally a time-expensive
operation.
The batchaddition option is available only for files opened with OUTPUT or EXTEND mode.
The number of records to cache is defined by the records attribute.
The batchaddition option is disabled by default.
Note: Adding records using <batchaddition> within explicit transactions started by the user is not
supported. If a file is OPEN WITH ROLLBACK and the file is configured for <batchaddition>, any
WRITE operation that adds a record within an active transaction will fail until the transaction ends
with a Commit or Rollback. To add records to a file with OPEN WITH ROLLBACK and
<batchaddition> enabled, perform WRITE operations without starting a transaction.
Accepted Values
Value
Effect
Synonyms
yes
Enable the record batch addition.
y, true, on, 1
no
Disable record batch addition. This is the default
value.
n, false, off, 0
Attribute
Description
Synonyms
records
Indicates the number of records to cache. This value
is set to 100 by default.
recs
Attributes
Examples
<batchaddition records="50">yes</batchaddition>
www.faircom.com
All Rights Reserved
185
<bulkaddition>
The bulkaddition option enables deferred key writes to improve performance of consecutive
record additions. This is achieved by writing only the data record and postponing the key addition
until the file is closed. When the file is closed, all pending keys are written in one single operation
by an index rebuild routine. This technique of adding records has two benefits:
1. The index rebuild operation is faster than the sum of each key addition operation.
2. The index rebuild operation creates an index that is efficiently organized resulting in faster
key searches.
The bulkaddition option is available only for files opened with OUTPUT or EXTEND mode. The
bulkaddition option is disabled by default.
Accepted Values
Value
Effect
Synonyms
yes
Enable the bulkaddition technique.
y, true, on, 1
no
Disable the bulkaddition technique. This is the default
value.
n, false, off, 0
Examples
<bulkaddition>yes</bulkaddition>
www.faircom.com
All Rights Reserved
186
<ctfixed>
The ctfixed option indicates whether to create fixed record-length files with c-tree file mode
ctFIXED. If this option is set to yes, files with fixed record length are created with c-tree file mode
ctFIXED. If this option is set to no, all files are created with c-tree file mode ctVLENGTH. This
option is disabled by default.
Setting ctfixed to yes imposes a minimum record length of 9 bytes for huge files or 5 bytes for
non-huge files (based on the setting of the <hugefile> configuration option).
Accepted Values
Value
Effect
Synonyms
yes
Fixed record length files are created with ctFIXED file
mode.
y, true, on, 1
no
All files are created with ctVLENGTH file mode. This is
the default value.
n, false, off, 0
Example
<ctfixed>yes</ctfixed>
www.faircom.com
All Rights Reserved
187
<datacompress>
The datacompress option indicates whether to create files with data compression enabled. When
data compression is enabled, data records are compressed using the compression algorithm
specified by the type attribute. Data compression reduces disk space utilization but it may also
impact performance. This feature is turned off by default.
Note: If your configuration file does not include a datacompress element, the application can turn
on compression programmatically for the files that need them. If you include this attribute in the
configuration file, the setting will override programmatic requests from the application.
Accepted Values
Value
Effect
Synonyms
yes
Files are created with data compression enabled.
y, true, on, 1
no
Files are created without data compression. This is the
default value.
n, false, off, 0
Attribute
Description
Synonyms
type
Selects the type of compression.
Values:
"rle" : Use a simple RLE compression algorithm.
"zlib" : Use the zlib compression algorithm (you will
need to download the zlib library and place it in the
local directory with the c-tree Server binary).
The default value is "rle".
strategy
Selects the compression strategy.
Depending on the compression type the possible
values for strategy are:
Valid values for type "rle":
"0" : Use the default simple RLE compression strategy.
Valid values for type "zlib":
"0" : Use the default zlib compression strategy.
"1" : Use the zlib filtered compression strategy.
"2" : Use zlib Huffman only compression strategy.
"3" : Use zlib RLE compression strategy. This is the
default value.
"4" : Use zlib fixed compression strategy.
The default value is "0".
level
Selects the compression level.
Valid values are 0 and the range between 1 and 9:
"0" : Use the compression algorithm default level.
"1" : Provides best speed but uses more disk space
"9" : Provides best compression at the expense of
performance.
The default value is "0".
Attributes
www.faircom.com
All Rights Reserved
188
Please refer to the zlib documentation available at http://zlib.net/manual.html
(http://zlib.net/manual.html) for more information about zlib compression.
Note: The zlib library is not included with c-treeRTG. You will need to download the zlib library
and place it in the local directory with the c-tree Server binary). If the c-treeRTG Server does not
find ZLIB1.DLL in the path when it is started, an error 946 is returned when attempting to create
files with zlib data compression.
Examples
<datacompress type="rle" level="5">yes</datacompress>
<datacompress type="zlib" strategy="3" level="9">yes</datacompress>
<datacompress level="1">yes</datacompress>
www.faircom.com
All Rights Reserved
189
<datafilesuffix>
The datafilesuffix option defines the string to append to data file names. It can be used to
define the default data file extension. The file extension is considered by c-treeRTG to be part of
file name. If you want to override the "suffix", use the datafilesuffix configuration option.
If not specified the default data file extension is .dat.
Any string is accepted. Make sure your operating system's file system accepts the value you
specify.
Please remember to specify the "." (dot) if you want to use this as part of your file extension.
If you want your files to be created with no file extension, you can leave the datafilesuffix
empty or set it to a SPACE character as follows:
<datafilesuffix> </datafilesuffix>
or
<datafilesuffix></datafilesuffix>
Example
<datafilesuffix>.cdt</datafilesuffix>
www.faircom.com
All Rights Reserved
190
<detectlock>
This configuration option simulates the behavior of the Micro Focus DETECT-LOCK compiler
directive:
 DETECT-LOCK - If a READ statement reads a record locked by another program, it reads
the record successfully and returns an error.
 NO DETECT-LOCK - If a READ statement reads a record locked by another program, it
reads the record successfully and returns no error.
The <detectlock> option defaults to "no" which means that no error is returned when trying to
retrieve a record locked by another user if the LOCK MODE is MANUAL and the READ operation
does not have an explicit WITH LOCK option.
Example
<detectlock>yes</detectlock>
www.faircom.com
All Rights Reserved
191
<encrypt>
The encrypt option indicates whether to create files with FairCom's Data Camouflage or
encryption enabled or disabled. When enabled, files are masked using the Data Camouflage
technique or with the type of advanced encryption specified.
Note: If your configuration file does not include an <encrypt> element, the application can turn
on Data Camouflage programmatically for the files that need them. If you include this attribute in
the configuration file, the setting will override programmatic requests from the application.
Accepted Values
Value
Effect
Synonyms
yes
Create file with support for Data Camouflage or
encryption enabled.
y, true, on, 1
no
Create file with support for Data Camouflage or
encryption disabled. This is the default value.
n, false, off, 0
Attribute
Description
Synonyms
type
Use <encrypt type=""> to specify the type of encryption.
Values:
"camo" (default) : This option provides simple data
masking to hide data from casual observers. For
stronger encryption, use one of the other options.
"des8", "des16", "des24"
"twofish16", "twofish24", "twofish32"
"blowfish8", "blowfish9", etc. up to "blowfish56"
"aes16", "aes24", "aes32"
Attributes
Example
To encrypt using the default Data Camouflage masking:
<encrypt>yes</encrypt>
To encrypt using des8 encryption:
<encrypt type="des8">yes</encrypt>
See Also
 Security and Encryption: The Keys to Client/Server Security
(http://www.faircom.com/ace/ace_AES_encryption_t.php)
 Data Camouflage in the c-tree Plus Programmer's Reference Guide
(http://docs.faircom.com/doc/ctreeplus/#29877.htm)
 Encryption in the c-tree Plus Programmer's Reference Guide
(http://www.faircom.com/doc/ctreeplus/#29876.htm)
www.faircom.com
All Rights Reserved
192
<filecopy>
The <filecopy> configuration setting forces the use of the server-side file copy capability to
carry on copy operations. The <filecopy> option is not enabled by default so a user must
explicitly enable it in the configuration file in order to use it. When <filecopy> is enabled and
conditions do not allow it to be used, the copy operation fails rather than falling back other copy
methods.
The <filecopy> option forces a physical copy of the data and index files. The other copy
mechanisms available extract the structure information for the source file, create a new file
accordingly with the current ctree.conf settings, and then copy records from the source to the
destination (the outcome of this process can be a file which is not identical to the source file, for
example it might be compressed when the source was not).
In addition a new ctutil option has been added:
ctutil -filecopy source_file dest_file [-overwrite].
The command is not dependent on the configuration file, thus a ctutil -filecopy command will
always perform a physical file copy independently from the configuration settings.
The ctutil -filecopy does not overwrite existing files unless the -overwrite option is specified.
See also:
 ctutil -filecopy (page 132)
<filepool>
Enables and disables support for file pooling.
Description
In COBOL applications it is common practice to close and re-open files when entering
procedures. This can cause unnecessary overhead and performance issues in c-treeRTG.
The new Filepool feature introduces support for file pooling to keep files open when the COBOL
application requests to close it. This allows the file handle to be returned immediately when the
COBOL application request to re-open it.
The <filepool> global configuration keyword enables and disables support for file pooling and
optionally sets the size of the file pool with attribute <filepool size> where size is the
maximum number of files to keep in the pool.
A new configuration keyword <inpool> defines if a file can be included in the file pool.
For example:
<config>
<filepool size="40">yes</filepool>
<instance server="FAIRCOMS">
<file>
<inpool/>
</file>
</instance>
</config>
www.faircom.com
All Rights Reserved
193
www.faircom.com
All Rights Reserved
194
<hugefile>
This configuration keyword allows the huge file mode to be turned off so that non-huge files are
created. The default is to use c-treeRTG support for huge files, which accommodate up to 16
exabytes of data when segmented files are used. Non-huge files accommodate up to 2 or 4
gigabytes of data depending on the operating system.
Accepted Values
Value
Effect
Synonyms
yes
Create huge file (c-tree files larger than four gigabytes).
This is the default value.
y, true, on, 1
no
Create non-huge file.
n, false, off, 0
Example
<hugefile>yes</hugefile>
www.faircom.com
All Rights Reserved
195
<ignorelock>
The ignorelock option specifies whether READ operations should ignore locks. This option is
turned off by default.
Accepted Values
Value
Effect
Synonyms
yes
Turns off record lock detection.
y, true, on, 1
no
Turns on record lock detection. This is the default value.
n, false, off, 0
Example
<ignorelock>yes</ignorelock>
www.faircom.com
All Rights Reserved
196
<indexfilesuffix>
The indexfilesuffix option defines the string to append to index file names. It can be used to define
the default index file extension.
If not specified the default data file extension is .idx.
Any string is accepted. Make sure that your operating system file system accepts the value you
specified.
Please remember to specify the "." (dot) if you want to use this as part of your file extension.
If you want your files to be created with no file extension, you can leave the indexfilesuffix empty
or set it to a SPACE character as follows:
<indexfilesuffix> </indexfilesuffix>
or
<indexfilesuffix></indexfilesuffix>
Example
<indexfilesuffix>.cix</indexfilesuffix>
www.faircom.com
All Rights Reserved
197
<keycheck>
The keycheck option specifies whether to check that all the keys belonging to an indexed file are
defined in the COBOL program. If this option is enabled, keys must match key definitions
otherwise an error is returned. If this option is disabled, files containing more keys than described
in a COBOL program are allowed. Files that contain fewer keys than key definitions are never
allowed regardless of the keycheck setting. Disabled by default.
Accepted Values
Value
Effect
Synonyms
yes
All key definitions must match otherwise an error is
returned during OPEN operations.
y, true, on, 1
no
Open the file even if it contains more indices than the
key definitions. (default)
n, false, off, 0
Example
<keycheck>no</keycheck>
www.faircom.com
All Rights Reserved
198
<keycompress>
The keycompress option indicates whether to create files with key compression enabled. This
feature is turned off by default. It may impact performance but reduces disk space usage.
Accepted Values
Value
Effect
Synonyms
yes
Turns on key compression combining both leading
character and padding compression. This provides
the maximum key compression.
y, true, on, 1
no
Turns off key compression.
n, false, off, 0
Additionally the keycompress option may accept the following sub-options to specify which
compression type to use:
<leading> (page 200) keycompress option
Indicates to compress the leading characters of key values.
<padding> (page 201) keycompress option
Indicates to compress the padding characters of key values.
Examples
The following example turns on default key compression that implicitly uses leading and padding
compression:
<keycompress>yes</keycompress>
The following example turns on leading and padding key compression explicitly:
<keycompress>
<leading>yes</leading>
<padding>yes</padding>
<keycompress>
The following example turns on only padding key compression:
<keycompress>
</keycompress>
The following example turns off key compression:
<keycompress>no<keycompress>
www.faircom.com
All Rights Reserved
199
<leading>
The keycompress leading option indicates to compress the leading characters of key values. It is
indicated when there is significant leading character duplication among the key values.
Accepted Values
Value
Effect
Synonyms
yes
Turns on leading key compression.
y, true, on, 1
no
Turns off leading key compression.
n, false, off, 0
Examples
The following example turns on only leading key compression:
<keycompress>
<leading>yes<leading>
</keycompress>
www.faircom.com
All Rights Reserved
200
<padding>
The keycompress padding option indicates to compress the padding characters of key values. It
is indicated when key lengths vary in size and are padded with spaces.
Accepted Values
Value
Effect
Synonyms
yes
Turns on padding key compression.
y, true, on, 1
no
Turns off padding key compression.
n, false, off, 0
Examples
The following example turns on only padding key compression:
<keycompress>
</keycompress>
www.faircom.com
All Rights Reserved
201
<log>
The log option indicates whether to log events such as errors that occur in c-treeRTG. This
feature might be helpful for diagnostics purposes.
Attributes
Value
Effect
file
Specifies the log file name. If omitted the log
messages are redirected to the standard error stream
(stderr).
Synonyms
Accepted Values
Value
Effect
Synonyms
yes
Turns on logging. This option has the same effect as
turning on the <error>, <warning>, and <info>
sub-options.
y, true, on, 1
no
Turns off logging. This is the default value.
n, false, off, 0
Additionally the log option may accept the following sub-options to specify which event to log:
<debug> (page 204) log option
The debug option indicates to log debug information.
<error> (page 206) log option
The error option indicates to log errors.
<info> (page 207) log option
The info option indicates to log generic information.
<profile> (page 208) log option
The info option indicates to log performance profiling information.
<warning> (page 209) log option
The info option indicates to insert a warning into the log file.
Examples
The following example turns on implicit logging of errors and generic information to standard error
stream:
<log>yes</log>
The following example turns on explicit logging of errors and generic information to file mylog.txt:
<log file="mylog.txt">
<error>yes</error>
<info>yes</info>
</log>
The following example turns on only error logging:
www.faircom.com
All Rights Reserved
202
<log>
<error>yes</error>
</log>
Substitution Specifiers
Substitution specifiers can be used in the <log file> configuration attribute. The <log file>
attribute can contain substitution specifiers to build the log file name using (for example) an
environmental variable.
Example:
The following setting creates a different log file for each Windows user:
<log file="%(USERNAME).log">yes</log>
www.faircom.com
All Rights Reserved
203
<debug>
The debug log option instructs the c-treeRTG to insert debug information in the log file.
Accepted Values
Value
Effect
Synonyms
yes
This value turns on the debug logging.
y, true, on, 1
no
This value turns on the debug logging.
n, false, off, 0
The debug log option also accepts the following Boolean (yes or no) sub-options to include or
exclude certain type of debug information from the log file.
Children elements
Name
Description
Accepted
Values
<config>
This value turns on configuration file debug logging.
This option is disabled by default. This element also
accepts an attribute named "full" that enables full
configuration file debug logs. See the examples below
to see how to use this attribute.
yes and no
<prefetch>
This value turns on prefetch debug information
logging. This option is disabled by default.
yes and no
<batchaddition>
This value turns on batch addition debug information
logging. This option is disabled by default.
<extfh>
The value turns on the logging of information about
the EXTFH switcher. The following is logged: the
loading of the library and function, the number of
redirected instances, if the switcher is active on open
(i.e., when there is at least one redirect instance), and
if the calls are redirected or sent to c-tree.
yes and no
<file>
This option logs file open/create events. An entry is
logged when a file is created and when it is opened.
The entry includes the file name and the assigned file
number. Entries are also logged when a file rule is
matched and when file mapping rules are used.
yes and no
<generic>
This option disables generic debug log messages
which are enabled by default when <log><debug> is
not specifically set to no.
yes and no
<transaction>
This option logs all calls to TRANBEG, TRANEND,
TRANABTX, and PUTHDR with parameter
ctIICTbegin, ctIICTcommit, and ctIICTabort.
yes and no
Examples
The following example enables the logging of debug information only:
<log file=mylog.txt>
<debug>yes</debug>
</log>
www.faircom.com
All Rights Reserved
204
The following example enables debug logging of configuration and explicitly disables the debug
logging of prefetch and batch addition operations:
<debug>
<config full="yes">yes</config>
<prefetch>no</prefetch>
<batchaddition>no</batchaddition>
</debug>
</log>
www.faircom.com
All Rights Reserved
205
<error>
The error log option instructs the c-treeRTG to log file error events.
Accepted Values
Value
Effect
Synonyms
yes
This value turns on the error logging.
y, true, on, 1
no
This value turns off the error logging.
n, false, off, 0
The error log option also accepts the following Boolean (yes or no) sub-options to include or
exclude certain type of errors from the log file.
Children elements
Name
Description
Accepted
Values
<atend>
This value turns on logging of end-of-file errors. This
option is disabled by default.
yes and no
<notfound>
This value turns on logging of record-not-found errors.
This option is disabled by default.
yes and no
<duplicate>
This value turns on logging of duplicate-key errors.
This option is disabled by default.
yes and no
By default, the entries associated with <atend>, <notfound>, and <duplicate> are not
logged unless they are explicitly enabled.
Examples
The following example enables the logging of errors only:
<error>yes</error>
</log>
The following example enables the logging of end-of-file errors but not of record-not-found errors:
<error>
<atend>yes</atend>
<notfound>no</notfound>
</error>
</log>
www.faircom.com
All Rights Reserved
206
<info>
The info option indicates to log generic information in the specified log file.
Accepted Values
Value
Effect
Synonyms
yes
This value turns on generic information logging.
y, true, on, 1
no
This value turns off generic information logging
n, false, off, 0
Examples
The following example enables the logging of generic information only:
<info>yes</info>
</log>
www.faircom.com
All Rights Reserved
207
<profile>
The profile option indicates to log performance profiling information in the specified log file.
Accepted Values
Value
Effect
Synonyms
yes
This value turns on profiling information logging.
y, true, on, 1
no
This value turns off profiling information logging.
n, false, off, 0
Examples
The following example enables the logging of profiling information:
<log file="mylog.txt">
<profile>yes</profile>
</log>
www.faircom.com
All Rights Reserved
208
<warning>
The warning option indicates to log warnings about potentially unwanted conditions in the
specified log file.
The warnings do not represent blocking errors.
Accepted Values
Value
Effect
Synonyms
yes
This value turns on warning logging.
y, true, on, 1
no
This value turns off warning logging.
n, false, off, 0
Examples
The following example enables the logging of warnings only:
<warning>yes</warning>
</log>
www.faircom.com
All Rights Reserved
209
<locktimeout>
In V2 and later, a new configuration option, <locktimeout>, sets the blocking lock timeout. For
example: <locktimeout>15</locktimeout> sets the timeout for blocking locks to 15
seconds.
 If <retrylock> is enabled and <locktimeout> is set to a value greater than 0, an
operation attempting to acquire a lock on a locked record returns after <locktimeout>
seconds with a locked error.
 If <retrylock> is enabled and <locktimeout> is set to 0 (default), an operation
attempting to acquire a lock on a locked record waits until the record becomes available.
See Also
 <retrylock> (page 222)
www.faircom.com
All Rights Reserved
210
<locktype>
The locktype option allows changing the default record locking behavior of the COBOL system in
use.
Note: If not specified, the default record locking behavior of the COBOL system is used:
The default record locking behavior of COBOL systems using ExtFH interface (i.e. Micro Focus)
is to return locked records.
The default record locking behavior of ACUCOBOL is to return a locked record only if a lock on it
is not requested.
Accepted Values
Value
Effect
0
Locked records are returned.
1
Locked records are not returned.
Synonyms
Example
<locktype>0</locktype>
www.faircom.com
All Rights Reserved
211
<maxlencheck>
The maxlencheck option specifies whether to check that the record being read from disk fits
entirely into the record buffer for which length is equal to the maxlen file definition. If this option is
set to yes, an error is returned if the record read from disk is larger than maxlen bytes. If this
option is set to no, the record is truncated at maxlen bytes before it is returned to COBOL. This
option is enabled by default.
Accepted Values
Value
Effect
Synonyms
yes
Return an error if record is larger than maxlen bytes.
This is the default value.
y, true, on, 1
no
Return record truncated at maxlen bytes.
n, false, off, 0
Example
<maxlencheck>yes</maxlencheck>
www.faircom.com
All Rights Reserved
212
<map>
The map option replaces the file name or directory passed by the COBOL application with the
specified values.
The map option may contain the following sub-options:
<name> (page 214) map option
The name option specifies the string that replaces the file name portion of the file path
passed by the COBOL application.
<dir> (page 215) map option
The dir option specifies the string that replaces the directory portion of the file path passed by
the COBOL application.
Examples
The following example replaces only the file name portion of the passed file path:
<map>
<name>CUSTMAST2010</name>
</map>
The following example replaces both the name and directory portion of the passed file path:
<map>
<dir>/Data2010</dir>
</map>
Wildcards
If wildcards are used in the <file> matching rule, the <map> string does not replace the part of the
file name or directory that matches a wildcard. Only the part of the file name that is specified
explicitly is replaced by the <map> string.
Wildcard Example
The following example changes all file names ending with "2010" so that they end with "2013". If
a file named CUSTMAST2010 is found, it will be changed to CUSTMAST2013.
<file name="*2010">
<map>
<name>2013</name>
</map>
</file>
www.faircom.com
All Rights Reserved
213
<name>
The name option specifies the string that replaces the file name portion of the file path passed by
the COBOL application. It supports %n and %d substitution specifiers. For more information
about substitution specifiers, please refer to "Substitution specifiers (page 231)."
Examples
The following example replaces only the file name portion of the passed file path:
<map>
</map>
www.faircom.com
All Rights Reserved
214
<dir>
The dir option specifies the string that replaces the directory portion of the file path passed by the
COBOL application. It supports %n and %d substitution specifiers. For more information about
substitution specifiers, please refer to "Substitution specifiers (page 231)."
Examples
The following example replaces the directory portion of the file path with the content of the
FILEDIR environment variable:
<map>
<dir>%(FILEDIR)</dir>
</map>
www.faircom.com
All Rights Reserved
215
<memoryfile>
The memoryfile option indicates whether to create files in memory rather than on disk. This
feature is indicated for temporary files. This feature is off by default.
Accepted Values
Value
Effect
Synonyms
yes
Create file as memory file.
y, true, on, 1
no
Create file as disk file. This is the default value.
n, false, off, 0
c-treeRTG memory files default to a maximum size of 4Gb. The KEEPOPEN attribute is
automatically applied.
Example
<memoryfile>yes</memoryfile>
See Also
 Memory Files Overview in the c-tree Plus Programmer's Reference Guide
(http://docs.faircom.com/doc/ctreeplus/#29678.htm)
<normalize>
The <normalize> configuration option helps normalizing file paths passed to c-treeRTG. This
option is global-only and can be set only as a child of <config>. It is not valid if specified as
child of <*instance> or <file>. When this option is in use the file path gets normalized before
any file configuration matching.
The <normalize> section can perform two types of normalization:
1. <sep> - Specifies the path separator, such as forward slash (/) or backslash (\).
2. <drive> - Specifies a drive letter to be used if the path does not include a drive letter.
3. If the file path to be normalized already includes a drive letter, <drive> accepts a force=
attribute to force it to change the drive to the one specified, for example <drive
force="y">.
Examples
The following <normalize> section replaces all path separators with a backslash (\) and
prefixes all the file paths with a C drive unless the path to be normalized already includes a drive
letter:
<normalize><sep>\</sep><drive>C</drive></normalize>
www.faircom.com
All Rights Reserved
216
If the file path to be normalized already has a drive it is not changed by default. It is possible to
force the drive to be changed to the one specified by setting the force= attribute to yes. For
example:
<normalize><drive force="y">C</drive></normalize>
It is also possible to remove an existing drive by specifying an empty drive. For example:
<normalize><drive></drive></normalize>
www.faircom.com
All Rights Reserved
217
<optimisticadd>
The <optimisticadd> option enables adding keys before the data during WRITE operations.
The strategy that c-tree uses to add new records consists of adding the data record first and
subsequently adding the keys in the indices. In case of duplicate keys errors, the record just
added is deleted. This approach is optimistic as it assumes that the user is attempting to add new
records with unique keys and only occasionally the operation fails with duplicate errors.
In COBOL is common to use a pessimistic approach where the WRITE is performed mostly on
already existing keys and the COBOL programmer relies on the WRITE return code to know if a
key already exists. In such cases, the default optimistic approach used by c-tree does not provide
optimal performance.
When <optimisticadd> is enabled (default), c-tree uses an optimistic strategy which provides
optimal performance when adding non-existing records.
When <optimisticadd> is disabled, c-tree uses a pessimistic strategy that attempts to add
unique keys before adding the data record.
Examples
To disable <optimisticadd>:
<optimisticadd>no<optimisticadd>
To enable <optimisticadd> (default):
<optimisticadd>yes<optimisticadd>
www.faircom.com
All Rights Reserved
218
<prefetch>
This option enables batch record retrieval to improve performance of consecutive sequential
reads. This is achieved by retrieving a given number of records (specified by the records
attribute) from the server to the client side at the second consecutive sequential read operation.
The next sequential read operations do not need to contact the server to retrieve the records as
the records are now cached on the client side. Once all the records in the client cache are
processed, the next block of records is requested to the server.
By default, the records cached on the client side cannot be updated by other users (the
allowwriters attribute overrides this default). This avoids situations in which the cached
records do not match the records on the server.
The records are prefetched during the second subsequent call to an operation that reads the next
record (READ NEXT for COBOL; Get Next for BTRV). The READ NEXT or Get Next operation
performs as follows when <prefetch> is active:
COBOL
BTRV
Action
START
Get Key
READ NEXT
Get Next
Reads one record from the server, therefore performs as normal.
READ NEXT
Get Next
Reads n records from the server, but returns only one record,
therefore performs worse than normal.
READ NEXT
Get Next
Reads one record from client's prefetch buffer, therefore performs
very fast.
READ NEXT
Get Next
Reads one record from client's prefetch buffer, therefore performs
very fast.
READ NEXT
Get Next
...
Prefetching records improves performance of sequential reads in environments where the client
and server reside on different systems connected with a network. In such environments any
request from the client to the server is sent over the network which is generally a time-expensive
operation. It is advisable to configure c-tree so that <prefetch> is enabled only on files were
large numbers of READ NEXT or Get Next operations are performed, as shown in the examples
below.
The default value of <prefetch record="10"> has been demonstrated to be optimal for most
cases. However, if you want to fine tune the value, please make sure that it matches (as closely
as possible) the number of subsequent READ NEXT or Get Next operations performed by your
application. Setting <prefetch records> to a larger number will result in reading records from
disk that will never be returned to the application which may neutralize the performance gain of
prefetching records.
Please notice that a READ KEY or any Get Record operation in the middle of a READ NEXT or
Get Next sequence invalidates the prefetched records causing the prefetch logic to restart at the
next READ NEXT or Get Next operations.
The number of records to prefetch is defined by the records attribute. The size of the prefetch
buffer is determined by the record size and the number of records:
prefetch_buffer_size = record_size * <prefetch_records>
www.faircom.com
All Rights Reserved
219
Accepted Values
Value
Effect
Synonyms
yes
Enable record prefetch.
y, true, on, 1
no
Disable record prefetch. This is the default value.
n, false, off,
0
Attributes
Attribute
Values
Description
Synonyms
records
n = number
of records
Indicates the number of records to prefetch. This
value is set to 10 by default. Note: Increasing this
setting too far might cause a slow down, so adjust
it wisely
recs
allowwriters
yes, y, true,
on, 1
or
n, false, off,
0
When a set of records is prefetched, the
prefetched records are locked with a read lock
that allows other users to read them but prevents
other users from updating them. When this
attribute is enabled, the read lock is not used so
that other users can alter the prefetched records.
This attribute is disabled by default (prefetch
allowwriters="no").
See Notes about <prefetch allowwriters>
below.
writers
Notes about <prefetch allowwriters>
If you are calling READ NEXT or Get Next with any locking options, then <prefetch
allowwriters> has basically no effect as all the prefetched records will be locked as a result of
the requested lock options of the READ NEXT or Get Next calls.
If you are calling READ NEXT or Get Next without any locking options, then <prefetch
allowwriters> is significant. With allowwriters=no (the default), the prefetched records
are locked with a read lock type that allows other users to read them but prevents other users
from updating them. Setting allowwriters=yes allows other users to read and write the
prefetched records, which may cause the user reading the prefetched record to retrieve a record
that has been changed or even deleted by another user.
Note: It is the programmer's responsibility to ensure that the application does not have issues
with prefetched records that have been modified. Enable allowwrites only when data is not
critical and/or seldom changes. For example, a list of countries or dealer locations may not
change frequently, so prefetched records will rarely be out-of-date.
Do not enable allowwrites if the data is critical and/or frequently changing. For example,
account balances or line items on an open order need to be up-to-date.
Examples
To enable <prefetch> and set the number of prefetched records to 50:
<prefetch records="50">yes</prefetch>
To enable prefetch and allow prefetched records to be modified by other users:
<prefetch allowwriters="yes">yes</prefetch>
www.faircom.com
All Rights Reserved
220
To configure c-tree so that <prefetch> is enabled only on specific files (i.e., files where large
numbers of READ NEXT are performed):
<config>
<file/>
<file name="specific_file">
<prefetch>yes</prefetch>
</file>
</config>
The configuration above turns on <prefetch> only for specific_file, leaving it off all other files.
www.faircom.com
All Rights Reserved
221
<retrylock>
The retrylock option indicates whether a READ operation that fails because a record is locked
should wait until the lock is released rather than returning an immediate lock error. When this
option is enabled, records are locked with the c-tree lock mode of ctENABLE_BLK instead of
ctENABLE.
Accepted Values
Value
Effect
Synonyms
yes
Wait until the lock is released.
y, true, on, 1
no
Do not wait and return immediately with an error. This
is the default value.
n, false, off, 0
Example
<retrylock>yes</retrylock>
www.faircom.com
All Rights Reserved
222
<runitlockdetect>
The runitlockdetect option specifies whether to check if a record has been locked by a separate
OPEN statement issued from within the same run unit. When this option is turned on, a lock error
is returned while reading a record that was locked within the same instance. When this option is
turned off, reading a record that was locked within the same instance does not produce a locking
error.
Accepted Values
Value
Effect
Synonyms
yes
Detect record locks. This is the default value.
y, true, on, 1
no
Do not detect record locks.
n, false, off, 0
Example (detect record locks):
<runitlockdetect>yes</runitlockdetect>
<runitlockdetect anyunlock> Attribute
The anyunlock attribute overrides the defaults to match the behavior of COBOL compilers:
 <runitlockdetect anyunlock="yes"> - The shared locks are released by any OPEN
instance (which mimics the behavior of the Micro Focus runtime).
 <runitlockdetect anyunlock="no"> - The shared locks are released only by the
OPEN instance that obtained the lock (which mimics the ACUCOBOL runtime).
The anyunlock attribute is meaningful only if <runitlockdetect> is set to No. When is set to
Yes, each OPEN instance is treated as a different run unit.
Example (shared locks released by any OPEN instance):
<runitlockdetect anyunlock="yes">no</runitlockdetect>
www.faircom.com
All Rights Reserved
223
<skiplock>
The skiplock option advances the current record pointer when a locked record is encountered.
This feature is off by default.
Accepted Values
Value
Effect
Synonyms
yes
Advance the current record pointer when a locked record
is encountered.
y, true, on, 1
no
Do not advance the current record pointer. This is the
default value.
n, false, off, 0
Example
<skiplock>yes</skiplock>
www.faircom.com
All Rights Reserved
224
<smartcopy>
The smartcopy option enables the use of batched read/write techniques to improve performance
of file copy operations. If this option is set to yes, the file copy reads and writes records in blocks
in order to reduce the number of read and write operations. If this option is set to no, the records
are copied one by one. This option is enabled by default.
Accepted Values
Value
Effect
Synonyms
yes
Records are copied in blocks. This is the default value.
y, true, on, 1
no
Records are copied one by one.
n, false, off, 0
Attributes
Attribute
Values
Description
Default
rpc
yes or no
Uses an RPC function to copy records from
one file to another directly within the server
process.
yes
raw
yes or no
Uses physical batches instead of standard
functions. This enhancement is available only if
the <smartcopy rpc> attribute is set to yes; it is
not enabled by default.
not enabled
Example
To enable smartcopy:
<smartcopy>yes</smartcopy>
To disable the server-side copy, define the following attribute:
<smartcopy rpc="no">
To enable raw copying (using physical batches), define the following attribute:
<smartcopy raw="yes">
www.faircom.com
All Rights Reserved
225
<sqlize>
The sqlize option indicates whether to attempt linking the table to c-treeACE SQL. If this option is
set to yes, the necessary operations to make the file accessible from c-treeACE SQL are
performed when the file is open with OUTPUT or EXTEND mode. This option is disabled by
default. The sqlize option accepts XFD or XDD files as input.
Accepted Values
Value
Effect
Synonyms
yes
Files opened with OUTPUT or EXTEND mode are linked to
c-treeACE SQL.
y, true, on, 1
no
No attempt to link table is made. This is the default value.
n, false, off,
0
Attribute
Description
Synonyms
xfd
Path to XFD or XDD data definition file.
If a directory is specified, a file with same name but ".xfd" or ".xdd"
extension is searched.
Value may contain %n and %d substitution specifiers. For more
information about substitution specifiers please refers to paragraph
Substitution specifiers (page 231).
xdd
database
Database name to add the file to.
The default value is "ctreeSQL".
db
password
c-treeRTG ADMIN password.
The default value is "ADMIN".
pw
symbolic
Optional table name to use when adding file to a database.
symb
prefix
Optional prefix for table or symbolic name.
owner
Optional user name to assign table ownership.
public
Optionally grant public access permissions. Values:
"yes" : Grant public permissions.
"no" : Turns off CRC checks.
"readonly" : Grant read-only permission.
(The owner of the table and the DBA have all the permissions)
convention
Numeric storage convention ID. Values:
Attributes
A
B
D
I
M
N
R
V
- ACUCOBOL-GT
- MBP COBOL
- Data General
- IBM
- Micro Focus
- NCR COBOL
- Realia COBOL
- VAX COBOL
conv,
numformat
The default value is "M" for EXTFH or "A" for ACUCOBOL-GT.
rules
Optional path to rules file - see Define External Rules (page 59)
rule
www.faircom.com
All Rights Reserved
226
Examples
<sqlize xfd="custmast.xfd" symbolic="customers">yes</sqlize>
<sqlize xfd=".\xfd\" prefix="2012">yes</sqlize>
<sqlize xfd="%n.xfd">yes</sqlize>
www.faircom.com
All Rights Reserved
227
<temporary>
In V2 and later, a c-treeRTG configuration element, <temporary> can be used to suppress the
disk flush of certain operations to increase performance.
Note: Use this option only on files that are not required to persist in the event of a system crash
or power failure.
www.faircom.com
All Rights Reserved
228
<transaction>
The transaction option indicates whether or not to create files with transaction support enabled.
This feature is turned on by default.
Please note that it is possible to enable/disable transaction support and transaction logging on
existing files using the -tron (page 153) option of the ctutil (page 121) utility.
Accepted Values
Value
Effect
Synonyms
yes
Turns on transaction support. This is the default
value.
y, true, on, 1
no
Turns off transaction support.
n, false, off, 0
Attribute
Description
Default Value
logging
Enable/disable transaction logging.
Values:
"yes" : Turns on transaction logging. It is indicated
when data safety is more important than
performance. Files are created with c-tree file mode
ctTRNLOG and are automatically recovered after a
crash.
"no" : Turns off transaction logging. It is indicated
when performance is more important than data
safety. Files are created with c-tree file mode
ctPREIMG. This is the default value.
"no"
fileoperations (or
fileops)
Determines whether file operations (such as file
create, delete, and rename) performed within an
active transaction are affected by the transaction
ending operation (commit or abort):
"yes" : File operations are transaction dependent.
"no" : File operations performed within an active
transaction are not affected by the transaction ending
operation (commit or abort).
Attributes
Examples
Example 1: To turn off transaction logging:
<transaction logging="no">yes</transaction>
Example 2: The following pseudo-code creates a file if <transaction fileops="no"> and
does not create a file if <transaction fileops="yes">:
begin
create file
rollback
www.faircom.com
All Rights Reserved
229
<trxholdslocks>
This configuration keyword simulates ACUCOBOL's TRX_HOLDS_LOCKS=1 option, which does
not free locks at transaction commit unless the locked records are updated during the transaction.
Note: The <trxholdslocks> option is global-only and can be set only as a child of <config>.
It is not valid if specified as child of <*instance> or <file>.
Accepted Values
Value
Effect
Synonyms
yes
Only the locks on records updated during the transaction
are released at transaction commit while all other locks not
specifically released are held.
y, true, on, 1
no
All pending locks are released during a transaction commit
or rollback. This is the default value.
n, false, off, 0
Example
<trxholdslocks>yes</trxholdslocks>
www.faircom.com
All Rights Reserved
230
<writethru>
The writethru option specifies whether to enable write synchronization.
Accepted Values
Value
Effect
Synonyms
yes
Turn on write synchronization.
y, true, on, 1
no
Turns off write synchronization. This is the default
value.
n, false, off, 0
Example
<writethru>yes</writethru>
B.3.
Substitution Specifiers
The value of some configuration elements may contain substitution specifiers that are expanded
to actual content at runtime. This feature is useful when it is required to set configuration
elements to values that are known only at runtime.
The following substitution specifiers are supported:
%n Expands to name of the file affected by configuration
%d Expands to directory of the file affected by configuration
%(ENV) Expands to content of environment variable ENV
www.faircom.com
All Rights Reserved
231
Appendix C.
c-treeRTG COBOL Edition Directories
A brief description of each of the c-treeRTG COBOL Edition directories is given below:
Driver - The Driver directory contains drivers for COBOL and each of the supported SQL APIs as
well as tutorials for stored procedures.
The 64-bit installation provides both 32- and 64-bit drivers: The ctree.cobol directory contains
64-bit drivers and the ctree.cobol.32bit directory contains 32-bit drivers, which are provided in
case you need to run a legacy 32-bit application on a 64-bit system.
 ctree.cobol (see below for more details)
 sql.ado.net (Windows only)
 sql.jdbc
 sql.odbc
 sql.php
 sql.python
 sql.stored.procedures
Server - The server\sql directory contains the powerful c-treeACE SQL engine, already started as
a service in most Microsoft Windows environments. You will find your data in this area when you
begin using c-treeACE SQL. A single directory contains the entire c-treeACE SQL database.
c-treeACE SQL is smaller than 10 megabytes yet rivals the performance of other database
products hundreds of times its size!
SetUp - If you installed from the Windows Zip file, a folder called SetUp is created. It contains the
configuration tool, FairComConfig.exe, which will help you configure the ODBC driver, the
ADO.NET driver, and the c-treeACE Windows Service. If you installed using the Windows
installation program (e.g., *.msi), the setup is done for you so this folder does not exist.
Non-Windows packages do not include this folder.
Tools - This area contains a collection of sleek and modern c-treeACE tools. Two folders are
provided. cmdline contains basic command line tools, for administrative tasks. A guitools folder
contains the binaries for all of the c-treeACE tools installed and available from the Windows Start
menu. The section titled c-treeACE Tools explains the graphical tools provided with c-treeRTG.
These folders are provided:
 cmdline – Contains basic command line tools, for administrative tasks.
 gui – (Windows only) Contains .NET versions of the c-treeACE tools, which are available
from the Windows Start menu.
 guitools.java – Contains cross-platform Java-based tools for configuring c-treeRTG and
migrating your data.
Inside the Driver/ctree.cobol Directory
The Driver directory includes the ctree.cobol directory, which contains drivers and utilities for
each COBOL compiler (on 64-bit systems, the ctree.cobol directory provides 64-bit drivers and
ctree.cobol.32bit provides 32-bit drivers):
www.faircom.com
All Rights Reserved
232
 acucobol
• ctreeacu.c – Required to support ACUCOBOL on Windows and Unix. See the
c-treeRTG COBOL Edition User's Guide for instructions about ACUCOBOL-GT setup.
• ctutil.exe – A special version of ctutil is provided for each compiler.
 extfh
• CTEXTFH.dll – The c-treeRTG COBOL Edition driver for the ExtFH supported compilers,
which includes the Micro Focus compiler.
• CTEXTFH.lib – The static link library version of the c-treeRTG COBOL Edition driver for
the ExtFH supported compilers. Most often, you will not be using need this library.
 iscobol
• ctree.dll – This is the c-treeRTG COBOL Edition driver for the isCobol compiler
developed by Veryant.
 rm-cobol
• mtclient.dll – This is the c-treeRTG COBOL Edition driver for the RM/COBOL compiler.
Samples - The samples directory is located in:
<install directory>\<platform>\Driver\ctree.cobol\samples\
The samples directory includes conversion routines that can be integrated into your programs.
These samples allow you to create additional functionality that is not required to implement
c-treeRTG.
 acucobol
• cscopy.cbl – A sample COBOL program that provides a working example of using the
COBOL C$COPY functionality for properly copying a c-treeRTG data file.
• getinfo.cbl – A COBOL program that shows how to retrieve file information.
• visionconvert
 filesys.def – Contains variables and values for use with the ACUCOBOL file handler.
 mig.cbl – An example of a COBOL program to migrate files from Vision to c-tree by
reading from the Vision database and writing into the c-tree database.
 readme.txt
• XDDcheck
 xddchk.cbl – A COBOL program that reads an XDD and validates it.
 xdddef.def – Contains return codes and definitions used by xddchk.cbl.
 extfh\mfconvert
• mfconvert.cbl – A COBOL program to migrate files from Vision to c-tree by reading from
Vision and writing to c-tree.
• xfhfcd.cpy – A copybook to be used with mfconvert.cbl.
 iscobol
• cobol-esql.cbl – This example shows how to use Veryant’s isCobol Embedded SQL API
in your program. Note: This is not the FairCom Embedded SQL that is included with
c-treeACE.
www.faircom.com
All Rights Reserved
233
Tutorials - The c-treeACE tutorials are contained here. To ensure your c-treeRTG COBOL
Edition environment is correctly set up and working, a helpful COBOL example is provided in the
tutorials directory under ctree.cobol.
 Tutorial1
• cobol_Tutorial1.cbl – This tutorial follows the standard "Init, Define, Manage, Done"
format provided for all c-treeACE interfaces. You will not need to use these procedures to
use c-treeRTG. Simply follow the procedures in the c-treeRTG User Guide to install,
configure, and migrate into c-treeRTG.
• custmast.xdd – This is a data definition file to be used with cobol_Tutorial1.cbl.
 Sqlize
• SQLIZEEXAMPLE.CBL – This tutorial guides you through the process of making your
data ready for SQL access. This process, called "sqlizing," prepares your data for full
read/write SQL access without affecting access from COBOL applications. This
directory includes the supporting files used in this tutorial: CARDFILE.FD, CARDFILE.SL,
rules.xml, and Tutorial.sql.
www.faircom.com
All Rights Reserved
234
Appendix D.
Sample Programs
The c-treeRTG products provide a directory that includes sample programs described in this
section.
D.1.
The Samples Directory
The samples directory is located in:
<install directory>\<platform>\Driver\ctree.cobol\samples\
The samples directory includes conversion routines that can be integrated into your programs.
These samples allow you to create additional functionality that is not required to implement
c-treeRTG.
 acucobol
• cscopy.cbl – A sample COBOL program that provides a working example of using the
COBOL C$COPY functionality for properly copying a c-treeRTG data file.
• getinfo.cbl – A COBOL program that shows how to retrieve file information.
• visionconvert
 mig.cbl – An example of a COBOL program to migrate files from Vision to c-tree by
reading from the Vision database and writing into the c-tree database.
 readme.txt
• XDDcheck
 xddchk.cbl – A COBOL program that reads an XDD and validates it.
 xdddef.def – Contains return codes and definitions used by xddchk.cbl.
 extfh\mfconvert
• mfconvert.cbl – A COBOL program to migrate files from Vision to c-tree by reading from
Vision and writing to c-tree.
• xfhfcd.cpy – A copybook to be used with mfconvert.cbl.
 iscobol
• cobol-esql.cbl – This example shows how to use Veryant’s isCobol Embedded SQL API
in your program. Note: This is not the FairCom Embedded SQL that is included with
c-treeACE.
www.faircom.com
All Rights Reserved
235
D.2.
isCOBOL Samples
The c-treeRTG COBOL Edition product contains a directory that includes sample programs
described in this section. The samples directory is located in \Driver\ctree.cobol\samples\iscobol
under the FairCom installation directory.
Accessing ESQL from isCOBOL
isCOBOL supports Embedded SQL (ESQL), which is an alternate way to access c-treeACE files.
This is a product of isCobol and it not to be confused with the ESQL available from FairCom.
c-treeRTG COBOL Edition contains a directory that includes the ESQL sample program
described in this section. The samples directory is located in \Driver\ctree.cobol\samples\iscobol
under the FairCom installation directory.
Compile cobol-esql with isCOBOL
To compile the cobol-esql.cbl program, start the isCOBOL compiler as follows.
iscc.exe –sp=C:\Program Files\Veryant\isCOBOL\sample\isdef cobol-esql.cbl
The –sp option instructs the isCOBOL compiler where to find the SQLCA copybook.
Run cobol-esql with isCOBOL
Before running the tutorial, either copy ctreeJDBC.jar to the isCOBOL lib directory or add
ctreeJDBC.jar to the CLASSPATH environment variable.
To run the cobol-esql program, start the isCOBOL runtime as follows:
iscrun.exe COBOL_ESQL
www.faircom.com
All Rights Reserved
236
Appendix E.Connecting to the c-treeRTG Server
The following table indicates when the application connects to, and disconnects from, the
c-treeRTG Server:
Connects
when...
Connects to...
Exceptions
Disconnect
when...
COBOL
program starts
All instances
defined in the
configuration file
Instances with
connect="no"
are connected on
first file-system
operation on files
belonging to the
instance
COBOL program
exits
ACUCOBOL
First
file-system
operation
(typically an
OPEN)
Only the instance
owning the file
affected by the
file-system
operation
Instances with
connect="yes"
are connected
when program
starts
COBOL program
exits
MicroFocus
(and other
ExtFH-based
programs)
First
file-system
operation
(typically an
OPEN)
Instance owning
the file affected by
the file-system
operation and any
instances with
connect="yes"
COBOL-IT
(compiled
with -fctree)
First
file-system
operation
(typically an
OPEN)
Only the instance
owning the file
affected by the
file-system
operation
COBOL-IT
(compiled
with
-use-extfh)
First
file-system
operation
(typically an
OPEN)
Instance owning
the file affected by
the file-system
operation and any
instances with
connect="yes"
isCOBOL
Any file-system
operation after
which no files or
transactions are
open in any
instances
Instances with
connect="yes"
are connected
when the program
starts
COBOL program
exits
Any file system
operation after
which no files or
transactions are
open in any
instances
For an explanation of <instance> (page 177), the connect attribute, and other aspects of the
configuration file, see Configuration File Elements (page 175).
www.faircom.com
All Rights Reserved
237
Appendix F. Transaction Processing Notes
c-treeRTG is transaction-ready and supports ROLLBACK out of the box. There is no need to
enable <transaction logging> if you need ROLLBACK.
By default, c-treeRTG files are created as c-tree PREIMG files (an intermediate level of
transaction processing supported by c-treeACE). This provides full atomicity of transactions
including rollback with the best of performance. However, this model of transaction processing
does not log transactions to disk, thus does not provide durability and recovery of transactions in
case of system failure. Full transaction processing, provided by write-ahead logs on disk,
provides complete ACID protection of data.
In addition, c-treeRTG allows working without any transaction capability. This is useful when you
need extreme performance such as very large batch loads, etc.
ctutil provides for switching COBOL tables between these various modes. Be cautious when
switching modes, as data loss can occur if an appropriate mode is not appropriately applied for
specific usage patterns.
ACUCOBOL and Micro Focus programs support transaction processing in slightly different ways,
as described below:
ACUCOBOL
ACUCOBOL has START TRANSACTION, so a transaction is explicitly started using a
START TRANSACTION directive. See the ACUCOBOL documentation
(http://documentation.microfocus.com/help/topic/com.microfocus.eclipse.infocenter.extendAC
USuite/BKRFRFPROC00000001S208.html).
COMMIT TRANSACTION and ROLLBACK TRANSACTION directives are supported by both
ACUCOBOL and Micro Focus.
An ACUCOBOL program allows you to rollback updates only if a file has been defined as
WITH ROLLBACK. See the ACUCOBOL documentation
(http://supportline.microfocus.com/documentation/acucorpproducts/docs/v6_online_doc/gtma
n1/gt159.htm).
Micro Focus
Micro Focus does not have START TRANSACTION. A transaction is automatically started
first time you update a file that has been opened with the openwithrollback option.
COMMIT TRANSACTION and ROLLBACK TRANSACTION directives are supported by both
ACUCOBOL and Micro Focus.
www.faircom.com
All Rights Reserved
238
Appendix G.
Troubleshooting
Error Codes
Most of the c-treeRTG errors are intended for developers and will seldom be seen during normal
operation.
The c-treeRTG products are built upon a specialized version of the c-treeACE core database
engine. The complete list of possible c-treeRTG errors can be found in the c-treeACE Error
Codes section of the c-tree Programmer's Reference Guide
(http://docs.faircom.com/doc/ctreeplus/#28320.htm).
Error 407
Support has been added to the c-treeRTG ctutil utility to open files affected by error 407 so it can
export data from a file that has a damaged resource chain. This support requires ADMIN
permission and the OPENCRPT file mode. To use this functionality, ctutil must be renamed to
ctunload407. The ctunload407 utility functions similar to ctutil -unload except that it
automatically connects as ADMIN (with the default ADMIN password) and enables the
<allowcorrupt> setting.
Error 408 / 438
Error 408 / 438 during -sqlink indicates that no record definition is available. Either the file does
not have an XDD resource (-sqlinfo was not performed) or the server did not load the data
conversion callback library. Possible causes are:
 LOAD_CALLBACK_LIB ctsrvr.cfg keyword was not specified or invalid.
Or
 The callback library is not in LD_LIBRARY_PATH (UNIX).
Troubleshooting Performance
The following features can improve performance:
 Using the <prefetch> feature to improve performance of sequential reads.
 Using the KEEPOPEN feature (which can be enabled in ctsrvr.cfg) if the COBOL application is
frequently using OPEN/CLOSE.
 Disabling <optimisticadd> if the COBOL application frequently performs WRITE
operations on existing records.
 Disabling <transaction> if transactions are not in use and data is stored on secure media
(hardware redundancy, etc.).
 Enabling <ctfixed> to force creating fixed-length record data files as ctFIXED files.
Client/Server Incompatibility
An internal error CTE_INCOMPATIBLE (37) is returned when the client or server is outdated. An
entry is sent to <log> with a logical error 37 and one of the following:
www.faircom.com
All Rights Reserved
239
 c-tree error -3 (CTE_OLD_CLIENT) when the client is older than the server
 c-tree error -4 (CTE_OLD_SERVER) when the server is older than the client
File Matching Rules in ctree.conf
When ctree.conf contains only one <instance> element, it is not mandatory to specify a
<file> rule because it is implicit that c-treeRTG needs to use the one available instance to open
files.
If you specify more than one instance, you need to specify a <file> rule so that c-treeRTG
knows which instance to use to open files. When specifying more than one instance, specify a
default file rule into the instance you want to use:
<config>
<log>n</log>
<instance server="FAIRCOMS"></instance>
<redirinstance>
<file name="*">
</file>
</redirinstance>
</config>
Please notice that to specify a default file rule you can omit the name/dir attributes so the above
configuration can also be specified as follows:
<config>
<log>n</log>
<instance server="FAIRCOMS"></instance>
<redirinstance><file/></redirinstance>
</config>
The above concept applies to all <*instance> elements: <instance>, <redirinstance>,
etc.
isCOBOL Fails to Run cobol_Tutorial1
The tutorial will fail if you have the following setting in iscobol.properties:
iscobol.io_creates=1
If you ran the tutorial with iscobol.io_creates=1 enabled, comment out that setting and
delete the custmast.dat and custmast.idx files.
See Also
 Troubleshooting Data Conversion Errors (page 87).
www.faircom.com
All Rights Reserved
240
Appendix H.
Logging & Error Codes
This section lists error codes that are specific to c-treeRTG. You may encounter these errors in
addition to c-treeACE errors and standard COBOL and BTRV errors.
H.1.
Improved log output with file names on ERROR entries
In later versions, the output of the c-treeRTG log has been improved by appending a file name to
log messages. The file name is preceded by the instance name, when specified in ctree.conf with
the <instance name> attribute, or by the instance number and file number to uniquely identify
the file as follows:
instance_number#file_number:file_name.
The file name is logged for START, READ, NEXT, PREVIOUS, WRITE, REWRITE, DELETE,
and UNLOCK operations.
In addition every entry in the log is pre-pended with a thread ID to uniquely identify the
process/thread that made the log entry. The thread ID is made of 8 hexadecimal digits followed
by a “>” sign.
Example:
00002D40> 20140915T141358 core:3494:cts_rewdel ERROR 5:42:0 record is locked 0#0:arc1.dat
This modification also introduces 3 new substitution specifiers to be used in the name attribute of
the <instance> and its variant elements:
 %t to print the thread ID in unsigned decimal format
 %p to print the process ID in unsigned decimal format
 %i to print the instance number in unsigned decimal format
These 3 new specifiers can optionally contain embedded format specifiers with the following
prototype:
%[0][width][x|X]specifier
 [0] left-pads the number with zeroes (0) instead of spaces when width is specified
 [width] minimum number of characters to be printed. If the value to be printed is shorter
than this number, the result is padded with blank spaces. The value is not truncated even if
the result is larger.
 [x] (lower case) number is as unsigned hexadecimal integer
[X] (upper case) number is as unsigned hexadecimal integer
www.faircom.com
All Rights Reserved
241
H.2.
Driver Error Codes
The table below lists the logical error codes logged by the driver in the log file and returned by
ctutil. These errors are generated internally by the driver and are converted into an error to be
returned to the COBOL runtime. They do not match any standard COBOL error codes.
The error codes returned by c-treeRTG are formatted as follows:
THREAD> DATE
T
TIME
SRC:LINE:FUNCTION
TYPE
E1:E2:E3 MESSAGE
For example:
00002038> 20150506T105656
displayed),FAIRCOMS)
api:5248:ctl_regins ERROR 19:133:0 INTISAMX(1280,32,64,1280,1,,(not
The first part of the message is the thread ID. The next part is a date-time stamp. DATE is
formatted as yyyymmdd followed by T and then the TIME formatted as hhmmss:
20140312T081659 = March 12, 2014 at 8:16:59 AM.
The next part of the message (SRC:LINE:FUNCTION) indicates the source module, line number,
and function returning the error, which may be required by FairCom Support:
 SRC: Columns 16-20 acronym for source module where the error is logged (usually add
ctcb in front to get the actual source module name)
 LINE: Columns 22-25 line number where the error has been logged (usually just after it is
generated)
 FUNCTION: Columns 27-36 function name where the error has been logged
For example:
api:4397:ctl_regins
Columns 38-42 indicate the event type: ERROR, WARNG, INFO, PROFL, DEBUG.
Following the ERROR event type, you will see three numbers delimited by colons (":"). These
numbers indicate the following in the order listed:
 E1: Logical driver error (see the table below)
 E2: c-tree isam_err/uerr_cod (see the appropriate manual, such as the c-treeACE
Programmer's Reference Guide (http://docs.faircom.com/doc/ctreeplus/#28320.htm))
 E3: c-tree sysiocod
For example, ERROR 19:133:0 indicates COBOL error 19 (CTE_INTERFACE), c-treeACE error
133 (ASKY_ERR), and sysiocod 0.
The final part of the message is internal information (the failing function and the function
arguments), for example:
INTISAMX(1280,32,64,1280,1,a)
Below are examples of other event types:
www.faircom.com
All Rights Reserved
242
20140725T165133
20140725T165133
20140725T165133
api:0436:ctl_init
INFO
api:0437:ctl_init
INFO
api:4706:ctl_setins INFO
configuration file: ctree.conf
client version:10.5.0.28751-140717 id:34
server version:10.5.0.28751-140717 id:34
20140725T165908 core:0611:cts_make
DEBUG FILE created: custmast
20140725T165908 api:5492:ctl_conffi DEBUG FILE "custmast" matches <file> #0
20140725T165908 fsi:0576:ct_make2
PROFL 079310 counts on file:custmast
20140725T170057 api:1926:ctl_open2 WARNG transaction configuration mismatch:
<transaction>no</transaction> but file is ctPREIMG
www.faircom.com
All Rights Reserved
243
Error Codes
CTE_NO_ERROR
0
Operation completed successfully
CTE_SYS_ERR
1
System error
CTE_PARAM_ERR
2
Parameter not correct
CTE_TOO_MANY_FILES
3
Too many files open. Check the FILES keyword
CTE_MODE_CLASH
4
File is open read-only
CTE_REC_LOCKED
5
Record locked by another user
CTE_BROKEN
6
File is corrupt. Rebuild it or restore it from a backup
CTE_DUPLICATE
7
Duplicate record not allowed
CTE_NOT_FOUND
8
Record not found
CTE_UNDEF_RECORD
9
Record position not set
CTE_DISK_FULL
10
Write error
CTE_FILE_LOCKED
11
File locked by another user
CTE_MISMATCH
13
File definition mismatch
CTE_NO_MEMORY
14
Out of memory error
CTE_MISSING_FILE
15
File not found
CTE_PERMISSION
16
User does not have appropriate access permission
CTE_NO_SUPPORT
17
Unsupported functionality
CTE_INTERFACE
19
Interface error, check c-tree error code (you may need to
activate the error logging in ctree.conf and view the error log)
CTE_MODE_CLASH_W
23
File is open write-only
CTE_MODE_CLASH_RW
24
File is not open for read and write
CTE_AT_END
25
End of file
CTE_SYNTAX_ERR
31
Configuration syntax error
CTE_CONFIG_ERR
32
Configuration error
CTE_ENCRYPTED
33
Operation not allowed. File is encrypted
CTE_REDIRINST
34
Unexpected reference to redir instance
CTE_NOT_SQL
35
Server/database is not SQL
CTE_MISSING_TABLE
36
SQL table not found
CTE_INCOMPATIBLE
37
Client/server incompatibility
CTE_FILE_EXISTS
38
File already exists
CTE_NO_TRANSACTION
39
No active transaction
CTE_NOT_MODIFIABLE
40
Key is not modifiable
www.faircom.com
All Rights Reserved
244
Appendix I. XDDCHECK Errors
The table below lists the error codes returned by XDDCHECK:
XDD_CONV_NOERR
0
No error.
XDD_CONV_NOMRTMATCH
1
Record does not match filter definition.
XDD_CONV_NOMRTFILTERERR
2
Filter definition evaluation error. Contact FairCom.
XDD_CONV_NOMEM
3
No memory.
XDD_CONV_UNDERLEN
4
Record length smaller than defined minlen.
XDD_CONV_OVERLEN
5
Record length larger than defined maxlen.
XDD_CXDD_CONV_INTERNAL
1000
Internal error. Contact FairCom.
XDD_CONV_INVTYP
1001
Unexpected Field type. Contact FairCom.
XDD_CONV_NOTSUPPORTED
1002
Conversion not supported.
XDD_CONV_INVBOOL
1003
Invalid mapping to Boolean value.
XDD_CONV_UNDERFLOW
1004
Conversion causes an underflow error.
XDD_CONV_OVERFLOW
1005
Conversion causes an overflow error.
XDD_CONV_INVNUMBER
1006
Value is not a valid number.
XDD_CONV_INVDATETIMEFOR
MAT
1007
Invalid date/time format specification.
XDD_CONV_INVHOUR
1008
Invalid Hour value.
XDD_CONV_INVMINUTE
1009
Invalid Minute value.
XDD_CONV_INVSECOND
1010
Invalid Second value.
XDD_CONV_INVDATE
1011
Invalid Date value.
XDD_CONV_INVYEAR
1012
Invalid Year Value.
XDD_CONV_INVMONTH
1013
Invalid Month Value.
XDD_CONV_INVDAY
1014
Invalid Day Value.
XDD_CONV_ARGSMALL
1015
Conversion buffer too small. Contact FairCom.
XDD_CONV_NOTADIGIT
1016
COBOL buffer contains a value that cannot be
interpreted as a digit.
XDD_CONV_BADSIGN
1017
COBOL buffer contains a value that cannot be
interpreted as sign for numeric types
XDD_CONV_INVINTSIZE
1018
Integer value of an unsupported size. Contact FairCom.
XDD_CONV_DIGITOVERFLOW
1019
Converted value has more digit than defined.
www.faircom.com
All Rights Reserved
245
Appendix J. 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
246
13. Index
%
% (percent sign Substitution Specifiers) ............... 231
<
<[Action]> do elements ........................................... 66
<[Condition]> when elements ................................. 64
<[Operator]> filter elements .................................... 78
<[Target]> action element ....................................... 67
<automkdir> .......................................................... 184
<batchaddition> .................................................... 185
<bulkaddition> ...................................................... 186
<config> ................................................................ 176
<ctfixed> ............................................................... 187
<datacompress> ................................................... 188
<datafilesuffix>...................................................... 190
<debug> ................................................................ 204
<detectlock> ......................................................... 191
<dir> ...................................................................... 215
<do> rule element ................................................... 65
<encrypt> .............................................................. 192
<error> .................................................................. 206
<field> filters element.............................................. 76
<field> operator element ......................................... 79
<field> schema element ......................................... 83
<file> ..................................................................... 181
<filecopy> ............................................................. 193
<filepool> .............................................................. 193
<filter> filters element ............................................. 77
<filters> table element ............................................ 75
<hugefile> ............................................................. 195
<ignorelock> ......................................................... 196
<indexfilesuffix> .................................................... 197
<info> .................................................................... 207
<instance> ............................................................ 177
<key> table element ............................................... 72
<keycheck>........................................................... 198
<keycompress> .................................................... 199
<leading> .............................................................. 200
<locktimeout> ....................................................... 210
<locktype> ............................................................ 211
<log> ..................................................................... 202
<map> ................................................................... 213
<maxlencheck>..................................................... 212
<memoryfile> ........................................................ 216
<name> ................................................................. 214
<normalize> .......................................................... 216
<optimisticadd>..................................................... 218
<padding> ............................................................. 201
<part> key element ................................................. 73
<prefetch>............................................................. 219
<profile> ................................................................ 208
<redirinstance> ..................................................... 179
<retrylock> ........................................................... 222
<rule> XFDRules element ..................................... 62
<runitlockdetect>.................................................. 223
<schema> table element ....................................... 81
<segment> key element ........................................ 74
<skiplock> ............................................................ 224
<smartcopy> ........................................................ 225
<sqlize>................................................................ 226
<table> root element .............................................. 71
<temporary>......................................................... 228
<transaction> ....................................................... 229
<trxholdslocks> .................................................... 230
<value> operator element ...................................... 80
<warning> ............................................................ 209
<when> rule element ............................................. 63
<writethru> ........................................................... 231
<XFDrules> root element ....................................... 61
A
ACUCOBOL, Converting Data............................... 12
ACUCOBOL-GT....................................................... 5
ACUCOBOL-GT Environment Variables ............... 10
ACUCOBOL-GT Setup ............................................ 5
ACUCOBOL-GT Verb ............................................ 11
Adding SQL Indices to Sqlized Files...................... 90
Adding Support for --setenv Command-Line
Argument to Runtime ........................................... 8
Additional Command-Line Tools.......................... 173
Additional Documentation ...................................... 26
Adjusting the Paths ................................................ 22
Adjusting the RM/COBOL Configuration File ........ 22
anyunlock ............................................................. 223
API for SQL Conversion Error Checking ............... 93
Attribute............................................................ 31, 34
automkdir option .................................................. 184
B
Background Information about Sqlizing ................. 97
base directory ........................................................ 45
Basic Configuration wizard .................................... 38
batchaddition option ............................................. 185
Btrieve ................................................................ 2, 21
Btrieve library WBTRV32.DLL ............................... 21
Btrieve owner name ............................................... 45
bulkaddition option ............................................... 186
C
CALLFH Compiler Directive ................................... 15
Camouflage.......................................................... 192
CARDFILE.FD ..................................................... 113
CARDFILE.FD, CARDFILE.SL ............................ 104
CARDFILE.SL ...................................................... 117
-check .................................................................. 124
-checkimg............................................................. 125
CLASS Clause ....................................................... 17
-clone ................................................................... 126
COBOL to SQL .................................................... 100
www.faircom.com
All Rights Reserved
247
Index
Combining Multiple XDD Directives...................... 107
Common Issues .................................................... 102
-compact ............................................................... 127
-compress ............................................................. 128
config ..............................................................40, 176
Configuration
Creating a New File (Advanced) ......................... 40
Creating a New File (Basic) ................................ 38
creating with RTG Migrate .................................. 45
Editing a Configuration File................................. 42
instance element ...................................31, 40, 177
Configuration File Elements ................................. 175
Configuration File Format ..................................... 175
Configuration files directory .................................. 165
Configuration Note for Micro Focus on 64-bit AIX .. 15
Configure the c-treeRTG Server............................. 29
Configuring the Runtime for ACUCOBOL-GT ........ 10
Configuring the Runtime for isCOBOL ................... 17
Configuring the Runtime for Micro Focus ............... 14
Connecting to the c-treeRTG Server .................... 237
-conv ..................................................................... 129
Converting ACUCOBOL Data to c-treeRTG
COBOL Edition Data........................................... 12
-copy ..................................................................... 130
Copying Server-Controlled Files........................... 172
Copying the RM Library to the Local Folder ........... 22
Copyright Notice ...................................................... iii
Create Conf. File...............................................30, 45
Creating a New File (Advanced)............................. 40
Creating a New File (Basic) .................................... 38
Creating an XDD from an XFD ............................... 55
Creating an XDD from the COBOL Source ............ 56
Creating an XDD Manually ..................................... 57
-cryptconf .............................................................. 132
ct_XDDCheck ......................................................... 95
ct_XDDClose .......................................................... 96
ct_XDDOpen........................................................... 94
ctcbtran ................................................................. 158
ctclntrn and cthghtrn utilities for managing
transaction mark numbers ................................ 173
CTE_NO_ERROR and other driver errors ........... 242
ctfileid - Update File IDs ....................................... 172
ctfixed option......................................................... 187
ctmigra .................................................................... 50
CTREE_CONF ....................................................... 33
CTREE_CONF Environment Variable .................... 33
CTREE_CONF_DUMP environment variable to
specify configuration dump file ........................... 33
CTREE_LIB ............................................................ 10
CTREE_LIB Environment Variable......................... 10
c-treeACE error codes .......................................... 239
c-treeACE Server Setup ......................................... 27
c-treeRTG BTRV Edition ...................................... 1, 2
c-treeRTG COBOL Edition ....................................... 1
c-treeRTG COBOL Edition Directories ................. 232
c-treeRTG COBOL Edition Quick Start .................... 4
c-treeRTG Configuration ........................................ 30
c-treeRTG Configuration File ................................. 31
c-treeRTG Configuration Tool - RTG Config ......... 34
c-treeRTG Errors ................................................. 246
c-treeRTG File System Details ............................ 174
c-treeRTG for Unix ................................................. 27
c-treeRTG for Windows ......................................... 27
c-treeRTG Migration tool ................................. 45, 50
c-treeRTG Products ................................................. 1
c-treeRTG Ready-to-Go Products ........................... 1
c-treeRTG Server Setup ........................................ 27
c-treeRTG SQL Access ......................................... 54
c-treeRTG SQL Support ...................................... 102
ctsrvr.cfg ................................................................ 29
cttrnmod - Change Transaction Mode Utility ....... 168
ctunload407 to unload data of files affected by
error 407........................................................... 122
ctutil ...................................................................... 121
ctutil ...................................................................... 121
ctutil ...................................................................... 158
ctutil Commands .................................................. 122
ctutil Notes ........................................................... 121
D
Data Camouflage ................................................. 192
Data Conversion .................................................... 44
Data Conversion Considerations ........................... 99
Data Conversion wizard ......................................... 45
Data Migration wizard ............................................ 45
datacompress option ........................................... 188
datafilesuffix ......................................................... 190
datafilesuffix option .............................................. 190
debug error log option .................................. 202, 204
DEFAULT_HOST................................................... 10
Defining External Rules ......................................... 59
Details about the File System and SQL ............... 174
dir option ...................................................... 213, 215
Documentation Overview ......................................... 2
Driver Error Codes ............................................... 242
Dynamic Redirection .............................................. 14
DYNREDIR ............................................................ 14
E
Editing a Configuration File.................................... 42
Element .......................................................... 31, 175
Enabling XDDOPEN, XDDCHECK, and
XDDCLOSE for Programmatic SQL
Conversion Error Checking ................................ 11
encrypt option ...................................................... 192
Error 408 / 438 ..................................................... 239
error codes ................................... 239, 241, 242, 245
driver error codes ............................................. 242
Troubleshooting ............................................... 239
XDDCHECK errors .......................................... 245
error log option ............................................. 202, 206
Error message
www.faircom.com
All Rights Reserved
248
Index
F
FairCom Typographical Conventions ....................... x
features ..................................................................... 3
file element ........................................................... 181
File Filter ................................................................. 45
File Format, Configuration .................................... 175
File Matching Precedence .................................... 183
file matching rules ................................................. 182
file system ............................................................. 174
-filecopy ................................................................ 132
filename_HOST ...................................................... 11
maxlencheck option ............................................. 212
memoryfile option................................................. 216
Micro Focus COBOL .............................................. 14
Micro Focus COBOL Setup ................................... 14
migration utility (ctmigra) ........................................ 50
Migration wizard ..................................................... 45
More xddgen enhancements ............................... 166
Multiple File Systems with RM/COBOL ................. 23
Multi-Record Example ......................................... 108
N
-getimg .................................................................. 133
Name Conflicts..................................................... 107
name option ................................................. 213, 214
numeric format ....................... 94, 147, 148, 151, 226
H
O
HIDDEN Directive ................................................. 108
hugefile keyword ................................................... 195
Option elements ................................................... 183
Optional Btrieve owner name ................................ 45
I
P
ignorelock option................................................... 196
Improved log output with file names on ERROR
entries ............................................................... 241
Index Suffix ............................................................. 45
indexfilesuffix ........................................................ 197
indexfilesuffix option ............................................. 197
-info ....................................................................... 134
info option .....................................................202, 207
installation ...........................................2, 5, 14, 17, 27
Installing the RM/COBOL Driver............................. 21
Installing the RM/COBOL Driver on Linux .............. 21
Installing the RM/COBOL Driver on Windows ........ 21
instance element.......................................31, 40, 177
isCOBOL................................................................. 17
isCOBOL Samples................................................ 236
isCOBOL Setup ...................................................... 17
iscobol.file.index ..................................................... 17
iscobol.file.index.filename ....................................... 17
padding keycompress option ....................... 199, 201
-param .................................................................. 139
Performance ........................................................ 239
prefetch option ..................................................... 219
-profile .................................................................. 140
profile option ................................................ 202, 208
G
R
leading keycompress option .........................199, 200
-load ...................................................................... 137
-loadtext ................................................................ 138
locktype option ...................................................... 211
log option ..................... 202, 204, 206, 207, 208, 209
Logging & Error Codes ......................................... 241
-rblimg .................................................................. 141
-rebuild ................................................................. 142
Recompiling the Runtime......................................... 5
Recompiling the Unix Runtime ................................ 6
Recompiling the Windows Runtime ......................... 5
Recompiling Your Application (Optional) ............... 15
Record Structure Definition
The XDD ............................................................ 97
redirinstance element .......................................... 179
-remove ................................................................ 143
-rename................................................................ 144
retrylock option..................................................... 222
RM/COBOL ............................................................ 21
RM/COBOL Setup ................................................. 21
Root Path ............................................................... 45
RTG Migrate .......................................................... 45
Rule Examples ....................................................... 68
Rules file ................................................................ 59
rules, XDD file schema59, 61, 62, 63, 64, 65, 66, 67, 69
<[Action]> do elements ...................................... 66
<[Condition]> when elements ............................ 64
<[Target]> action element .................................. 67
rules.xml ............................................................... 117
runitlockdetected option ....................................... 223
Runtime Configuration ........................................... 28
M
S
J
java.lang.UnsatisfiedLinkError ................................ 20
K
Key Benefits of c-treeRTG COBOL Edition .............. 3
keycheck option .................................................... 198
keycompress option ..............................199, 200, 201
L
-make .................................................................... 135
-makeimg .............................................................. 136
map option ............................................213, 214, 215
Sample Programs ................................................ 235
Samples and Utilities ........................................... 235
script, Create Script - Script Name ........................ 45
www.faircom.com
All Rights Reserved
249
Index
-segment ............................................................... 145
SET ENVIRONMENT ACUCOBOL-GT Verb ......... 11
SET ENVIRONMENT Verb .................................... 17
-setpath ................................................................. 146
Settings Elements ...................................31, 175, 183
Shared Memory for c-treeRTG ............................... 27
-sign ...................................................................... 147
sign convention ...................... 94, 147, 148, 151, 226
skiplock option ...................................................... 224
smartcopy option .................................................. 225
source base directory ............................................. 45
Source Code ......................................................... 109
Source Environment ............................................... 45
Source Files ............................................................ 45
Specifying c-tree as Indexed File Handler at Link
Time .................................................................... 15
Splitting an OCCURR ........................................... 107
SQL access ............................................................ 54
SQL Considerations.............................................. 101
SQL to COBOL ....................................................... 99
-sqlcheck ............................................................... 147
-sqlinfo .................................................................. 148
-sqlize ................................................................... 151
sqlize option .......................................................... 226
Sqlize Tutorial ....................................................... 104
SQLIZEEXAMPLE.CBL ................................104, 109
-sqllink ................................................................... 149
-sqlunlink ............................................................... 150
Step-by-Step Sqlizing Instructions........................ 104
Storing the XDD in the Data File ............................ 58
Structure Elements .........................................31, 175
Substitution Specifiers .......................................... 231
Support for Encrypting the Configuration File ........ 32
Suppress dash or replace with underscore .......... 166
Syntax for WITH DUPLICATES on RECORD
KEY ................................................................... 164
Utilities ................................................................. 235
ctutil, ctcbtran, xddgen, cttrnmod, ctmigra,
ctfileid ........................................................... 118
V
Variable-length fields mapped into LONGVAR*
SQL field ............................................................ 86
Viewing Sqlized Tables in c-treeACE SQL
Explorer .............................................................. 89
vutil ....................................................................... 121
W
warning option.............................................. 202, 209
WBTRV32.DLL ...................................................... 21
wildcard ................................................ 181, 182, 213
Wildcard file matching rules ................................. 182
Wildcard File Matching Rules .............................. 182
writethru option .................................................... 231
X
XDD Directives..................................................... 161
XDD File Schema .................................................. 69
XDD_CONV_NOERR and other XDDCHECK
errors ................................................................ 245
XDDCHECK Errors .............................................. 245
xddgen ................................................................. 160
xddgen Configuration File .................................... 164
xddgen now allows names larger than 31 chars . 165
xddgen Techniques ............................................. 106
XDDOPEN, XDDCHECK, XDDCLOSE ................. 11
-xfd2xdd ............................................................... 158
XFDRules file ......................................................... 59
XML configuration file .......................................... 175
T
-test ....................................................................... 152
The Samples Directory ......................................... 235
The SQL Challenge .............................................. 174
Tips for Advanced Sqlizing ................................... 104
transaction option ................................................. 229
Transaction Processing Notes.............................. 238
-tron ...................................................................... 153
Troubleshooting ..........................................9, 20, 239
Troubleshooting Data Conversion Errors ............... 87
Tutorial.sql ............................................................ 104
Type Mapping Table ............................................... 86
U
-uncompress ......................................................... 154
-unload .................................................................. 155
-unloadtext ............................................................ 156
-upgrade ............................................................... 157
Using Group Names ............................................. 106
Using the CALLFH Compiler Directive ................... 15
www.faircom.com
All Rights Reserved
250

c-treeRTG COBOL Edition

Transcription

Similar documents

Visual COBOL helps Trasmediterranea Acciona navigate to the Cloud

for COBOL

Contact no.(M):9780893349 jalandhar city

COBOL orientation for management, 1965

How to Install SQL Server 2008

Natural Language Understanding

Product Release Bulletin AccountMate 8.1 for SQL and Express July

CS 403: A Brief History of Programming Languages

Graphical database management solutions for HP NonStop SQL/MX

Web Application Hacking/Security 101

Mass SQL Injection for Malware Distribution