Once the FairCom Server is installed on the operating system, it is ready to be used. Starting and stopping the FairCom Server are basic Administrator responsibilities, therefore this chapter is required reading.
ctadmn - Server Administrator Utility
The FairCom Server Administrator Utility, ctadmn, is used by an Administrator to manage general server operations including configuring users, groups and files. It can also be used to monitor the users logged on to the FairCom Server and to disconnect any user from the c-FairCom Server.
To use this utility, do the following (which may vary between environments, depending on user-interface specifics):
- Start running the program, ctadmn, as any other program in the environment.
- Enter an ADMIN group User ID. Initially, only ADMIN will exist until you create others.
- Supply the current password for the User ID given.
- If this is the first time ctadmn has been run and the password for the User ID ADMIN is still ADMIN, change it before leaving ctadmn to ensure secure access to this program in the future. You can also change your password using ctpass (see Controlling FairCom Server Access).
- You will be prompted for the (optional) file password for the file FAIRCOM.FCS. We recommend you do NOT give this file a password since you should already be the only one who can run this utility. To confirm the absence of a password, press the return key.
- In response to the next prompt, supply the current name for the FairCom Server and press enter. If the FairCom Server name has not been changed (see Basic Keywords for details on SERVER_NAME), simply press Enter to use the default name.
Authentication File - This utility supports the use of an encoded password file. Encoded password files keep user IDs and passwords from plain view when the utility is used within a script file. They are created with the ctcmdset utility. The plain text form of the file should be:
; User Id
USERID ADMIN
; User Password
PASSWD <pass>Use the -1 option to specify the name of the encoded file.
Menus
After finishing these steps, the main menus for the FairCom Server Administrator Utility will be displayed, allowing access to the following groups of operations:
1. User Operations
2. Group Definitions
3. File Security
4. Monitor Clients
5. Server Information (IOPERFORMANCE)
6. Server Configuration (SystemConfiguration)
7. Stop Server
8. Quiesce the Server
9. Monitor Server Activity
10. Change Server SettingsThe following sections detail the areas controlled by the Administrator Utility. The steps necessary for each operation may vary slightly in different environments.
Note: While using the Administration Utility, press the question mark key (‘?’) at any prompt to access Help.
User Operations
User operations available in ctadmn are as follows:
- Add New User by:
- Entering a new User ID. (The ID is limited to alphanumeric characters, hyphens, underscores, and periods. A hyphen cannot be the first character in a name.)
- (optional) Enter a long name (i.e., a text string) for use as a User Description (e.g., for screen displays, where the User ID may be too terse).
- (optional) Enter a User Memory Limit, which is a maximum memory allocation for this particular user that will override maximum memory allocations set at the server-level (for any user) or at the group level (for any particular group).
- (optional) Enter the User Memory Rule: Absolute, Guideline, or Default. See USR_MEM_RUL in Configuring the FairCom Server for details.
- (optional) Enter a user password.
- (optional) Assign user membership in from 1 to 128 Groups (i.e., Group IDs).
- (optional) Enter the first valid date for this User ID.
- (optional) Enter the last valid date for this User ID.
- (optional) Enter limit on consecutive logon failures if different from system default. See LOGON_FAIL_LIMIT in Miscellaneous Control for details.
- Remove an existing User ID.
- List authorized User IDs.
- Change the Password for a given User ID.
- Change which Group(s) a User ID is associated with by adding (up to 128) or removing groups from a list of a User’s association with Group IDs.
- Change the User Description, i.e., change the long name identifying the User ID.
- Change User Memory. Change the maximum amount of FairCom Server memory a given user can consume.
- Change Extended Logon Validation, including start date, end date, and consecutive logon failures.
- Change User Logon Limit limits users to a specified number of concurrent logons based on their user name. By default, the limit is zero, meaning no limit.
Group Definitions
Group definition operations available in ctadmn are as follows:
- Add New Group by:
- Entering a new Group ID.
- (optional) Entering a long name (i.e., a text string) for use as a Group Description (e.g., to display, where the Group ID may be too terse).
- (optional) Entering a Group Memory Allocation, which is a maximum memory allocation for Users who are a member of this particular Group, and will override maximum memory allocations set at the server-level (for any user).
- Remove an Existing Group ID.
- List Groups: List all current Group IDs and descriptions.
- Change Group Membership: Add or remove User IDs from a given Group.
- Change Group Description: Change the long name for the Group ID.
- Change Group Memory: Change the maximum amount of server memory user in a given group can consume.
- Change Group Logon Limit: Limit users to a specified number of concurrent logons based on their group membership. By default, the limit is zero, meaning no limit.
File Security
File security operations that can be performed on a given file using ctadmn are as follows:
- Change the File’s Password.
- Change the File’s Permission Mask, controlling file operation permissions for three classes of users: World, Group, and File Owner.
- Change the File’s Group.
- Change the File’s Owner.
Note: Applications can be designed so separate data files and/or index files can be joined into a “superfile,” which is a single physical file from the point of view of the operating system. Separate “logical” files within a superfile are called superfile member files. From the point of view of the Administrator, superfiles, member files, and separate data or index files are all treated the same way.
Monitor Clients
The Administrator may want to know which users are currently attached to the FairCom Server or may want to force a user to disconnect from the FairCom Server. These functions are available:
- List Attached Users.
- Disconnect Users.
Note: Users IDs are associated with Task users (i.e., sessions). It is a task, or session, that is actually terminated. If a User is disconnected using ctadmn, the CTSTATUS.FCS entry is augmented by the terminated user ID and node name.
Server Information
This prompt provides performance information since the last startup of the FairCom Server.
The following is an example of the server performance statistics:
==============================================================
============ Server performance statistics =================
============ Values are since last startup =================
==============================================================
data buffer requests = 382
data buffer hits = 364
data buffer hit rate = 95 %
index buffer requests = 77
index buffer hits = 73
index buffer hit rate = 94 %
# of read operations = 113
bytes read = 226761
# of write operations = 20
bytes written = 91264
==============================================================
Press RETURN to continue...
Server Configuration
This prompt provides configuration information since the last startup of the FairCom Server.
Note that FairCom DB developers can retrieve much of this information using the SystemConfiguration() function.
The following is an example of current server resource values:
=============== Current Server Resource Values ===============
current system memory usage = 229825491 (219.178 MB)
highest system memory use = 229825491 (219.178 MB)
current system net allocations = 51292
c-tree Plus files opened by system = 15
physical c-tree Plus files open = 6
c-tree Plus file control blocks in use = 18
# message in delete node queue = 0
# message in checkpoint queue = 0
# messages in system monitor queue = 0
current # of logons = 1
current # of pending locks (system wide) = 0
maximum number of logons = 32
limit for the maximum number of logons = 32
maximum number of client nodes = no limit
maximum number of connections per node = no limit
remote connections allowed = YES
c-tree Server process ID = 3115
c-tree Server version = V11.8.0.xxxxx(Build-190607)
================================================================
Press RETURN to continue...
Stop Server
This prompt allows the Administrator to stop the FairCom Server. ctadmn will ask for verification that the FairCom Server is to be stopped and ask for a shutdown delay in seconds.
Note: If the Replication Agent is running on a server, replication should be stopped before trying to stop the server. If replication is running when you attempt to stop the server, you will see error 792 (External server shutdown disabled).
Quiesce Server
The Quiesce Server option allows an administrator to immediately block all access from clients to the server while maintaining a consistent server state.
Successful Quiesce.
It is now safe to perform a system backup of FairCom DB Server's controlled files.
Press RETURN once the backup is completed to resume the FairCom DB Server.
Press RETURN to continue...While in this state all data and index files are physically closed and can be safely copied, backed up, or moved. Simply press RETURN to bring the server back online to clients.
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.
When the administrator selects the ctadmn utility's option to quiesce a FairCom Server, ctadmn checks for active transactions. If any transactions are active, ctadmn prompts the user for a maximum time to wait for transactions to complete. That value is passed to the ctQUIET() function, which waits up to the specified number of seconds before aborting active transactions and quiescing FairCom Server.
Monitor Server Activity
From this menu an administrator can quickly obtain lists of files, including by connection, as well as locks on a particular file. These options are useful in determining active file usage by applications.
The "Purge SYSLOG entries" option (available with V13), prompts for the number of days of activity to keep. "0 Days" results in a truncate, while larger values use the regular per record approach. See the SYSLOG TRUNCATE Server System Event Log Keyword.
Monitor Server Activity:
1. List all files open by the FairCom DB Server
2. List all files open by a particular connection
3. List connections that have a particular file open
4. List locks held on a particular file
5. Close a file that is open in KEEPOPEN mode
6. Purge SYSLOG entries
Enter your choice (1-6), or 'q' to return to previous menu>>
Change Server Settings
FairCom DB allows certain options to be enabled/disabled at run time. This ctadmn menu displays available options. As the list grows over time, you may find additional entries not specifically listed here.
Change Server Settings:
1. Configure function monitor
2. Configure checkpoint monitor
3. Configure memory monitor
4. Configure request time monitor
5. Change dynamic dump sleep time
6. Change dynamic dump sleep interval
7. Enable or disable a status log mask option
8. Change advanced encryption master password
9. Change a DIAGNOSTICS option
10. Change the specified configuration option
Enter your choice (1-10), or 'q' to return to previous menu>>Dynamic Data and Index Cache
Memory caching of data is one of the most important subsystems of a database server, including FairCom DB. Caching allows the database process to optimally serve clients with data directly from memory when possible. Separate independent memory caches are used for data and indexes (buffers). Proper cache sizing is a critical performance tuning task of the database administrator. Too little memory, and the database engine becomes bottlenecked with persisted storage I/O. Too much, and not enough memory is made available to the operating system and other applications running on the host machine.
Cache resizing is a powerful feature for performance tuning with increasing database loads. Adding additional client connections, thus increasing user concurrency, frequently benefits from larger caches. Another situation is a very large ad-hoc database load or query where temporarily having a larger memory cache improves overall performance. Changing a cache size requires restarting the FairCom DB server process which is not an easy task in the 24/7 enterprise environment.
FairCom DB "hard" allocates memory for caches at server startup directly from the OS memory heap. Once allocated, the memory is permanently associated with the database for the life of the process. Allocated memory is chunked into page size blocks within the memory cache subsystem, historically making it difficult to resize as needed. An additional complication is how to handle existing data residing in cache. Losing that "hot" data will likely result in performance loss for connected applications until a runtime steady state is again achieved over time.
FairCom has had increasing requests for ability to change cache sizes at runtime and this release introduces dynamic cache resizing. Now, you can fine tune data and index caches as performance demands based on database connections and load avoiding costly database down time.
How to Resize Your Current Cache
The server administrator utility, ctadmn, supports a new configuration option set_cache_options as a parameter. This is followed with a null-terminated JSON string with desired options. Supported cache options are as follows:
-
"timeout": <timeoutInSeconds> where <timeoutInSeconds> is the maximum number of seconds to wait for active transactions to complete when quiescing the server in order to change the cache sizes. The default timeout is 1 second.
-
"dat_memory": "<new_data_cache_size>" where <new_data_cache_size> is an integer cache size followed by optional suffix such as mb for megabytes or gb for gigabytes. For example, "dat_memory": "100 mb". If not specified, the data cache size is not changed.
-
"idx_memory": "<new_index_cache_size>" where <new_index_cache_size> is an integer cache size followed by optional suffix such as mb for megabytes or gb for gigabytes. For example, "idx_memory": "200 mb". If not specified, the index cache size is not changed.
-
"keep_cached_data": "<yes_or_no>" where <yes_or_no> is either yes, which means the currently-cached data is kept in the data cache, or no, which means the currently-cached data is removed from the data cache. The default is yes.
- "keep_cached_nodes": "<yes_or_no>" where <yes_or_no> is either yes, which means the currently-cached nodes are kept in the index cache, or no, which means the currently-cached nodes are removed from the index cache. The default is yes.
Administrator Utility Usage
From ctadmn, choose option 10 "Change the specified configuration option"
Change Server Settings:
1. Configure function monitor
2. Configure checkpoint monitor
3. Configure memory monitor
4. Configure request time monitor
5. Change dynamic dump sleep time
6. Change dynamic dump sleep interval
7. Enable or disable a status log mask option
8. Change advanced encryption master password
9. Change a DIAGNOSTICS option
10. Change the specified configuration option
11. Change Logon Block Settings
Enter your choice (1-11), or 'q' to return to previous menu>> 10
Enter the configuration option and its value >> set_cache_options {"dat_memory": "200 mb"}
Successfully changed the configuration option.
Press RETURN to continue...Expected Status Log Messages
The resize request triggers an internally generated server quiesce state with the following common messages.
Mon Jun 13 13:47:51 2022 - User# 00030 ctQUIET: attempt quiet transaction state with action: 1100a0x timeout: 1 sec
Mon Jun 13 13:47:51 2022 - User# 00030 ctQUIET: blocking call with action: 641a2x
Mon Jun 13 13:47:54 2022 - User# 00030 Transaction aborted at ctQTaborttran for user# 33: 817
Mon Jun 13 13:47:54 2022 - User# 00030 Transaction aborted at ctQTaborttran for user# 40: 817
Mon Jun 13 13:47:54 2022 - User# 00030 Transaction aborted at ctQTaborttran for user# 47: 817
Mon Jun 13 13:47:54 2022 - User# 00030 Transaction aborted at ctQTaborttran for user# 52: 817
Mon Jun 13 13:47:54 2022 - User# 00030 Transaction aborted at ctQTaborttran for user# 58: 817
Mon Jun 13 13:47:54 2022 - User# 00030 Transaction aborted at ctQTaborttran for user# 65: 817
Mon Jun 13 13:47:54 2022 - User# 00030 ctQUIET: end of blocking call
Mon Jun 13 13:47:54 2022 - User# 00030 Using 3 index node LRU lists with 3962 buffers per list
Mon Jun 13 13:47:54 2022 - User# 00030 ctQUIET: unblocking call with action: 809e00x
Mon Jun 13 13:47:55 2022 - User# 00030 ctQUIET: end of unblocking callExamples
- Set data cache size to 100 MB and keep existing data in cache (since "keep_cached_data" defaults to "yes"). No change to index cache. In this example, if data cache is already 100 MB, no action is taken:
-
set_cache_options {"dat_memory": "100 mb"}
-
- Set data cache size to 100 MB and remove all data from data cache:
-
set_cache_options {"dat_memory": "100 mb", "keep_cached_data": "no"}
-
- Keep current data cache size and remove all data from data cache:
-
set_cache_options {"keep_cached_data": "no"}
-
- Set index cache size to 200 MB and keep existing nodes in cache:
-
set_cache_options {"idx_memory": "200 mb"}
-
- Set index cache size to 200 MB and remove all nodes from index cache:
-
set_cache_options {"idx_memory": "200 mb", "keep_cached_nodes": "no"}
-
- Keep current index cache size and remove all nodes from index cache:
-
set_cache_options {"keep_cached_nodes": "no"}
-
This example shows actions on both data and index cache:
set_cache_options {"dat_memory": "500 mb", "idx_memory": "400 mb", "keep_cached_nodes": "no", "timeout": 5}
Direct SDK API
An application that is logged in as the ADMIN user can change data and/or index caches by calling the ctSETCFG() API function with option of setcfgCONFIG_OPTION and value set to:
set_cache_options {<cache_options>}
where <cache_options> is the null-terminated string in JSON format.
This example showing how to change the cache sizes in C or C++ code by calling the ctSETCFG() API function:
NINT rc;
rc = ctSETCFG(setcfgCONFIG_OPTION, "set_cache_options {\"dat_memory\": \"100 mb\"}");
Diagnostic Logs
The configuration option DIAGNOSTICS RESIZE_CACHE, which can be specified in ctsrvr.cfg and changed at runtime, causes cache resize diagnostic messages to be logged to CTSTATUS.FCS.
See Also
ctadmn user listing for rtexecute thread running report launched by RTSCRIPT
The Communications section of the user listing shows rtexecute for threads launched by RTSCRIPT calls. Below is an example listing:
UserID: --- NodeName:
Task 15 Communications: rtexecute
Memory: 1512K Open Files: 8 Logon Time: --
Tran Time: -- Rqst Time: 0:30 InProcess Rqst# 0 -unknown-This is analogous to how the launched dynamic dump thread, idyndmp, is listed. The listing states which thread to kill if one is using ctadmn to stop a report. Killing the thread that shows RTSCRIPT as the last function called will not interrupt the report being compiled by rtexecute.
ctstop - Server Stop Utility
Operational Model:
- Client
Usage
ctstop [ -auto ] [ <AdminId> <AdminPassword> <ServerName> [ delay ] ]
This utility shuts down a FairCom Server.
Passing the -auto switch to ctstop without specifying a ServerName, AdminPassword, or AdminID shuts down a FairCom Server with the defaults shown below:
ctstop -AUTO ADMIN ADMIN FAIRCOMS
The ctstop utility supports passing in ServerName, AdminPassword, 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 and a maximum of 60 seconds.
Note: If the Replication Agent is running on a server, replication should be stopped before trying to stop the server. If replication is running when you attempt to stop the server, you will see error 792 (External server shutdown disabled).
Authentication File
This utility supports the use of an encoded password file. Encoded password files keep user IDs and passwords from plain view when the utility is used within a script file. They are created with the ctcmdset utility. The plain text form of the file should be:
; User Id
USERID ADMIN
; User Password
PASSWD <pass>Use the -1 option to specify the name of the encoded file.
ctstat - Statistics Utility
The FairCom DB Statistics Utility, ctstat, is a client utility used to display statistics collected by FairCom DB. This utility provides valuable real-time monitoring of critical FairCom DB operations.
Operational Model:
- Client
Usage
# ctstat report_type [-s svn] [-u uid] [-p upw] [-i int [cnt]] [-h frq] [-d] [-m] [-t]
Reports:
| -clf | Get the CHECKLOCK_FILE list entries |
| -deleted_files | Deleted Files Report |
| -file [csv] | File Activity Report |
| -filelist listname | List the entries on the specified file list |
| -filelocks file [N] | List all locks on a data file. Display Nth key |
| -fileops | File Operation Activity Report |
| -func | Function Timing Report |
| -funcfile | Function timing by File Report |
| -iotime on|off | Turn disk I/O call timing on or off |
| -isam | ISAM Activity Report |
| -ma logfile | Log aggregate memory allocations to the specified file |
| -meminfo | Server Memory Info Report |
| -mf logfile | Log all memory allocations to the specified file |
| -ml | Get current memory allocation statistics |
| -mr min,max | Log only memory allocation statistics |
| -ms | Output memory allocation statistics |
| -mt options |
Set memory allocation tracking options. Examples: -mt +ALL -mt +PI8TYP, -MBATYP |
| -mu | Unload module debug symbols |
| -sql | SQL Activity Report |
| -text | System Activity Report |
| -tranlog_flush | Transaction Log Flush Fixed Histogram Report |
| -userinfo | User Report with stats from USERINFO() function |
| -userinfox | User Report with stats from USERINFOX() function |
| -userlocks user | List all locks held by a user |
| -vaf file... | Admin-File Report |
| -vah handle... | Admin-User Report by User Handle |
| -var | Admin-Replication Reader Report |
| -vas | Admin-System Report |
| -vat | Admin-Transaction Report |
| -vau user... | Admin-User Report by User Name |
| -vtf file... | Tivoli-File Report |
| -vts | Tivoli-System Report |
| -wrktime on|off|reset | Turn function call timing on or off, or reset statistics |
Options:
| -d | Show cache stats as delta |
| -h frq | Print a description header every frq outputs |
| -i int [cnt] | Pause int seconds for optional cnt times |
| -I int [cnt] | Pause int seconds also before first row for optional cnt times |
| -m | Show memory file stats when using -vaf report |
| -p upw | User password |
| -s svn | c-tree Server name |
| -t | Output timestamp with header |
| -u uid | User name |
Authentication File
This utility supports the use of an encoded password file. Encoded password files keep user IDs and passwords from plain view when the utility is used within a script file. They are created with the ctcmdset utility. The plain text form of the file should be:
; User Id
USERID ADMIN
; User Password
PASSWD <pass>Use the -1 option to specify the name of the encoded file.
-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:
- The displayed key is from before or after any changes made by the lock holder.
- The locked offset no longer holds a valid record (it has been deleted, or updated and moved).
- 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)
-fileops Notes
Database resource consumption requires close monitoring of all file I/O activities. FairCom DB tracks values for additional physical file operations. The following values are tracked:
- logical file opens
- logical file closes
- physical file opens
- physical file closes
- file creates
- file renames
- file deletes
Each value is a cumulative value since server startup, stored as an 8-byte integer field in the system snapshot structure.
The counters include every call, not just successful calls. Note that the physical file open count can be smaller than the physical file close count, because when a file is created it does not increment the physical file open count.
The ctstat utility supports a new option, -fileops, that displays these counters. Example:
ctstat -fileops -t -i 1 -h 10 -u ADMIN -p ADMIN -s FAIRCOMS
logopn/s logcls/s phyopn/s phycls/s filcre/s filren/s fildel/s total/s
0 0 0 0 0 0 0 0
0 0 0 0 0 0 0 0
154 158 23 26 13 0 3 377
959 926 70 63 25 0 4 2047
1016 989 4 0 0 1 1 2011
574 562 0 0 0 0 0 1136
481 486 2 0 0 0 0 969
425 417 0 0 0 0 0 842
376 380 0 0 0 0 0 756The ctstat -fileops option requires a server that uses snapshot version 21 or later. If this option is used with a server that uses an earlier version of the utility, the utility fails with the error message:
Error: The -fileops option requires snapshot version 21, but this server is using snapshot version <version>.
where <version> is the older snapshot version that FairCom DB is using.
The snapshot file parsing utility, ctsnpr, has been updated to support the new SNAPSHOT.FCS file format.
-tranlog_flush notes:
The -tranlog_flush displays the transaction log flush histogram values. Use the -d option to display delta values. Otherwise, ctstat displays the cumulative histogram values. For example:
C:\> ctstat -tranlog_flush -h 1 -t -d -u ADMIN -p ADMIN -s FAIRCOMS -d
Fri Oct 4 16:24:30 2024
Since server startup:
tranlog flush count: 21761
tranlog flush time: 25.737986
tranlog flush average: 0.001183
Since last checkpoint:
tranlog flush count: 2
tranlog flush time: 0.007201
tranlog flush average: 0.003600
Since last sample:
tranlog flush count: 324
tranlog flush time: 0.495657
tranlog flush average: 0.001530
adaptive histogram adjustments: 3
time since most recent adjustment: 0
time since fixed histogram last cleared: 18
fixed histogram adaptive histogram
count time count time
132 < 0.001000 0 < 0.000031
0 < 0.002000 0 < 0.000062
192 < 0.003000 0 < 0.000093
0 < 0.004000 0 < 0.000124
1 < 0.005000 0 < 0.000155
0 < 0.006000 0 < 0.000186
0 < 0.007000 0 < 0.000217
0 < 0.008000 0 < 0.000248
0 < 0.009000 0 < 0.000279
0 < 0.010000 0 < 0.000310
0 < 0.011000 0 < 0.000341
0 < 0.012000 0 < 0.000372
0 < 0.013000 0 < 0.000403
0 < 0.014000 0 < 0.000434
0 < 0.015000 0 < 0.000465
0 < 0.016000 0 < 0.000496
0 < 0.017000 0 < 0.000527
0 < 0.018000 0 < 0.000558
0 < 0.019000 0 < 0.000589
0 < 0.020000 0 < 0.000620
0 < 0.021000 1 < 0.000651
0 < 0.022000 0 < 0.000682
0 < 0.040000 [0 avg] 1 < 0.001240 [0 avg]
0 >= 0.040000 0 >= 0.001240-userinfox Notes
In V11.6 and later, the -userinfox option displays extended connection information. For example:
ctstat -userinfox -u ADMIN -p ADMIN -s FAIRCOMS -h 1 -t -i 1
status lastrequest trntime mem fils time uid/tid/nodename commprotocol readops readbytes writeops writebytes datarqsts datahits indexrqsts indexhits
0s busy TRANEND 0s 96K 1 3s CTQA/21/(2) ctqa FSHAREMM 643 35831372 706 16111449 18569 17930 2535 2535
0s busy USERINFOX -- 76K 2 11s ADMIN/22/ctstat FSHAREMM 4 16544 0 0 12 11 0 0
0s busy TRANEND 0s 70K 1 3s CTQA/23/(3) ctqa FSHAREMM 566 31750812 507 14227936 23180 22614 1467 1467
0s busy FRSVREC 0s 75K 1 3s CTQA/24/(4) ctqa FSHAREMM 754 41842916 520 16605870 32476 31722 2484 2484
0s busy FRSVREC 0s 90K 1 3s CTQA/25/(5) ctqa FSHAREMM 833 46135384 649 19387611 25274 24441 3602 3602
0s busy TRANEND 0s 94K 1 3s CTQA/26/(6) ctqa FSHAREMM 760 43814980 548 16663966 28098 27339 2700 2700
2s busy RRDREC 2s 236K 5 3s CTQA/27/(13) ctqa FSHAREMM 560 11343722 644 3677007 853 793 2033 1898
0s busy FRSREC 0s 253K 2 3s CTQA/28/(8) ctqa FSHAREMM 819 52887780 1690 53585664 40324 39518 6342 6341
0s busy TRANABT 0s 260K 2 3s CTQA/29/(9) ctqa FSHAREMM 776 50069732 1456 45076587 38689 37925 5968 5968
0s busy TRANEND 0s 183K 2 3s CTQA/30/(10) ctqa FSHAREMM 0 0 2198 44113920 0 0 776 776
0s busy NXTREC 0s 2956K 1 2s CTQA/31/(18) ctqa FSHAREMM 455 29557760 361 15667386 10848 10397 2 2
2s busy BATSETX 3s 16950K 6 3s CTQA/32/(12) ctqa FSHAREMM 17139 142302504 45462 42391289 10232 8130 80823 80756
-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.
Filelocks and Userlocks Note: Dumping large quantities of locks in a very active system could affect performance.
List files on internal server lists
In V12 and later, ctstat provides a list of files on specific internal server lists, such as ctKEEPOPEN.
Example
C:\> ctstat ‑filelist keepopen_list ‑u ADMIN ‑p ADMIN ‑d ‑h 1 ‑t ‑s FAIRCOMS
Fri Dec 20 09:29:39 2019
value member scale filename
1 0 0 mark.dat
-isam header changed to avoid misunderstanding
The header of the ctstat -isam command displays a /s suffix to indicate that the statistics are per second. For example, the following syntax will produce the output below:
ctstat.exe -s FAIRCOMS -u ADMIN -p ADMIN -h 2 -isam
add/s del/s upd/s read/s total/s
0 0 0 0 0
0 0 0 0 0
add/s del/s upd/s read/s total/s
0 0 0 0 0Note: This constitutes a Compatibility Change.
Admin-System Report -vas
The admin-system (-vas) report displays FairCom DB Server system-wide statistics in the areas of cache usage, disk I/O, open files, established client connections, file locks, and transactions.
Example
Below is a sample admin-system report produced by executing the command:
ctstat -vas -u ADMIN -p ADMIN -s FAIRCOMS -h 10 -i 2
| cache | disk i/o | files | connect | locks | transactions | ||||||||||
| d%h | %m | i%h | %m | r/s | w/s | cur/max | cur/max | cur | l%h | %m | dead | act | t/s | r/t | w/t |
| 99 | 1 | 99 | 1 | 1 | 1 | 2581/10000 | 2/128 | 0 | 100 | 0 | 0 | 1 | 36 | 0 | 0 |
| 99 | 1 | 99 | 1 | 2 | 0 | 2581/10000 | 2/128 | 0 | 100 | 0 | 0 | 1 | 35 | 0 | 0 |
| 99 | 1 | 99 | 1 | 2 | 0 | 2581/10000 | 2/128 | 0 | 100 | 0 | 0 | 1 | 28 | 0 | 0 |
| 99 | 1 | 99 | 1 | 0 | 0 | 2581/10000 | 2/128 | 0 | 100 | 0 | 0 | 1 | 22 | 0 | 0 |
The columns shown in this report are described as follows:
d%h Data cache hit rate
%m Data cache miss rate [100 - Data cache hit rate]
i%h Index cache hit rate
%m Index cache miss rate [100 - Index cache hit rate]
r/s Disk reads per second
w/s Disk writes per second
cur Current number of open files
max Server limit on number of open files
cur Current number of client connections
max Server limit on number of client connections
cur Number of locks currently held
l%h Lock hit rate [(lock attempts - locks blocked - locks denied) / lock
attempts]
%m Lock miss rate [100 - Lock hit rate]
dead Number of dead locks detected
act Current number of active transactions
t/s Number of transactions per second
r/t Number of read operations per transaction
w/t Number of write operations per transaction
log save Avg log save time per interval (microseconds) when used with the delta (-d) option
Tivoli-System Report -vts
The Tivoli-system (-vts) report displays FairCom DB Server system-wide statistics in the areas of cache usage, disk I/O, open files, established client connections, file locks, and transactions. The Tivoli-system report displays much of the same statistics that the admin-system (-vas) report displays, but in a format appropriate for input to tools such as the Tivoli monitoring application.
Example
Below is a sample Tivoli-system report produced by executing the command:
ctstat -vts -u ADMIN -p ADMIN -s FAIRCOMS -h 10 -i 2
#%cachehit %cachemiss r/s w/s maxfiles openfiles totalconnections activetransactions numdeadlock trans-r/s trans-w/s %hashhit %hashmiss transactions/s
92 8 0 0 10000 18 1 0 0 0 0 100 0 0
92 8 0 9 10000 18 1 0 0 0 17 100 0 1
92 8 0 0 10000 18 1 0 0 0 0 100 0 1
92 8 0 0 10000 18 1 0 0 0 0 100 0 1
92 8 0 1 10000 18 1 0 0 0 1 100 0 1
92 8 0 0 10000 18 1 0 0 0 0 100 0 1Note: The header line shown in this example is written as a single output line although it may be shown on multiple lines here.
The columns shown in this report are described as follows:
%cachehit Data and index cache hit rate
%cachemiss Data and index cache miss rate
r/s Disk reads per second
w/s Disk writes per second
maxfiles Server limit on number of open files
openfiles Current number of open files
totalconnections Current number of client connections
activetransactions Current number of active transactions
numdeadlock Number of dead locks detected
trans-r/s Number of read operations per transaction
trans-w/s Number of write operations per transaction
%hashhit Lock hit rate
%hashmiss Lock miss rate
transactions/s Number of transactions per second
Admin-File Report -vaf
The admin-file (-vaf) report displays FairCom DB Server statistics for the specified file. Note that multiple data or index files can be specified on the command line. Below is a sample admin-file report produced by executing the command:
ctstat -vaf mark.dat mark.idx -u ADMIN -p ADMIN -s FAIRCOMS -h 10
r/s w/s entries locks l%h %m dlock recrd node t filename
2 4 11863 4 100 0 0 128 n/a F mark.dat
0 4 11863 2 96 4 0 n/a 32768 I mark.idx
1 3 12192 4 100 0 0 128 n/a F mark.dat
0 9 12192 3 97 3 0 n/a 32768 I mark.idx
2 4 12730 5 100 0 0 128 n/a F mark.dat
0 3 12730 1 97 3 0 n/a 32768 I mark.idx
2 4 13236 5 100 0 0 128 n/a F mark.dat
0 2 13236 0 97 3 0 n/a 32768 I mark.idxThe columns shown in this report are described as follows:
r/s Disk reads per second for the file
w/s Disk writes per second for the file
entries Number of data records or key values in file
locks Number of locks currently held on file
l%h Lock hit rate for the file
%m Lock miss rate for the file
dlock Number of dead locks detected for the file
recrd Record length if data file, otherwise n/a
node Node size if index, otherwise n/a
t File type (F=fixed-length data, V=variable-length data, I=index)
filename Name of the file
Tivoli-File Report -vtf
The Tivoli-file (-vtf) report displays FairCom DB Server statistics for the specified file in a format appropriate for input to tools such as the Tivoli monitoring application.
Below is a sample Tivoli-file report produced by executing the command:
ctstat -vtf mark.dat mark.idx -u ADMIN -p ADMIN -s FAIRCOMS -h 10
#r/s w/s currentlocks waitinglocks filename
0 0 5 0 mark.dat
0 0 1 1034 mark.idx
1 3 4 0 mark.dat
0 6 0 1120 mark.idx
3 5 5 0 mark.dat
0 0 0 1208 mark.idx
2 4 4 0 mark.dat
0 0 2 1324 mark.idx
2 4 5 0 mark.dat
0 3 2 1402 mark.idxThe columns shown in this report are described as follows:
r/s Disk reads per second for the file
w/s Disk writes per second for the file
currentlocks Number of locks currently held on file
waitinglocks Cumulative lock wait count
filename Name of the file
Admin-User Report -vau
The admin-user report, -vau user..., displays FairCom DB Server statistics for the specified users. All existing connections whose user ID match the specified user ID are displayed.
Example
Below is a sample admin-user report produced by executing the command:
ctstat -vau GUEST -u ADMIN -p ADMIN -s FAIRCOMS -h 10
log function sec fil lok l%h %m dlock tid/uid/nodename
7s TRANEND 0 2 1 98 2 0 GUEST/10/
7s ADDREC 0 2 2 98 2 0 GUEST/12/
7s ADDREC 0 2 1 98 2 0 GUEST/13/
7s ADDREC 0 2 0 98 2 0 GUEST/14/
0s ctSNAPSHOT 0 2 0 0 0 0 ADMIN/15/ctstat
7s ADDREC 0 2 0 98 2 0 GUEST/17/The columns shown in this report are described as follows:
log Total logon time for client
function Function client is currently executing
sec Current function request time
fil Current number of files open by this client
lok Current number of locks held by this client
l%h Lock hit rate for this client
%m Lock miss rate for this client
dlock Number of deadlocks detected for this client
tid/uid/nodename Server thread ID/User ID/Node name for this client
Function Timing Report -func
The function timing report (-func) displays FairCom DB Server statistics for each c-tree function that a client has called at least once since function timing was enabled. See -wrktime.
Below is a sample function timing report produced by executing the command:
ctstat -func -u ADMIN -p ADMIN -s FAIRCOMS -h 10
function counter secs
FRSVSET 10 0.002
NXTVSET 20 0.001
GETDODAX 2 0.000
COMMBUF 1 0.000
ctSNAPSHOT 10 0.002The columns shown in this report are described as follows:
function Function name
counter Cumulative number of times this function has been called
secs Cumulative elapsed time for this function
Text Report -text
The following command generates a report in text format:
ctstat -text -u ADMIN -p ADMIN -s FAIRCOMS -h 10
This command writes a FairCom DB Server system snapshot to the file SNAPSHOT.FCS (output to the data folder). See the file SNAPSHOT.FCS for the detailed server statistics.
Example Output (truncated for brevity)
Server Shutdown System Snapshot
Wed May 22 15:36:41 2019
server version of structure: 21
bit map of var len contents: 0x
snapshot time stamp (seconds since 1970): 1558557401
elapsed server operation time: 173106.444
high res timer ticks per sec: 10000000
compatibility flag #1: 00002000x
compatibility flag #2: 00020000x
compatibility flag #3: 00000000x
compatibility flag #4: 00000000x
diagnostic flag #1: 40000000x
diagnostic flag #2: 00000000x
diagnostic flag #3: 00000000x
ct_udefer yield threshold (usec): 0
ct_udefer 64 yield duration (usec): 0
delete node thread queue reads: 2908
delete node thread queue writes: 2908
delete node thread queue rewrites: 0
delete node thread queue abandons: 0
delete node thread queue removals: 0
delete node thread queue no action: 0
count of lock attempts: 21708
subcount of hdr lock attempts: 2135
count of locks freed: 21707
count of locks denied: 0
count of locks blocked: 0
subcount of header blocks: 0
count of blocks released: 0
count of dead locks: 0
count of killed locks: 0
current count of locks held: 1
current count of blocked requests: 0
maximum count of locks held: 161
COMMIT LOCK loop defer (millisecs): 10
COMMIT LOCK loopers: 0
COMMIT LOCK total loop count: 0
cumulative blk record lock count: 0
cumulative blk record lock time: 0.000 (seconds)
maximum blk record lock time: 0.0000
cumulative blk index lock count: 0
cumulative blk index lock time: 0.000 (seconds)
maximum blk index lock time: 0.0000
cumulative transaction count: 369
cumulative transaction time: 534.255 (seconds)
average transaction time: 1.44784
transaction time detail:
122 < 0.05000
8 < 0.10000
5 < 0.15000
3 < 0.20000
16 < 0.25000
63 < 0.30000
69 < 0.35000
20 < 0.40000
11 < 0.45000
12 < 0.50000
5 < 0.55000
2 < 0.60000
1 < 0.65000
0 < 0.70000
0 < 0.75000
0 < 0.80000
1 < 0.85000
0 < 0.90000
0 < 0.95000
0 < 1.00000
1 < 1.05000
0 < 1.10000
1 < 2.00000 [avg of 0 per unit width]
29 >= 2.00000
maximum transaction time: 102.2966
checkpoint delay (microseconds): 0
commit delay block to clear ration: 2
commit delay cohort size base: 50
commit delay nominal time (microseconds): 2000
I/O Time Statistics -iotime
The FairCom DB Server SNAPSHOT feature includes support for collecting disk read and write timings on a per-file basis when high-resolution timer support is activated. Use the ctstat utility’s -iotime option to toggle the collection of disk I/O timings.
- Turn on disk I/O timings:
# ctstat -iotime on -u ADMIN -p ADMIN -s FAIRCOMS
- Turn off disk I/O timings:
# ctstat -iotime off -u ADMIN -p ADMIN -s FAIRCOMS
The ctstat utility’s -vaf option also outputs differential I/O timings for each file when the FairCom DB Server returns version 2 (or higher) GFMS structure statistics.
Example
C:\> ctstat -vaf mark.dat mark.idx -h 1 -i 10
r/s w/s read time write time entries locks l%h %m dlock recrd node t filename
0 0 0 0 26239 1 100 0 0 128 n/a F mark.dat
0 0 0 0 26239 0 99 1 0 n/a 8192 I mark.idx
r/s w/s read time write time entries locks l%h %m dlock recrd node t filename
128 237 1 12 108309 2 100 0 0 128 n/a F mark.dat
0 2 0 0 108308 0 99 1 0 n/a 8192 I mark.idx
r/s w/s read time write time entries locks l%h %m dlock recrd node t filename
121 243 1 14 186164 2 100 0 0 128 n/a F mark.dat
2 27 0 4 186163 0 99 1 0 n/a 8192 I mark.idx
r/s w/s read time write time entries locks l%h %m dlock recrd node t filename
109 219 1 10 256356 2 100 0 0 128 n/a F mark.dat
3247 3296 39 77 256355 0 99 1 0 n/a 8192 I mark.idx
r/s w/s read time write time entries locks l%h %m dlock recrd node t filename
103 206 1 10 322381 4 100 0 0 128 n/a F mark.dat
5623 5640 67 124 322380 1 99 1 0 n/a 8192 I mark.idx
I/O Statistics per File -file
The FairCom DB Server SNAPSHOT feature supports a mode to write snapshot statistics for all files open by the FairCom DB Server to disk. Use the ctstat utility’s -file option. The snapshot statistics for all open files are then written to the SNAPFILE.FCS file in comma-delimited or human-readable format.
CSV Example
Write statistics for all open files to SNAPFILE.FCS in comma-delimited format using the ctstat utility:
# ctstat -file csv -i 1 1
Sample SNAPFILE.FCS Contents
On-Demand File Snapshot
Mon Jun 25 16:40:51 2007
physical file size,logical file size,serial number,active entries,tran high mark,update timestamp,max file size,read ops,bytes read,write ops,bytes written,memory file high bytes,read time (msec.),write time (msec.),index height,file id,server id,time id,node size,record length,permanent file mode,max leaf key bytes,max non-leaf key bytes,file type,key length,key member number,number of members, super file type,max leaf marks,wrthdr sequence number,total lock attempts,header lock attempts,total lock wait count,header lock wait count,deadlocks,total locks denied,total locks freed,total blocks released,current locks held,current blocked requests,max special cache pages,current special cache pages,number of buffer pages,number of data cache pages,number of channels,number of users with file open,current memory record count,highest memory record count,killed locks,max segments,active segments,update flag,file type,duplicate key flag,index delete type,key padding byte,flavor,alignment,pointer size,file name
16384,16384,0,15,0,0,0,0,0,5,16768,0,0,0,-1,0x00000000,0x00000000,0x00000000,8192,0,0x00000000,8148,8174,1,12,0,0,0,2048,3,44,23,0,0,0,0,44,0,0,0,0,0,0,0,1,1,0,0,0,1,0,0xff,0,0,0,32,2,8,4,I0000001.FCS
====================Human Readable Example
Write statistics for all open files to SNAPFILE.FCS in human-readable format using the ctstat utility:
# ctstat -file -i 1 1
Sample SNAPFILE.FCS Contents
On-Demand File Snapshot
Tue Jun 26 09:58:28 2007
phyrec numrec sernum nument hghtrn tstamp mxfilz fredops fredbyt fwrtopts fwrtbyt mhghbyt fredtim fwrttim idxhgt fileid servid timeid nodsiz reclen logtyp maxkbl maxkbn filtyp keylen kmem nmem suptyp maxmrk hdrseq floktry flokhlk flokblk flokhbk flokdlk flokdny flokfre flokrel flokcur fblkcur datlmt datspl bufcnt datcnt numchn fusrcnt memcnt hghcnt flokkil segmax seglst updflg ktype autodup deltyp keypad flflvr flalgn flpntr filename
16384 16384 0 15 0 0 0 1 8192 10 57728 0 0 0 -1 0x00000000 0x00000000 0x00000000 8192 0 0x00000000 8148 8174 1 12 0 0 0 2048 3 68 35 0 0 0 0 68 0 0 0 0 0 0 0 1 1 0 0 0 1 0 0xff 0 0 0 32 2 8 4 I0000001.FCS
====================
Connection Information -userinfo and -userinfox
Connection reporting options -userinfo and -userinfox are available to display additional statistics about existing user connections.
New information included in this alternative output:
- The status and idle time of the connection.
- The last FairCom DB Server request made.
- Time spent in a transaction.
- Amount of memory consumed by the client.
- Number of files open by the client.
- The time the user has been logged in.
- User ID, Thread ID, and Nodename of the user.
- User communication protocol used to connect to the FairCom DB Server. Because the column labeled uid/tid/nodename is not fixed in size, the space between nodename and commprotocol is a tab character. Even if the output is not properly aligned, the parsing will be easy by looking for a '\t' (tab).
-userinfo Example
ctstat.exe -userinfo -u ADMIN -p ADMIN -s FAIRCOMS -h 5
status lastrequest trntime mem fils time uid/tid/nodename commprotocol
0s busy ADDVREC 1s 596K 46 11s ADMIN/22/cttctx(p26576,t27692) FSHAREMM
58m00s idle tmexec -- 7626K 7 58m00s ADMIN/23/SLCDESK SQL_SHAREMM
0s busy ADDVREC 1s 189K 46 11s ADMIN/25/cttctx(p26576,t9220) FSHAREMM
0s busy DELVREC 0s 185K 46 11s ADMIN/26/cttctx(p26576,t31684) FSHAREMM
0s busy DELVREC 0s 186K 46 11s ADMIN/27/cttctx(p26576,t28564) FSHAREMM
0s busy DELVREC 0s 187K 46 11s ADMIN/28/cttctx(p26576,t27780) FSHAREMM
0s busy ADDVREC 0s 592K 46 12s ADMIN/22/cttctx(p26576,t27692) FSHAREMM
58m01s idle tmexec -- 7626K 7 58m01s ADMIN/23/SLCDESK SQL_SHAREMM
0s busy ADDVREC 0s 186K 46 12s ADMIN/25/cttctx(p26576,t9220) FSHAREMM
0s busy ADDVREC 0s 185K 46 12s ADMIN/26/cttctx(p26576,t31684) FSHAREMM
0s busy ADDVREC 0s 186K 46 12s ADMIN/27/cttctx(p26576,t28564) FSHAREMM
0s busy ADDVREC 0s 186K 46 12s ADMIN/28/cttctx(p26576,t27780) FSHAREMM
0s busy DELVREC 0s 593K 46 13s ADMIN/22/cttctx(p26576,t27692) FSHAREMM
58m02s idle tmexec -- 7626K 7 58m02s ADMIN/23/SLCDESK SQL_SHAREMM-userinfox Example
In V11.6 and later, the -userinfox option displays extended connection information. For example:
ctstat -userinfox -u ADMIN -p ADMIN -s FAIRCOMS -h 1 -t -i 1
status lastrequest trntime mem fils time uid/tid/nodename commprotocol readops readbytes writeops writebytes datarqsts datahits indexrqsts indexhits
0s busy TRANEND 0s 96K 1 3s CTQA/21/(2) ctqa FSHAREMM 643 35831372 706 16111449 18569 17930 2535 2535
0s busy USERINFOX -- 76K 2 11s ADMIN/22/ctstat FSHAREMM 4 16544 0 0 12 11 0 0
0s busy TRANEND 0s 70K 1 3s CTQA/23/(3) ctqa FSHAREMM 566 31750812 507 14227936 23180 22614 1467 1467
0s busy FRSVREC 0s 75K 1 3s CTQA/24/(4) ctqa FSHAREMM 754 41842916 520 16605870 32476 31722 2484 2484
0s busy FRSVREC 0s 90K 1 3s CTQA/25/(5) ctqa FSHAREMM 833 46135384 649 19387611 25274 24441 3602 3602
0s busy TRANEND 0s 94K 1 3s CTQA/26/(6) ctqa FSHAREMM 760 43814980 548 16663966 28098 27339 2700 2700
2s busy RRDREC 2s 236K 5 3s CTQA/27/(13) ctqa FSHAREMM 560 11343722 644 3677007 853 793 2033 1898
0s busy FRSREC 0s 253K 2 3s CTQA/28/(8) ctqa FSHAREMM 819 52887780 1690 53585664 40324 39518 6342 6341
0s busy TRANABT 0s 260K 2 3s CTQA/29/(9) ctqa FSHAREMM 776 50069732 1456 45076587 38689 37925 5968 5968
0s busy TRANEND 0s 183K 2 3s CTQA/30/(10) ctqa FSHAREMM 0 0 2198 44113920 0 0 776 776
0s busy NXTREC 0s 2956K 1 2s CTQA/31/(18) ctqa FSHAREMM 455 29557760 361 15667386 10848 10397 2 2
2s busy BATSETX 3s 16950K 6 3s CTQA/32/(12) ctqa FSHAREMM 17139 142302504 45462 42391289 10232 8130 80823 80756
ISAM Statistics -isam
The FairCom DB Server system SNAPSHOT includes counters for ISAM record add, delete, update and read operations. The ctstat utility includes an -isam option which displays various ISAM counters, such as Adds/second, Deletes/second, Updates/second, Reads/second, and totals.
Example
# cstat -isam -u ADMIN -p ADMIN -s FAIRCOMS
add/s del/s upd/s read/s total/s
10216 10215 0 10215 30646
10113 10114 0 10114 30341
10147 10146 0 10146 30439
10164 10165 0 10165 30494
10070 10069 0 10070 30209
Enable Function Call Times by File -wrktime
The FairCom DB Server SNAPSHOT support collects c-tree function call counts and timings on a per-c-tree file basis. This support enhances the FairCom DB server’s existing support for collecting c-tree function call counts and timings, which are collected as totals for all files. Enabling collection of c-tree function timings now enables collection of both the total and file-specific function timings.
The ctstat utility includes a -wrktime option to enable the collection of this data. Accepted values are case sensitive and include:
on | off | reset.
Note:
ctstat -wrktime on enables the collection of function timing data; it does not generate any output.
ctstat -text is needed to see output to SNAPSHOT.FCS,
ctstat -funcfile sends per-file timings to SNAPFUNC.FCS.
ctstat -func sends the function timing output to stdout.
Example
Turn on function call timings:
# ctstat -wrktime on -u ADMIN -p ADMIN -s FAIRCOMS
Turn off function call timings:
# ctstat -wrktime off -u ADMIN -p ADMIN -s FAIRCOMS
Reset function call timings:
# ctstat -wrktime reset -u ADMIN -p ADMIN -s FAIRCOMS
Example Output in SNAPSHOT.FCS
function name count elapsed average
DELVREC 4681 25.656 0.00548
CLISAM 1 0.000 0.00004
STPUSR 2 0.000 0.00035
SETDEFBLKX 46 0.017 0.00038
GTEVREC 4684 1.697 0.00036
GETSEG 138 0.000 0.00000
GETMAP 138 0.000 0.00000
CREIFIL 23 4.605 0.20023
CLIFIL 23 3.262 0.14185
INTISAM 8 0.000 0.00003
SETNODE 5 0.000 0.00017
ADDVREC 4707 35.760 0.00759
SETOPS 28 0.000 0.00000
GETFIL 46 0.000 0.00000
CTSRVCTL 1 0.043 0.04377
GETDODAX 276 0.006 0.00002
OPNRFIL 139 0.861 0.00619
ctSNAPSHOT 2 0.029 0.01482
Function Call Times by File -funcfile
The FairCom DB Server SNAPSHOT function supports a mode that writes function timings for all files open by the FairCom DB Server to disk. Use the ctstat utility’s -funcfile option to output these timing statistics for all open files to SNAPFUNC.FCS (output to the data folder) in either a comma-delimited format (adding the csv option), or a human readable format shown below:
CSV Example
# ctstat -funcfile csv -i 1 1
SNAPFUNC.FCS Contents
On-Demand Function Snapshot
Tue Jun 26 13:22:40 2007
DELVREC,DELVREC,ADDREC,ADDREC,RWTREC,RWTREC,GETALTSEQ,GETALTSEQ,SETDEFBLKX,SETDEFBLKX, ...
count,time,count,time,count,time,count,time,count,time,count,time,count,time,count,time,...
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,I0000001.FCS
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,D0000000.FCS
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,FAIRCOM.FCS
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,FAIRCOM.FCS!USER.dat
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,FAIRCOM.FCS!USER.idx
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,FAIRCOM.FCS!GROUP.dat
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,FAIRCOM.FCS!GROUP.idx
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,FAIRCOM.FCS!UG.dat
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,FAIRCOM.FCS!UG.idx
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,FAIRCOM.FCS!UG.idx M#01
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,FAIRCOM.FCS!UVAL.dat
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,FAIRCOM.FCS!UVAL.idx
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,SYSLOGIX.FCS
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,SYSLOGDT.FCS
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,SYSLOGIX.FCS M#01
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,SYSLOGIX.FCS M#02
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,D0000001.FCS
0,0,590737,502096,698884,347088,0,0,2,0,0,0,0,0,5,0,0,0,0,0,20,0,mark.dat
0,0,0,0,0,0,5,0,0,0,0,0,5,0,0,0,322988,136944,0,0,0,0,mark.idx
0,0,0,0,0,0,5,0,0,0,0,0,5,0,0,0,376483,171571,0,0,0,0,mark.idx M#01
0,0,0,0,0,0,5,0,0,0,0,0,5,0,0,0,0,0,0,0,0,0,mark.idx M#02
====================Human-readable Example
# ctstat -funcfile -i 1 1
SNAPFUNC.FCS Contents
On-Demand Function Snapshot
Wed Jun 27 15:26:06 2007
ADDREC RWTREC GTEREC
count time count time count time filename
0 0 0 0 0 0 I0000001.FCS
0 0 0 0 0 0 D0000000.FCS
0 0 0 0 0 0 FAIRCOM.FCS
0 0 0 0 0 0
0 0 0 0 0 0 FAIRCOM.FCS!USER.dat
0 0 0 0 0 0 FAIRCOM.FCS!USER.idx
0 0 0 0 0 0 FAIRCOM.FCS!GROUP.dat
0 0 0 0 0 0 FAIRCOM.FCS!GROUP.idx
0 0 0 0 0 0 FAIRCOM.FCS!UG.dat
0 0 0 0 0 0 FAIRCOM.FCS!UG.idx
0 0 0 0 0 0 FAIRCOM.FCS!UG.idx M#01
0 0 0 0 0 0 FAIRCOM.FCS!UVAL.dat
0 0 0 0 0 0 FAIRCOM.FCS!UVAL.idx
0 0 0 0 0 0 SYSLOGIX.FCS
0 0 0 0 0 0 SYSLOGDT.FCS
0 0 0 0 0 0 SYSLOGIX.FCS M#01
0 0 0 0 0 0 SYSLOGIX.FCS M#02
0 0 0 0 0 0 D0000001.FCS
9910 74592 1380 10993 0 0 mark.dat
0 0 0 0 1381 67772 mark.idx
0 0 0 0 0 0 mark.idx M#01
0 0 0 0 0 0 mark.idx M#02
====================Function Timing Limitations
- The function timings for a file are reset to zero when the file is physically closed.
- As currently implemented, the c-tree function timings do not track c-tree API function calls made by FairCom DB SQL clients.
Memory File Usage -m
The ctstat utility supports an option, -m, that when specified with the -vaf report option, causes ctstat to output the following additional memory file statistics:
- 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.
Example
# ctstat -vaf disk.dat mem.dat -h 1 -i 2 -m
r/s w/s entries locks l%h %m dlock recrd node t phyrec mhghbyt memcnt hghcnt filename
0 0 n/a 0 100 0 0 15 n/a V 1923110761 1923110761 19232 19232 mem.dat
0 0 3 0 0 0 0 128 n/a F 4096 0 0 0 disk.dat
Transaction Statistics -vat
Use ctstat -vat to view the transaction statistics. Sample output is shown below.
- loglow is the server's lowest-numbered active log.
- curlog is the server's current log.
- lstent is the offset in the current log where the last entry was written (which may still be in the in-memory log buffer).
- lstpnt is the last byte position written to the log file on disk.
- lstsuc is the offset of the last SUCTRAN or CLSTRAN entry in the log.
- tranno is the next available transaction number.
- tfil is the next available transaction file number.
| lowlog | curlog | lstent | lstpnt | lstsuc | tranno | tfil |
| 1 | 4 | 2702686 | 2702092 | 2697872 | 51806 | 17298 |
File and User Lock -filelocks
Retrieve lock information by file or by user.
Note: Dumping large quantities of locks in a very active system could affect performance.
Filelocks
For the -filelocks report:
- -filelocks file [N] lists all locks on a data file. Displays the Nth key. Keys are displayed in hexadecimal format following each lock.
Example
>ctstat -filelocks custmast.dat -u ADMIN -p ADMIN -s FAIRCOMS -i 1 1
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. Because the records used to generate the key are locked by other users, there is no guaranteed relationship between the lock and the displayed key. The following are possible scenarios:
- The displayed key is from before or after any changes made by the lock holder.
- The locked offset no longer holds a valid record (it has been deleted, or updated and moved).
- 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.
Userlocks
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.
Example
To identify all locks and associated files held by Task ID 23
>ctstat -userlocks 23 -u ADMIN -p ADMIN -s FAIRCOMS -i 1 1
./cxd01.dat
---
./cxd03.dat
---
./cxd05.dat
---
./cxd23.dat
0x0000000000004dd1 Write 25 0 ADMIN
To identify all locks and associated files held by user SALLY
>ctstat -userlocks SALLY -u ADMIN -p ADMIN -s FAIRCOMS -i 1 1
./cxd01.dat
0x00000000000055e5 Write 21 0 ADMIN
./cxd04.dat
0x0000000000004dd1 Write 25 0 ADMIN
./cxd10.dat
0x0000000000004dd1 Write 24 0 ADMINBecause 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.
List files on Internal Server Lists
-filelist [ list_type ]
Support List Types
- keepopen_list - list of file marked as ctKEEPOPEN within the server. For example, memory files and files specified with KEEPOPEN_LIST.
Example
C:\> ctstat ‑filelist keepopen_list ‑u ADMIN ‑p ADMIN ‑d ‑h 1 ‑t ‑s FAIRCOMS
Fri Dec 20 09:29:39 2019
value member scale filename
1 0 0 mark.dat
Memory Use and Allocation Call Stacks -ml -mt
It is possible to monitor memory use and allocation call stacks for each suballocator list.
Support has been added for monitoring FairCom Server memory use and collecting allocation call stacks for each suballocator list. The ability to monitor FairCom Server's memory use has been enhanced in the following ways:
- It now tracks the number and byte count of allocations that do not go through FairCom DB's memory suballocator.
- FairCom Server now makes its memory suballocator usage figures available to monitoring tools. The ctstat utility's ‑ml option can be used to display current memory allocation figures. Example:
# ctstat -ml -t -i 2 -h 1 -s FAIRCOMS
Thu May 01 14:31:22 2014
name allocated in use pct
KLNTYP 0 0 0.00%
PI1TYP 32768 1704 0.01%
PI2TYP 32768 6800 0.01%
PI4TYP 1376256 1224360 0.31%
PI8TYP 1245184 1155592 0.28%
PIwTYP 32768 19008 0.01%
PIxTYP 32768 16120 0.01%
PIyTYP 49152 25800 0.01%
PIzTYP 32768 0 0.01%
PIaTYP 82560 69768 0.02%
PIbTYP 296064 270600 0.07%
SHDTYP 0 0 0.00%
BATTYP 0 0 0.00%
ILKTYP 16384 0 0.00%
FNMTYP 0 0 0.00%
COMTYP 16384 0 0.00%
ABTTYP 0 0 0.00%
LOKTYP 16384 0 0.00%
DCMTYP 0 0 0.00%
IXCTYP 32129024 29018360 7.24%
DTCTYP 6782976 6547464 1.53%
CTCTYP 81920 70000 0.02%
IXBTYP 180854968 180854968 40.74%
DTBTYP 203169792 203169792 45.76%
MBATYP 17690815 17690815 3.98%
TOTAL: 443971703 440141151Note: If memory allocation call stack is enabled for a suballocator list, the name of the suballocator list is followed by an asterisk in this output (for example, as MBATYP*).
Just as the ctstat utility does, a FairCom Server client can read the memory use figures by calling the ctSNAPSHOT() API function with the new mode ctPSSmemAlloc. This mode returns the memory use figures in a new structure named ctGMMS. See ctstat.c for an example of this ctSNAPSHOT() call.
- On Windows and Linux systems, FairCom Server supports collection of call stacks for memory allocations. The ctMEMSTAT() API function is used to change these settings, and the ctstat utility's ‑mt option provides a convenient way to use this function.
Only a member of the ADMIN group is allowed to change memory allocation settings.
Memory Suballocator List Descriptions
- KLNTYP - key buffer, size of the largest supported maximum key value (MAXLEN = 1024)
- PI1TYP - allocations of size > 0 and <= PI_UNIT (PI_UNIT = 16)
- PI2TYP - allocations of size > PI_UNIT and <= 2 * PI_UNIT
- PI4TYP - allocations of size > 2 * PI_UNIT and <= 4 * PI_UNIT
- PI8TYP - allocations of size > 4 * PI_UNIT and <= 8 * PI_UNIT
- PIwTYP - allocations of size > 8 * PI_UNIT and <= 16 * PI_UNIT
- PIxTYP - allocations of size > 16 * PI_UNIT and <= 32 * PI_UNIT
- PIyTYP - allocations of size > 32 * PI_UNIT and <= 64 * PI_UNIT
- PIzTYP - allocations of size > 64 * PI_UNIT and <= 128 * PI_UNIT
- PIaTYP - allocations of size > 128 * PI_UNIT and <= 256 * PI_UNIT
- PIbTYP - allocations of size > 256 * PI_UNIT and <= 512 * PI_UNIT
- SHDTYP - preimage space list entry, size of SHADLST structure (the variable-length contents are allocated separately if larger than ctSHADOWlen)
- BATTYP - batch retrieval list entry, size of BATLST structure
- ILKTYP - user lock table list entry, size of LOKS structure
- FNMTYP - file name, size of the largest supported file name (MAX_NAME = 255)
- COMTYP - commit node list entry, size of COMLST structure
- ABTTYP - abort node list entry, size of ABTLST structure
- LOKTYP - system lock table list entry, size of RECLOK structure
- DCMTYP - commit data list entry, size of COMLST structure
- IXCTYP - index cache page control structure, size of TREEBUFF structure (allocated at startup and does not change after that)
- DTCTYP - data cache page control structure, size of DATBUF structure (allocated at startup and does not change after that)
- CTCTYP - system file control block entry, size of CTFILE structure
- IXBTYP - index cache page buffer, size of PAGE_SIZE + MAXLEN + 2 * sizeof(ctRECPT) (allocated at startup and does not change after that)
- DTBTYP - data cache page buffer, size of PAGE_SIZE (allocated at startup and does not change after that)
- MBATYP - allocation size > 512 * PI_UNIT
Examples:
- Enable memory allocation call stack collection for all suballocator lists:
ctstat -mt +ALL -u ADMIN -p ADMIN -s FAIRCOMS
- Enable memory allocation call stack collection for only the MBATYP and LOKTYP suballocator lists:
ctstat -mt +MBATYP,+LOKTYP -u ADMIN -p ADMIN -s FAIRCOMS
- Disable memory allocation call stack collection for all suballocator lists:
ctstat -mt -ALL -u ADMIN -p ADMIN -s FAIRCOMS
As before, the current memory allocations can be logged to a file using the ctMEMSTAT() function, as used by the ctstat utility's ‑ma option:
ctstat -ma mem.log -i 1 1 -u ADMIN -p ADMIN -s FAIRCOMS
Compatibility Notes:
- The use of the existing and new memory monitoring options is now restricted to members of the ADMIN group.
- If troubleshooting unexpected memory growth, first use ctstat ‑ml to monitor memory use by suballocator list. Then enable memory allocation call stack collection just for the lists that show the unexpected growth. This approach can reduce the overhead of the memory allocation call stack collection and can simplify analysis of the unexpected memory growth.
- Windows requires debug symbol file ctreedbs.pdb to log call stack information. This may be obtained from FairCom by request. See Memory Allocation (Windows) -mf -ma -mr -ms for additional details.
Memory Allocation (Windows) -mf -ma -mr -ms
The c-tree Server for Windows has an option that causes c-tree's memory suballocator to collect call stacks for each allocation call made through ctgetmem(). Each memory allocation is assigned a sequence number. The ctMEMSTAT() API function can be used to read the current allocation sequence number and the current number of allocations and to log the call stacks for the allocations to the specified file.
For Windows and Linux systems, this option is ON by default in V10.4 and later.
The ctstat utility supports the following new memory tracking options:
- -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
- -ml - Display current memory allocation usage figures
Examples:
C:\>ctstat -ms -h 10 -s FAIRCOMS
Results:
memseq memalc
1267 992
1289 997
1289 997
1289 997
C:\>ctstat -mf memfull.log -i 1 1 -s FAIRCOMS
A log of all memory allocations (with each allocation listed separately) is written to the file memfull.log in the c-tree Server's working directory.
C:\>ctstat -ma memaggr.log -i 1 1 -s FAIRCOMS
A log of all memory allocations (with allocations having the same call stack listed only once each) is written to the file memaggr.log in the c-tree Server's working directory.
C:\>ctstat -ma memaggr.log -mr 1900,2000 -i 1 1 -s FAIRCOMS
A log of all memory allocations that have sequence numbers between 1900 and 2000 is written to the file memaggr.log in the c-tree Server's working directory.
For windows, -ma or -mf require debug symbols files (ctreedbs.pdb) for callstacks to be generated. These can be provided by faircom support if excessive memory usage is being investigated. ctstat -mu will attempt to reload this symbol file.
Note: These options will fail with error 170 if used with a c-tree Server that was built prior to our introduction of this feature and will fail with error 454 if used with a c-tree Server that was built after the introduction of this feature but that was not compiled with #define ctFeatMEMTRACK.
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.
Operational Model:
- Client
Usage:
sa_admin [-a<adminuserid>] [-p<adminpassword>] [-f<filepassword>] [-s<servername>] [-1 <auth_filename>] <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
- -ofg Change file 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
- -oug Add a user to a group
- -oux Remove a user from a group
Options File
- -ofg Change file group
- -ofl List files matching filename
- -oflp List file permissions mask
- -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 FairCom Server system matching the specified filename including wildcard characters.
sa_admin Support for Encrypted Password Files
This utility supports the use of an encoded password file. Encoded password files keep user IDs and passwords from plain view when the utility is used within a script file. They are created with the ctcmdset utility. The plain text form of the file should be:
; User Id
USERID ADMIN
; User Password
PASSWD <pass>Use the -1 option to specify the name of the encoded file.
The encrypted password file name is specified using the command-line option:
-1 <filename>
Using -ofs to Clear the Permission Mask
Sometimes it is desirable to make the permission mask empty instead of just adding more permissions to allow all access. For example, consider a file with this permission mask, which has permissions for "owner" and "world":
Permission mask = 0x2783e = {
owner: read write def delete
world: read write def delete nopass
}To remove all permissions for "owner" and "world" you can use the -ofs option as follows:
sa_admin -aadmin -pADMIN -f"" -sFAIRCOMS -ofs ./ctreeSQL.dbs/admin_permTest.dat -worldall -ownerall
-worldall removes all permissions for "world" and -ownerall removes all permissions for "owner." The resulting permission mask will be:
Permission mask = 0x421 = {
}
To clear permissions for world, user, and group, use the following:
sa_admin -aadmin -pADMIN -f"" -sFAIRCOMS -ofs ./ctreeSQL.dbs/admin_permTest.dat -worldall -ownerall -groupallDisplay File Permissions
C:\> sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oflp "vcust*"
Permission mask for file vcusti: OPF_READ OPF_WRITE OPF_DEF OPF_DELETE GPF_READ GPF_WRITE WPF_READ
Permission mask for file vcusti.2: OPF_READ OPF_WRITE OPF_DEF OPF_DELETE GPF_READ GPF_WRITE WPF_READ
Permission mask for file vcusti.ndx: OPF_READ OPF_WRITE OPF_DEF OPF_DELETE GPF_READ GPF_WRITE WPF_READ
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). The ID is limited to alphanumeric characters, hyphens, underscores, and periods. A hyphen cannot be the first character in a name.
- -d desc: Optional user description
- -w password: Optional user password
- -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 which the user must logon at least once, otherwise the account is blocked.
- Example:
sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oua user1sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oua user2 -d "description" -w password -ggroup1sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oua user3 -m 5000000g -b 01/31/2022 -e 02/20/2022sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oua user4 -l 10 -r unblock -t 15 - Example for blocking users:
sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oue user1 -r block - Example for unblocking users:
sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oue user1 -r unblock
Option User Remove
-our userid
- userid: User id (required)
- Example:
sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -our user1sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -our user2sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -our user3sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -our user4
Option User List
-oul
- Example:
sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oul
Option User Change Password
-oup userid password
- userid: User id (required)
- password: New password (required)
- Example:
sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oup user1 mynewpassword
Option User Add user to Group
-oug userid group
- userid: User id (required)
- group: Group name (required)
- Example:
sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oug user1 group1sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oug user2 group1sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oug user3 group2sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oug user4 group2
Option User (Group) Extract - Remove a user from a group
-oux userid group
- userid: User id (required)
- group: Group name (required)
- Example:
sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oux user1 group1
Option User Change Description
-oud userid desc
- userid: User id (required)
- desc: New user description
- Example:
sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oud user1 "My new description for user1"
Option User Memory
-oum userid -m memory rule
- userid: User id (required)
- memory: New memory limit. This can be a number of bytes or ‘D’ for default or left NULL for no limit
- 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
- Example:
change user1 to 5 MiB as a Guidelinechange user2 to unlimitedchange user3 to default limitchange user4 to 2 MiB absolute fixed limitsa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oum user1 -m 5000000gsa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oum user2sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oum user3 -m dsa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oum user4 -m 2000000a
Option User Change Extended Settings
-oue <userid> [-b <begdat>] [-e <enddat>] [-l <loglimit>] [-r <rsmlogon>] [-t <mstlogon>]
- userid: User id (required)
- -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 which 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 FairCom 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.
- Example:
sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oue user1 -b 01/31/2022 -e 02/20/2022 -l 10 -r 1 -t 15
Option User Show
-ous userid
- userid: User id (required)
- Example:
sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ous user1sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ous user2sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ous user3sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ous user4
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).
- Example:
sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oga group1sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oga group2 -d "Description for group2" -m 10485760a
Option File Group
-ofg filename groupid
- filename: File name (required)
- groupid: File group id (required)
- Example:
sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ofg "C:\FairCom\data\db1.dbs\owner1_table2.dat" OWNER1_RWD
Option Group Remove
-ogr groupid
- groupid: Group id (required)
- Example:
sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ogr group1sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ogr group2
Option Groups List
-ogl
- Example:
sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ogl
Option Group Change Description
-ogd groupid desc
- groupid: Group id (required)
- desc: New group description
- Example:
sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ogd group1 -d "group1 description"sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ogd group2 -d "group2 description"
Option Group Memory
-ogm groupid [-m <memory>[<rule>]]
- groupid: Group id (required)
-
-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).
- Example:
sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ogm group1 -m 5000000gsa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ogm group2 -m d
Option Group Show
-ogs groupid
- groupid: Group id (required)
- Example:
sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ogs group1sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ogs group2
Option User Add user to Group
-oug userid group
- userid: User id (required)
- group: Group name (required)
- Example:
sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oug user1 group1sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oug user2 group1
Option User (Group) Extract - Remove a user from a group
-oux userid group
- userid: User id (required)
- group: Group name (required)
- Example:
sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oux user1 group1sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oug user3 group2sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oug user4 group2
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)
- Example:
Set new password:sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ofp "C:\FairCom\data\db1.dbs\owner1_table2.dat" mynewpassword
Remove password:sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ofp "C:\FairCom\data\db1.dbs\owner1_table2.dat"
Option File Security (permissions)
-ofs <filename> <permission> ...
-ofs +|-<permission> ...
- filename: File name (required)
-
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 5 6 7 8 9 10 11 12 13 14
----OWNER---- ----GROUP---- -----WORLD----
r w f d p r w f d p r w f d p
r = Read w = Write f = define d = Delete p = noPass- permission can also be one of the following:
ownerall, ownerread, ownerwrite, ownerdefine, ownerdelete, ownernopass,
groupall, groupread, groupwrite, groupdefine, groupdelete, groupnopass,
worldall, worldread, worldwrite, worlddefine, worlddelete, worldnopassOptions 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.
- Example - remove all file permissions:
sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ofs "C:\FairCom\data\db1.dbs\owner1_table2.dat" -ownerall -groupall -worldallsa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ofs "C:\FairCom\data\db1.dbs\owner1_table2.dat" --------------- - Example - set all file permissions:
sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ofs "C:\FairCom\data\db1.dbs\owner1_table2.dat" +ownerall +groupall +worldall
sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ofs "C:\FairCom\data\db1.dbs\owner1_table2.dat" +++++++++++++++ - Example - set typical file permissions: owner ALL, group RWDP, world R:
sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ofs "C:\FairCom\data\db1.dbs\owner1_table2.dat" +ownerall +groupall -groupdefine -worldall +worldreadsa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ofs "C:\FairCom\data\db1.dbs\owner1_table2.dat" +++++++-+++----
Option File Group
-ofg filename groupid
- filename: File name (required)
- groupid: File group id (required)
- Example:
sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ofg "C:\FairCom\data\db1.dbs\owner1_table2.dat" OWNER1_RWD
Option File Owner
-ofo filename owner
- filename: File name (required)
- owner: File owner (required)
- Example:
sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ofo "C:\FairCom\data\db1.dbs\owner1_table2.dat" OWNER1
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
ctpass - Password Utility
FairCom Server utility to allow users to change their password.
Operational Model:
- Client
The following steps are required for a user to change the password associated with their own User ID.
For optional information on setting requirements for user passwords, see Setting password requirements.
- Run the utility program ctpass as any other program in the environment.
- Enter your current User ID.
- Enter the current password for your User ID, if you have one. (Maximum 1024 characters. Maximum nine characters for V9 and prior).
- Continue by entering the current name of the FairCom Server (i.e., the default name or another name, supplied in the FairCom Server configuration file).
- Now change your password by entering the new password.
- 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 FairCom 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 group. Only the super ADMIN account (named ADMIN) can change a password for an account that is a member of the ADMIN group.
Authentication File
This utility supports the use of an encoded password file. Encoded password files keep user IDs and passwords from plain view when the utility is used within a script file. They are created with the ctcmdset utility. The plain text form of the file should be:
; User Id
USERID ADMIN
; User Password
PASSWD <pass>Use the -1 option to specify the name of the encoded file.
ctquiet - Quiesce FairCom DB Utility
The ctquiet utility allows an administrator to quiet the server from a script. An interactive option is available in the ctadmn utility.
Operational Model:
- Client
Usage:
ctquiet [-c] [-f] [-i] [-m] {-p password|-a authfile} [-r] [-s server] [-t timeout] [-u] [-x] [-w]
Parameters:
- -a: Authentication file name
- -c: Wait for replication readers to finish processing
- -f: Full consistency (default: crash consistency)
- -i: Ignore inactive replication readers (used with -c option)
- -m: Quiesces the server, changes the specified configuration options, and resumes normal server activity. Allows changing server configuration options that require the server to be quiesced, avoiding additional calls to the Server. Can be specified one or more times in a call to ctquiet.
- -p: Admin Password
- -r: Create an incremental backup restore point. Automatically unquiets server
- -s: Server (default: FAIRCOMS@localhost)
- -t: Set transaction timeout in seconds. (maximum/default: 60 seconds).
- -u: Unquiet server
- -x: Abandon Quiet request if timeout exceeded. (Default: Abort long transactions.) Applies ctQTfailAfterTimeout mode. This mode has been extended to apply to restore point checkpoint creation for incremental forward rolls.
- -w - (Linux only) Execute command on successful quiet. Waits for SIGINT to unquiet server.
Note: The -c option requires ALL client utilities, replication readers, and servers to be installed from FairCom DB V11.3 or later. It is not compatible as a drop-in to current running environments.
Support for Incremental Backup Restore Points
Several changes have been made to ctquiet to support restore points necessary to carry out an incremental backup strategy:
- The -r feature can be used to generate the restore point files necessary to carry out an incremental backup strategy.
- The ctQTfailAfterTimeout mode has been extended to apply to restore point checkpoint creation for incremental forward rolls.
- The -x option applies the ctQTfailAfterTimeout mode to the already existing options.
- The -t timeout output has an effect only if -f or -r is specified.
- The default timeout has been changed to match the server's maximum.
Authentication File
This utility supports the use of an encoded password file. Encoded password files keep user IDs and passwords from plain view when the utility is used within a script file. They are created with the ctcmdset utility. The plain text form of the file should be:
; User Id
USERID ADMIN
; User Password
PASSWD <pass>Use the -1 option to specify the name of the encoded file.
Full Consistency
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 or recovery from transaction logs to occur.
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.
Physical Copy of Files
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.
The -r option creates an incremental backup restore point. After the ctquiet call succeeds, this new restore point and all server transaction logs can be copied to a backup area and used for an incremental recovery.
Timeout
The -f and -r options require that no transactions are active for the quiet to complete. The quiet operation defaults to waiting 60 seconds for the outstanding transaction to complete before aborting these transactions. Operations by other users and connections wait during this time.
The -t and -x options modify the timeout behavior:
- -t - Allows setting a shorter timeout. Times longer than 60 seconds are reduced to 60 seconds.
- -x - Instead of aborting the transactions, the quiet operation will fail if the timeout expires without all transactions completing.
Example 1:
You want to create a server backup for your application that is not using transaction logging on all the files you want to backup. Only allow 10 seconds before aborting outstanding transactions.
ctquiet -f -t 10 -s FAIRCOMS -p <admin password>
Make your backup and then end the quiet:
ctquiet -u -s FAIRCOMS -p <admin password>
Example 2:
You want to create a fast server backup, and all your files are using transaction logging. Your backup will need to go through recovery before being used.
ctquiet -s FAIRCOMS -p <admin password>
Make your backup and then end the quiet:
ctquiet -u -s FAIRCOMS -p <admin password>
Example 3:
You want to create a restore point for an incremental backup and only allow a brief (1 second) delay. You don't want ctquiet to abort any long running transactions.
ctquiet -r -t 1 -x -s FAIRCOMS -p <admin password>
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 (unavailable on Windows), the behavior of ctquiet is modified to perform as follows:
- After successfully quieting the server, it makes a system call to execute COMMAND.
- 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.
ctfilblkif - File Block Utility
ctfilblkif
ctfilblkif will block, or unblock a specified FairCom DB file. The default behavior is to block access to the specified file. Pass the -u option to unblock a file.
Operational Model:
- Client
Usage
ctfilblkif [-s server][-f filename][-u][-m] {-p password|-a authfile}
- -s: Server (default: FAIRCOMS@localhost)
- -f: File name, including extension and relative or absolute path (a relative path of "./" can be omitted)
- -u: Unblock file
- -m: Block file with manual reopen option (otherwise automatic reopen)
- -a: Authentication file name
- -p: Admin Password
- -t: Allow active transactions time (seconds) to complete before blocking
- -n: Block new transactions
Example:
Block new transactions and allow active transactions 3 seconds to complete before blocking the mark.dat file:
ctfilblkif -f mark.dat -n -t 3
Manual Reopen
The ctfilblkif utility now supports an option (-m) to block a file with the reopen option. This means that when the file is unblocked, those connections that had the file open when it was blocked must "manually" reopen the file (e.g., the application must explicitly reopen the file).
Example 1:
Block the file with the reopen option:
ctfilblkif -f mydatafile.dat -m -p ADMIN -s FAIRCOMS
Example 2:
Unblock the file. The connections that originally had the file open must reopen the file:
ctfilblkif -f mydatafile.dat -u -p ADMIN -s FAIRCOMS
Note: FairCom does not guarantee preserving the state of a transaction, locks, ISAM context when a file is blocked and then unblocked, even if using the auto open option. Because ISAM context information is lost when the file is blocked, an error 590 may be returned after the file has been blocked and unblocked using ctFBautopen or when using ctfilblkif utility, which uses this mode.
Authentication File
This utility supports the use of an encoded password file. Encoded password files keep user IDs and passwords from plain view when the utility is used within a script file. They are created with the ctcmdset utility. The plain text form of the file should be:
; User Id
USERID ADMIN
; User Password
PASSWD <pass>Use the -1 option to specify the name of the encoded file.
See also
- ctquiet - Quiesce FairCom DB Utility (ctquiet - Quiesce FairCom DB Utility, ctquiet Utility)
ctdump - Schedule Backup Utility
Note: For a complete discussion of dynamic dumps, see Backups and Data Integrity in the FairCom Server Administrator's Guide.
Operational Model:
- Client
ctdump schedules a dynamic dump on the fly. The backup definition script may be located either on the server, or passed in from the client.
Command Syntax
ctdump [-s svn] [-u uid] [-p upw] [-t script] [-b bufsiz] [-n] [-c] [-o backup_filename] [-x]
Options
- -s svn - c-tree Server name
- -u uid - User name
- -p upw - User password
- -t script - Dump script name
- -b bufsiz - Use buffer size of bufsiz bytes
- -c - Send dump script from client
- -m - Minimize progress notifications
- -n - Send progress notifications to client
- -o backup_filename - Write dump stream from server to file on client
- -x - Write dump stream from server to stdout
For options available when scripting a dynamic dump, see Dynamic Dump Options.
The following demonstrates example usage of this utility:
ctdump ADMIN ADMIN thescript FAIRCOMS
Secure Authentication File
This utility supports the use of an encoded password file. Encoded password files keep user IDs and passwords from plain view when the utility is used within a script file. They are created with the ctcmdset utility. The plain text form of the file should be:
; User Id
USERID ADMIN
; User Password
PASSWD <pass>Use the -1 option to specify the name of the encoded file.
Dump and Restore Version Compatibility
The ctrdmp utility is used to restore a Dynamic Dump and the ctfdmp utility can be used to roll forward. Occasionally an update to the FairCom Database Engine may cause an incompatibility between versions. For this reason you must use the ctrdmp from the same release from which the dump was created. It is important to save a copy of the ctrdmp utility that is compatible with each dump file. ctfdmp, ctldmp, and ctrdmp utilities display the FairCom DB version used to compile them when they are run.
Compression and Encryption
The ctdump.exe utility can accept compression and encryption utility inputs.
Windows backup compressed with 7z compression utility:
ctdump -s FAIRCOMS -u admin -p ADMIN -t dump.txt -c -x | 7z a -si backup.7z
Unix backup compressed and AES encrypted with standard utilities:
./ctdump -s FAIRCOMS -u admin -p ADMIN -t dump.txt -c -x | gzip|openssl enc -aes-256-cbc -salt >backup.gz.aes
Tip! Unix/Linux Alternative
This method also works with server-side dynamic dump backups prior to this new support and can be implemented on Unix systems using named pipes (mkfifo), and sending the dump to the named pipe.
- Create a named pipe:
mkfifo testpipe
- The pipe blocks until both sides are in use. So we start our compression command:
cat testpipe | gzip > backup.gz &
- Now we create our dynamic dump, with "testpipe" as the dump file. (This example uses the client output, however it should work the same from the server):
ctdump -s FAIRCOMQ -u admin -p ADMIN -t dump.txt -c -o testpipe c-tree(tm) Version 11.8.0.61131(Build-180802) Dynamic Backup Utility Copyright (C) 1992 - 2018 FairCom Corporation ALL RIGHTS RESERVED. Reading dump stream from server with buffer size of 100000 Dynamic Dump has been successfully written to the file testpipe.
- The backup.gz file contains the dump file.
The same approach can be used to compress and encrypt (and potentially other operations provided by system utilities):
cat testpipe|gzip|openssl enc -aes-256-cbc -salt >backup.gz.aes
To extract the dump:
cat backup.gz.aes | openssl enc -aes-256-cbc -d |gzip -d >backup.ctree
Use ctrdmp to extract the files from backup.ctree.
Error Codes
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:
- ctrdmp - Dynamic Dump Recovery or System Rollback (ctrdmp - Backup Restore or System Rollback, Backup Restore Utility)
- System Rollback (FairCom Database Rollback Guide, FairCom Database Rollback Guide)
- Rolling Forward from Backup (FairCom Database Forward Roll Guide, FairCom Database Forward Roll Guide)
ctrdmp - Backup Restore or System Rollback
Used to restore backups created with ctdump.
Operational Model:
Standalone
Usage:
ctrdmp [ dumpscript ] [ -x ]
- dumpscript - The name of a valid dynamic dump restore script
- -x - Read dump stream from stdin
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.
When the -x option is specified, the !DUMP keyword in the dump script is ignored and the dump stream is read from standard input.
This might be combined with the ctdump output redirection to pipeline a backup and restore operation:
ctdump -s FAIRCOMS -u admin -p ADMIN -t test6.dmp -c -x| ctrdmp test6.dmp -x
Note: If an error occurs during the restore phase, no backup exists on disk.
If encrypted files are being restored and input redirection is used, ctrdmp is not able to prompt for the master password during the recovery phase of the restore. In this case, an alternate means of providing the master password is required, such as using the CTREE_MASTER_KEY_FILE environment variable.
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.
Note: A 32-bit ctrdmp could fail with error 75 if run on transaction logs created by a 64-bit FairCom Server, which might support more than 2048 connections.
The ctfdmp, ctldmp, and ctrdmp utilities display the FairCom DB version used to compile them when they are run.
Dump and Restore Version Compatibility
The ctrdmp (ctrdmp - Backup Restore or System Rollback, Backup Restore Utility) utility is used to restore (FairCom Database Restore Guide, FairCom Database Restore Guide) a Dynamic Dump and the ctfdmp utility can be used to roll forward (FairCom Database Forward Roll Guide, FairCom Database Forward Roll Guide). Occasionally an update to the FairCom Database Engine may cause an incompatibility between versions. For this reason you must use the ctrdmp from the same release from which the dump was created. It is important to save a copy of the ctrdmp utility that is compatible with each dump file.
Restore Recovery Options
The ctrdmp utility now supports the RECOVER_DETAILS and RECOVER_MEMLOG transaction recovery options (the same options that FairCom Server supports).
If you specify !RECOVER_DETAILS YES in your dump restore script, ctrdmp will log progress messages to the file CTSTATUS.FCS as it performs its automatic recovery.
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.
ctrdmp supports options to help analyze recovery behavior. The following options behave like their corresponding server configuration options:
- !DIAGNOSTICS TRAN_RECOVERY logs detailed recovery steps to RECOVERY.FCS.
- !RECOVER_DETAILS YES logs additional recovery progress messages to CTSTATUS.FCS.
See also
- Maintaining Database Integrity in the c-tree Server Administrator's Guide
Rollback to New Restore Points with ctrdmp
In V11 and later, ctrdmp is able to rollback to a Restore Point. Restore Points permit server clients to establish quiet spots in the transaction log where there are no active transactions.
Prior to the V11 modifications, ctrdmp could either perform a dynamic dump recovery or rollback to a specified date and time. ctrdmp has been extended such that, as an alternative to specifying a date and time, the rollback script can provide the name of a Restore Point file.
A typical ctrdmp script file used for a rollback looks like:
!ROLLBACK
!DATE MM/DD/YYYY
!TIME HH:MM:SS
....
Now the script can be composed as follows:
!RP <Restore Point File Name>
....
The Restore Point File Name generated by the server is either of the following:
- RSTPNT_NO_CHK.YYYYMMDD_HHMMSS.FCS for a Lightweight Restore Point
- RSTPNT_CHKPNT.YYYYMMDD_HHMMSS.FCS for a Checkpoint Restore Point
Note that, as with the !ROLLBACK script keyword, the !RP keyword must be the first entry in the script file.
See also
- ctrdmp - Dynamic Dump Recovery or System Rollback (ctrdmp - Backup Restore or System Rollback, Backup Restore Utility)
- ctfdmp - Forward Dump Utility
ctrdmp options to convert path separators to operating system's native path separator
The dynamic dump restore utility, ctrdmp, supports options for converting path separators to the operating system's native path separator. These options are useful when restoring a dynamic dump that was created on an operating system that uses a different path separator. For example, using ctrdmp on a Linux system to restore a dynamic dump that was created on a Windows system.
!CONVERT_PATHSEP
The dynamic dump restore script option !CONVERT_PATHSEP instructs ctrdmp to convert path separators to the native path separator. ctrdmp applies this conversion to:
- filenames read from the dump stream file
- filenames read from transaction logs that are included in the dynamic dump
- data and index filenames in IFIL resources of all data files restored by ctrdmp
Note: If the file name begins with a drive letter (for example, C:) or a UNC reference (for example, \\machinename\sharename), it is not changed. In these cases, we recommend using the !REDIRECT option in the dynamic dump restore script to replace these references with the desired target directory names.
The dynamic dump restore script option !REDIRECT_IFIL instructs ctrdmp to apply the !REDIRECT rules that are specified in the dump restore script to the data and index filenames in the IFIL resources of the data files restored by ctrdmp.
An alternative to the !REDIRECT_IFIL option is to run the ctredirect utility after ctrdmp completes.
Example
As an example, consider a backup made on a Windows system of the c-tree data and index files accounts.dat and accounts.idx that are stored in the directory E:\mydata. In this example, the data file name in the IFIL resource is E:\mydata\accounts.
Here is an example dynamic dump backup script:
!DUMP backup.fcd
!FILES
E:\mydata\accounts.*
!ENDBelow is an example dynamic dump restore script to run on a Unix system that uses a !REDIRECT option to redirect E:\mydata to myrestoredir, which is a subdirectory in the directory where ctrdmp is being run. It uses the !REDIRECT_IFIL option to update the IFIL resource in accounts.dat based on the redirect rule:
!DUMP backup.fcd
!REDIRECT E:\mydata myrestoredir
!REDIRECT_IFIL
!CONVERT_PATHSEP
!FILES
E:\mydata\accounts.*
!ENDIn this example, accounts.dat and accounts.idx are restored to the myrestoredir directory, and then the data file name E:\mydata\accounts in accounts.dat is changed to myrestoredir/accounts. If the !REDIRECT_IFIL option had not been used, only the path separators would have been changed, so the data file name in the IFIL resource would have been changed to E:/mydata/accounts.
Limitations: The byte ordering of the two systems must be the same so that ctrdmp can restore the dump.
ctfdmp - Forward Roll Utility
Operational Model:
- Standalone
ctfdmp
Used to restore data to a given time following a ctrdmp restore.
ctfdmp takes an optional !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. More information on the !RP <name> can be found here: ctfdmp - Forward Roll Utility
Note: The ! prefix needs to be escaped when using the Unix Bash shell.
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.
ctfdmp accepts !RECOVER_DETAILS for additional progress notifications diagnostic output.
See also
- Maintaining Database Integrity in the c-tree Server Administrator's Guide
- ctrdmp - Dynamic Dump Recovery or System Rollback (ctrdmp - Backup Restore or System Rollback, Backup Restore Utility)
- Rollback to New Restore Points with ctrdmp
Master Password Verification Options
FairCom DB advanced encryption (AES, Blowfish, Twofish, 3DES) requires a master password to protect encrypted file access. Before starting FairCom DB for the first time with Advanced Encryption enabled, the Administrator must use the ctcpvf utility to create the master password verification file. Each time FairCom DB 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 - 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 FairCom 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 FairCom Server under any user account on the system. (See Advanced encryption master key store encrypted at system level on Windows.)
Note: FairCom DB looks for the file ctsrvr.pvf in the server binary area, so this file name should be specified. ctcpvf.exe creates the ctsrvr.pvf file in that same directory where it is run (e.g., the tools directory). On launch, the server looks for ctsrvr.pvf in the server directory, so ctsrvr.pvf needs to be moved or copied to the server directory.
Key Store Option
By default, this master key must be presented to FairCom DB 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. FairCom DB 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 FairCom DB configuration option MASTER_KEY_FILE specifies the key store file, <store>, from which FairCom DB 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.
Non-server applications must set the environment variable CTREE_MASTER_KEY_FILE=<keystore> to enable using a key store rather than prompting for the master password at FairCom DB initialization.
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.
Advanced encryption master key store encrypted at system level on Windows
FairCom DB supports creating an advanced encryption master key store encrypted at the system level on Windows. Prior to this revision, the encrypted master key store file created by the ctcpvf utility on Windows could only be decrypted by the user account that created the file. This made it difficult to set up a Windows service that is using the LocalSystem account to be able to read the encrypted master key store file. (The ctcpvf utility had to be run as LocalSystem when creating the master key store.)
An option has been added to the ctcpvf utility to create the encrypted store using system-level encryption, meaning that any user account on the system can decrypt the file. Use the ctcpvf utility's ‑syslevel option to use this feature. Example:
ctcpvf -k mymasterkey -s ctsrvr.fkf -syslevel
This option has been added to the ctadmn utility's "Change advanced encryption master password" option. Example:
Enter the name of the filename list file >> files.txt
Enter the current advanced encryption master password >> ****************
Enter the new advanced encryption master password >> ******************
Please confirm the new master password by entering it again:
Enter the new advanced encryption master password >> ******************
Enter the encryption level [U]ser or [S]ystem for the encrypted store >> u
Changing master password for the specified files...
Successfully changed the advanced encryption master password.See ctadmn.c for an example showing how to call the SECURITY() function with mode of SEC_CHANGE_ADVENC_PASSWD to change the master key. If you want to create the master key encrypted store using the system-level encryption option, OR in the ctENCMODsysl bit to the options field of the ctENCMOD structure whose address you pass to SECURITY().
Note: This support was added on the Windows platform only.
ctencrypt - Utility to Change Master Password
The FairCom DB 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.
Operational Model:
- Standalone
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 FairCom 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-tree 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
L0000008.FCS
L0000009.FCS
L0000010.FCT
; data files
mydatafile.dat
C:\My Documents\test.dat
vcustiNote: 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 ] SYSLOGDT.FCS
[ OK ] vcusti
[ OK ] L0000000.FCT
[ OK ] L0000002.FCA
[ OK ] L0000003.FCA
[ OK ] L0000004.FCA
[ OK ] L0000005.FCA
[ OK ] L0000006.FCS
[ OK ] L0000007.FCS
[ OK ] L0000008.FCS
[ OK ] L0000009.FCS
[ OK ] L0000010.FCT
12 succeeded, 0 failed
Successfully changed master password for all specified filesError 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.
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 mode1
- -delstk - Check delete stack (on by default)
- -link - Check links (on by default)
- -leaf - Check leaf nodes (on by default)
- -local - causes the utility to use a standalone (local side) connection instead of a client connection when linked with a LOCLIB library.
- -chkkey - Check keys in leaf nodes
1Exclusive mode prevents other users from accessing the file. This is only necessary when a server is being used. If you get an error from ctvfyidx referring to a locking issue (or stating that exclusive mode is needed), re-run ctvfyidx with -excl enabled.
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 indexes. 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 indexes. 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 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.
Example
Below is an example of launching ctvfyidx along with output showing the results of the index verification.
# ctvfyidx -2048 custmast.idx 0
Index page scan finds entries=4 header=4
Index nodes per level of tree structure - [0: 1]
Internal Index Verify: SUCCESSFUL
ctvfyidx - Prior to V10.3.1
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.
ctvfyfil - File Verify Utility
The ctvfyfil utility calls the ctVerifyFile() function. (See function for details.) 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:
- <page size> - Use the specified page size
- -chkdat - Read data file only (default)
- -chkdatkeys - Read data file and check keys in index
- -chkdeletedspace - Check deleted space
- -chkidx - Read index file
- -chkidxrec - Read index file and check records in data file
- -chkidxint - Additional index checks
- -excl - Open the file in exclusive mode1
- -int - Interactive mode: stop on each error
- -index=<N> - Check only the Nth index (N=1,2,...)
- -local - causes the utility to use a standalone (local side) connection instead of a client connection when linked with a LOCLIB library.
1Exclusive mode prevents other users from accessing the file. This is only necessary when a server is being used. If you get an error from ctvfyfil referring to a locking issue (or stating that exclusive mode is needed), re-run ctvfyfil with -excl enabled.
The example below shows the utility run on a file called mark.dat with the page size set to 8192:
ctvfyfil -8192 mark.dat
ctsmon - Server Heartbeat Monitor
ctsmon is used to check the current running status of a FairCom DB Server. Frequently, this is the "heartbeat" monitoring component in a clustering failover solution.
Usage
ctsmon [-u name] [-p pw] [-s s1,s2,...] [-t nn] [-c nn] [-d nn] [-o api_option]
where
- -u name - User name to connect to the server with. Default is none.
-
-p pw - User password. Default is none.
- It is assumed that all servers in the server list (-s) have the same user ID and password.
-
-s Server_name - Name of the Faircom server to log into.
- The server name has the form of name[@host]. If no @host is given the local host is assumed. @host can also be given as using an I/P address Example: FAIRCOMS@192.168.1.1 Default is FAIRCOMS
- -t nn - Time out value in seconds. Default is 30 seconds.
-
-c nn - Loop count for checking the server. This parameter has three possible values:
- +nn - Exit after nn times regardless if the server is up or down.
- 00 - Loop forever regardless if the server is up or down.
- -nn - Loop forever while the server is up, if unable to log into the server, exit after nn loops.
- -d nn - Set debugging trace level to n (0 to 5).
- -o api_option - An optional API call to retrieve additional information from server demonstrating the server is functional.
api_option is one of the following:
- appname - First APP_NAME_LIST entry
- curtime - Current server time in seconds since 1970
- commits - Current number of database commits (ctGSMS.sct_trend)
Return status
-1 - Usage error, or internal error.
0 - Server responded.
+n - Error returned from InitISAMXtd call.
Description
This utility is intended for use with cluster management systems such as the Open Cluster Framework (OCF) and Pacemaker on Linux, and Solaris and Microsoft cluster managers. This is usually run in the background as a daemon process. It is a useful utility to use with any monitoring the current availability status of a FairCom DB server process.
The availability check is a basic connection/disconnection attempt. If the connection succeeds, it is assumed the server is active and available. If a further check such as the ability to retrieve data is required, the api_option can be used to trigger that request.
The source code of this utility is provided in the FairCom DB SDK and can be further customized for specific usages.
Example
ctsmon -u ADMIN -p ADMIN -s 10.6.1.1 -t 20 -c 3