Command-Line Tools

Transcription

Command-Line Tools

Reference Guide
Command-Line Tools
Reference Guide
Command-Line Tools
Contents
1.
FairCom Command-Line Tools .......................................................................... 1
1.1
File Locations ........................................................................................................ 1
2.
Administrative Utilities - Client .......................................................................... 2
2.1
2.2
ctadmn - Server Administrator Utility ..................................................................... 2
ctcmpcif - IFIL-based Compact Utility .................................................................... 2
Updates in handling of security attributes ........................................................................... 3
2.3
2.4
ctdbpartidxent - Utility to Enable GUIx Key Count Optimization ............................ 4
ctdump - Dynamic Dump Utility ............................................................................. 5
Scripting a Dynamic Dump ................................................................................................. 6
2.5
2.6
2.7
2.8
2.9
2.10
ctfilbkif - File Block Utility ....................................................................................... 7
ctfileid - Update File IDs ........................................................................................ 9
ctpass - Password Utility ....................................................................................... 9
ctpathmigr - Change Internal Path Separators .................................................... 10
ctquiet - Quiesce c-treeACE Utility ...................................................................... 10
ctrbldif - IFIL-based Rebuild Utility....................................................................... 11
Option to set index's automatic segment attributes .......................................................... 12
Updates in handling of security attributes ......................................................................... 13
2.11
2.12
2.13
2.14
2.15
2.16
2.17
2.18
2.19
2.20
2.21
2.22
2.23
2.24
ctsqlcdb - c-treeACE SQL Database Maintenance Utility.................................... 14
ctsqlimp - SQL Import Utility ................................................................................ 14
ctsqlutl - c-treeSQL Maintenance Utility .............................................................. 16
ctstat - Statistics Monitoring Utility ....................................................................... 16
ctstop - Server Stop Utility ................................................................................... 18
ctsysm - Server Status Monitoring Utility ............................................................. 19
cttrap - Communications Trap Playback utility .................................................... 20
cttrap - TRAP_COMM Utility................................................................................ 21
cttrnmod - Change Transaction Mode Utility ....................................................... 23
dbdump - Data Unload Utility .............................................................................. 26
dbload - Data Load Utility .................................................................................... 27
dbschema - Schema Export Utility ...................................................................... 28
ISQL .................................................................................................................... 29
sa_admin - Command-line security administration utility .................................... 30
ADMINISTRATOR OPTIONS ........................................................................................... 31
USER OPTIONS ............................................................................................................... 31
GROUP OPTIONS ............................................................................................................ 33
FILE OPTIONS ................................................................................................................. 34
3.
Administrative Utilities - Standalone ............................................................... 36
www.faircom.com
All Rights Reserved
iii
FairCom Command-Line Tools
3.1
3.2
3.3
3.4
3.5
3.6
3.7
ctcfgset - Server Configuration File Encoding Utility ........................................... 36
ctcmdset - Configuration File Encoding Utility ..................................................... 37
ctcpvf - Master Password Verification File Utility ................................................. 37
ctfchk - File Checksum Utility .............................................................................. 38
cthghtrn - Displays the high-water mark for transactions .................................... 39
ctredirect - IFIL Update Utility for Redirected Filenames ..................................... 39
cttrnmod - Change Transaction Mode Utility ....................................................... 41
4.
Utilities - Client .................................................................................................. 45
4.1
4.2
4.3
4.4
4.5
ctinfo - ISAM File Info .......................................................................................... 45
ctixmg - Incremental ISAM / Resource sample ................................................... 46
ctsfex - Superfile Data Export Utility .................................................................... 47
ctvlqa - Variable-length quality assurance utility.................................................. 47
ISQL .................................................................................................................... 48
5.
Utilities - Low Level ........................................................................................... 49
5.1
5.2
5.3
5.4
5.5
5.6
5.7
5.8
5.9
5.10
5.11
5.12
5.13
5.14
5.15
5.16
5.17
5.18
5.19
ctalgn - Change Alignment .................................................................................. 49
CTCMPC - File compaction ................................................................................. 49
ctcnfg - System Configuration Example .............................................................. 50
CTCV43 - Convert V4.3 Data File to c-tree Format............................................. 50
ctcv67 - Extended File Conversion Utility ............................................................ 50
ctdidx - Create flat key file ................................................................................... 53
ctdmpidx - Index Dump Utility .............................................................................. 53
ctflat - Create c-treeACE file from a flat file ......................................................... 54
ctflvrfy - Index Verify Utility .................................................................................. 55
ctindx - Create index file from flat key file ............................................................ 57
ctpkey - Print key utility ........................................................................................ 58
ctpotp - Parameter to OTP conversion ................................................................ 58
ctptoi - Parameter to IFIL conversion .................................................................. 58
ctrbld - Parameter file rebuild utility ..................................................................... 59
ctsfil - Superfile contents ..................................................................................... 59
ctunf1 - File Reformatting Utility .......................................................................... 59
ctupdpad - Update the c-treeDB Pad Resource Utility ........................................ 61
ctvfyidx - Index Verify Utility................................................................................. 61
ctvfyfil - File Verify Utility...................................................................................... 62
6.
Utilities - Standalone ......................................................................................... 64
6.1
6.2
6.3
6.4
ct_ver - Display c-treeACE version that created file ............................................ 64
ctchkbin - Checking for affected tables ............................................................... 64
ctclntrn Utility - Clean Transaction Mark .............................................................. 65
ctcmpcif - IFIL-based Compact Utility .................................................................. 66
www.faircom.com
All Rights Reserved
iv
6.5
6.6
6.7
6.8
6.9
6.10
6.11
6.12
ctencrypt - Utility to Change Master Password.................................................... 70
ctfdmp - Forward Dump Utility ............................................................................. 72
ctfileid - Update File IDs ...................................................................................... 73
ctfixbin - Fixing Affected Tables........................................................................... 73
ctidmp - Examine Dump Files.............................................................................. 74
ctinfo - ISAM File Info .......................................................................................... 74
ctldmp - Transaction Log Dump .......................................................................... 75
ctrbldif - IFIL-based Rebuild Utility....................................................................... 75
Option to set index's automatic segment attributes .......................................................... 76
6.13
6.14
6.15
6.16
6.17
6.18
ctrdmp - Dynamic Dump Recovery or System Rollback...................................... 77
ctsbld - Superfile rebuild pre-pass ....................................................................... 78
ctsbldm - Rebuild Superfile Index Members ........................................................ 78
ctscmp - Superfile Compact Utility....................................................................... 79
ctsfex - Superfile Data Export Utility .................................................................... 80
ctsqlmgr - Migration Utility ................................................................................... 81
7.
Utilities for Stored Procedures, User-Defined Functions & Triggers ........... 82
7.1
7.2
7.3
7.4
dbschema – Option to dump SP, UDF, and triggers ........................................... 82
dbdeploy – Utility to deploy SP, UDF, and triggers ............................................. 82
Password Security ............................................................................................... 83
Requirements to Develop and Deploy (JDK, JRE) .............................................. 83
8.
Index ................................................................................................................... 85
www.faircom.com
All Rights Reserved
v
1.
The FairCom products ship with a wealth of utilities for developers
and administrators. This book documents the command-line tools
that are available with your product.
1.1
File Locations
The command-line tools are provided in the following folders:
All tools:
All command-line tools:
All administrative tools:
Client-side administrative tools
Administrative Utilities - Client (page 2)
Standalone administrative tools
Administrative Utilities - Standalone (page 36)
All other utilities:
Client-side utilities
Utilities - Client (page 45)
Low-level utilities
Utilities - Low Level (page 49)
Standalone utilities
Utilities - Standalone (page 64)
Note: The exact set of tools and utilities and their directory structure depends on the FairCom
product you have installed.
www.faircom.com
All Rights Reserved
1
2.
Administrative Utilities - Client
These utilities are intended for administrators. They are run from the client-side. They are located
in the following folder:
All tools:
tools\cmdline\admin\client
Low-level utilities
2.1
ctadmn - Server Administrator Utility
ctadmn [<AdminId> <AdminPassword> [ <filepassword>
[ <ServerName> ]]]]
Used by the Server Administrator to manage users, groups, and files.
See Also
 Administrator Utilities > c-treeACE Server Administrator Utility
(http://docs.faircom.com/doc/ctserver/8286.htm) in the c-tree Server Administrators Guide
2.2
ctcmpcif - IFIL-based Compact Utility
New Standalone Usage
# ctcmpcif DataFileName [-purge] [-updifil]
[-temppath=<temporary_path>] [-<sectors>]
www.faircom.com
All Rights Reserved
2
where:
 -purge - purge duplicate records.
 -updifil - update IFIL resources in the data file.
 -temppath=<temporary_path> - the temporary file directory. The default is the current
directory.
 -<sectors> - the sector size to use. The sector parameter is especially useful if you need to
adjust a file’s PAGE_SIZE to match the c-treeACE Server.
Client Side Usage
# ctcmpcif DataFileName [-purge] [-updifil] [<UserId>]
[<UserPassword> [<ServerName>]]
where
UserID, UserPassword, and ServerName are only needed for client versions of this utility.
FairCom recommends building this utility as a Single-user Standalone application.
ctcmpcif reads the IFIL structure from DataFileName and calls CompactIFileXtd() and
RebuildIFileXtd() to compact and rebuild DataFileName and its associated indices. If ctcmpcif
cannot extract the IFIL from the target file, it will ask for the name of another copy of the file from
which to extract the IFIL information.
Considerations
 Even without the -x8 option, some extended create block settings such as the huge file,
extended header, and 6-byte transaction number options, are always applied to new files.
 This option requires all associated index files that are referenced in the data file's IFIL
structure to exist, as the utilities use OpenIFile() to open the data file and all associated index
files to read the extended create block values.
 When an application calls the standalone version of the Xtd8 file compact or rebuild functions
(For example, CMPIFILX8() or RBLIFILX8() ), index files created by the compact or rebuild
no longer have the 6-byte transaction number attribute enabled if the specified extended
create block's x8mode field has the ctNO6BTRAN bit set.
Updates in handling of security attributes
In V10.3 and later, the ctrbldif utility assigns data file owner/group/permissions to index files and
ctcmpcif assigns original data file owner/group/permissions to compacted data/index files.
The rebuild and compact utilities now read the permission mask, owner, and group settings from
the original data file and after the rebuild or compact is completed, the utilities assign these same
attributes to the new files. It is desirable for the newly rebuilt or compacted files to preserve the
original security attributes as much as possible and the index file security attributes should match
the data file security attributes.
A command-line option has been added to the utilities to restore the previous security attribute
behavior. Use the -oldsec option to cause the rebuild and compact utilities to set the security
attributes as they did before this revision. For example:
www.faircom.com
All Rights Reserved
3
ctrbldif mark.dat -oldsec ADMIN ADMIN FAIRCOMS
The -oldsec option can be used if rebuild and compact are failing with error 455 (user does not
belong to group) if you delete an index then run the rebuild or compact utility on the data file using
a user account that does not belong to the group that is assigned to the data file.
Note: These changes only apply to the client and server versions of these utilities. Setting the
security attributes is not supported in standalone mode, so the standalone rebuild and compact
utilities behave as follows:
1) When the standalone mode rebuild utility creates new index files instead of reusing the new
index files (for example if the original index files have been deleted before running the rebuild
utility), the new index files are assigned a permission mask of zero (no restrictions on
permissions), and the owner and group are unassigned (empty).
2) The standalone mode compact utility always preserves the security attributes of the data file. If
the index files do not exist, the newly-created index files are assigned the same values as the
standalone rebuild does when it creates new index files.
2.3
ctdbpartidxent - Utility to Enable GUIx Key Count
Optimization
Enhancements to partitioned file query efficiency required changes to certain header bits of the
files. While these are default with newly created tables, existing tables with partitioned files will
need to have this bit enabled to take advantage of the new optimizations.
A command-line utility that can be used to enable the partition file global unique index (GUIx) key
count optimization for partitioned files. The usage is as follows:
usage: ctdbpartidxent -u <username> -p <password> -s <servername> -m on|off -d <dbname> -t <tblname>
Options
 -u <username> User name
 -p <password> User password
 -s <servername>
c-tree Server name
 -m on|off
(default=on)
Enable or disable the partition file GUIx key count optimization
 -d <dbname>
Database name (default=update all databases)
 -t <tblname>
Table name (default=update all tables)
Example
Enables optimization for all tables in the ctreeSQL database on server FAIRCOMS:
ctdbpartidxent -u ADMIN -p ADMIN -s FAIRCOMS -d ctreeSQL
The ctinfo utility has also been updated to display the file definition bits. To check if the GUIx key
count optimization is enabled, look for the DEF_MARK_PRTENT bit to be set, as shown below:
File Definition Mask Details
DEF_MASK_PRTENT : enhanced IDXENT for GUIx
www.faircom.com
All Rights Reserved
4
Note: ctdbpartidxent also attempts to rename partition files to ensure they are properly named
should a rebuild be required.
2.4
ctdump - Dynamic Dump Utility
The user may pass a User ID, Password, Dump Script name, and Server Name to a ctdump
utility, which schedules a dynamic dump. The syntax is as follows:
ctdump [adminuser adminpass] dumpscript [servername]
 adminuser: ADMIN group User ID
 adminpass: Administrator password
 dumpscript: Name of the dynamic dump script file on the server system. A path relative to
the server system may be included.
 servername: Optional server name.
For new options added in c-treeACE V11, see V11 Dynamic dump enhancements (page 6).
The following demonstrates example usage of this utility:
ctdump ADMIN ADMIN thescript FAIRCOMS
The following error codes are related to dynamic dump operations:
Error Name
Error Code
Explanation
FUNK_ERR
13
Cannot determine file type. Possibly a c-tree V4.3 file?
READ_ERR
36
Failed to read file, either a corrupted or non-tree file.
TCOL_ERR
537
Transaction log collision. Two sets of transaction logs in the same
directory?
FCPY_ERR
796
Immediate dump restore file copy failed.
DRST_ERR
797
Immediate dump restore failed.
See Also
 For a complete discussion of dynamic dumps, see Maintaining Database Integrity
(http://docs.faircom.com/doc/ctserver/8373.htm) in the c-treeACE Server Administrator's
Guide.
www.faircom.com
All Rights Reserved
5
Scripting a Dynamic Dump
In V11 and later, the Dynamic Dump can send a script to the server and receive a dump stream
and/or status messages from the server. The following capabilities are available for scripting a
dynamic dump:
1. When scheduling a dynamic dump, the client can send the dump script to the server. Prior to
V11, the only option was to create the dump script on the server beforehand and the client
passed the name of the existing dump script file to the server.
2. When running a dynamic dump, the client can request that status messages be sent to it
while the dump is performed and/or the dump stream file can also be sent to the client
process.
To use these options, call the function dyndmpsetopt() before calling dyndmp():
extern NINT dyndmpsetopt(NINT option,pVOID value);
The following are the supported options. All options are disabled by default.
 DDOPT_SENDSCRIPT - Send dump script to server. Set value to the script name, or set it to
NULL to disable this option. Example:
dyndmpsetopt(DDOPT_SENDSCRIPT, ""script.txt"");
 DDOPT_RECVSTREAM - Receive dump stream from server. Set value to YES to enable this
option or NO to disable this option. Example:
dyndmpsetopt(DDOPT_RECVSTREAM, (pVOID) YES);
 DDOPT_RECVSTATUS - Receive status messages from server. Set value to YES to enable
this option or NO to disable this option. Example:
dyndmpsetopt(DDOPT_RECVSTATUS, (pVOID) YES);
 DDOPT_SETCALLBK - Set callback function. Set value to the callback function pointer, or
set it to NULL to disable the use of the callback function. Example:
extern ctCONV NINT mycallback(pVOID pctx,pVOID pdata,NINT datalen,NINT
opcode);
dyndmpsetopt(DDOPT_SETCONTEXT, &mycallback);
 DDOPT_SETCONTEXT - Set callback function context pointer. Set value to the context
pointer that will be passed to the callback function. Example:
mystruct mycontext;
dyndmpsetopt(DDOPT_SETCONTEXT, &mycontext);
 DDOPT_SETBUFSIZ - Set communication buffer size. Set value to the buffer size to use.
Example:
dyndmpsetopt(DDOPT_SETBUFSIZ, (pVOID) 100000);
Notes:
1) The dump options remain in effect for all dynamic dumps performed by the current connection
until they are changed.
2) When the DDOPT_RECVSTREAM or DDOPT_RECVSTATUS options are used, the following
dynamic dump script options are ignored:
COPY_NONCTREE - Non-c-tree files cannot be copied.
DATE and TIME - No scheduling of dump for later time.
EXT_SIZE - Only one dump extent is created.
www.faircom.com
All Rights Reserved
6
FREQ - No repeat of dump.
SEGMENT - No segmenting of dump stream.
In V11 and later, the ctdump utility supports these features through command-line options:
usage: ctdump
[-s svn] [-u uid] [-p upw] [-t script] [-b bufsiz] [-n] [-c] [-o backup]
Options:

-s svn - c-tree Server name

-u uid - User name

-p upw - User password

-t - Dump script name

-b bufsiz - Use buffer size of bufsiz bytes

-c - Send dump script from client

-n - Send progress notifications to the client

