|
|
|
SetSystemConfigurationOption
SetSystemConfigurationOption() dynamically changes server configuration settings at runtime.
Declaration
NINT SetSystemConfigurationOption(NINT option, constTEXT * value);
Short Name
ctSETCFG()
Description
SetSystemConfigurationOption() allows a FairCom Server configuration to be changed at run time. This means you do not have to restart the server to operate with these specified configuration changes. This allows utilities and other diagnostic monitoring tools to directly call the server to activate or inactivate various server configuration options.
setcfgCONFIG_OPTION
setcfgCONFIG_OPTION is a general-purpose option used to set values for settings by passing a string value identical to a line in the server configuration file. Note that this option also supports the other existing options, making it possible to call ctSETCFG(setcfgCONFIG_OPTION, "CHECKPOINT_MONITOR YES").
Dynamic Adjustment Support
The following keywords support dynamic adjustment using setcfgCONFIG_OPTION. See the FairCom DB Configuration Options for keyword specific documentation.
Partial Dynamic Adjustment Support
The following keywords have some sub-options that may be changed, see below for additional details.
Disabling Binary Sub-Options
Use a tilda (~) character as a prefix to negate the sub-option to turn it off. This applies to the following keywords
DIAGNOSTICS Sub-Options
Not all sub-options are changeable at runtime. Prefix the sub-option with a tilde (~) to turn it off.
The following suboptions are supported.
COMPATIBILITY Sub-Options
Not all sub-options are changeable at runtime. Prefix the sub-option with a tilda (~) to turn it off.
The following sub-options are supported.
SUBSYSTEM details and supported Sub-Options
Keywords belonging to a SUBSYSTEM may support changes at runtime. To do so requires specific formatting like that required in the server configuration file. Multiple sub-options may be changed at once.
The following are SUBSYSTEM values with at least one supported sub-option.
Specifying any other option value than those shown above causes ctSETCFG() to return error PBAD_ERR (749).
Options besides setcfgCONFIG_OPTION
Option may be one of the following FairCom Server configuration supported values (the new setting value specified as a string).
Option |
Supported Values |
Description |
|---|---|---|
setcfgCHECKPOINT_MONITOR |
YES | NO | DETAIL |
Dynamically turn on and off the Checkpoint Monitor. |
setcfgCTSTATUS_MASK |
WARNING_AUTO_TRNLOG DYNAMIC_DUMP_FILES |
Dynamically turn on and off masking of messages specified by value in CTSTATUS.FCS. A tilda (~) character prefix negates the setcfgCTSTATUS_MASK options thus turning them off. |
setcfgDIAGNOSTICS |
LOWL_FILE_IO VSS_WRITER REPLICATE |
Dynamically turn on or off supported DIAGNOSTICS keywords. A tilda (~) character prefix negates the setcfgDIAGNOSTICS options thus turning them off. |
setcfgDYNAMIC_DUMP_DEFER |
<numeric value> |
Dynamically set the Dynamic Dump defer (sleep) time for enhanced on-line performance. value is in milliseconds. |
setcfgDYNAMIC_DUMP_DEFER_INTERVAL |
<blocks> |
Pauses the dynamic dump for DYNAMIC_DUMP_DEFER milliseconds each time it writes specified number of 64 KB blocks of data to dynamic dump stream file. |
setcfgFUNCTION_MONITOR |
YES | NO | <filename> |
Dynamically turn on and off the Function Monitor. |
setcfgMAX_FILE_WAIT_SECS |
<seconds> | -1 | 0 |
Change th number of seconds a user thread waits for internal threads to close file before retrying. -1 disables this feature. 0 (default) sets no wait limit. |
setcfgMEMORY_MONITOR |
<numeric value> |
Dynamically turn on and off Memory Monitor. value is in bytes. |
setcfgREQUEST_TIME_MONITOR |
<numeric value> |
Dynamically set the function monitoring time interval. value is in seconds. |
setcfgVSS_WRITER |
YES | NO |
Dynamically enable VSS writer for Windows. |
setcfgLOADKEY_OPTION |
LOADKEY_LEAF_PCT_FULL |
Dynamically modify rebuild options to create nodes less than 100% capacity. |
Details
An attempt to change an option that is specified in a FairCom Server encrypted settings file (ctsrvr.set) will fail with a "SETO_ERR (804) error, cannot override option specified in settings file." ctSETCFG() can only be called by a member of the ADMIN group; otherwise it will fail with error LADM_ERR (589).
The function monitor file output now also includes a time stamp.
Return Values
Value |
Symbolic Constant |
Explanation |
|---|---|---|
0 |
NO_ERROR |
Successful operation. |
589 |
LADM_ERR |
Member of ADMIN group required. |
749 |
PBAD_ERR |
Bad parameter value. Can be caused by any of these conditions: a) segcount is less than or equal to zero. b) lrange is NULL. c) invalid operator specified. d) between operator specified but urange is NULL. |
804 |
SETO_ERR |
cannot override configuration option that was specified in settings file |
See c-tree Error Codes for a complete listing of valid c-tree error values.
Examples
/* Enable function monitor logging to a file. */
ctSETCFG(setcfgFUNCTION_MONITOR, "fncmon.log");
/* Dynamically set the Dynamic Dump defer time */
ctSETCFG(setcfgDYNAMIC_DUMP_DEFER, "25");
/* Dynamically turn on masking of Dynamic Dump messages */
ctSETCFG(setcfgCONFIG_OPTION, "CTSTATUS_MASK DYNAMIC_DUMP_FILES");
/* Dynamically disable masking of Dynamic Dump messages */
ctSETCFG(setcfgCONFIG_OPTION "CTSTATUS_MASK ~DYNAMIC_DUMP_FILES");
/* Dynamically set stack generation option to FULL_DUMP */
ctSETCFG(setcfgCONFIG_OPTION "STACK_DUMP FULL_DUMP");
/* Change the SUBSYSTEM SQL LATTE MAX_STORE option to 11 GB */
ctSETCFG(setcfgCONFIG_OPTION,
"SUBSYSTEM SQL LATTE {\nMAX_STORE 11 GB\n}");
/* Change multiple SUBSYSTEM SECURITY PASSWORD options */
const char * newconfig = "SUBSYSTEM SECURITY PASSWORD {\n" \
"MINIMUM_LENGTH 16\n" \
"REQUIRED_CLASSES 2\n" \
"EXPIRE_IN_DAYS 365\n}";
ctSETCFG(setcfgCONFIG_OPTION,newconfig);
History
V11.6 and later adds SQL_DEBUG configurable options.
