APP_NAME_LIST
APP_NAME_LIST permits the server configuration file to create a list of arbitrary names that can be retrieved by clients. The names are any text string not containing spaces. If spaces are desired, the text string can be placed in quotes, however, the quotes will be part of the text string on retrieval.
As many APP_NAME_LIST entries as required may be created in the configuration file. For example: a list of file names may be created and then the names of the files can be retrieved by the client application. Further, by convention, one could use a delimiter to add parameters to the end of the string. Assuming, for the sake of example, that a pound sign (#) is used as a delimiter, then some entries could be added as follows:
APP_NAME_LIST first.dat#parm11#parm12#parm13
APP_NAME_LIST second.dat#parm21#parm22#parm23#parm24It is up to the client application to determine how to parse the APP_NAME_LIST string that is returned in its entirety by calls to the c-tree GetSymbolicNames() API function.
The text string used in APP_NAME_LIST entries have the following restrictions:
- The text string cannot contain a vertical bar (|) character; and
- The string cannot exceed the maximum file name length (255 characters, or 512 characters when multi-byte characters are enabled).
CACHE_LINE
CACHE_LINE<size>To maximize the performance of the FairCom Server under multi-CPU systems, ensure the cache-line setting matches the setting for your equipment. A cache-line is the smallest amount of memory a processor will retrieve and store in its highest speed cache. Using an appropriate CACHE_LINE setting helps reduce false sharing in CPU caches. Typical cache-line sizes are 32, 64, or 128 bytes.
It is common for 32-bit CPUs to use a 32-byte cache line size, and for 64-bit CPUs to use a 64-byte or larger cache line size, thus the default CACHE_LINE setting is 32 for 32-bit systems and 128 for 64-bit systems.
Supported CACHE_LINE values are: 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, and 1024. If an invalid CACHE_LINE value is specified, the server logs a warning message to CTSTATUS.FCS and uses the default value.
Default: 32 or 128
CHECK_CONFIG
CHECK_CONFIG <YES | NO>Forces FairCom DB to continue processing the configuration file when an error occurs. The server logs information about the success and failure of each keyword.
Note CHECK_CONFIG currently only supports a minimal subset of configuration keywords. Errors with other keywords still terminate server processing of the configuration file.
COMPATIBILITY NO_EXTERNAL_SHUTDOWN
COMPATIBILITY NO_EXTERNAL_SHUTDOWNFairCom DB can be configured to disallow server shutdown attempts made by external c-tree clients. (The term “external clients” refers to clients that communicate with the server through the server's communication subsystem.)
When this option is specified, attempts by external clients to shut down FairCom DB fail with error XSHT_ERR (792). This feature is most useful when FairCom DB is loaded as a DLL or shared library into an application server process. While external clients are prevented from shutting down the process, the application server process can shut down the FairCom DB subsystem by calling the ctThrdTerm() c-tree API function.
CONSOLE CTRL_C_ENABLE
CONSOLE CTRL_C_ENABLEBy default, FairCom Server ignores a <CTRL>+C signal. Adding this keyword to ctsrvr.cfg permits <CTRL>+C to stop the FairCom Server.
Default: Disabled
CONSOLE NO_MESSAGEBOX
CONSOLE NO_MESSAGEBOXWhen activated for Windows machines, this keyword deactivates error messages coming to the console in the form of a message box. The FairCom Server continues to log messages to CTSTATUS.FCS.
Default: Disabled
CONSOLE NO_PWRDWNPASSWORD
CONSOLE NO_PWRDWNPASSWORDBypass the ADMIN group User ID and password validation typically required at shutdown. When this option is active and a machine shutdown or restart occurs, the prompt is bypassed and the FairCom Server shuts down cleanly.
Default: Request prompts
CONSOLE NO_SHUTDOWN_PROMPT
CONSOLE NO_SHUTDOWN_PROMPTTo prevent an accidental unload, the FairCom Server prompts the console to acknowledge the shutdown. The number of active connections is displayed and the user has the option to proceed with the shutdown (unload) or allow the server to continue running. Use the CONSOLE NO_SHUTDOWN_PROMPT keyword to disable this shutdown prompt.
Default: Show prompt
CONSOLE TOOL_TRAY
CONSOLE TOOL_TRAYUnder Microsoft Windows, starts the FairCom Server in background, displaying only a c-tree icon in the Windows tool tray. This feature can also be activated with the ampersand, ‘&’, character on the command line. For example:
C:>faircom &or
C:>ctsrvr &The server waits until it has created the transaction logs, performed automatic recovery if necessary, and initialized the communication subsystem before displaying the balloon tip. This makes it easier for a developer or a server administrator to know the point in time at which c-tree Server is ready to accept connections.
Default: Disabled
CONSOLE W9X_SERVICE
It is possible to execute the FairCom Server as a Windows 95/98 service. Not to be confused with a Windows Server 2003/XP/Vista Service, this support is limited to the Windows 95/98 platform. This feature allows the server to remain in operation even if a user logs off of Windows without shutting down. Add the following keyword to the server configuration file to activate this support:
CONSOLE W9X_SERVICEThis keyword will be ignored on all other platforms except Windows 95/98.
Default: Disabled
CTSRVR_CFG
CTSRVR_CFG <path and filename>Specify the configuration file used when executing the FairCom Server from the command line.
This configuration option can include an environment variable name that will be substituted with its value when the configuration file is read. See Environment Variables in Configuring FairCom DB.
Default: Server Working directory
DNODEQ_SHUTDOWN_LIMIT
DNODEQ_SHUTDOWN_LIMITFairCom DB supports a configurable limit on the number of delete node queue entries that FairCom DB processes when it is shutting down. If the option DNODEQ_SHUTDOWN_LIMIT is specified in the configuration file, then when FairCom DB shuts down, if there are more than the specified number of entries in the delete node queue, the delete node thread writes all the unique queue entries to a disk stream file named DNODEQUE.FCS. A memory-based index file is used to eliminate duplicate queue entries, and only the unique entries are written to disk. If the number of unique entries is less than DNODEQ_SHUTDOWN_LIMIT, those entries are returned to the delete node queue and are processed by the delete node thread before FairCom DB finishes shutting down.
DNODEQ_SHUTDOWN_LIMIT 0 causes FairCom DB to process all entries in the delete node queue when shutting down.
FairCom DB always attempts to open and read all entries from the file DNODEQUE.FCS into the delete node queue at startup, regardless of the DNODEQ_SHUTDOWN_LIMIT setting. The FairCom Server deletes the file DNODEQUE.FCS after populating the delete node queue with its contents.
An administrator can delete the file DNODEQUE.FCS before starting FairCom DB to avoid processing these persistent delete node queue entries.
NO_SHUTDOWN_FLUSH
NO_SHUTDOWN_FLUSH <file name>With very large (2GB+) caches, it may be possible for a file to never be written to disk during its entire life cycle. When the FairCom Server is shut down, it begins to flush files to disk. In the case of a “scratch” or “temp” file, the application vendor may not care if c-tree flushes this file to disk.
NO_SHUTDOWN_FLUSH skips file flushing during server shutdown. Note that <file name> may specify a wildcard pattern, with ‘?’ replacing a single character and ‘*’ replacing a group of characters. See FairCom DB Standard Wildcards. Non-transaction controlled files can be specified as shown below for this treatment, but such a file will be corrupted after shutdown if file flushing was actually skipped. Transaction-controlled files that are not flushed will simply lengthen automatic recovery times.
Default: Flush at shutdown
PLUGIN
Specifies a specially designed plugin module (a DLL or shared library) to be loaded and initialized at startup.
PLUGIN <LABEL>;<DLL>- <LABEL> - The name used when referencing this plugin in CTSTATUS.FCS error messages.
- <DLL> - The library that will be loaded at server startup, and unloaded prior to shutdown.
PLUGIN_CALLBACK
Record update callbacks are file-based, loading a DLL/SO library on physical file open and unloading the DLL/SO on file close. This design leads to difficulties for more complex callbacks that attempt to maintain longer-term state information. To address this, the PLUGIN keyword functionality has been extended to support loading generic, user-defined libraries once at server startup, and unloading them at server shutdown.
This is enabled by setting in ctsrvr.cfg:
PLUGIN_CALLBACK <LABEL>;<DLL>where:
- <DLL> - The library that will be loaded at server startup, and unloaded prior to shutdown.
- <LABEL> - The name used when referencing this plugin in CTSTATUS.FCS error messages.
When the library is loaded at startup, it must export the following function:
int ctDECL ctPlugin_describe(char * name,size_t * size,int request)and may optionally provide the following functions:
Example
An example implementation is provided in ctrucbdll.c.
Note Currently, only Record Update callbacks and Deferred Index callbacks can utilize this PLUGIN_CALLBACK functionality.
PROCESS_PRIORITY
PROCESS_PRIORITYSpecifies the FairCom Server's process priority.
Note Use with caution, as a changing priority can substantially impact other processes on the system, or diminish database performance if decreased.
PROCESS_EXIT_COMMAND
PROCESS_EXIT_COMMAND <command>Used to run a command when the FairCom DB process calls the system function exit(). Before running the command, FairCom DB sets the following environment variables:
CTREE_PROCESS_ID is set to the FairCom DB process ID.
CTREE_SHUTDOWN_STATE is set to one of the following database engine shutdown status codes:
0 Shutdown not initiated.
1 Shutdown initiated.
2 Shutdown completed, but some clients remain active.
3 Shutdown completed with all files closed and final checkpoint logged.
Description
At shutdown the server calls the application indicated by the PROCESS_EXIT_COMMAND keyword within that application. It is possible to access the CTREE_PROCESS_ID and the CTREE_SHUTDOWN_STATE environment variables that exist within the scope of that application.
Example:
Create test.bat in the server executable directory, containing the following:
@echo %CTREE_PROCESS_ID% > shutdown.txt
@echo %CTREE_SHUTDOWN_STATE% >> shutdown.txtAdd this line to ctsrvr.cfg:
PROCESS_EXIT_COMMAND .\test.batStart the server and then stop it.
The content of shutdown.txt (created by test.bat) will be something like the following:
27700
3Where 27700 indicates the c-tree server PID and 3 is the shutdown state (clean shutdown).
SIGNAL_DOWN
SIGNAL_DOWN <executable>Ability to launch an application when the FairCom Server comes down. This keyword takes as its argument the name of an executable that will be launched when the FairCom Server has been successfully terminated. Supported by FairCom Server for Unix and Windows.
This configuration option can include an environment variable name that will be substituted with its value when the configuration file is read.
Default: OFF
See Also
SIGNAL_READY
SIGNAL_READY <executable>Ability to launch an application when the FairCom Server comes up. This keyword takes as its argument the name of an executable, which will be launched when the FairCom Server is ready (i.e., automatic recovery is completed). Supported by FairCom Server for Unix and Windows.
This configuration option can include an environment variable name that will be substituted with its value when the configuration file is read.
Default: OFF
See Also
STACK_DUMP
STACK_DUMP {OFF | STACK_ONLY | CONTEXT | FULL_DUMP }A server crash triggered by the Windows Exception Handler now defaults to generating a full dump (similar to a Unix core), while other diagnostic stack trace generation creates a smaller dump without heap memory. Prior to this change, a full dump was only generated if DIAGNOSTICS FULL_DUMP was enabled. A new server keyword has been added to control stack generation:
- OFF - Disables all diagnostic stack generation (available on Windows & unix systems).
- STACK_ONLY - all diagnostic stack generation is stack only (available on Windows & unix systems).
- CONTEXT - Default. Special diagnostic situations may trigger a full dump. (behaves as STACK_ONLY on unix)
- FULL_DUMP - All stack generation triggers a full dump (behaves as STACK_ONLY on Unix)
STACK_DUMP FULL_DUMP is equivalent to the preexisting keyword DIAGNOSTICS FULL_DUMP on Windows. DIAGNOSTICS FULL_DUMP should be considered deprecated, and may be removed in future versions.
The server admin can change STACK_DUMP during runtime.
Compatibility Note: This is a Behavior Change.
USER_SIGNAL_DOWN
USER_SIGNAL_DOWN my_parameterDevelopers using the c-tree Server SDK may define functionality to occur at Server shutdown.
This keyword passes my_parameter to a user-defined function in ctclbk.c, which the developer should alter to suit the needs of the custom server:
NINT ctusersig_down(TEXT mystring)This keyword can be specified multiple times with different parameters to accomplish different tasks provided the user-defined function is implemented accordingly.
Default: OFF
See Also
USER_SIGNAL_READY
USER_SIGNAL_READY my_parameterDevelopers using the c-tree Server SDK may define functionality to occur at Server startup.
This keyword passes my_parameter to a user-defined function in ctclbk.c, which the developer should alter to suit the needs of the custom server:
NINT ctusersig_ready(TEXT mystring)This keyword can be specified multiple times with different parameters to accomplish different tasks provided the user-defined function is implemented accordingly.
Default: OFF
See Also
WAIT_ON_SHUTDOWN_SEC
WAIT_ON_SHUTDOWN_SEC <seconds>Permits explicit control on how long to wait for server shutdown. If all of the wait loops have been exhausted, and if it appears that some users are still not disconnected or that some files are still pending close, and if the wait specified with this key word has not been exceed, the server will retry its shut down loops. The new key word defaults to zero: no additional waiting. A negative values means to wait forever. A positive value specifies the time to wait. Due to sleeps within the shutdown loops, the actual wait time might exceed the specified time by an amount on the order of fifteen seconds, possibly more.
DIAGNOSTICS SHUTDOWN_COMM
DIAGNOSTICS SHUTDOWN_COMMLogs messages showing the operations performed at server shutdown to disconnect client connections.
Entries logged via this diagnostic option start with the text
shutdown_diag:Additionally, with this option, the FairCom Server logs the details for each active thread that exists when the server begins to shut down, in the same format produced when using the DIAGNOSTICS REMAINING_THREADS keyword.