-o backup_filename - Write dump stream from server to file on client
Example:
# ctdump -u ADMIN -p ADMIN -o backup.fcd -c -t script.txt -s FAIRCOMS -n
Results:
c-treeACE(tm) Version 11.1.0.46197(Build-150826) Dynamic Backup Utility
Copyright (C) 1992 - 2015 FairCom Corporation
ALL RIGHTS RESERVED.
Reading dump stream from server with buffer size of 100000
Start dump. Estimated dump size:
2691072
FAIRCOM.FCS
86% 100% [
2328576 of
2326528 bytes]
SYSLOGDT.FCS
89% 100% [
86016 of
81920 bytes]
SYSLOGIX.FCS
99% 100% [
266240 of
262144 bytes]
S0000000.FCS
100% 100% [
4096 of
128 bytes]
S0000001.FCS
100% 100% [
4096 of
128 bytes]
L0000001.FCS
100% 100% [
2048 of
679 bytes]
End dump.
Actual dump size:
2705408
Dynamic Dump has been successfully written to the file backup.fcd.
2.5
ctfilbkif - File Block Utility
ctfilbkif
ctfilblkif will block, or unblock a specified c-treeACE file. The default behavior is to block access
to the specified file. Pass the -u option to unblock a file.
Usage
ctfilblkif [-s server][-f filename][-u] {-p password|-a authfile}
-s: Server (default: FAIRCOMS@localhost)
www.faircom.com
All Rights Reserved
7
-f:
-u:
-a:
-p:
file name
unblock file
Authentication file name
Admin Password
See also
 ctquiet - Quiesce c-treeACE Utility (page 10)
www.faircom.com
All Rights Reserved
8
2.6
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 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).
2.7
ctpass - Password Utility
c-treeACE Server utility to allow users to change their password.
The following steps are required for a user to change the password associated with their own
User ID:
1. Run the utility program ctpass as any other program in the environment.
2. Enter your current User ID.
3. Enter the current password for your User ID, if you have one. (Maximum 63 characters.
Maximum nine characters for V9 and prior).
4. Continue by entering the current name of the c-treeACE Server (i.e., the default name or
another name, supplied in the c-treeACE Server configuration file).
5. Now change your password by entering the new password.
6. To be sure to enter the new password, you may be asked to enter it twice before it will be
accepted. If the same name is not entered both times, try again.
Note: Whenever input is requested, the user may enter a question mark (?) to receive HELP.
After the new password is entered and confirmed, a message saying your User ID password has
been successfully updated will be displayed. After being updated successfully, the new password
must be used with the User ID to log on to the c-treeACE Server.
Note: All users can change their own passwords. In addition, users who are members of the
ADMIN group can change the password of all accounts that are not members of the ADMIN
www.faircom.com
All Rights Reserved
9
group. Only the super ADMIN account (named ADMIN) can change a password for an account
that is a member of the ADMIN group.
2.8
ctpathmigr - Change Internal Path Separators
The ctpathmigr utility is used to change embedded path separators for c-treeACE SQL
databases when migrating between Unix and Windows platforms. This functionality was
previously available in the ctpath utility. This utility changes database and IFIL resource path
separators from the native format of the system where the utility is run (i.e., \ for Windows; / for
Unix) to the non-native format. It should be run before moving the files.
Syntax
ctpathmigr [-s <server>] [-u <user>] [-p <password>] [-d <database>]
Description
 ctpathmigr with command line arguments returns 0 when the execution detected no errors,
or a value different than 0 when errors were detected and the error messages are written to
the screen.
 If you omit the -d database switch, all databases in the session will be scanned.
 Command line options should start with a '-' or '/' character. Use a lowercase character for the
option (e.g., -s not -S).
 Command line switches may have optional spaces between the switch and the argument.
Example: -s FAIRCOMS or -sFAIRCOMS are the same.
 Command line options may be entered in any order.
2.9
ctquiet - Quiesce c-treeACE Utility
The ctquiet utility allows an administrator to quiet the server from a script. An interactive option is
available in the ctadmn utility.
Usage
ctquiet [-s server][-f][-u][-w command] {-p password|-a authfile}
 -s Server (default: FAIRCOMS@localhost)
 -f Full consistency - files are flushed to disk from cache (default: crash consistency - no
flush). See below.
 -u Unquiet server
 -w Execute command on successful quiet. Waits for SIGINT to unquiet server
 -a Authentication file name
 -p Admin Password
