Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic

SetSystemConfigurationOption

SetSystemConfigurationOption() dynamically changes server configuration settings at runtime.

Declaration

NINT SetSystemConfigurationOption(NINT option, pTEXT 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.

  • option is one of the following FairCom Server configuration values
  • value is 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 online 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

Changes number of seconds user thread waits for internal threads to close file before retrying.
-1 disables this feature.
0 (default) sets no wait limit.
Max value is 86400.

setcfgMEMORY_MONITOR

<numeric value>

Dynamically turn on and off Memory Monitor. value is in bytes.

setcfgREQUEST_TIME_MONITOR

<numeric value>

Dynamically set 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.


setcfgCONFIG_OPTION

setcfgCONFIG_OPTION is a general-purpose option used to set values for settings. Note that this option also supports the other existing options, making it possible to call ctSETCFG(setcfgCONFIG_OPTION, "CHECKPOINT_MONITOR YES").

Option

Supported Values

Description

setcfgCONFIG_OPTION, "NONTRAN_DATA_FLUSH_SEC value"

<time_limit_in_seconds>

Sets the time limit in seconds that a data cache page or index buffer can remain dirty before it is written to the file system cache.

setcfgCONFIG_OPTION, "TRAN_DATA_FLUSH_SEC value"

<time_limit_in_seconds>

Sets the time limit in seconds that a data cache page can remain dirty before it is written to the file system cache.

setcfgCONFIG_OPTION, "NONTRAN_INDEX_FLUSH_SEC value"

<time_limit_in_seconds>

Sets the time limit in seconds that an index buffer can remain dirty before it is written to the file system cache.

setcfgCONFIG_OPTION, "TRAN_INDEX_FLUSH_SEC value"

<time_limit_in_seconds>

Sets the time limit in seconds that an index buffer can remain dirty before it is written to the file system cache.

setcfgCONFIG_OPTION, "NONTRAN_DATA_FLUSH_BUCKETS value"

<number_of_buckets>

Sets the number of counter buckets for the dirty data page list.

setcfgCONFIG_OPTION, "TRAN_DATA_FLUSH_BUCKETS value"

<number_of_buckets>

Sets the number of counter buckets for the dirty data page list.

setcfgCONFIG_OPTION, "NONTRAN_INDEX_FLUSH_BUCKETS value"

<number_of_buckets>

Sets the number of counter buckets for the dirty index buffer list.

setcfgCONFIG_OPTION, "TRAN_INDEX_FLUSH_BUCKETS value"

<number_of_buckets>

Sets the number of counter buckets for the dirty index buffer list.

setcfgCONFIG_OPTION, "CHECKLOCK_FILE
Notice one set of parentheses surround the option and the file name:
"CHECKLOCK_FILE +<file_name>"

+<file_name>"

Turns on ctCHECKLOCK for the file specified (immediately if it is already open, or the next time a file by this name is created or opened).
Use ‑<file_name> to turn off.
<file_name> can include wildcards.
Returns INOT_ERR error 101 if no matching file_name is in effect.

setcfgCONFIG_OPTION, "SQL_DEBUG value"

SQL_DEBUG option
SQL_DEBUG ~option

Enables SQL_DEBUG options for specific SQL diagnostics.


Diagnostic Options

No values are used for these options: Specify an option to enable it. Use a tilda (~) character as a prefix to negate the option to turn it off.(for example, ~LOWL_FILE_IO).

Option

Description

setcfgDIAGNOSTICS, "LOWL_FILE_IO"

Logs Low-Level system errors into the server status file, CTSTATUS.FCS.

setcfgDIAGNOSTICS, "VSS_WRITER"

Enables VSS writer to log diagnostic messages to CTSTATUS.FCS.

setcfgDIAGNOSTICS, "PTADMIN"

Enables the filename and list of open instances of that file to be logged to CTSTATUS.FCS when a partition member purge fails with error 718.

setcfgDIAGNOSTICS, "REPLICATE"

Enables FairCom DB to log messages to CTSTATUS.FCS when a file that is being created or opened matches the filename specified for the REPLICATE keyword, and it does not meet replication requirements.

setcfgDIAGNOSTICS, "BACKGROUND_FLUSH"

Enables logging of flush thread operations to the file BGFLS.FCS.

setcfgDIAGNOSTICS, "BACKGROUND_FLUSH_BUCKETS"

Enables logging of flush counter bucket statistics to the file NTFLSBKT.FCS.

setcfgDIAGNOSTICS, "READ_ERR"

Enables additional diagnostic logging of read errors.

setcfgDIAGNOSTICS, "TR_TRAN_ERR"

(Supported in V11.5 and later) Enables additional diagnostic replication two-phase commit logging to the TR_TRAN.FCS file.


Specifying any other option value than those shown in the tables above causes ctSETCFG() to return error PBAD_ERR (749).

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");


/* Enable memory monitor output with 30000000 byte threshold. */
ctSETCFG(setcfgMEMORY_MONITOR, "30000000");


/* Enable checkpoint monitor detailed output. */
ctSETCFG(setcfgCHECKPOINT_MONITOR, "DETAIL");


/* Dynamically set the monitoring of function timings */
ctSETCFG(setcfgREQUEST_TIME_MONITOR, "15");

/* Dynamically set the Dynamic Dump defer time */
ctSETCFG(setcfgDYNAMIC_DUMP_DEFER, "25");

/* Dynamically turn on masking of Dynamic Dump messages */
ctSETCFG(setcfgCTSTATUS_MASK, "DYNAMIC_DUMP_FILES");

/* Dynamically disable masking of Dynamic Dump messages */
ctSETCFG(setcfgCTSTATUS_MASK, "~DYNAMIC_DUMP_FILES");

History

V11.6 and later adds SQL_DEBUG configurable options.

TOCIndex