The -a authfile option takes as argument an encrypted settings file (using ctcmdset.exe) with the
plaintext form given as:
; User
USERID
; User
PASSWD
Id
ADMIN
Password
<pass>
www.faircom.com
All Rights Reserved
10
Note: This utility provides a -f option, which enables full consistency (also known as a "clean
quiesce") in which files are flushed to disk from cache. When this option is used, the system does
not require any files to be rebuilt.
The default is the -f option is off, which results in "crash consistency" (also known as a "dirty
quiesce"). The default means that transaction logs are required and, if present, the transaction
logs are used to get back into a clean state once recovery completes.
If files are NOT under transaction control, the -f option is strongly recommended, otherwise you
will have to do a rebuild to get the files back to a clean state.
A quiesced state allows a physical copy of files to be taken that can then be restored at a later
time. For systems that provide hardware-based snapshot features, this allows extremely fast
system backups to take place while maintaining full data integrity.
Notes
 When you quiesce the server, as long as the connection that quiesced the server remains
connected, all other connections are blocked. Only if that connection goes away do we allow
the ADMIN user to logon again and undo the quiesce.
 After the server is quiet and the ctquiet utility disconnects, one ADMIN connection is allowed
to reconnect. There is no prevention of a separate process connecting as ADMIN while the
server is in a quiet state and precluding the unquiet call.
 There is a subtle distinction between a "quiet" state, and a file blocked with the ctFILBLK()
call. While in the quiet state, files are not physically closed and cannot be moved or replaced
while in this mode. Compare this to a "blocked" state, where the file can be replaced, as the
OS file handle has been released.
 When the optional -w COMMAND switch is used, the behavior of ctquiet is modified to
perform as follows:
a. After successfully quieting the server, it makes a system call to execute COMMAND.
b. It remains connected and waits for SIGINT to unquiet the server. If ctquiet is killed before
receiving SIGINT, the server will remain in a quiet state until a new connection unquiets
the server.
 When connecting to a quieted server with the intent to remove the quiet state when the
original caller of ctquiet has disconnected you must now set the USERPRF_ADMSPCL bit.
2.10
ctrbldif - IFIL-based Rebuild Utility
Usage
A rebuild utility using the IFIL definitions stored in the header of a file:
ctrbldif DataFileName [ -x8 ] [ -purge ] [ -updifil ] [ -<sectors> ]
[ -temppath=<temporary_path> ] [ -sortmem=<n> ]
[ <UserId> ] [ <UserPassword> ] [ <ServerName> ]
Description
ctrbldif reads the IFIL structure from DataFileName and calls RebuildIFileXtd() to rebuild
DataFileName and its associated indices.
 -purge - Purge duplicate records.
www.faircom.com
All Rights Reserved
11
 -updifil - Update the IFIL resource within the data file.
 -sortmem=<N> - Use N KB of memory for sorting. This option can be used to increase the
rebuild speed for large files.
 -x8 - Use extended create blocks read from data and index files.
 -idxseg=<M>@<S> - If creating index, use M automatic segments of size S. Size is specified
in megabytes, or you can specify MB or GB as a suffix. For example: -idxseg=10@1GB
c-treeACE Standalone Options
 -temppath= - directory path, <temporary_path>, to create temporary sort and purged record
files. (This standalone option is the equivalent of the TMP_PATH server configuration option.)
The default location is the current directory.
 -<sectors> - sector size, <sectors>. (in multiples of 128). The sector parameter is especially
useful if you need to adjust a file’s PAGE_SIZE (index node size) to match the c-treeACE
Server. c-treeACE standalone models default to 16 sectors (2048 byte node size) while the
c-treeACE Server defaults to 64 sectors (8192 bytes).
c-treeACE Server Options
 <UserID> : client user name to logon to a c-treeACE Server.
 <UserPassword> : client user password to authenticate to a c-treeACE Server.
 <ServerName> : c-treeACE Server name for a client to connect.
Considerations
(for example, CMPIFILX8() or RBLIFILX8()), index files created by the compact or rebuild no
longer have the 6-byte transaction number attribute enabled if the specified extended create
block's x8mode field has the ctNO6BTRAN bit set.
 A rebuild or compact will fail with the new error code TFLN_ERR (943) when a client library
that supports the new rebuild or compact option format attempts to use this feature with a
c-treeACE Server that does not support this new format.
Option to set index's automatic segment attributes
If a segmented index file was deleted and rebuilt using the ctrbldif utility or the rebuild API
function, the new index file was not segmented. The index file's segment attributes, which are
stored in the index file, were lost when the index file was deleted.
Beginning with V10.3, an option is provided with the rebuild and compact utilities that causes
index files that are created by the utilities to be created using automatic segments of the specified
size and maximum. The option is:
-idxseg=M@S
www.faircom.com
All Rights Reserved
12
where M is the maximum number of segments and S is the segment size. S is interpreted as
megabytes by default. Two suffixes, MB and GB, are also supported. MB indicates that the value
is in megabytes and GB indicates that the value is in gigabytes.
Examples:
50 segments of 10 MB each:
ctrbldif test.dat -idxseg=50@10
ctrbldif test.dat -idxseg=100@300MB
20 segments of 3 GB each:
ctrbldif test.dat -idxseg=20@3GB
Note: If the index files exist, the -idxseg option has no effect. It is only when the rebuild or
compact utility creates new index files because the old index files do not exist that the -idxseg
option affects the automatic segment properties of the index files.
www.faircom.com
All Rights Reserved
13
2.11
ctsqlcdb - c-treeACE SQL Database Maintenance Utility
Usage
ctsqlcdb <command> <dbname> [<servername>]
Valid Commands:
 -add: Adds a reference to an existing database
 -create: Creates a new database
 -drop: Removes a reference to an existing database
 -exist: Returns 1 if database exists, 0 if not, 2 on error
 -list <servername>: Lists databases available from the server
 -create_preimage: Creates a preimage only database (supporting only atomicity; no
transaction logs for durability.)
Or the following command syntax copies an existing database and adds a reference to the new
copy:
 -copy <dbname> <newname> [<servername>]
-copy also includes non c-tree files when present in the database directory area.
where:
• <dbname> is the database name, and
• <servername> is the optional c-treeACE SQL name.
The -copy command supports virtual tables (called "Multi Record Tables" or "MRT tables").
2.12
ctsqlimp - SQL Import Utility
ctsqlimp is used as follows (after creating the database file):
ctsqlimp <filename> [-d database] [-s server] [-u userid] [-a password]
[-n symbolic] [-o userid]
[-i] [-r] [-k] [-c] [-x] [-p|-P] [-z] [-g] [-b|-B] [-j]
[-w script] [-m idxname] [-e xmlfile] [-f s|z|sz] [-l size] [-q prefix] [-h]
 <filename>: data file name/path (relative paths to c-treeACE SQL directory)
 -d database : database name (default: ctreeSQL)
www.faircom.com
All Rights Reserved
14
 -s server: c-treeACE SQL Server name (default: FAIRCOMS)
 -u userid: userid for logging into c-treeACE SQL
 -a password: password for authorization
 -n symbolic: set SQL table name to symbolic symbolic
 -o userid: set owner of table to userid
 -i: non interactive mode: ignore errors and continue
 -r: remove existing linked table (file is not deleted)
 -k: skip fields that don't comply with conventional identifiers rules
 -c: allow table names not complying with conventional identifiers rules
 -x: skip indices
 -p: promote unsigned integer to greater signed type
 -P: promote unsigned types to greater signed type and set check for fitting value
 -z: allow indices with missing string terminator in key segments
 -g: ignore existing index name in IFIL resource
 -b: (lowercase) switch grants all permissions on the table to the public
 -B: (uppercase) switch grants read-only permissions on the table to the public
Note: If both -B and -b are specified, the read-only setting takes precedence. Notice that the
owner of the table and the DBA have all the permissions.
This introduces a change in behavior for existing applications because this switch is
now-case sensitive.
 -j: non-interactive relink of existing table
 -w script: write CREATE statements into script file script instead of importing the table
 -m idxname: set index idxname as primary key
 -e xmlfile: get DODA definitions from external XML file xmlfile
 -f s | z | sz: force string padding to (s)paces (z)eroes or (sz)spaces zero terminated
 -l size: specify LONGVAR* field size threshold
 -q prefix: prefix SQL table name with prefix (when the -q option is combined with the symbolic
table name option, -n, the prefix is prepended to the symbolic name instead to the table
name)
 -h: display usage help
Note: The parameters are case-sensitive. By default they are lower case unless otherwise stated.
www.faircom.com
All Rights Reserved
15
2.13
ctsqlutl - c-treeSQL Maintenance Utility
The c-treeSQL Maintenance Utility, ctsqlutl, is a general purpose program to perform
maintenance on the c-treeSQL Server. At this time only the "rename column" (-rencol ) command
has been implemented. Please refer to the V8.14 Update Guide, Section 14.7, for complete
details.
Syntax
The ctsqlutl utility syntax is as follows:
ctsqlutl [options] -rencol table_name column newcolumn
 table_name: Name of the table
 column: Current name of the column you are going to rename
 newcolumn: Name of the columns after renaming
Options
 -o owner_name: Owner of table
 -d database_name: Database name (default: ctreeSQL)
 -s server_name: c-treeSQL Server name (default: FAIRCOMS)
 -u userid: userid for logging onto the c-treeSQL Server
 -a password: Password for authentication
 -h: Display usage help
2.14
ctstat - Statistics Monitoring Utility
The c-treeACE Statistics Utility, ctstat, is a client utility used to display statistics collected by
c-treeACE. ctstat, provides valuable real time monitoring of critical c-treeACE operations.
Usage
# ctstat
report_type [-s svn] [-u uid] [-p upw]
[-i int [cnt]] [-h frq] [-d] [-m] [-t]
Reports:
-vas
Admin-System Report
-vts
Tivoli-System Report
-vaf file...
Admin-File Report
-vtf file...
Tivoli-File Report
-vau user...
Admin-User Report by User Name
-vau handle...
Admin-User Report by User Handle
-vah handle...
Admin-User Report by Connection Handle
-vat
Admin-Transaction Report
www.faircom.com
All Rights Reserved
16
-var
Admin-Replication Reader Report
-func
Function Timing Report
-funcfile
Function Timing By File Report
-userinfo
User Report with stats from USERINFO() function
-isam
ISAM Activity Report
-sql
SQL Activity Report
-sqlidx
Shows index scan statistics
-sqlcache
Shows SQL cache information
-text
System Activity Report, Write System Snapshot to SNAPSHOT.FCS.
-file [csv]
File Activity Report
-iotime on | off
Turn disk I/O call timing on or off
-wrktime on |
off | reset
Turn function call timing on or off or reset the function-timing statistics
-mf logfile
Log all memory allocations to the specified file
-ma logfile
Log aggregate memory allocations to the specified file
-mr min,max
Log only memory allocations in the range min,max
-ms
Output memory allocation statistics
-mu
Unload module debug symbols
-filelocks
datafile
List all locks on a data file
-filelocks file
[N]
List all locks on a data file. Displays the Nth key. See -filelocks Notes below.
-userlocks user
List all locks held by a user. See -userlocks Notes below.
Options:
-s svn
c-treeACE Server name
-u uid
User name
-p upw
User password
-i int [cnt]
Pause int seconds for optional cnt times.
In V11 and later, standard output is flushed after the interval determined by -i
so that output is written to the file immediately. This better handles cases
where output is redirected to a file.
-h frq
Print a description header every frq outputs
-d
Show cache stats as delta
-m
Show memory file stats when using -vaf report. The following additional
statistics are output:
• phyrec - Last byte offset of file for non-memory file or current memory in
use for memory file.
• mhghbyt - Largest amount of memory used for memory file since file was
created.
• memcnt - Current number of memory records.
• hghcnt - Largest number of memory records since file was created.
www.faircom.com
All Rights Reserved
17
-t
Output timestamp with header.
-filelocks Notes
The -filelocks option lists all locks on a data file and, optionally, displays the Nth key. The lock
offset and the associated keys are not read at the same time. Since we are reading records
locked by other users to generate the key, there is no guaranteed relationship between the lock
and the displayed key. The following are possible scenarios:
1. The displayed key is from before or after any changes made by the lock holder.
2. The locked offset no longer holds a valid record (it has been deleted, or updated and moved).
3. The locked offset could have been locked/modified/unlocked more than once between the
time the lock offset was acquired and the time the record is read, so the offset could hold an
entirely different record than what was originally locked.
The -filelocks file [key] command supports c-tree's standard wildcard filename matching for the
specified file, allowing locks from multiple files to be displayed. The standard wildcards (used by
ctsrvr.cfg keywords such as MEMORY_FILE and REPLICATE, etc) are:
* - Multi-character match
? - Single-character match
^ - Negation (must be first character)
-userlocks Notes
For the -userlocks report:
 If UserID is a number, it is interpreted as a task ID.
 If UserID is a string, it is interpreted as a name, and information on locks held by each task ID
with a matching name is returned.
Because the -userlocks report may generate a large number of server calls (for each task ID and
file), the -userlocks report interval may be increased up to 60 seconds, depending on the number
of matching users and files involved.
See Also
 ctstat - Statistics Utility (http://docs.faircom.com/doc/ctserver/52856.htm) in the c-tree Server
Administrator's Guide
2.15
ctstop - Server Stop Utility
Usage
ctstop [ -auto ] [<ServerName> <AdminId> <AdminPassword>]
This utility shuts down a c-treeACE Server.
Passing the -auto switch to ctstop without specifying a ServerName, Password, or AdminID
shuts down a c-treeACE Server with the defaults shown below:
ctstop -AUTO FAIRCOMS ADMIN ADMIN
www.faircom.com
All Rights Reserved
18
The ctstop utility supports passing in ServerName, Password, and AdminID when the -auto
switch is used.
The optional delay value is the number of seconds to wait before shutting down, with a default of
no delay.
2.16
ctsysm - Server Status Monitoring Utility
The c-treeACE Server status monitoring utility, ctsysm, facilitates the monitoring of error,
warning, and informational messages logged to the server status log, CTSTATUS.FCS, by the
c-treeACE Server. Using this utility, the c-treeACE Server status log can be monitored by an
automated external process such as the Tivoli monitoring system from IBM.
To use the ctsysm utility, the c-treeACE Server must be configured to log messages to the
system log. This can be achieved by adding the following keyword to the server's configuration
file:
SYSLOG CTSTATUS
With this keyword in place, the server logs each entry in the CTSTATUS.FCS file to the system
log files (SYSLOGDT.FCS and SYSLOGIX.FCS).
The utility can read the system log from the beginning each time it starts up, or it can save its
current position and start again from that set position by specifying the -f command line option.
The following is the supported command line usage of the c-treeACE Server Status Monitoring
Utility:
ctsysm [-s svn] [-u uid] [-p upw] [-r rpt] [-c cfg] [-f fil] [-l log]
 -s svn - c-treeACE Server name
 -u uid - user name
 -p upw - user password
 -r rpt - repeat interval in seconds (for example, -r 1 is a one-second delay before checking
for new messages)
 -c cfg - config file
 -f fil - save/restore state to file
 -l log - status log name (SYSLOGDT.FCS)

-e - direct ctsysm error messages to standard output in the same format as messages
read from the server status log
Example
The following command causes ctsysm to monitor the c-treeACE Server system log for the
server FAIRCOMS (-s FAIRCOMS) for status messages, checking for new messages every
second (-r 1), saving the position of the last entry read to the file ctsysm.log (-f ctsysm.log).
ctsysm -s FAIRCOMS -u ADMIN -p ADMIN -r 1 -c ctsysm.cfg -f ctsysm.log
The ctsysm utility outputs messages in the following format:
<timestamp> <code> <subsystem> <action> <text>
Sample output from the utility is shown below (each message is output as a single line but is
shown split into two lines here):
www.faircom.com
All Rights Reserved
19
Thu Jul 29 16:44:04 2004 I0455 STUP NONE
Alternative server name... FAIRCOMS
Compatibility bit maps: 00000000 00002000x
Diagnostic bit maps: 00000000 00000000x
64-bit File Address Support
6 Byte Transaction Numbers
NOWAIT usrsema enabled
- User# 01
- User# 01
- User# 01
- User# 01
- User# 01
- User# 01
Note: When the repeat (-r) option is used, the utility can be stopped by sending it a SIGINT
signal.
See Also
 c-treeACE Server Status Monitoring Utility, ctsysm
(http://docs.faircom.com/doc/ctserver/34515.htm) in the c-tree Server Administrator's Guide
2.17
cttrap - Communications Trap Playback utility
Usage
cttrap <Trap Comm Log File Name> [-p <password_file>][-x] [<Server>]
Where:
 <TrapCommLogFileName> - the name of the file to be played back.
 <ServerName> - the optional name of the server.
 -p <password_file> - use a text file containing a list of user names and passwords, one per
line (see Using a Password File, below).
 -x - skip serialization. cttrap serializes all the recorded operations and enforces the original
call ordering when allowing multiple client threads to replay the original operation. The -x
option allows for faster replay, although it increases the likelihood of causing errors or
differences in the final state of the data that did not exist in the original.
Description
cttrap is a multi-threaded client application that "plays back" a TRAP_COMM log file. Whenever
a multi-threaded Client library is created, cttrap will also be generated. The default TRAP_COMM
file name is TRAPCOMM.FCS.
When the DIAGNOSTICS TRAP_COMM keyword is active, the trap file, TRAPCOMM.FCS, is
created in the server directory by default. To prepend a path onto the trap file name (to route it to
a separate disk or directory), add an entry of the form DIAGNOSTIC_STR <trap file path>.
For example, if the trap file is located in /bigdisk/TRAPCOMM.FCS, the configuration file needs to
contain the following:
DIAGNOSTIC_STR /bigdisk/
Using a Password File
To allow cttrap to connect to a password-protected server when reading from a
TRAPCOMM.FCS file, use the -p <password_file> option to specify the name of a text file
www.faircom.com
All Rights Reserved
20
containing a list of user names and passwords, one per line. For example, the file pass.txt might
contain the entries:
ADMIN ADMIN
myusername mypswd
Then cttrap can be run as follows:
cttrap TRAPCOMM.FCS -p pass.txt FAIRCOMS
The passwords must match the passwords on the server where the playback occurs, not
necessarily where the playback was recorded.
Up to 16 user user name/password entries can be specified in the cttrap password file. If you
wish to support more entries, change #define MAXUPW in cttrap.c and recompile the utility.
2.18
cttrap - TRAP_COMM Utility
The DIAGNOSTICS TRAP_COMM Server keyword allows developers to ‘record’ the communication
traffic coming in to a Server and play it back with the cttrap utility.
DIAGNOSTICS TRAP_COMM
When activated, the DIAGNOSTICS TRAP_COMM keyword instructs the Faircom Server to log
incoming communications packets to TRAPCOMM.FCS prior to execution. This log can be
played back using the cttrap utility and a debug Server to observe the results of the client
requests, allowing the developer to exactly duplicate and repeat client activities.
cttrap Utility
Usage
cttrap <Trap Comm Log File Name> [-p <password_file>][-x] [<Server>]
Where:
 <TrapCommLogFileName> - the name of the file to be played back.
 <ServerName> - the optional name of the server.
 -p <password_file> - use a text file containing a list of user names and passwords, one per
line (see Using a Password File, below).
 -x - skip serialization. cttrap serializes all the recorded operations and enforces the original
call ordering when allowing multiple client threads to replay the original operation. The -x
option allows for faster replay, although it increases the likelihood of causing errors or
differences in the final state of the data that did not exist in the original.
Description
cttrap is a multi-threaded client application that "plays back" a TRAP_COMM log file. Whenever
a multi-threaded Client library is created, cttrap will also be generated. The default TRAP_COMM
file name is TRAPCOMM.FCS.
When the DIAGNOSTICS TRAP_COMM keyword is active, the trap file, TRAPCOMM.FCS, is
created in the server directory by default. To prepend a path onto the trap file name (to route it to
a separate disk or directory), add an entry of the form DIAGNOSTIC_STR <trap file path>.
www.faircom.com
All Rights Reserved
21
For example, if the trap file is located in /bigdisk/TRAPCOMM.FCS, the configuration file needs to
contain the following:
DIAGNOSTIC_STR /bigdisk/
Using a Password File
To allow cttrap to connect to a password-protected server when reading from a
TRAPCOMM.FCS file, use the -p <password_file> option to specify the name of a text file
containing a list of user names and passwords, one per line. For example, the file pass.txt might
contain the entries:
ADMIN ADMIN
myusername mypswd
Then cttrap can be run as follows:
cttrap TRAPCOMM.FCS -p pass.txt FAIRCOMS
The passwords must match the passwords on the server where the playback occurs, not
necessarily where the playback was recorded.
Up to 16 user user name/password entries can be specified in the cttrap password file. If you
wish to support more entries, change #define MAXUPW in cttrap.c and recompile the utility.
www.faircom.com
All Rights Reserved
22
2.19
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
23
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
www.faircom.com
All Rights Reserved
24
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
ctTRNLOG
0x8032
www.faircom.com
All Rights Reserved
25
Note: If cttrnmod is used to disable full transaction logging for a file, it also disables replication
for that file.
2.20
dbdump - Data Unload Utility
The dbdump utility writes the data in a database to a file. The format of the exported data is
specified by the record description given in an input command file.
The dbdump command accepts the commands file name, the database name and a command
option.
Syntax
dbdump -f commands_file [-u user_name] [-a password] [-n] [-z] [-p] [-l] database_name
Options
 -f commands_file - Specifies the file containing dbdump commands.
 -u user_name - The user name c-treeSQL uses to connect to the database. If omitted, the
default value depends on the environment. (On UNIX, the value of the DH_USER
environment variable specifies the default user name. If DH_USER is not set, the value of the
USER environment variable specifies the default user name.)
 -a password - The password c-treeSQL uses to connect to the database. If omitted, the
default value depends on the environment. (On UNIX, the value of the DH_PASSWD
environment variable specifies the default password.)
 -n - Parse the commands file and display errors, if any, without exporting data. If the
parsing is successful, the following message displays on stdout:
No errors in the commands file.
 -z (10.3 and later) - The number of records to fetch per call is controlled by the -z switch.
To be consistent with the switch of dbload, it defaults to 1.
 -l (10.3 and later) - The -l switch controls the progress output frequency in terms of record
reads (the output is generated whenever the number of record reads since the last output
becomes greater than or equal to the specified value).
 -p (10.3 and later) - The dbdump -p command-line switch activates the new query
passthru mechanism, which does not perform any major change in the query. When this
switch is in use, dbdump interprets the query in the command file, converts it to lowercase,
and wraps everything that is considered an identifier with double-quotes. This can cause a
syntax error if the command file contains functions. For example, consider the following
statement:
SELECT RTRIM(cm_custnumb),...
The default behavior of dbdump results in the following statement, which would cause a
syntax error:
select "rtrim" ( "cm_custnumb" ) ,...
Using the dbdump -p switch results in this statement, which does not cause an error:
select rtrim ( cm_custnumb ) ,...
 database_name - Name of the database.
www.faircom.com
All Rights Reserved
26
See Also
 Data Unload Utility: dbdump (http://docs.faircom.com/doc/isql/32623.htm) in the c-treeSQL
ISQL Tools and Reference Guide
2.21
dbload - Data Load Utility
The dbload utility loads records from an input data file into tables of a database. The format of
the data file is specified by a record description given in an input commands file.
The dbload command does not directly specify an input file, but instead names a commands file
that in turn specifies data input files. The dbload command accepts the commands file name, the
database name, and a list of command options.
Syntax
dbload -f commands_file [ options ] database_name
 -f commands_file - Specifies the file containing dbload commands.
 options - One or more of the options as described below
 database_name - Name of the database.
Options
 -u user_name - The user name c-treeSQL uses to connect to the database. If omitted, the
default value depends on the environment. (On UNIX, the value of the DH_USER
environment variable specifies the default user name. If DH_USER is not set, the value of the
USER environment variable specifies the default user name.)
 -a password - The password c-treeSQL uses to connect to the database. If omitted, the
default value depends on the environment. (On UNIX, the value of the DH_PASSWD
environment variable specifies the default password.)
 -z maximum multiple inserts - The maximum number of records to be inserted at one time
in each bulk insert (used to improve performance)
 -l logfile - Specifies the file into which the error logging is done. stderr is the default.
dbload also writes statistics to the file:
• Number of records read
• Number of records skipped
• Number of records loaded
• Number of records rejected
 -b badfile - The file into which the bad rows that were not loaded, are written. By default
badfile is put in the current directory.
 -c commit_frequency - Store the specified number of records before committing the
transaction. The default frequency is 100 records.
 -e maxerrs - The maximum number of tolerable errors. The default number is 50 errors.
 -s skipcount - Skip the specified number of rows in the first data file. If multiple files are
specified, the rows are skipped only in the first file. The default number is zero rows.
 -m maxrows - Stop storing rows at the specified number.
www.faircom.com
All Rights Reserved
27
 -n - Parse the commands file and display errors, if any, without doing the database load. If
the parsing is successful, the following message displays on stdout: "No errors in the
commands file."
See Also
 Data Load Utility: dbload (http://docs.faircom.com/doc/isql/32580.htm) in the c-treeSQL ISQL
Tools and Reference Guide
2.22
dbschema - Schema Export Utility
The dbschema utility generates c-treeACE SQL statements to recreate the specified database
elements and data.
The c-treeACE SQL utility, dbschema, recreates specified database elements and data.
Syntax
dbschema [
[
[
[
[
-h ] [ -d ] [-u user_name ] [-a password ] [ -o outfile ]
-p [ user_name.]procedure_name [ , ... ] ]
-t [ user_name.]table_name [ , ... ] ]
-T [ user_name.]trigger_name [ , ... ] ]
database_name ]
Description
Generates c-treeSQL statements to recreate the specified database elements and data. If the
dbschema statement omits all arguments, it displays definitions for all elements (tables, views,
indexes, procedures, and triggers) for the default database on the screen.
Options
 -h - Displays brief online help of dbschema syntax and options.
 -d - In conjunction with the -t option, specifies that dbschema generates c-treeSQL
INSERT statements for data in the tables, in addition to CREATE statements. The output of
the dbschema command invoked with the -d option can be directed to a command file and
executed in interactive c-treeSQL to duplicate and load table definitions.
 -u user_name - The user name c-treeSQL uses to connect to the database. c-treeSQL
verifies the user name against a corresponding password before it connects to the database.
If omitted, the default value depends on the environment. (On UNIX, the value of the
DH_USER environment variable specifies the default user name. If DH_USER is not set, the
value of the USER environment variable specifies the default user name.)
 -a password - The password c-treeSQL uses to connect to the database. c-treeSQL
verifies the password against a corresponding user name before it connects to the database.
If omitted, the default value depends on the environment. (On UNIX, the value of the
DH_PASSWD environment variable specifies the default password.)
 -o outfile - Redirects the output to the specified file. The default is standard output.
www.faircom.com
All Rights Reserved
28
 -t [ user_name.]table_name [ , ... ] - A comma-separated list of tables and views for which
definitions should be generated. Specify a list of specific tables, or use the % to generate
definitions for all tables.
Note: With the -t option, the % character is not a true wildcard character. It substitutes for the
entire table_name argument and cannot be used for pattern matching within in a character
string. This differs from the behavior of the % in the -p and -T options.
By default, dbschema generates definitions for tables owned by the current user. Use the
optional user_name qualifier to specify a table owned by a different user.
 -p [ user_name.]procedure_name [ , ... ] - A comma-separated list of stored procedures for
which definitions should be generated. The table names in the list can include the ‘%’ and
underscore, ‘ _ ’, characters, which provide pattern-matching semantics:
• The ‘%’ matches zero or more characters in the procedure name
• The underscore ‘ _ ’ matches a single character in the procedure name
By default, dbschema generates definitions for procedures owned by the current user. Use
the optional user_name qualifier to specify a procedure owned by a different user.
 -T [ user_name.]trigger_name [ , ... ] - A comma-separated list of triggers for which
definitions should be generated. The table names in the list can include the ‘%’ and
underscore ‘ _ ’ characters, which provide pattern-matching semantics:
• The ‘%’ matches zero or more characters in the trigger name
• The underscore ‘ _ ’ character matches a single character in the trigger name
By default, dbschema generates definitions for triggers owned by the current user. Use the
optional user_name qualifier to specify a trigger owned by a different user.
 database_name - The database for which dbschema should generate definitions. If you
omit database_name, dbschema uses the default database, if specified. (How you define the
default database varies between operating systems. On UNIX, the value of the DB_NAME
environment variable specifies the default database.)
See Also
 Schema Export Utility: dbschema (http://www.faircom.com/doc/isql/32653.htm) in c-treeSQL
ISQL Tools and Reference Guide
2.23
ISQL
The c-treeACE SQL Interactive SQL utility (ISQL) provides an industry-standard "command
processing" interface to the c-treeACE SQL Database Engine.
FairCom offers two separate implementations of Interactive SQL:
1. A command-line version (isql.exe or isql). This utility is designed as a command-line tool
and can be placed in job streams.
2. A GUI tool version within the Windows program c-treeACE SQL Explorer.
Either implementation allows you to issue SQL statements directly from a command prompt for
immediate displayed results. You can use Interactive SQL to:
 Learn how SQL statements work;
www.faircom.com
All Rights Reserved
29
 Test and prototype SQL statements to be embedded in programs;
 Modify an existing database with data definition statements;
 Perform ad-hoc queries and generate formatted reports with special ISQL formatting
statements;
 Run existing SQL scripts.
With few exceptions, you can issue any SQL statement in ISQL that can be embedded in a
program, including CREATE, SELECT, and GRANT statements. Interactive SQL includes an
online help facility with syntax and descriptions of the supported statements.
See Also
 c-treeSQL ISQL Tools and Reference Guide
(http://docs.faircom.com/doc/isql/#cover.htm)
2.24
sa_admin - Command-line security administration utility
The command-line version of the system administrator program, sa_admin, can be used to
perform many user operations directly from shell scripts.
sa_admin [-a<adminuserid>] [-p<adminpassword>]
[-f<filepassword>] [-s<servername>] <option>
option is one of the following:
Options Users
 -oua
Add a user account
 -oud
Change user account description
 -oue
Change user account extended settings
 -oug
Add a user to a group
 -oul
List user accounts
 -oum
Change user account memory limit
 -oup
Change user account password
 -our
Delete a user account
 -ous
Show user account information
 -oux
Remove a user from a group
Options Group
 -oga
Add a group
 -ogd
Change group description
 -ogl
List groups
 -ogm
Change group memory limit
 -ogr
Delete a group
 -ogs
Show group information
Options File
 -ofg
Change file group
www.faircom.com
All Rights Reserved
30
 -ofl
List files matching filename
 -ofo
Change file owner
 -ofp
Change file password
 -ofs
Change file permissions
Wildcard specifiers with sa_admin
sa_admin, -ofp, -ofs, -ofg, and -ofo options support specifying filenames with wildcard
characters. When one of these options specifies a filename that includes ? or * characters, the
utility retrieves a list of files matching the filename wildcard specifier and executes the specified
command for each file.
Retrieve a List of Filenames from the server with sa_admin
-ofl (list files) is used to list the files on the c-treeACE Server system matching the specified
filename including wildcard characters.
sa_admin Support for Encrypted Password Files
The sa_admin utility supports the use of an encrypted password file. Encrypted password files
are created with the ctcmdset utility and keep user IDs and passwords from plain view within
script files. An encrypted password file name is specified using the command-line option:
-1 <filename>
ADMINISTRATOR OPTIONS
 -a
System administrator User ID.
 -p
System administrator password.
 -f
Optional server system file password.
 -s
Optional server name.
Note: There is no space between the switch and its parameter.
USER OPTIONS
The following options, all beginning with -ou, allow changes to user information. Additional group
and file options are described below.
Note: To use any optional entry, you must use all the previous entries even if they would
otherwise be optional. For example, to add a user with the -oua option and specify a group, you
must also enter the userid, desc, and password.
Option User Add
-oua <userid> [-d <desc>] [-w <password>] [-g <group>] [-m <memory>[<rule>]]
[-b <begdat>] [-e <enddat>] [-l <loglimit>] [-r <rsmlogon>] [-t <mstlogon>]
 userid: User id (required)
 -d desc: Optional user description
 -w password: Optional user password
www.faircom.com
All Rights Reserved
31
 -g group: Optional user group
 -m memory: Optional user memory limit.
• rule: Optional user memory rule. Used only with memory. The optional <rule> is A for
absolute, D for default, or G for guideline (example -m 10485760a specifies an absolute
memory limit of 10 MB). NULL for Default.
 -b begdat: Optional starting validity date. Specify as mm/dd/yyyy. NULL for Default.
 -e enddat: Optional ending validity date. Specify as mm/dd/yyyy. NULL for Default.
 -l loglimit: Optional maximum invalid logon attempts. NULL for Default.
 -r rsmlogon is the logon block period in minutes. Specifying a value of “block” (e.g., -r block)
blocks the account indefinitely (until it is unblocked by an administrator, and specifying a
value of “unblock” (e.g., -r unblock) unblocks the account immediately.
 -t mstlogon is the interval in minutes during the user must logon at least once, otherwise the
account is blocked.
Option User Remove
-our userid
Option User List
-oul
Option User Change Password
-oup userid password
 password: New password (required)
Option User Add user to Group
-oug userid group
 group: Group name (required)
Option User (group) Extract - Remove a user from a group.
-oux userid group
 group: Group name (required)
Option User Change Description
-oud userid desc
 desc: New user description
Option User Memory
-oum userid memory rule
 memory: New memory limit. This can be a number of bytes or ‘D’ for default or left NULL for
no limit
www.faircom.com
All Rights Reserved
32
 rule: Optional user memory rule. Used only with memory. This may be ‘A’ for Absolute, ‘G’
for Guideline, ‘D’ for Default, or NULL for Default
Option User Change Extended Settings
-oue <userid> [-b <begdat>] [-e <enddat>] [-l <loglimit>] [-r <rsmlogon>] [-t <mstlogon>]
 -b begdat: Optional starting validity date. Specify as mm/dd/yyyy. NULL for Default
 -e enddat: Optional ending validity date. Specify as mm/dd/yyyy. NULL for Default
 -l loglimit: Optional maximum invalid logon attempts. 0 for Default. -1 to disable invalid logon
check.
 -t mstlogon: Optional must logon period, e.g., how often the user must log on to remain
active. The interval in minutes during the user must logon at least once, otherwise the
account is blocked. Specify as number of minutes. NULL for Default. -1 to disable must logon
period.
 -r rsmlogon: Optional logon timeout remaining. If a user has been denied access to the
c-treeACE Server due to excessive invalid logon attempts, you can adjust the remaining user
lockout time here. Specify as number of minutes. NULL to leave unchanged. Specifying a
value of “block” (e.g., -r block) blocks the account indefinitely (until it is unblocked by an
administrator), and specifying a value of “unblock” (e.g., -r unblock) unblocks the account
immediately.
Option User Show
-ous userid
GROUP OPTIONS
The following options, all beginning with -og, allow changes to group information. Additional user
and file options are described elsewhere.
Note: To use any optional entry, you must use all the previous entries. For example, to specify a
rule when adding a group with the -oga option, you must also enter the desc and memory options
for the group.
Option Group Add
-oga <groupid> [-d <desc>] [-m <memory>][<rule>]]
 groupid: Group id (required)
 -d desc: Optional group description
 memory is the memory limit and the optional <rule> is A for absolute, D for default, or G for
guideline (example -m 10485760a specifies an absolute memory limit of 10 MB).
Option Group Remove
-ogr groupid
www.faircom.com
All Rights Reserved
33
Option Groups List
-ogl
Option Group Change Description
-ogd groupid desc
 desc: New group description
Option Group Memory
-ogm groupid [-m <memory>[<rule>]]
 -m memory: New memory limit. memory is the memory limit
• <rule> (optional) is A for absolute, D for default, or G for guideline (example -m
10485760a specifies an absolute memory limit of 10 MB).
Option Group Show
-ogs groupid
FILE OPTIONS
The following options, all beginning with -of, allow changes to file information. Additional user and
group options are described elsewhere.
Option File Password
-ofp filename password
 filename: File name (required)
 password: File password (required)
Option File Security (permissions)
-ofs <filename> <permission> ...
-ofs +|-<permission> ...
 permission: File permission mask.
To set a permission, set the byte at the corresponding offset to a value of ‘+’.
To reset a specified permission, set the corresponding byte to ‘-’.
For example, the string “+++++-----+++++” sets all OWNER and WORLD permissions, and
clears all GROUP permissions.
This field is interpreted as a 15-byte permission mask containing owner, group, and world
permissions:
(offset)
0 1 2 3 4
----OWNER---r w f d p
r = Read
5 6 7 8 9
----GROUP---r w f d p
w = Write
10 11 12 13 14
-----WORLD---r w f d p
f = define
d = Delete
p = noPass
 permission can also be one of the following:
www.faircom.com
All Rights Reserved
34
ownerall, ownerread, ownerwrite, ownerdefine, ownerdelete, ownernopass,
groupall, groupread, groupwrite, groupdefine, groupdelete, groupnopass,
worldall, worldread, worldwrite, worlddefine, worlddelete, worldnopass
Options are evaluated left to right. For example, specifying -groupwrite +groupwrite has the
effect of adding the groupwrite permission, and specifying +worldall -worldread turns on all
world permissions except read permission.
Option File Group
-ofg filename groupid
 groupid: File group id (required)
Option File Owner
-ofo filename owner
 owner: File owner (required)
Examples of -ofs usage:
-ofs <filename> <permmask> is the same as current usage:
-ofs test.dat ++++++++++-----
-ofs <filename> <permission> ... sets the file permissions to the specified permissions.
The following command sets all owner and group permissions and resets all world permissions:
-ofs test.dat ownerall groupall
-ofs <filename> +|- <permission> ... adds/removes specified permissions to/from
current file permissions. The following command adds the worldread permission to the current file
permissions and removes the groupwrite permission from the current file permissions:
-ofs test.dat +worldread -groupwrite
www.faircom.com
All Rights Reserved
35
3.
Administrative Utilities - Standalone
These standalone utilities are intended for administrators. They are located in the following folder:
All tools:
tools\cmdline\admin\standalone
Low-level utilities
3.1
ctcfgset - Server Configuration File Encoding Utility
Converts the standard ASCII-text configuration file, ctsrvr.cfg, into an encoded settings file,
ctsrvr.set. The utility ctcfgset takes as its argument the name of a configuration file, ctsrvr.cfg, to
be converted into a tamper-proof ctsrvr.set file. This creates an optional tamper-proof version of
the server configuration file, referred to as the ‘settings’ file. Because entries in the settings file
cannot be overridden, users cannot alter important aspects of the server configuration.
Usage:
ctcfgset ctsrvr.cfg
www.faircom.com
All Rights Reserved
36
3.2
ctcmdset - Configuration File Encoding Utility
Creates an encrypted password file from a text file by encoding a *.cfg file into a *.set file. The file
to be processed should have an extension of .cfg.
Usage:
ctcfgset [filename].cfg
3.3
ctcpvf - Master Password Verification File Utility
c-treeACE advanced encryption (AES, Blowfish, Twofish, 3DES) requires a master password to
protect encrypted file access. Before starting c-treeACE for the first time with Advanced
Encryption enabled, the Administrator must use the ctcpvf utility to create the master password
verification file. Each time c-treeACE starts, it prompts for the master password to allow it to open
encrypted files.
ctcpvf creates the master password verification file. It accepts optional parameters: filename (the
file name to create) and password (the master password). If the parameters are not given, ctcpvf
will prompt for the required information.
Usage
ctcpvf
[-c <cipher>] [-f <filename>] [-k <key>] [-s <store>]
Where:
 -c <cipher> - Use encryption cipher <cipher>. Supported ciphers: aes256 and aes128.
Default is aes256.
 -f <filename> - Create password verification file <filename>. Default is ctsrvr.pvf.
 -k <key> - Use <key> as the master key.
 -s [<store>] - Store key in encrypted file <store>. Default is ctsrvr.fkf.
 -syslevel - (V11 and later) Create encrypted store file with system-level encryption: all user
accounts on the system can decrypt it.
Note: If you don't use the -syslevel switch, you must run the c-treeACE Server under the same
user account that was used to run the ctcpvf utility that created the master key store file. Using
the -syslevel switch creates the master key store file so that it can be opened by any user
account on that machine, which allows you to run the c-treeACE Server under any user account
on the system. (See Advanced encryption master key store encrypted at system level on
Windows.)
Note: c-treeACE looks for the file ctsrvr.pvf in the server binary area, so this file name should be
specified.
www.faircom.com
All Rights Reserved
37
Key Store Option
By default, this master key must be presented to c-treeACE on startup as prompted. However,
this prompted interaction is not always possible. Consider the case of a failover strategy for
business continuity, or the case where no single person should ever know the complete key as
keys are built from random secure key generators. c-treeACE supports a key store file to provide
this key value at startup.
The ctcpvf utility -s option is used to select the master key length, and to write the master key to
an encrypted keystore file <store>.
The c-treeACE configuration option MASTER_KEY_FILE specifies the key store file, <store>, from
which c-treeACE reads the master encryption key. On Linux and Unix systems, the master key is
stored AES encrypted in a file on disk, with permissions set such that only the user that created
the file can read it (permissions are set to 400). For complete security, it is important to use file
system access safeguards to fully protect this key store file.
Note: The key file (or user key on Linux and Unix) is encrypted using AES. The encryption is
intended to only prevent casual inspection of the data when the file's contents are viewed. The
permissions on the file are the defense against an unauthorized user reading the file. The
Windows master key approach uses the Microsoft DPAPI to encrypt data with user credentials,
and only that user can decrypt the file. Unix support is a bit weaker in this regard as it relies on
file permissions, which can potentially be changed such that another user could read and decrypt
the key.
3.4
ctfchk - File Checksum Utility
ctfchk is a standalone c-tree utility that calculates the checksum on all active records in a
fixed-length c-tree data file. It reads active records from a fixed-length c-tree data file in physical
order and outputs a checksum and active record count. The utility uses the CRC-32 algorithm to
compute the checksum.
This utility can be used to compare the record contents of two fixed-length data files. Two c-tree
data files that contain the same active record images in the same order will generate identical
checksums. Two c-tree data files whose active record contents differ will generate different
checksums (subject to the limitations of the CRC-32 algorithm).
Usage
ctfchk <filename> [-skpchk] [-logcrc] [-logbyt]
[-logrec <record number>] [-opencrpt]
Where:
 -logcrc - Output the current CRC after each active record is read.
 -logbyt - Output the offset of each active record.
 -logrec <record_number> - Output the contents of the specified record. The first active record
in the file in physical order is record 1.
 -opencrpt - Permits the utility to open a file whose update flag is set.
When the file is already opened by another instance (Server, for instance), trying to open it to
calculate the checksum will fail with error FCRP_ERR (14, File Corrupt at Open). If the -opencrpt
www.faircom.com
All Rights Reserved
38
option is added, the utility tries to open the file using the ctOPENCRPT filemode. If this second
open attempt succeeds, the utility outputs the following message and proceeds to calculate the
checksum of all active records in the file:
NOTE: This file's update flag is set. Opened file using ctOPENCRPT mode.
3.5
cthghtrn - Displays the high-water mark for transactions
This utility displays the high-water transaction marks within an index file. This would be typically
used when the c-treeACE Server transaction mark number gets too large.
Usage
cthghtrn [-<page size in bytes (e.g., -1024)>] <file name> [-nonzero]
Where:
 -nonzero - outputs only the non-zero transaction high water mark values.
Examples
cthghtrn
cthghtrn
custmast.idx
-4096 custmast.idx
See also
 ctclntrn Utility - Clean Transaction Mark (page 65,
http://docs.faircom.com/doc/ctreeplus/#31074.htm)
3.6
ctredirect - IFIL Update Utility for Redirected Filenames
Updates IFIL Filenames for redirection to alternate locations.
The Redirect feature is used to allow a file originating in one directory structure to be repositioned
into another directory location following autorecovery, dynamic dump restore, or replication. As a
result, if the IFIL resource of the file contained a path, this path would be incorrect after the file
was redirected to the new location. To support copying c-tree files from one directory location to
another (on the same system or on a different system) and accessing them in their new location,
it is necessary to update any filename paths in a c-tree data file's IFIL resource.
ctredirect is used to update the file names contained in the IFIL resource of the specified files.
ctredirect accepts as command-line options the name of a text file containing the list of files
whose IFIL resources are to be updated and the name of a text file containing the filename
redirection rules.
A comment may be placed in the redirection rules file by starting the line with a semi-colon (;).
Note: The rules must match the path in the IFIL resource, which may differ from the path used to
open the file. The rules must precisely match the path in the IFIL resource, which may differ from
the path used to open the file, therefore you may not use wild cards.
Usage
ctredirect -f <filenamelist> -r <redirectlist> -n <sect>
www.faircom.com
All Rights Reserved
39
Where:
 -f <filenamelist> - Name of a text file containing the names of c-tree data files whose IFIL
resources are to be updated.
 -r <redirectlist> - Name of a text file containing the redirection rules. The rules are in the
format: <current path> <new path> (see the example below).
 -n <sect> - Node sector size. The default is 64, corresponding to the server default
PAGE_SIZE of 8192.
Example
Consider the current directory contains the data files customer.dat and inventory.dat, and their
IFIL resources specify the path /export/home/users/marketing/data for the data and index files.
The current directory contains the file myfiles.txt listing the following file names:
customer.dat
inventory.dat
The current directory also contains the file myrules.txt containing the following redirection rules:
/export/home/users/marketing/data /export/home2/users/support/data
ctredirect is then called to change the paths in the IFIL resource of these two data files:
./ctredirect -f myfiles.txt -r myrules.txt
Updating the file paths in the IFIL resources of the specified files...
[ OK
] customer.dat
[ OK
] inventory.dat
Successfully changed IFIL resource for all specified files
www.faircom.com
All Rights Reserved
40
3.7
cttrnmod - Change Transaction Mode Utility
cttrnmod allows an advanced user to change the transaction status of a c-treeACE data file and
its associated index files. The utility can also be used to display the transaction status of a c-tree
data file and its associated indices.
It is expected only advanced database administrators will run this utility.
Usage
cttrnmod (set <tranmode>|get) (-d <database>|-f <filelist>)
[-u <userid>] [-p <password>] [-s <servername>] [-n <sect>]
Where
 set <tranmode> - Set the transaction mode to one of the following:
• T - Full Transaction Control
• P - Partial Transaction Control (No Recoverability)
• N - No Transaction Control (No Recoverability)
repl=on - Enable replication (requires full transaction control).
repl=off - Disable replication.
The following extended header attributes may also be set:
• {+,-}R - {Enable,Disable} Restorable deletes
• {+,-}C - {Enable,Disable} Transaction controlled deletes
• {+,-}A - {Enable,Disable} Auto transaction switching.
 get - Display the current transaction mode.
 -d or -f - Operate on all files in the database or all listed files:
• -d <database> - Operate on all files in the c-tree database <database>.
• -f <filename> - Operate on all files listed in the file <filelist>.
 -u <userid> - Specify c-tree user ID.
 -p <password> - Specify c-tree user password.
 -s <servername> - Specify c-treeACE Server name to connect to. Default: FAIRCOMS
 -n <sect> - Specify node sector size. Default: 64 (PAGE_SIZE=8192)
The files to change are specified by either the -d <database> option or the -f <filelist> option. The
-d <database> option specifies the name of a c-tree database -- when this option is specified, the
utility operates on all files referenced in that database (excluding SQL system data and index
files). The -f <filelist> option specifies the name of a text file containing names of c-tree data files,
one per line -- when this option is specified, the utility operates on all files specified in that text
file.
Note: Indices created with ctPREIMG or ctTRNLOG are physically structured differently than
indices that do not support transactions. Thus a non-tran index cannot be converted to
transaction control, and must be rebuilt after the conversion. If an index file is created ctPREIMG
or ctTRNLOG, it can be accessed in all transaction and non-transaction access modes.
www.faircom.com
All Rights Reserved
41
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
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
www.faircom.com
All Rights Reserved
42
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
ctTRNLOG
0x0032
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
ctTRNLOG
0x8032
www.faircom.com
All Rights Reserved
43
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
44
4.
Utilities - Client
These client-side utilities are located in the following folder:
All tools:
tools\cmdline\utils\client
Low-level utilities
4.1
ctinfo - ISAM File Info
Usage
ctinfo FileName [-isam] [-rdkeys] [<UserId> [<UserPassword> [<ServerName>]]]
Description
ctinfo retrieves IFIL and DODA structures from a c-treeACE file as well as XCREblk extended
header information if available. This utility is useful in both client-server and standalone mode.
 -isam - Open the specified data file in ISAM mode (V10.3 and later). See below.
 -rdkeys - If this option is enabled, ctinfo opens the data file and associated indexes at the
ISAM level instead of performing a low-level open, which avoids FRSKEY error: 26. Without
this opion, ctinfo does not cause c-treeACE Server to log replication diagnostics; an ISAM
level file open used by -rdkeys will cause the details to be logged
Note: The ISAM open requires the index files to exist and to be accessible, unlike the
low-level open which requires only the data file to exist.
www.faircom.com
All Rights Reserved
45
Utilities - Client
In V10.3 and later, the ctinfo utility displays the owner, group, and permissions for the specified
file. Example output:
File owner
File group
Permission mask
= ADMIN
= ADMIN
= 0x85e = {
owner: read write def delete
group: read
world: read
}
In V10.3 and later, the ctinfo -isam option causes the utility to open the specified data file in
ISAM mode. This option is useful for checking if a REPLICATE keyword enables replication for
the file.
In V11 and later, the ctinfo utility outputs the header record for fixed-length files or the header
key count for each logical index. For example:
Header Count
4776 keys in index 0
4.2
ctixmg - Incremental ISAM / Resource sample
Usage
ctixmg [<UserID>
<UserPassWord> <ServerName>]
Description
ctixmg supports variable-length data records using Incremental ISAM structures to specify the
file parameters for creation and optionally supports resources. If RESOURCES are defined in
ctoptn.h prior to opening the files the proper resource open, OpenFileWithResource(), and
close, CloseRFile(), functions are used. If RESOURCES are not defined, then OpenIFileXtd()
and CloseIFile() are used to open and close the files. The optional UserId, UserPassWord and
ServerName parameters only apply to c-treeACE Server based systems.
ctixmg automatically creates the files it needs if they do not exist. It rebuilds the files if they
appear corrupt. In transaction processing environments, automatic recovery replaces the need for
rebuilding the files.
ctixmg runs in all c-treeACE console-based models. ctixmg permits transaction processing
control including Begin(), and Commit(). In a non-transaction processing system, Begin() and
Commit() are replaced by LockISAM() to control ISAM level locking.
www.faircom.com
All Rights Reserved
46
Utilities - Client
4.3
ctsfex - Superfile Data Export Utility
The ctsfex utility exports data from a superfile to another superfile or to individual files identical to
the superfile members. This high-performance utility exports the data without index updates,
transaction control, or file extension. After the data export is completed, the indices are rebuilt
and transaction control and file extension properties are restored on the newly-created files. This
utility also supports a multi-threaded version allowing each thread to process a superfile member.
Usage:
ctsfex sf1 [-f sf2 | -d dir] [-cCrovV] [-t thds] [-e key]
[-m recs] [-n size] [-T <path>] [-ctscmp <args>]
[-s svn] [-u uid] [-p upw]
Where:
 -f sf2 - Export to superfile sf2
 -d dir - Export to standard files in directory dir
 -c - Create the target files without exporting data.
 -C - Create AND export data for _isp@ and .group tables only.
 -r - Force replacement (overwrite) of existing files.
 -o - Force open of a corrupted file using the ctOPENCRPT file mode.
 -v - Open the superfile and its members to validate a superfile.
 -V - Used in conjunction with -v, this option validates records with a read.
 -m recs - Send record counter to stdout every recs records.
 -e key - Encrypt the target files with key
 -t threads - Maximum number of concurrent threads to use.
 -T <path> - Specify the location of temporary files created by the rebuild operation.
 -s server_name - Server name for connecting to the server.
 -u userID - User ID for connecting to the server.
 -p userpassword - User password for connecting to the server.
 -ctscmp <args> - Invoke the superfile compact utility, ctscmp with <args>.
Standalone Usage
In standalone mode an additional option is available to specify the index node size:
 -n size - Index node size to use (standalone mode only).
4.4
ctvlqa - Variable-length quality assurance utility
Usage
ctvlqa
www.faircom.com
All Rights Reserved
47
Utilities - Client
Description
ctvlqa is designed as a torture and performance test for variable-length records. The program
generates random data to build generic records based on the file structure layout from ctixmg.
ctvlqa prompts the user for the file name, beginning record size, ending record size, record
increment size, and quantity of records to add.
The program does the following:
1.
2.
3.
4.
5.
Creates the data file with the desired file name.
Adds the first record of the beginning record size.
Reads back the record to ensure it was properly inserted into the database.
Adds the desired quantity of records, checking each insertion by re-reading.
Increments the beginning record size by record increment size and inserts the desired
quantity of records for this record size.
Steps 2 - 5 repeat until the ending record size is encountered or an error occurs.
An output log can be created by changing OUTLOG in ctvlqa.c from 0 to 1.
4.5
ISQL
The c-treeACE SQL Interactive SQL utility (ISQL) provides an industry-standard "command
processing" interface to the c-treeACE SQL Database Engine.
FairCom offers two separate implementations of Interactive SQL:
1. A command-line version (isql.exe or isql). This utility is designed as a command-line tool
and can be placed in job streams.
2. A GUI tool version within the Windows program c-treeACE SQL Explorer.
Either implementation allows you to issue SQL statements directly from a command prompt for
immediate displayed results. You can use Interactive SQL to:
 Learn how SQL statements work;
 Test and prototype SQL statements to be embedded in programs;
 Modify an existing database with data definition statements;
 Perform ad-hoc queries and generate formatted reports with special ISQL formatting
statements;
 Run existing SQL scripts.
With few exceptions, you can issue any SQL statement in ISQL that can be embedded in a
program, including CREATE, SELECT, and GRANT statements. Interactive SQL includes an
online help facility with syntax and descriptions of the supported statements.
See Also
 c-treeSQL ISQL Tools and Reference Guide
(http://docs.faircom.com/doc/isql/#cover.htm)
www.faircom.com
All Rights Reserved
48
5.
Utilities - Low Level
These low-level utilities are located in the following folder:
All tools:
Low-level utilities
tools\cmdline\utils\lowlevel
5.1
ctalgn - Change Alignment
The ctalgn utility is used to change the creation alignment characteristic of a file by updating the
file's header.
Usage:
ctalgn <file name> <alignment constant: 1,2,4,8> [<# sectors>]
5.2
CTCMPC - File compaction
ctcmpc <name of file to compact>
This utility is run in single user mode. It takes the name of a data file or an index file. It creates a
compacted copy in the file with name CTREE.TMP. After being compacted, file must be rebuilt
using the c-treeACE Rebuild utility, ctrbld, or RebuildIFile() to update the indices.
CompactIFile() can be used instead of ctcmpc when using Incremental ISAM structures.
www.faircom.com
All Rights Reserved
49
ctcmpc does not support indices contained in superfiles or index files that support transaction
processing. To compact an index file member of a superfile and/or which supports transactions,
use ctdidx to create a flat key file, then use ctindx to rebuild the index compactly.
DEPRECATED as of V7. Please use the enhanced ctcmpif (page 66) utility.
5.3
ctcnfg - System Configuration Example
This sample demonstrates the SystemConfiguration() function. Upon running the utility, you will
see the main menu with the following choices:
SYSCFG: SystemConfiguration example
1. Dynamic system resources
2. Static system resources
3. FairCom Server only resources
4. Client and Server side resources
5. Pre-initialization resources
Enter the number of your choice to see a display of the current configuration. For example, if you
type the number 2 and then press the Enter key, you will see a display similar to the following:
Static system resources
----------------------Maximum c-tree Plus FCBs system wide :
Maximum indices per data file
:
Maximum key segments per index
:
14
32
12
Press the Enter key to return to the main menu.
To exit from the utility, type q at the main menu and then press the Enter key.
5.4
CTCV43 - Convert V4.3 Data File to c-tree Format
ctcv43 <V4.3 data file name> <c-treeACE file name>
This utility converts a data file from c-tree V4.1F-V4.3C to c-treeACE format. It supports the
conversion of files with up to 4 GB in size. Both fixed and variable-length files are supported.
If the new data file does not exist, it will be created. ctcv43 is designed to run in single user
mode.
After converting the data files, you may use the rebuild utility, ctrbld, or function, RebuildIFile(),
to construct the associated index files. If you have stand-alone indices to convert, use ctin43 to
first create a flat key file, and then use ctindx to build the new index file.
Note: ctin43, provided with c-treeACE, must be linked with your c-tree V4.3 application library.
5.5
ctcv67 - Extended File Conversion Utility
ctcv67 <old file name> <new path> [<option> <argument> ...]
The first two arguments are required. The new path is prepended to the old file name or the files
in the parameter file. The options are listed in the table later in this topic.
www.faircom.com
All Rights Reserved
50
ctcv67 performs various conversions, including:
 Converting data and index files from Standard c-treeACE format to Extended c-tree format
(HUGE or non-HUGE) using Incremental ISAM (IFIL) or parameter files.
 Adding huge file support to a non-huge file.
 Adding, removing, or changing segment support.
 Automatically compacting the output file.
Note: ctcv67 must be built by FairCom. An executable version is included in the c-treeACE
Server installation for each platform, in the Utils folder.
If the original file has an extended header, the new file inherits the extended header attributes.
This utility does not convert a huge file to a non-huge file. If a superfile host is specified, ctcv67
converts all member data files and their associated indices. When a mirrored file is specified, the
conversion does NOT produce the mirrors, but maintains the mirrored names in IFIL structures.
Copy the converted master files to produce the mirror files.
Unless a parameter file is used, a data file must have an embedded IFIL definition for its
associated indices to be converted. A data file will have an embedded IFIL definition if it was
created with one of the CreateIFile() routines or PutIFile() was called for the file.
If an index file is specified by the <old file name> parameter, then a new index file with an
extended header will be created, all the resources will be transferred to the new index, its key
length will be increased if HUGE is specified and the key supports duplicates, but no key values
will be transferred to the new file. In essence, it will be an empty index file.
The following options are available:
Optio
n
Arguments
Description
F
<yes | no>
If yes, <old file name> is a parameter file with file modes
set to ctREADFIL (8) and the second parameter (# of files)
doubled. PP ignored. Default: no
T
<yes | no>
Set to yes to output the names that will be assigned to the
converted files along with pro forma segment specifications.
This option is for information purposes only: No actual
conversion takes place. Default: no
P
<page size>
Sets the page size in bytes used to create the new files.
This setting must be compatible with the existing file.
Default: 8192
PP
<yes | no>
Set to yes to have the conversion run the Superfile prepass.
Default: no
6
<yes | no>
Set to yes to enable 6-byte transaction number support.
This option is recommended for all files using c-treeACE
Server Version 8 and later. Default: no
H
<yes | no>
Set to yes to create a huge file. Default: yes
www.faircom.com
All Rights Reserved
51
Optio
n
Arguments
Description
G
<new segment host file
name>
<host segment size in MB>
The new file name of a data or index file to be created as a
segmented file. Derive this name from the new path and the
file’s original name. (The T option can be used to check on
the new name assigned to a file.) Use a G entry for each
new file to be segmented.
Note: Even if the old file is segmented, segments must be
specified for the new file or it will no longer be segmented.
S
<segment name>
<segment size in MB>
This option must follow immediately after the G option for
the associated host file. Repeat this option as necessary to
create all the additional segments of the file. The segment
name will be used exactly as specified. The new path will
NOT be prepended to the name.
A
<max # auto segments
including host>
Use as many S <name> <size> entries as needed or OR
one A <max> entry for each host. The S or A entries for
each host must follow immediately after each host's G
entry.
E
<encryption method>
Specify a valid ctSETENCRYPT() mod value (see
SetEncryption). For example: ctAES32 for AES with a
32-byte key.
L
<File Extension size in
Bytes>
Note: 2GB maximum.
TP
<Temp file directory>
Defaults to .\
Example:
ctcv67 vcusti new H no G new\vcusti.ndx 10 S e:\vc.s01 10 S f:\vc.s02 0
where:
 vcusti is the existing file name.
 new is the new path.
 H no creates a normal file rather than a huge file.
 G new\vcusti.ndx 10 sets the new segment host file name to new\vcusti.ndx and the host
segment size to 10 MB.
 S e:\vc.s01 10 S f:\vc.s02 0 creates the following segments:
e:\vc.s01 with a size of 10 MB.
f:\vc.s02 with a size of 0 MB.
Ordinarily, the new path name is simply prepended to the original file name. If both have absolute
names, the new (absolute) path replaces the absolute portion of the original name. If only the
original file is absolute, the new (relative) path is inserted immediately after the absolute portion of
the original file name. Otherwise, the new path (relative or absolute) is prepended to the original
(relative) file name.
For example, to convert the data file C:\DATA\SAMPLE.DAT and its associated index,
C:\DATA\SAMPLE.IDX, into huge files with three segments of 2000 MB each, use the following
command line:
ctcv67 C:\DATA\SAMPLE.DAT C:\HUGEDATA\ H yes
G C:\HUGEDATA\DATA\SAMPLE.DAT 2000 S D:\HUGEDATA\SAMPLE.SG1 2000 S E:\HUGEDATA\SAMPLE.SG2 2000
G C:\HUGEDATA\DATA\SAMPLE.IDX 2000 S D:\HUGEDATA\SAMPLE.IS1 2000 S E:\HUGEDATA\SAMPLE.IS2 2000
www.faircom.com
All Rights Reserved
52
Even if the original file is segmented, the new file will not be segmented unless a new segment
definition is specified using the ‘G’ and ‘S’ options.
The associated indices are recreated based on the IFIL resource embedded in the data file or
based on the parameter file information. If the associated data file becomes huge, index files
allowing duplicate records will have their key lengths automatically increased by 4 bytes to
accommodate the longer associated position information used to break the tie. If you recall, when
allowing duplicate key values in an index, you must add 4 bytes to the key length. For huge files,
you must add a total of 8 bytes. In addition, the index file names in the IFIL definition will reflect
the new path name.
ctcv67 creates (or appends to) a text file named CV67.REP, which reports on the actions and
progress of the utility program.
5.6
ctdidx - Create flat key file
ctdidx <index file name> <index member #> <flat key file name>
This utility will run either in single user mode or with the c-treeACE Server. The c-treeACE Server
or single-user transaction processing mode is necessary to dump the keys from an index which
supports transaction processing. ctdidx creates a flat file containing each key value at full,
uncompressed length followed by the associated record position in long integer, 4-byte, form.
ctdidx reads each key in order from the index member designated, 0 for the host index, 1 for the
first member, etc., and places the keys in the flat file it creates.
5.7
ctdmpidx - Index Dump Utility
ctdmpidx is available to dump an index. This utility is useful for viewing index header details,
viewing nodes and key values. The syntax is shown below:
ctdmpidx [-<page size>] [-listkeys] <filename> <member #> [<rflg>]
The optional parameter -page size equals sector size * 128 (third parameter in InitCtree()). If
page size is not entered, a default value of 16 will be used. filename specifies the index file
targeted for analysis. The member # refers to the index member number. A physical index file can
contain one or more indices. Each index has a member number (0, 1, 2, 3, etc.). For example, the
sample index file custordr.idx provided with the FairCom ODBC Driver contains a total of two
indices. Depending on whether you specify 0 or 1 you will be looking at either the order number
index or the customer number index. rflg represents an optional recovery flag switch and is only
applicable when compiled with TRANPROC. Any character will enable rflg, which will result in
c-tree skipping automatic recovery.
The -listkeys, option is available in V10.3 and later. It lists all the key values and their associated
record offsets in an index.
Example
Below is an example of launching ctdmpidx along with output showing the header and prompt for
an index node address.
# ctdmpidx -2048 custmast.idx 0
header info for file #0
[custmast.idx]:
www.faircom.com
All Rights Reserved
53
configuration version:
node size:
data record length:
max bytes per leaf node:
file mode:
file type:
update flag:
key type:
duplicate flag:
# of active entries:
delete stack ptr:
last byte used:
last physical byte:
permanent file mode flags:
leaf anchor ptr:
file flavor:
key padding byte:
header record ptr:
81x
2048
0
1348
16392
1
0x
0
0
4
0x
1800x
1800x
0
1000x
2
20x
0x
index root ptr:
superfile last member#:
extend file size:
max bytes per non-leaf:
key length:
# of additional members:
index member number:
file id number:
server id number:
current node ptr:
index high transaction #:
serial number:
delete type:
superfile type:
superfile member #:
file alignment:
maximum name length:
resource header ptr:
1000x
0
0
2030
4
0
0
0
0
0x
0
0x
0
0
0
8
255
800x
Enter node address in hex: 1000
NODE: 1000x
trans active:
predecessor node:
successor node:
# of entries:
# of bytes:
leaf flag:
member #:
element
1
5.8
offset
101fx
2
105ex
3
1099x
4
10d9x
no
0x
0x
4
32
1 (0 => non-leaf / 1 => leaf)
0
key value
31303030
1 0 0 0
31303031
1 0 0 1
31303032
1 0 0 2
31303033
1 0 0 3
ctflat - Create c-treeACE file from a flat file
Usage
ctflat <flat file> <new file> <record length> [<file mode> <ext size>]
Description
ctflat creates a c-treeACE fixed-length data file from an existing flat file with the specified record
length. Optionally, you can specify the file mode to use when creating the file. For example, to
enable transaction processing and the file size extension parameter.
ctflat assumes that the flat file begins at offset zero and has the record length indicated on the
command line. You can modify the source to make it more appropriate for your specific
circumstances.
www.faircom.com
All Rights Reserved
54
5.9
ctflvrfy - Index Verify Utility
Usage
ctflvrfy <filename.idx>
Description
The Index Verify utility, ctflvrfy, takes an index name as the parameter and calls the ctVERIFY()
and chkidx() functions to allow the user to verify and index, and optionally inspect it at a
low-level.
C:\ctree\utils\>ctflvrfy custmaster.idx
Verifying file [custmaster.idx]
Retrying open with sect of [8]
Verifying the host index
Verifying index delete stack...
Verifying index links...
Verifying index leaf nodes...
Index page scan finds entries=75 header=75
Index nodes per level of tree structure - [0: 1]
( 2 resource pages )
Internal Index Verify: SUCCESSFUL
The return of ctVERIFY = 0, 75 KEYS FOUND
Verifying member index #1
www.faircom.com
All Rights Reserved
55
Internal Index Verify: no tree structure
The return of ctVERIFY = 0,
0 KEYS FOUND
www.faircom.com
All Rights Reserved
56
Verify complete......
Do you wish to perform a low-level tree walk? (Y/N):
5.10
n
ctindx - Create index file from flat key file
Usage
ctindx <flat key file> <index file> <index member> [<transformation file>]
Description
This utility runs in single user mode. It supports indices requiring transaction processing. The
index file must already exist, and the index member (0 for the host index, 1 for the first additional
index member, etc.) must be empty. The key length of the index member is used to deduce the
www.faircom.com
All Rights Reserved
57
key length of the flat file. You can optionally specify a transformation file specifying how to
transform each key value before entry into the index file.
The optional transformation file is a text file similar to an ISAM parameter file formed as follows:
<# of segments>
<offset> <length> <mode>
... repeated for each segment ...
An offset of zero corresponds to the first byte of the key value stored in the flat key file. The
length dictates how many bytes are affected by the transformation. The mode is interpreted as
shown in “Key Segment Mod (http://www.faircom.com/doc/ctreeplus/30863.htm)es” in the
c-treeACE Programmer's Reference Guide (http://www.faircom.com/doc/ctreeplus/30863.htm).
5.11
ctpkey - Print key utility
Usage
ctpkey <parameter file name> [<# of entries>]
Description
ctpkey prints out 1 or more key value(s), up to the optional # of entries, from each index file in the
parameter file, showing how each key segment is defined. The keys are displayed in hex and
ASCII. This utility will run in all modes of operation. It is useful if you are having trouble retrieving
data. ctpkey will allow you to see how a key value is constructed from the data.
By changing a #define, ctpkey.c can be changed from a main line program to the callable function
ctpkey(), with the same parameters as OpenIFileXtd().
5.12
ctpotp - Parameter to OTP conversion
Usage
ctpotp <parameter file name> [<user profile bitmask>]
Description
This utility takes a parameter file and produces the corresponding OTP file(s) used by the
FairCom Drivers. If no record schema (DODA) is present, a dummy schema is created.
5.13
ctptoi - Parameter to IFIL conversion
Usage
ctptoi <parameter file name> [<user profile bitmask>]
Description
This utility opens the parameter file whose name is specified as a command-line argument and
writes an IFIL (based upon the parameter file definitions) to each data file referenced in the
parameter file. ctptoi is designed for use as a standalone non-server utility.
Note: Before running ctptoi, be sure your files have been created and are in the proper path
location as specified in the parameter file being passed into the ctptoi utility.
www.faircom.com
All Rights Reserved
58
5.14
ctrbld - Parameter file rebuild utility
Usage
ctrbld <parameter file name> [ -updateidx ] [ -autopurge ]
Description
ctrbld verifies the deleted space in the data file and completely recreates, in place, any
companion index files. If the index file(s) do not exist, they are created.
CTRBLD can only be used on a superfile if the superfile has first been processed by ctsbld,
which performs a necessary pre-pass. When ctsbld completes, the data file members are in
good form, but the index files are empty. ctrbld, ctindx, or RebuildIFile() can recreate the index
file contents. ctrbld returns a non-zero status code via the system exit to permit invoking from a
shell script and testing for possible errors.
Specify -updateidx to delete the existing indices and re-create the new indices using the index
definitions provided in the parameter file. To implement this feature, enable the
DO_IDX_HEADER_UPDATE define in ctrbld.c. Without -updateidx, ctrbld fails when it detects a
discrepancy between the properties of existing indices and the index properties as defined in the
parameter file, returning KMEM_ERR (23).
Executing ctrbld with -autopurge causes the rebuild to automatically purge records with duplicate
keys. A purge log will be generated.
DEPRECATED as of V7. Please use the enhanced ctrbldif - IFIL-based Rebuild Utility (page 11).
See also File Recovery.
5.15
ctsfil - Superfile contents
Usage
ctsfil <superfile name>
Description
ctsfil lists the members of the superfile, indicating whether each member is an index file,
fixed-length data file, or variable-length data file.
5.16
ctunf1 - File Reformatting Utility
Usage
ctunf1 <file name> <new alignment> <new flavor> <confirm> <binflag> [<files>]
www.faircom.com
All Rights Reserved
59
Description
ctunf1 reformats a file IN PLACE provided the new alignment restriction does not cause the data
record contents to become misaligned. Therefore, FairCom strongly encourages ctunf1 be used
only on a copy of your data. ctunf1 takes the place of the UNIFRMAT compile time option; plus it
handles data record contents if record definitions have been provided (DODA). ctunf1 is used to
port data between different machine architectures.
ctunf1 uses record definitions, if present, to convert the contents of the data records. A record
definition is stored as a resource in a data file using the PutDODA() function. In general, the
contents of resource records will NOT be converted. Therefore, if you intend to port your files,
take care with the resources you directly maintain yourself to ensure they are system
independent. However, the resources pertaining to file and record definitions and index
alternative collating sequences maintained by FairCom will have their contents automatically
converted by ctunf1.
<file name> requires the file extension. For example, to convert a file named cust.dat from Intel to
a SPARC platform, issue the following:
ctunf1 cust.dat 4 m
Parameter
Description
alignment
1 (byte)
2 (word)
4 (double word)
8
flavor
L (LSB first, e.g., 8086 form)
M (MSB first, e.g., 68000 form)
confirm
Y convert file without prompting to continue
binfllag
optional c-treeDB binary field attribute
B2 binary field data contains length count
B3 binary field data does not contain length count
files is the optional maximum number of files to open. ctunf1 defaults to 32 files, which should be
sufficient for most purposes.
ctunf1 runs in single user mode only. It supports data files, index files and superfiles, and must
be executed before the file is moved to the target machine.
In V11, a case was added for handling FCRES_ATTR resource type. Prior to that release, the
ctunf1 utility failed with DCNV_ERR (439) error on FAIRCOM.FCS.
www.faircom.com
All Rights Reserved
60
5.17
ctupdpad - Update the c-treeDB Pad Resource Utility
When importing an ISAM data file into a c-treeSQL database, the c-treeSQL import utility,
ctsqlimp, allows specifying the padding and delimiter characters used to pad string fields in a
data file. The c-tree Update Pad Resource Utility, ctupdpad, provides a way to change the
padding and delimiter characters in the c-treeDB padding resource.
Syntax
The usage of this utility is as follows:
ctupdpad [options] table-name pad-char delimiter-char
Options are any combination of the following:
-s server-name [Default: FAIRCOMS]
-u user-name
[Default: ADMIN]
-p password
[Default: ADMIN]
The pad-char and delimiter-char values are specified with their corresponding ASCII code values.
Examples
 To set the pad char to space and delimiter to space:
ctupdpad table.dat 32 32
 To set the pad char to space and delimiter to nul:
 To set the pad char to nul and delimiter to nul:
5.18
ctvfyidx - Index Verify Utility
The ctvfyidx utility uses the ctVERIFYidx() function to check the integrity of an index file. The
client version of the ctvfyidx utility supports the command-line options listed below.
Usage
ctvfyidx [<option> ...] [-u <userid>] [-p <password>] [-s <servername] <file name> [<member #>]
where <option> is one or more of the following:
 -excl - Open the file in exclusive mode
 -delstk - Check delete stack (on by default)
 -link - Check links (on by default)
 -leaf - Check leaf nodes (on by default)
 -chkkey - Check keys in leaf nodes
The optional parameter -page size equals sector size * 128 (third parameter in InitCtree()). If
page size is not entered, a default value of 16 will be used. filename specifies the index file
targeted for analysis. The member # refers to the index member number. A physical index file can
www.faircom.com
All Rights Reserved
61
contain one or more indices. Each index has a member number (0, 1, 2, 3, etc.). For example, the
sample index file custordr.idx provided with the FairCom ODBC Driver contains a total of two
indices. Depending on whether you specify 0 or 1 you will be looking at either the order number
index or the customer number index. rflg represents an optional recovery flag switch and is only
applicable when compiled with TRANPROC. Any character will enable rflg, which will result in
c-tree skipping automatic recovery.
In V10.3.1 and later, the ctvfyidx utility defaults to ctREADFIL. It uses ctEXCLUSIVE when
the -excl option is specified. A ctREADFIL open will fail with error 12 and sysiocod -8 if any
connection has the file open for write access.
In versions prior to V10.3.1, ctvfyidx will only work with the -excl option when connecting to
newer servers. Without the -excl option, older versions of ctvfyidx will fail with LERR_ERR.
Example
Below is an example of launching ctvfyidx along with output showing the results of the index
verification.
# ctvfyidx -2048 custmast.idx 0
5.19
ctvfyfil - File Verify Utility
The ctvfyfil utility calls the ctVerifyFile() function. The utility can be run in standalone and in
client/server mode.
Usage
ctvfyfil [<option> ...] <file name>
where <option> is one or more of the following:
 -chkdat - Read data file only (default)
 -chkdatkeys - Read data file and check keys in index
 -chkidx - Read index file
 -chkidxrec - Read index file and check records in data file
 -excl - Open the file in exclusive mode
 -int - Interactive mode: stop on each error
 -index=<N> - Check only the Nth index (N=1,2,...)
Standalone Usage
An additional option is available for standalone use:
 -<page size> - Use the specified page size (standalone only)
The example below shows the utility called standalone on a file called mark.dat with the page size
set to 8192:
ctvfyfil -8192 mark.dat
www.faircom.com
All Rights Reserved
62
www.faircom.com
All Rights Reserved
63
6.
Utilities - Standalone
These standalone utilities are located in the following folder:
All tools:
Low-level utilities
tools\cmdline\utils\standalone
6.1
ct_ver - Display c-treeACE version that created file
You can run the ct_ver utility to determine what version of c-treeACE was used to create your
data file.
Usage:
ctver <filename>
Where:
 <filename> - The name of the file to be checked.
6.2
ctchkbin - Checking for affected tables
Execute the ctchkbin utility to scan an entire server or a single database for tables that may be
affected by the binary/varbinary issue. The syntax of ctchkbin is as follows:
ctchkbin.exe [-f] [-s server] [-u username] [-a password] [-d database]
www.faircom.com
All Rights Reserved
64
Where:
 -f - Output only tables that fail check
 -d database - Scan database. Default: ctreeSQL
 -d ALL - Scan all databases in session.
 -s server name - Default: FAIRCOMS
 -u user name - Default: ADMIN
 -a user password - Default: ADMIN
Example
ctchkbin.exe –s FAIRCOMS –u ADMIN –a ADMIN –d ctreeSQL
The ctchkbin utility output to the screen the result of the check scan, printing one table per line,
with the following columns:
database table status comments
Where:
 database - database name
 table - table name
 status - status code of the check performed on table (please see code listing in the following
section)
 comments - brief comments if table fail scan
Example output
ctreeSQL
ctreeSQL
ctreeSQL
ctreeSQL
ctreeSQL
ctreeSQL
ctreeSQL
ctreeSQL
6.3
admin_tb1 0
admin_tb11 0
admin_tb12 0
admin_tb13 3 User may choose CTDB_BINARY_WITH_LENGTH or CTDB_BINARY_WITHOUT_LENGTH
admin_tb14 3 User may choose CTDB_BINARY_WITH_LENGTH or CTDB_BINARY_WITHOUT_LENGTH
admin_tb2 0
admin_tb3 0
admin_tb4 0
ctclntrn Utility - Clean Transaction Mark
Usage
ctclntrn [-<page size in bytes>] <file name> [<password>]
Description
ctclntrn “cleans” the high-water transactions marks within a c-treeACE index.
Suggested Steps for Successful Clean and Reset
In the event of an impending transaction number overflow, the server administrator should follow
these steps to restart transaction numbering:
1. Perform a clean c-treeACE shutdown.
2. Delete the transaction logs and housekeeping files: files S0000000.FCS, S0000001.FCS,
D*.FCS, I*.FCS, and L*.FCS.
www.faircom.com
All Rights Reserved
65
3. Use the ctclntrn utility to clean all indices (which resets the transaction numbers in the leaf
nodes and index header) used by your application, including your application index files,
superfiles, variable-length data, and c-tree Server files including the following if present:
• FAIRCOM.FCS -- If you are not using any User IDs or passwords other than ADMIN and
GUEST, you can simply delete this file. (If you do delete this file, tc-treeACE will re-create
it with the single user ADMIN and password ADMIN.)
• CTSYSCAT.FCS -- This is only present if you are using c-tree ODBC Drivers.
• SEQUENCEIX.FCS
• SYSLOGIX.FCS
• SYSLOG*.FCS
• ALL c-treeACE SQL Database Dictionaries
 <databasename>.dbs/SQL_SYS/<databasename>.fdd
 ctdbdict.fsd (session dictionary)
4. Restart the c-tree Server.
The server will create new transaction logs and start transaction numbering from 1 again.
It is important to run ctclntrn on all files. If you miss any files and later open that file with a large
transaction number in its header, the server will again increase its transaction number to that
large value. You will need to repeat this procedure should that occur.
FYI: The ctclntrn utility uses the CleanIndexXtd() c-treeACE function. This function cleans any
leaf nodes of exceptional transaction marks and resets the transaction high-water mark in the
header to zero. This avoids rebuilding the entire index file.
You can use the c-tree High-water Mark Utility, cthghtrn, to verify that the transaction high-water
marks in the files are back to zero, or other reasonably low number.
Tip: The AUTO_CLNIXX YES configuration option can help automate and detect files which
have been missed.
See also
 cthghtrn - Displays the high-water mark for transactions (page 39,
http://docs.faircom.com/doc/ctreeplus/#31083.htm)
6.4
ctcmpcif - IFIL-based Compact Utility
Standalone Usage
# ctcmpcif DataFileName [-purge] [-updifil]
[-temppath=<temporary_path>] [-<sectors>] [-compress] [-nocompress]
Where:
 -<sectors> - The sector size to use. The sector parameter is especially useful if you need to
adjust a file’s PAGE_SIZE to match the c-treeACE Server.
 -purge - Delete records that have illegal duplicate key values.
 -temppath=<temporary_path> - Use the specified directory for temporary files.
 -updifil - Update IFIL resources in the data file.
www.faircom.com
All Rights Reserved
66
 -sortmem=<N> - Set the size of sort memory to N KB in non-client builds. This option can be
used to increase the rebuild speed for large files.
 -redosrl - Reassign serial numbers to the records in the compacted file instead of copying the
values from the original file.
 -compress - Create the compacted data file with compression (defaults to zlib library if not
specified in server configuration).
 -nocompress - Create the compacted data file without compression.
 -idxseg=<M>@<S> - If creating an index, use M automatic segments of size S. Size is
specified in megabytes, or you can specify MB or GB as a suffix. (Example:
-idxseg=10@1GB)
 -encrypt=cipher - Create the compacted file using the specified cipher. See the encryption
sections below.
Accepted values:
• CAMO, camo:KEY_VALUE
• AES: aes16, aes24, or aes32
• Blowfish: blf8, blf9, ..., or blf56
• DES: des8, des16, or des24
• none
 -oldsec - Use the utility's original security attribute assignment.
Client-Side Usage
# ctcmpcif DataFileName [-purge] [-updifil] [<UserId>]
[<UserPassword> [<ServerName>]]
Where:
UserID, UserPassword, and ServerName are only needed for client versions of this utility.
FairCom recommends building this utility as a Single-user Standalone application.
ctcmpcif reads the IFIL structure from DataFileName and calls CompactIFileXtd() and
RebuildIFileXtd() to compact and rebuild DataFileName and its associated indices. If ctcmpcif
cannot extract the IFIL from the target file, it will ask for the name of another copy of the file from
which to extract the IFIL information.
Prior to c-treeACE V9.3, several option values were defined such as updateIFIL, purgeIFIL, and
badpartIFIL, that can be specified. These values are specified by adding them together. For
example: myifil.tfilno = updateIFIL + purgeIFIL. A new approach simplifies checking of these
options. The following option values are now specified in ctport.h:
#define
#define
#define
#define
updateIFILoption
purgeIFILoption
badpartIFILoption
redosrlIFILoption
0x0002
0x0004
0x0008
0x0010
These values can now be OR-ed together and the negative of the result stored in the tfilno field of
the IFIL structure passed to the compact or rebuild function. For example, to indicate that you
want to assign new serial numbers, do the following:
www.faircom.com
All Rights Reserved
67
myifil.tfilno = -redosrlIFILoption;
CMPIFIL(&myifil);
If you want to also use more than one option when compacting or rebuilding a file, OR them in to
the value and negate the result. For example,
/* assign new serial numbers and update IFIL resource. */
myifil.tfilno = -(redosrlIFILoption | updateIFILoption);
CMPIFIL(&myifil);
Note: This tool does not compact partitioned files. If you attempt to compact a partitioned file, the
tool will return PCMP_ERR (954, compacting partitioned file not supported).
Changing Encryption Attributes
In V11 and later, the compact utility can optionally change the encryption attributes. To use this
option, OR in the setencryptIFILoption bit into the tfilno field of the IFIL structure whose address
you pass to the compact API function. When using this and other options, remember to negate
the tfilno value after you OR in the options. For example:
myifil.tfilno = -(redosrlIFILoption | setencryptIFILoption);
CMPIFIL(&myifil);
Specifying the Encryption Cipher
In V11 and later, the ctcmpcif utility supports an option to specify the encryption cipher for the
data and index files created by the compact operation. Usage:
-encrypt=cipher - Create the compacted file using the specified cipher:
• for AES, use aes16, aes24, or aes32
• for Blowfish, use blf8, blf9, ..., or blf56
• for CAMO, use camo:MY_ENCRYPTION_KEY
• for DES, use des8, des16, or des24
• for Twofish, use twf16, twf24, or twf32
• for no encryption, use none
Note: If an index file does not exist, the original data file's encryption attributes are used
when creating that index file.
To change the encryption attributes of a file using the compact API function, you must add
the option CHANGE_ENCRYPTION_ON_COMPACT YES to ctsrvr.cfg. Otherwise, the operation
fails with error NSUP_ERR (454, not supported).
Considerations
 The -x8 option requires all associated index files that are referenced in the data file's IFIL
When an application calls the standalone version of the Xtd8 file compact or rebuild functions (for
example, CMPIFILX8() or RBLIFILX8()), index files created by the compact or rebuild no longer
have the 6-byte transaction number attribute enabled if the specified extended create block's
x8mode field has the ctNO6BTRAN bit set.
www.faircom.com
All Rights Reserved
68
 In V11 and later, the compact and rebuild API functions preserve the original files' encryption
attributes by default. If the index files don't exist when compact/rebuild are called, they will be
created with the data file's encryption attributes.
 In V11 and later, the compact utility always deletes and recreates the index files after saving
the resources from the original index file. This provides the expected behavior of (possibly)
reducing the size of the index file.
See also File Recovery.
www.faircom.com
All Rights Reserved
69
6.5
ctencrypt - Utility to Change Master Password
The c-treeACE advanced encryption feature uses a master password to encrypt the file-specific
advanced encryption key in c-tree data, index, and transaction log files that are encrypted using
advanced encryption. ctencrypt is a standalone utility that can be used to change this master
password for specified c-tree data, index, and transaction log files.
Usage
ctencrypt <options> <command>
Available Options:
 -n <sect> - Node sector size. The default is 64, which corresponds to PAGE_SIZE of 8192.
Available Commands (only one at a time may be specified):
 -chgmpw <filelist> - Change master password for the files whose names are listed in the file
<filelist>. <filelist> is the name of a text file created by the end user that lists the names of the
files (data and index), one per line, that are to be processed.
ctencrypt requires a password verification file named ctsrvr.pvf that was created using the
current master password to exist in its working directory. ctencrypt prompts the user for the
current master password and for the new master password (prompting twice in order to confirm
that the new password was properly entered).
Note: ctencrypt does not change the master password file, ctsrvr.pvf. The ctcpvf utility will need
to create a new file for server startup in coordination with the new password used to re-encrypt
the encryption key for the files. Failure to do so will result in DCOD_ERR errors (606, failure to
decode file) when opening files.
ctencrypt processes the specified files, indicating the status of each file and the total of
successful and failed operations. Note that the c-treeACE Server must be shut down while these
file modifications take place.
ctencrypt creates a temporary directory named temp\ctencrypt.tmp.<process_id> to store its
transaction logs. This directory is normally deleted when ctencrypt shuts down.
Important: ctencrypt does not undo any changes in case of error. The files that it lists as
successfully updated will use the new master password even if the utility failed to update other
files.
Example File List
A semicolon can be specified at the start of a line to indicate a comment which is ignored.
; c-treeACE Advanced Encryption Conversion Listing File
; ----------------------------------------------------; Created Wed Dec 01 01:38:00 2010
; transaction log files
L0000000.FCT
L0000002.FCA
L0000003.FCA
L0000004.FCA
L0000005.FCA
L0000006.FCS
L0000007.FCS
www.faircom.com
All Rights Reserved
70
L0000008.FCS
L0000009.FCS
L0000010.FCT
; data files
mydatafile.dat
C:\My Documents\test.dat
vcusti
Note: All physical encrypted files, data and index files, must be specified in order to be modified.
No attempt is made to determine associated files.
If the server was cleanly shutdown in such a manner that its transaction logs are no longer
necessary, then they will not need to be included as part of this password change. If you wish to
use the ctencrypt utility to modify any existing encrypted transaction logs (for example, archive
logs for replication), their names must be specified in the list file. ctencrypt does not attempt to
locate any transaction log files on its own.
Example Output
c-tree file encryption utility
This utility requires a master password in order to start.
Please enter master password:
Enter new master password
:
Confirm new master password :
Changing master password for the specified files...
[
[
[
[
[
[
[
[
[
[
[
[
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
OK
]
]
]
]
]
]
]
]
]
]
]
]
SYSLOGDT.FCS
vcusti
L0000000.FCT
L0000002.FCA
L0000003.FCA
L0000004.FCA
L0000005.FCA
L0000006.FCS
L0000007.FCS
L0000008.FCS
L0000009.FCS
L0000010.FCT
12 succeeded, 0 failed
Successfully changed master password for all specified files
Error Returns
Two new error codes have been added related new password management features:
 BMPW_ERR (932) - The specified encryption master password is incorrect.
 ICOD_ERR (933) - An encryption operation failed due to an unexpected internal error. See
CTSTATUS.FCS for details.
www.faircom.com
All Rights Reserved
71
6.6
ctfdmp - Forward Dump Utility
ctfdmp
Used to restore data to a given time following a ctrdmp restore.
ctfdmp takes an !RP <name> argument to set the point in time to stop the forward roll. This
argument is also used by the ctrdmp script option, as described in Rollback to New Restore
Points with ctrdmp. To incrementally roll forward from there, rename the previous
RSTPNT_CHKPNT*.FCS to S0000001.FCS (the start point for the ctfdmp), and supply a new
!RP and transaction logs.
Note: The ! prefix needs to be escaped when using the Unix Bash shell.
In V11 and later, the ctfdmp, ctldmp, and ctrdmp utilities display the c-treeACE version used to
compile them when they are run.
Environment Variable for Advanced Encryption Password
If this utility has advanced encryption enabled, it can read an encrypted password file instead of
being prompted to enter the master password. To enable this, set the environment variable
CTREE_MASTER_KEY_FILE to the name of the encrypted master password file.
See also
 Maintaining Database Integrity (http://docs.faircom.com/doc/ctserver/8373.htm) in the c-tree
Server Administrator's Guide
 ctrdmp - Dynamic Dump Recovery or System Rollback (page 77)
 Rollback to New Restore Points with ctrdmp
www.faircom.com
All Rights Reserved
72
6.7
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 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).
6.8
ctfixbin - Fixing Affected Tables
Based on the output of the ctchkbin utility, execute the ctfixbin utility on a particular table to set
the binflag property of CT_ARRAY and CT_2STRING fields to the appropriate value.
The syntax of ctfixbin is:
ctfixbin.exe table_name action [-s server] [-u username] [-a password] [-d database]
 table_name is the name of a table to fix (without the .dat extension)
 action is one of the following:
•
1 - set binflag to CTDB_BINARY_UNKNOWN
•
2 - set binflag to CTDB_BINARY_WITHOUT_LENGTH
•
3 - set binflag to CTDB_BINARY_WITH_LENGTH

-d database - Scan database. Default is ctreeSQL

-s server - Default is FAIRCOMS

-u username - Default is ADMIN

-a password - Default is ADMIN
Example
ctfixbin.exe admin_tb13 2 –s FAIRCOMS –d ctreeSQL –u ADMIN –a ADMIN
www.faircom.com
All Rights Reserved
73
6.9
ctidmp - Examine Dump Files
Usage
ctidmp [dump file name]
Description
The ctidmp utility lists the contents of a dynamic dump file or a specific extent of a dump broken
into multiple files with the !EXT_SIZE keyword. Compile and link this utility with a c-treeACE
Standalone Single-user TRANPROC library.
6.10
ctinfo - ISAM File Info
Usage
ctinfo FileName [-isam] [-rdkeys] [<UserId> [<UserPassword> [<ServerName>]]]
Description
ctinfo retrieves IFIL and DODA structures from a c-treeACE file as well as XCREblk extended
header information if available. This utility is useful in both client-server and standalone mode.
 -isam - Open the specified data file in ISAM mode (V10.3 and later). See below.
 -rdkeys - If this option is enabled, ctinfo opens the data file and associated indexes at the
ISAM level instead of performing a low-level open, which avoids FRSKEY error: 26. Without
this opion, ctinfo does not cause c-treeACE Server to log replication diagnostics; an ISAM
level file open used by -rdkeys will cause the details to be logged
Note: The ISAM open requires the index files to exist and to be accessible, unlike the
low-level open which requires only the data file to exist.
In V10.3 and later, the ctinfo utility displays the owner, group, and permissions for the specified
file. Example output:
File owner
File group
Permission mask
= ADMIN
= ADMIN
= 0x85e = {
owner: read write def delete
group: read
world: read
}
In V10.3 and later, the ctinfo -isam option causes the utility to open the specified data file in
ISAM mode. This option is useful for checking if a REPLICATE keyword enables replication for
the file.
In V11 and later, the ctinfo utility outputs the header record for fixed-length files or the header
key count for each logical index. For example:
Header Count
www.faircom.com
All Rights Reserved
74
6.11
ctldmp - Transaction Log Dump
Usage
ctldmp [ DATE mm/dd/yyyy ] [ TIME hh:mm:ss ] [ LOG number ]
Performs a partial dump of the transaction logs to assist the developer in problem resolution.
See also
6.12
ctrbldif - IFIL-based Rebuild Utility
Usage
A rebuild utility using the IFIL definitions stored in the header of a file:
ctrbldif DataFileName [ -x8 ] [ -purge ] [ -updifil ] [ -<sectors> ]
[ -temppath=<temporary_path> ] [ -sortmem=<n> ]
[ <UserId> ] [ <UserPassword> ] [ <ServerName> ]
Description
ctrbldif reads the IFIL structure from DataFileName and calls RebuildIFileXtd() to rebuild
DataFileName and its associated indices.
 -purge - Purge duplicate records.
 -updifil - Update the IFIL resource within the data file.
 -sortmem=<N> - Use N KB of memory for sorting. This option can be used to increase the
rebuild speed for large files.
 -idxseg=<M>@<S> - If creating index, use M automatic segments of size S. Size is specified
in megabytes, or you can specify MB or GB as a suffix. For example: -idxseg=10@1GB
c-treeACE Standalone Options
 -temppath= - directory path, <temporary_path>, to create temporary sort and purged record
files. (This standalone option is the equivalent of the TMP_PATH server configuration option.)
The default location is the current directory.
 -<sectors> - sector size, <sectors>. (in multiples of 128). The sector parameter is especially
useful if you need to adjust a file’s PAGE_SIZE (index node size) to match the c-treeACE
Server. c-treeACE standalone models default to 16 sectors (2048 byte node size) while the
c-treeACE Server defaults to 64 sectors (8192 bytes).
c-treeACE Server Options
 <UserID> : client user name to logon to a c-treeACE Server.
 <UserPassword> : client user password to authenticate to a c-treeACE Server.
 <ServerName> : c-treeACE Server name for a client to connect.
www.faircom.com
All Rights Reserved
75
Considerations
(for example, CMPIFILX8() or RBLIFILX8()), index files created by the compact or rebuild no
longer have the 6-byte transaction number attribute enabled if the specified extended create
block's x8mode field has the ctNO6BTRAN bit set.
Option to set index's automatic segment attributes
If a segmented index file was deleted and rebuilt using the ctrbldif utility or the rebuild API
function, the new index file was not segmented. The index file's segment attributes, which are
stored in the index file, were lost when the index file was deleted.
Beginning with V10.3, an option is provided with the rebuild and compact utilities that causes
index files that are created by the utilities to be created using automatic segments of the specified
size and maximum. The option is:
-idxseg=M@S
where M is the maximum number of segments and S is the segment size. S is interpreted as
megabytes by default. Two suffixes, MB and GB, are also supported. MB indicates that the value
is in megabytes and GB indicates that the value is in gigabytes.
Examples:
ctrbldif test.dat -idxseg=50@10
ctrbldif test.dat -idxseg=100@300MB
20 segments of 3 GB each:
ctrbldif test.dat -idxseg=20@3GB
Note: If the index files exist, the -idxseg option has no effect. It is only when the rebuild or
compact utility creates new index files because the old index files do not exist that the -idxseg
option affects the automatic segment properties of the index files.
www.faircom.com
All Rights Reserved
76
6.13
ctrdmp - Dynamic Dump Recovery or System Rollback
ctrdmp [ dumpscript ]
Used to restore dumps created with ctdump.
A successful ctrdmp completion always writes the following message to CTSTATUS.FCS:
DR: Successful Dump Restore Termination
A failed ctrdmp writes the following message to CTSTATUS.FCS when ctrdmp terminates
normally:
DR: Dump Restore Error Termination...: <cterr>
where <cterr> is the error code.
If for some reason ctrdmp terminates prematurely (for example, a fatal error causes ctrdmp to
terminate abnormally), the “Dump Restore Error Termination...” message might not be written to
CTSTATUS.FCS. In that case, ctrdmp might have written error messages to standard output or
to CTSTATUS.FCS before terminating that helps explain the reason for ctrdmp terminating
prematurely.
www.faircom.com
All Rights Reserved
77
Note: A 32-bit ctrdmp could fail with error 75 if run on transaction logs created by a 64-bit
c-treeACE Server, which might support more than 2048 connections.
In V11 and later, the ctfdmp, ctldmp, and ctrdmp utilities display the c-treeACE version used to
compile them when they are run.
Environment Variable for Advanced Encryption Password
If this utility has advanced encryption enabled, it can read an encrypted password file instead of
being prompted to enter the master password. To enable this, set the environment variable
CTREE_MASTER_KEY_FILE to the name of the encrypted master password file.
See also
6.14
ctsbld - Superfile rebuild pre-pass
The c-treeACE Superfile Recover Utility reconstructs data file members in place and empties
index file members. Index file members must be rebuilt via ctrbld, RBLIFIL() or ctindx.
Usage
ctsbld <superfile name>
Description
ctsbld processes the superfile in place. This utility “cleans” the data files and empties the index
files. This utility may also be incorporated into your application using the function
SuperfilePrepassXtd(). Afterward, the superfile must be processed by either ctrbld or the
RebuildIFile() function before it is usable. This utility is only operational in single-user mode. The
SuperfilePrepassXtd() function is available in single-user and client/server models.
6.15
ctsbldm - Rebuild Superfile Index Members
Usage
ctsbldm <DataFileName> [<Optional PageSize>]
For example:
ctsbldm suphost!myfile.dat 16384
Description
Ordinarily, the procedure to rebuild a superfile is to use ctsbld to prepare the entire superfile,
making the data good and returning space used by the indices. Then each set of ISAM files is
rebuilt. This approach is used since a superfile entwines all of the member files and no
assumptions are made about the integrity of the members.
ctsbldm permits the indices associated with a non-corrupt superfile member data file to be rebuilt
without having to process the entire superfile. It assumes that the data file contains an IFIL
www.faircom.com
All Rights Reserved
78
describing all the indices, that the data file is not corrupt, and that the superfile is in good shape
except for the indices in question.
One possible use for this utility is when recovery cannot repair an index. This rarely occurs, but
may be caused by a loop in the index leaf nodes. If this index is a member of a superfile, we can
now attempt to rebuild just the indices, and not process the entire superfile. The utility forces all
indices associated with the data file to be rebuilt.
The utility operates by opening the data and index files, deleting the index files, and then
rebuilding the index files.
6.16
ctscmp - Superfile Compact Utility
Usage
ctscmpi <filename> [-scanonly] [Y] [<sect>]
ctscmp <name of the superfile host to compact> [Y]
[new_sect_size]
Arguments
 <filename> The name of the superfile to compact or scan
 -scanonly Scan the superfile only; do not compact it. The -scanonly option generates details
from the header, extended header, IFIL, and DODA. It outputs the number of key values,
active records, deleted records and resource records. Using this utility with the -scanonly
option is useful for comparing superfiles before and after compacting them.
 Y An optional parameter; if specified, the utility compacts the file without prompting to confirm
(otherwise you will be prompted).
 <sect> An optional sector size of the resulting file (sect*128 = page size) to use for the new
superfile. If <sect> is omitted, the new superfile is created using the same page size as the
original superfile.
Description
The superfile compact utility, ctscmp, compacts and rebuilds a superfile and all of its members
provided the required IFIL resources are present in the superfile data members. It creates a
compacted version of the file in place, using a temporary file named CTREE.TMP as a
destination and then renaming it.
This utility is designed for the Standalone Single-user model. It compacts and rebuilds a superfile
and all of its members provided the required IFIL structures are in place. It creates a compacted
version of the file in place, using a temporary file named CTREE.TMP as a destination and then
renaming it.
The utility supports processing data and index member names having extensions other than .dat
and .idx.
A “% complete” progress indicator has been added to the ctscmp utility.
The ctscmp utility uses a standard error and warning message format. Error messages begin
with the text ‘Error:’ and warning messages with the text ‘Warning:’, so errors and warnings can
easily be located in the ctscmp output.
There is an ISAM-based version of the superfile compact utility named ctscmpi. This version of
the superfile compact utility uses ISAM c-tree functions rather than low-level c-tree functions to
www.faircom.com
All Rights Reserved
79
add records to the new compacted superfile. The advantage of using the ISAM approach is that
records are indexed as they are added, so the utility does not require a separate rebuild phase to
repopulate the indexes as the ctscmp utility does. Using this technique can significantly reduce
the time required to compact a superfile.
6.17
ctsfex - Superfile Data Export Utility
The ctsfex utility exports data from a superfile to another superfile or to individual files identical to
the superfile members. This high-performance utility exports the data without index updates,
transaction control, or file extension. After the data export is completed, the indices are rebuilt
and transaction control and file extension properties are restored on the newly-created files. This
utility also supports a multi-threaded version allowing each thread to process a superfile member.
Usage:
ctsfex sf1 [-f sf2 | -d dir] [-cCrovV] [-t thds] [-e key]
[-m recs] [-n size] [-T <path>] [-ctscmp <args>]
[-s svn] [-u uid] [-p upw]
Where:
 -f sf2 - Export to superfile sf2
 -d dir - Export to standard files in directory dir
 -c - Create the target files without exporting data.
 -C - Create AND export data for _isp@ and .group tables only.
 -r - Force replacement (overwrite) of existing files.
 -o - Force open of a corrupted file using the ctOPENCRPT file mode.
 -v - Open the superfile and its members to validate a superfile.
 -V - Used in conjunction with -v, this option validates records with a read.
 -m recs - Send record counter to stdout every recs records.
 -e key - Encrypt the target files with key
 -t threads - Maximum number of concurrent threads to use.
 -T <path> - Specify the location of temporary files created by the rebuild operation.
 -s server_name - Server name for connecting to the server.
 -u userID - User ID for connecting to the server.
 -p userpassword - User password for connecting to the server.
 -ctscmp <args> - Invoke the superfile compact utility, ctscmp with <args>.
Standalone Usage
In standalone mode an additional option is available to specify the index node size:
 -n size - Index node size to use (standalone mode only).
www.faircom.com
All Rights Reserved
80
6.18
ctsqlmgr - Migration Utility
The ctsqlmgr utility is used for migrating tables. This utility physically relocates data files for use
with c-treeACE SQL.
It is important to note the migrated new tables could very well not be accessible with your existing
ISAM application. If you have requirements to share data between existing ISAM applications and
c-treeACE SQL you should consider using the c-treeACE SQL Import Utility.
Usage:
ctsqlmgr <original file> <destination file> [-s <sect>] [-m <memory KB>]
 -s - The number of sectors.
 -m - The amount of memory (in KB) to use during the rebuild process (50Mb default).
See Also
 Migrating to c-treeACE SQL (http://docs.faircom.com/doc/sqlops/41034.htm) in the c-treeSQL
Server Operations and Utilities Guide
www.faircom.com
All Rights Reserved
81
7.
Utilities for Stored Procedures,
User-Defined Functions & Triggers
To simplify the process of deploying SP, UDF, and triggers to multiple servers, these new
command-line utilities can be used to dump and deploy:
 dbschema (page 82) - Dump utility option for exporting compiled SP, UDF, and triggers.
 dbdeploy (page 82) - Deploy utility for loading exported SP, UDF, and triggers on other
servers.
7.1
dbschema – Option to dump SP, UDF, and triggers
A new option has been added to the dbschema utility that allows stored procedures,
user-defined functions, and triggers to be exported so they can be deployed to other c-treeACE
Servers using dbdeploy. The dbschema -b option is used to dump stored procedures, user
defined functions, and triggers in binary format compatible with dbdeploy:
Usage
dbschema [-d] [-b] [-u username] [-a authentication] [-o outputfile]
[-t tablenamelist] [-p procedure_name_list]
[-f function_name_list] [-T trigger_name_list]
[dbsegment_name]
 -d - Dump the data.
 -b - Dump stored procedures, user-defined functions, or triggers in binary format so they can
be deployed using dbdeploy.
 -o - Output file (default: screen).
7.2
dbdeploy – Utility to deploy SP, UDF, and triggers
A new SQL tool, dbdeploy, is used to deploy stored procedures, user defined functions, and
triggers to c-treeACE SQL servers that have been exported using the dbdump tool.
Usage
The syntax is as follows:
dbdeploy [-f] [-u username] [-a authentication] [-i inputfile]
[dbsegment_name]
 -u - Username identifiable to the DBMS.
 -a - Password for authentication.
www.faircom.com
All Rights Reserved
82
Utilities for Stored Procedures, User-Defined Functions & Triggers
 -i - Input file.
 -f - Force overwriting of existing items.
7.3
Password Security
The dbdeploy and dbdump command-line utilities are intended to be password-friendly.
However, our customers’ need for security is of great concern. Therefore, utility source code is
provided and can be compiled directly into existing customer application utilities such that existing
security controls can be leveraged.
7.4
Requirements to Develop and Deploy (JDK, JRE)
With the use of the dump and deploy utilities, it is no longer necessary to have both a JDK and
JRE on every server.
 Develop: A JDK is required to develop and compile SP, UDF, and triggers on one server, but
is not required for servers with deployed procedures.
 Deploy: A JRE is required on a server to run SP, UDF, and triggers.
www.faircom.com
All Rights Reserved
83
Copyright Notice
Copyright © 1992-2016 FairCom Corporation. All rights reserved. No part of this publication may be stored in a retrieval
system, or transmitted in any form or by any means, electronic, mechanical, photocopying, recording or otherwise without
the prior written permission of FairCom Corporation. Printed in the United States of America.
Information in this document is subject to change without notice.
Trademarks
c-treeACE, c-treeRTG, c-treeAMS, c-tree Plus, c-tree, r-tree, FairCom and FairCom’s circular disc logo are trademarks of
FairCom, registered in the United States and other countries.
The following are third-party trademarks: AMD and AMD Opteron are trademarks of Advanced Micro Devices, Inc.
Macintosh, Mac, Mac OS, and Xcode are trademarks of Apple Inc., registered in the U.S. and other countries.
Embarcadero, the Embarcadero Technologies logos and all other Embarcadero Technologies product or service names
are trademarks, service marks, and/or registered trademarks of Embarcadero Technologies, Inc. and are protected by the
laws of the United States and other countries. Business Objects and the Business Objects logo, BusinessObjects, Crystal
Reports, Crystal Decisions, Web Intelligence, Xcelsius, and other Business Objects products and services mentioned
herein as well as their respective logos are trademarks or registered trademarks of Business Objects Software Ltd.
Business Objects is an SAP company. HP and HP-UX are registered trademarks of the Hewlett-Packard Company. AIX,
IBM, POWER6, POWER7, and pSeries are trademarks or registered trademarks of International Business Machines
Corporation in the United States, other countries, or both. Intel, Intel Core, Itanium, Pentium and Xeon are trademarks or
registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. Microsoft, the .NET
logo, the Windows logo, Access, Excel, SQL Server, Visual Basic, Visual C++, Visual C#, Visual Studio, Windows,
Windows Server, and Windows Vista are either registered trademarks or trademarks of Microsoft Corporation in the
United States and/or other countries. Novell and SUSE are registered trademarks of Novell, Inc. in the United States and
other countries. Oracle and Java are registered trademarks of Oracle and/or its affiliates. QNX and Neutrino are
registered trademarks of QNX Software Systems Ltd. in certain jurisdictions. CentOS, Red Hat, and the Shadow Man logo
are registered trademarks of Red Hat, Inc. in the United States and other countries, used with permission. UNIX and
UnixWare are registered trademarks of The Open Group in the United States and other countries. Linux is a trademark of
Linus Torvalds in the United States, other countries, or both. Python and PyCon are trademarks or registered trademarks
of the Python Software Foundation. OpenServer is a trademark or registered trademark of Xinuos, Inc. in the U.S.A. and
other countries. Unicode and the Unicode Logo are registered trademarks of Unicode, Inc. in the United States and other
countries.
Btrieve is a registered trademark of Actian Corporation.
ACUCOBOL-GT, MICRO FOCUS, RM/COBOL, and Visual COBOL are trademarks or registered trademarks of Micro
Focus (IP) Limited or its subsidiaries in the United Kingdom, United States and other countries.
isCOBOL and Veryant are trademarks or registered trademarks of Veryant in the United States and other countries.
All other trademarks, trade names, company names, product names, and registered trademarks are the property of their
respective holders.
Portions Copyright © 1991-2016 Unicode, Inc. All rights reserved.
Portions Copyright © 1998-2016 The OpenSSL Project. All rights reserved. This product includes software developed by
the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/).
Portions Copyright © 1995-1998 Eric Young (eay@cryptsoft.com). All rights reserved. This product includes cryptographic
software written by Eric Young (eay@cryptsoft.com). This product includes software written by Tim Hudson
(tjh@cryptsoft.com).
Portions © 1987-2016 Dharma Systems, Inc. All rights reserved. This software or web site utilizes or contains material
that is © 1994-2007 DUNDAS DATA VISUALIZATION, INC. and its licensors, all rights reserved.
Portions Copyright © 1995-2013 Jean-loup Gailly and Mark Adler.
7/20/2016
8.
Index
A
Administrative Utilities - Client .................................. 2
Administrative Utilities - Standalone ....................... 36
ADMINISTRATOR OPTIONS ................................. 31
C
Copyright Notice ................................................ lxxxiv
ct_ver - Display c-treeACE version that created
file ....................................................................... 64
ctadmn - Server Administrator Utility ........................ 2
ctalgn - Change Alignment ..................................... 49
ctcfgset - Server Configuration File Encoding
Utility ................................................................... 36
ctchkbin - Checking for affected tables................... 64
ctclntrn Utility - Clean Transaction Mark ................. 65
ctcmdset - Configuration File Encoding Utility ........ 37
CTCMPC - File compaction .................................... 49
ctcmpcif - IFIL-based Compact Utility .................2, 66
ctcnfg - System Configuration Example ................. 50
ctcpvf - Master Password Verification File Utility .... 37
CTCV43 - Convert V4.3 Data File to c-tree
Format................................................................. 50
ctcv67 - Extended File Conversion Utility ............... 50
ctdbpartidxent - Utility to Enable GUIx Key
Count Optimization ............................................... 4
ctdidx - Create flat key file ...................................... 53
ctdmpidx - Index Dump Utility ................................. 53
ctdump - Dynamic Dump Utility ................................ 5
ctencrypt - Utility to Change Master Password ...... 70
ctfchk - File Checksum Utility ................................. 38
ctfdmp - Forward Dump Utility ................................ 72
ctfilbkif - File Block Utility .......................................... 7
ctfileid - Update File IDs .....................................9, 73
ctfixbin - Fixing Affected Tables.............................. 73
ctflat - Create c-treeACE file from a flat file ............ 54
ctflvrfy - Index Verify Utility ..................................... 55
cthghtrn - Displays the high-water mark for
transactions ........................................................ 39
ctidmp - Examine Dump Files ................................. 74
ctindx - Create index file from flat key file ............... 57
ctinfo - ISAM File Info .......................................45, 74
ctixmg - Incremental ISAM / Resource sample ...... 46
ctldmp - Transaction Log Dump ............................. 75
ctpass - Password Utility .......................................... 9
ctpathmigr - Change Internal Path Separators ....... 10
ctpkey - Print key utility ........................................... 58
ctpotp - Parameter to OTP conversion ................... 58
ctptoi - Parameter to IFIL conversion ..................... 58
ctquiet - Quiesce c-treeACE Utility ......................... 10
ctrbld - Parameter file rebuild utility ........................ 59
ctrbldif - IFIL-based Rebuild Utility....................11, 75
ctrdmp - Dynamic Dump Recovery or System
Rollback ............................................................. 77
ctredirect - IFIL Update Utility for Redirected
Filenames .......................................................... 39
ctsbld - Superfile rebuild pre-pass ......................... 78
ctsbldm - Rebuild Superfile Index Members .......... 78
ctscmp - Superfile Compact Utility ......................... 79
ctsfex - Superfile Data Export Utility ................ 47, 80
ctsfil - Superfile contents ........................................ 59
ctsqlcdb - c-treeACE SQL Database
Maintenance Utility............................................. 14
ctsqlimp .................................................................. 14
ctsqlimp - SQL Import Utility .................................. 14
ctsqlmgr - Migration Utility ..................................... 81
ctsqlutl - c-treeSQL Maintenance Utility ................ 16
ctstat - Statistics Monitoring Utility ......................... 16
ctstop - Server Stop Utility ..................................... 18
ctsysm - Server Status Monitoring Utility ............... 19
cttrap - Communications Trap Playback utility ...... 20
cttrap - TRAP_COMM Utility .................................. 21
cttrnmod - Change Transaction Mode Utility ... 23, 41
ctunf1 - File Reformatting Utility............................. 59
ctupdpad - Update the c-treeDB Pad Resource
Utility .................................................................. 61
ctvfyfil - File Verify Utility ........................................ 62
ctvfyidx - Index Verify Utility ................................... 61
ctvlqa - Variable-length quality assurance utility.... 47
D
dbdeploy – Utility to deploy SP, UDF, and
triggers ............................................................... 82
dbdump - Data Unload Utility ................................. 26
dbload - Data Load Utility ...................................... 27
dbschema – Option to dump SP, UDF, and
triggers ............................................................... 82
dbschema - Schema Export Utility......................... 28
deploy .................................................................... 82
develop (dump and deploy) ............................. 82, 83
dump ...................................................................... 82
F
FairCom Command-Line Tools................................ 1
FILE OPTIONS ...................................................... 34
G
GROUP OPTIONS................................................. 33
I
ISQL ................................................................. 29, 48
J
JDK ........................................................................ 83
JRE ........................................................................ 83
O
Option to set index's automatic segment
attributes ...................................................... 12, 76
www.faircom.com
All Rights Reserved
85
Index
P
Password Security .................................................. 83
R
Requirements to Develop and Deploy (JDK,
JRE) .................................................................... 83
S
sa_admin - Command-line security
administration utility ............................................ 30
Scripting a Dynamic Dump ....................................... 6
U
Updates in handling of security attributes3, 13, 69, 77
USER OPTIONS..................................................... 31
Utilities - Client ........................................................ 45
Utilities - Low Level ................................................. 49
Utilities - Standalone ............................................... 64
Utilities for Stored Procedures, User-Defined
Functions & Triggers ........................................... 82
www.faircom.com
All Rights Reserved
86

Command-Line Tools

Transcription

Similar documents

Setting up Accounting information from PrintNet

verdiem rbo printlogistix - St. Louis Green Business Challenge

instructions for housing deposit ($250.00 usd)

Brochure - West Grove Borough

Clik here to open the Sterkinekor Moviestop: Membership Card Guide

DVU Log-in Credentials

September 2012 - Randolph Family Housing

ETRM Solutions - Primetech Systems Inc.

Teacher Pages

4. Select the “My Lexile Range” drop down. Now, click search. 2