FairCom ISAM for C

SystemConfiguration

Describes the configuration of the c-tree system.

Short Name

SYSCFG()

Type

Low-level function

Declaration

COUNT SystemConfiguration(pVOID bufptr)

Description

SystemConfiguration returns an array of LONGs describing the c-tree system configuration, as well as some of the important dynamic aspects of the system, such as the memory usage and the number of files in use. The number of elements in the array is given by ctCFGLMT, which defaults to 256.

To determine if a particular system configuration option is active, check to see if its corresponding array element is non-zero. For example, to determine if TRANPROC was turned on during system compilation, check element cfgTRANPROC of the configuration array to determine if it is non-zero.

Dynamic System Resources

The following configuration array subscripts correspond to dynamic system resources and are interpreted as noted:

cfgMEMORY_USAGE	Current system memory usage. Note: This value can overflow.
cfgMEMORY_HIGH	High-water mark of allocated memory: the largest amount of memory that has been allocated at one time since server startup. Note: This value overflows if over 2 GB. Use system snapshot to read the 8-byte sctmemhgh counter value instead.
cfgNET_ALLOCS	Current system net allocations. (Number of memory allocations minus the number of free calls.)
cfgOPEN_FILES	c-tree files opened by system.
cfgPHYSICAL_FILES	Physical c-tree files open. Includes superfile members omitted from cfgOPEN_FILES count.
cfgOPEN_FCBS	c-tree file control blocks in use by system.
cfgLOGIDX	Indicates if file mode ctLOGIDX is supported.

Server Implementations

The following array subscripts only apply to server implementations:

cfgDNODE_QLENGTH	Messages in delete node queue.
cfgCHKPNT_QLENGTH	Messages in checkpoint queue.
cfgSYSMON_QLENGTH	Messages in system monitor queue.
cfgLOGONS	Current number of logons.
cfgNET_LOCKS	Current number of pending locks (system wide).
cfgUSERS	Maximum number of logons.
cfgMAX_CONNECT	The limit for the maximum number of logons.
cfgUSER_FILES	Number of c-tree files opened by calling user.
cfgUSER_MEMORY	Current user memory usage.
cfgPATH_SEPARATOR	ASCII value for the file name path separator.
cfgMAX_CLIENT_NODES	The maximum number of client nodes that can be connected at a time (a value of zero indicates no limit)
cfgMAX_CONN_PER_NODE	The maximum number of concurrent connections per client node (a value of zero indicates no limit)
cfgLOCAL_CONN_ONLY	Whether or not connections from remote systems are allowed (a value of zero indicates that remote connections are allowed)

Static Compile-Time Values

The following array subscripts are static compile-time values:

cfgFILES	Maximum number of c-tree file control blocks available system wide.
cfgMAX_DAT_KEY	Maximum number of indexes per data file.
cfgMAX_KEY_SEG	Maximum number of key segments per index.

Client and Server Versions ("app" suffix)

The subscripts displayed in this section and the pre-initialization resources section below have client and FairCom Server versions, except for the following three subscripts:

cfgINIT_CTREEapp	Determine whether c-tree has been initialized.
cfgSERIALNBR	The FairCom Server serial number.
cfgTHREADapp	Indicates if threading has been enabled.

Subscripts ending with ‘app’ are specific to the client side of a client/server application. To check the same system setting for the FairCom Server, use the same subscript without the app extension. For example, to determine if Conditional Index support is active on the FairCom Server, use cfgCONDIDX as the subscript and cfgCONDIDXapp for the client side. On the client side, it is assumed the argument to SystemConfiguration is an array of properly aligned LONGs.

If SystemConfiguration is called for a non-client library, use the ‘app’ versions, i.e., cfgCONDIDXapp.

cfgBOUNDapp	Indicates if the application is bound to a database library. See the discussion on the different FairCom I/O models in these notes.
cfgDISKIO_MODELapp	A non-zero value indicates a stand-alone multi-user I/O model i.e. FPUTFGET.
cfgLOCLIBapp	A non-zero value indicates Local Library support.
cfgNOGLOBALSapp	A non-zero value indicates no globals are supported i.e. indicating all globals are stored in an allocated structure. This is the default setting.
cfgUNIFRMATapp	A non-zero value indicates FairCom’s automatic byte flipping (UNIFRMAT) is active.

The pre-initialization resource subscripts below may be specified prior to a c-tree initialization call, i.e., InitISAM, InitCTree, in addition to having both a client and FairCom Server version, as discussed above.

cfgANSIapp	Specifies whether to use ANSI. A non-zero value indicates ANSI.
cfgCONDIDXapp	A non-zero value indicates the application supports FairCom’s Conditional Index Logic.
cfgCTBATCHapp	A non-zero value indicates the application supports Batch Operations.
cfgCTSUPERapp	A non-zero value indicates the application supports Superfiles.
cfgCTS_ISAMapp	A non-zero value indicates the application supports FairCom’s ISAM API.
cfgHISTORYapp	A non-zero value indicates the application supports FairCom’s History Logic.
cfgINIT_CTREEapp	A non-zero value indicates c-tree has been initialized.
cfgLOGIDXapp	A non-zero value indicates the application supports the ctLOGIDX Logic.
cfgPARMFILEapp	A non-zero value indicates parameter files are supported.
cfgPASCAL24app	A non-zero value indicates 2-byte/4-byte length delimited strings are using the traditional pascal length convention.
cfgPASCALstapp	A non-zero value indicates byte length delimited strings are using the traditional pascal length convention.
cfgPATH_SEPARATORapp	Return the ASCII value for the file name path separator.
cfgPROTOTypeapp	A non-zero value indicates the application supports Prototypes.
cfgRESOURCEapp	A non-zero value indicates the application supports Resource Records.
cfgRTREEapp	A non-zero value indicates the application supports r-tree.
cfgSERIALNBR	Return FairCom Server serial number. You must display and use the returned number as a hex value.
cfgTHREADapp	A non-zero value indicates the application supports FairCom’s threading API.
cfgTRANPROCapp	A non-zero value indicates the application supports Transaction Processing.
cfgVARLDATAapp	A non-zero value indicates the application supports Variable-length Records.
cfgVARLKEYSapp	A non-zero value indicates the application supports Variable-length Keys i.e. Key compression.
cfgWORD_ORDERapp	Indicates the client data order: Low_High or High_Low. A non-zero value indicates Low_High.

Pascal Length Byte

c-tree supports two different methods for specifying the length byte in a Pascal data type. The original and non-traditional approach does not include the length byte in the byte count. For example, with a 1-byte data type, CT_FPSTRING, the smallest valid length byte would be 0. The new method follows the more traditional Pascal convention of including the length byte in the byte count. For example, with the traditional approach, the smallest valid length for a 1-byte data type would be 1. Therefore, if cfgPASCALstapp or cfgPASCAL24app return a non-zero value, the new traditional approach is active.

To receive a valid return value from cfgPATH_SEPARATOR, ctPATH_SEP must be defined. The default definition found in ctopt2.h is:

#define ctPATH_SEP '?'

This definition specifies that the system default path separator will be used. To use the same separator for all platforms, you might want to choose one of the following:

#define ctPATH_SEP '\\'

/* define for Windows */

#define ctPATH_SEP '/'

/* define for most Unix systems */

#define ctPATH_SEP ':'

/* define for Mac OSX */

Configuration Bitmaps

The following configuration bitmaps are used with the cfgCFGCHK element of the SystemConfiguration output array. When the bit is on, the corresponding configuration is in effect. The current configuration bit mask definition is:

cfgCFGCHK	This 32-bit value contains bits to indicate if particular features are enabled at runtime. See cfgCFGCHK below.
cfgCFGCHKmtclient ((LONG)0x00000002)	mtclient DLL loaded (V11 and later)
cfgCFGCHKxfrfile ((LONG)0x00000004)	File transfer API enabled (V11 and later)

cfgCFGCHK

The SYSCFG() function's cfgCFGCHK element is a 32-bit value that contains bits to indicate if particular features are enabled or disabled at runtime.

In V11.5 and later, a bit has been added to indicate if the advanced encryption feature is enabled:

#define cfgCFGCHKadvenc ((LONG)0x00000008) /* advanced encryption enabled */

The cfgCFGCHK element also indicates if REPL_MAPPINGS is in effect for FairCom Server.

Feature Bitmaps

The following feature bitmaps are used with the cfgFEACHK element of the SystemConfiguration output array. When the bit is on, the corresponding feature is available. This is useful for client applications where the availability of a feature is not known at compile/link time. The current feature bit mask definitions are:

cfgFEACHK

cfgFEACHKplusName	+index name support for PermIIndex.
cfgFEACHKhugeFile	Huge file support.
cfgFEACHKCLOSEInTran	Close or delete of an updated file inside an active transaction does not abort the transaction: either an error is returned, or the close or delete is deferred until transaction commit or abort.
cfgFEACHKencryption	Encryption is supported.
cfgFEACHKflexFile	Flexible file limits are supported.
cfgFEACHKdiskFull	Support disk full checks.
cfgFEACHKuniqFile	Support auto reassignment of duplicated file IDs.
cfgFEACHKxtdCmp	Extended key compression.
cfgFEACHK6BT	Extended 6-byte tran#.
cfgFEACHKoldBCD	Old BCD compatibility.
cfgFEACHKeventLogVer2	Advanced event log.
cfgFEACHKchkPntLst	Adj checkpoint list counters.
cfgFEACHKnoFlushDel	Suppress flush on delete.
cfgFEACHKzeroRecbyt	Zero RECBYT support.
cfgFEACHKsysView	System view log.
cfgFEACHKencrypTCPIP	Encrypt TCPIP.
cfgFEACHKlowlCRC	Common low-level CRC.
cfgFEACHKcommSUMCHK	Common sum check.
cfgFEACHKpag64K	64K page size supported.
cfgFEACHKreadShare	Read-only for shared files.
cfgFEACHKsplCache	Dedicated cache support.
cfgFEACHKpriCache	Cache priming support.
cfgFEACHKnoCache	No cache data file list.
cfgFEACHKnoFlush	Skip flush on close.
cfgFEACHKfpgCache	Data cache FPUTFGET.
cfgFEACHKdataFilter	Data filters.
cfgFEACHKdepRename	TRANDEP rename support.
cfgFEACHKchannels	Flexible I/O channels.
cfgFEACHKalgnchnl	Aligned I/O channels.
cfgFEACHKkeepopen	KEEPOPEN 4 nonMEMFILES.
cfgFEACHKiict	Immediate Commit Transaction (IICT) support.

cfgFEACHK2

cfgFEACHK2copyfile

File copy API enabled (V11 and later)

Note: An initial c-tree call (InitCTree, InitCtreeXtd, InitISAM, etc.) must be made before SystemConfiguration can check on the cfgFEACHK element. The cfgINIT_CTREEapp element can be evaluated to determine the status of the c-tree initialization.

For example:

LONG ca[ctCFGLMT];

SystemConfiguration(ca);

if (ca[cfgINIT_CTREEapp] == YES)

printf("c-tree Initialized");

else

printf("c-tree Uninitialized: %ld",

ca(cfgINIT_CTREEapp));

/* where the Uninitialized value is NINT_ERR for a client or FINT_ERR for a bound application */

System-wide Cache and Buffer Statistics

SystemConfiguration returns nine values referenced with the following constants used as subscripts in the output array of LONG values an application can use to capture system-wide cache and buffer statistics, (cache pages hold data record images and buffers hold index nodes), allowing an application to track the use of these resources.

cfgCACHE_PAGES	Available cache pages
cfgCACHE_PAGES_INUSE	Cache pages in use
cfgCACHE_PAGES_MXUSE	Maximum cache pages used
cfgCACHE_PAGES_DED	Available dedicated cache pages
cfgCACHE_PAGES_DEDINUSE	Dedicated cache pages in use
cfgCACHE_PAGES_DEDMXUSE	Maximum dedicated cache pages used
cfgBUFFER_PAGES	Available index buffers
cfgBUFFER_PAGES_INUSE	Index buffers in use
cfgBUFFER_PAGES_MXUSE	Maximum index buffers used

Note: The dedicated cache pages are a subset of the regular cache pages.

Please see the following example for the use of this feature.

LONG ctcfg[ctCFGLMT];

SystemConfiguration(ctcfg);

printf("\nAvailable Dedicated Cache Pages - %ld",

ctcfg[cfgCACHE_PAGES_DED]);

Version Information

These values allow a client to display the same server version and build date that the FairCom Server displays.

cfgVERSIONID	The version number.
cfgVERSIONID2	The mini version and build date values (V10.3 and later).
cfgVERSIONID_BASE	The base build date value (V10.3 and later).

The ctdbGetProductVersion() function is a good way to get these values in a form that is more readable than these binary values.

Additional Array Elements

The following array subscripts are also returned:

cfgBROADCAST_PORT	The TCP/IP port used for the broadcast (default: 5595). See https://docs.faircom.com/doc/ctserver/27902.htm
cfgBROADCAST_INTERVAL	The number of seconds between broadcasts. See https://docs.faircom.com/doc/ctserver/27901.htm
cfgBROADCAST_DATA	A token to be broadcast following the Server Name. See https://docs.faircom.com/doc/ctserver/27900.htm
cfgCACHE_LINE	The smallest amount of memory a processor will retrieve and store in its highest speed cache. See https://docs.faircom.com/doc/ctserver/27906.htm
cfgCACHE_PAGES_SCN	The number of data cache pages allowed to be used as scanner LRU pages. The configuration option SCAN_CACHE_PERCENT can be used to set this value as a percentage of the total data cache size.
cfgCACHE_PAGES_SCNINUSE	The current number of data cache pages that are being used as scanner LRU pages.
cfgCACHE_PAGES_SCNMXUSE	The high-water mark (maximum number at any time in the past) of data cache pages that have been used as scanner LRU pages.
cfgCACHE_STAT_ARRAY_SIZE	The number of memory locations for each counter (data cache requests, data cache hits, index cache requests, index cache hits). See http://docs.faircom.com/doc/v103ace/#59144.htm and http://docs.faircom.com/doc/v103ace/#59678.htm
cfgCONNECTIONS	The maximum number of connections to the FairCom Server. See https://docs.faircom.com/doc/ctserver/#27890.htm
cfgCOUNTED_LOGONS	The current number of logons that count toward the connection limit if the server uses connection group support (otherwise, the value is 0).
cfgDATA_LRU_LISTS	The number of LRU lists maintained for data cache pages. See https://docs.faircom.com/doc/ctserver/#49143.htm Note: The LRU algorithm is no longer used for the data cache.
cfgFIXED_LOG_SIZE	Indicates if the feature to automatically adjust the size of the log files to accommodate long records has been disabled (see also cfgLOG_RECORD_LIMIT). See https://docs.faircom.com/doc/ctserver/#27928.htm
cfgFLEX_FCBS	System file number high-water mark: the largest system file number that has been used since server startup.
cfgINDEX_LRU_LISTS	The number of LRU lists maintained for index cache/buffer pages. See https://docs.faircom.com/doc/ctserver/#49142.htm
cfgLANGUAGE	Support the r-tree language feature in an r-tree enabled server. Accepts three arguments: ENGLISH, SJIS, or EUC. See https://docs.faircom.com/doc/ctserver/#57454.htm
cfgLOG_RECORD_LIMIT	The data record length limit that triggers an increase the size of the log files. Transaction controlled records longer than this limit increase the size of the log files, or cause a TLNG_ERR (error 654) if the log space is fixed. The initial record length limit is approximately one fortieth of the total log space. The limit is reset each time the log size is adjusted (increased). (See also cfgFIXED_LOG_SIZE.)
cfgLOG_SPACE	The number of megabytes of disk space allocated to storing active transaction logs. See https://docs.faircom.com/doc/ctserver/#27945.htm
cfgLOGON_FAIL_LIMIT	The optional limit on the number of consecutive failed logons that causes subsequent logon attempts to fail for LOGON_FAIL_TIME minutes. See https://docs.faircom.com/doc/ctserver/#27946.htm
cfgLOGON_FAIL_TIME	The length of time logons are blocked after the logon limit is exceeded (see also cfgLOGON_FAIL_LIMIT). See https://docs.faircom.com/doc/ctserver/#27947.htm
cfgLOGON_MUST_TIME	A non-zero value requires users to log on at-least-once within the defined time or else their profile will be deactivated. See https://docs.faircom.com/doc/ctserver/#27948.htm
cfgMAX_LOGONS	High-water mark of concurrent logons: the largest number of connections that have existed at one time since server startup.
cfgMAX_PHYSICAL_FILES	High-water mark of open physical files: the largest number of physically opened files that have existed at one time since server startup.
cfgMAX_VIRTUAL_FILES	The maximum number of virtual files that may be opened at one time. See https://docs.faircom.com/doc/ctserver/#27949.htm
cfgMEMORY_HASH	The number of internal memory suballocator lists to be created for each of 11 ranges of allocation size (an entry of N indicates 11N lists are created, with N dedicated to a particular range of allocation size). See https://docs.faircom.com/doc/ctserver/#55778.htm
cfgMEMORY_HIGH	High-water mark of allocated memory: the largest amount of memory that has been allocated at one time since server startup. Note: This value overflows if over 2 GB. Use system snapshot to read the 8-byte sctmemhgh counter value instead. (MEMORY_USAGE can also overflow.)
cfgMONAL1_QLENGTH	Not used.
cfgMONAL2_QLENGTH	Not used.
cfgPROCESS_ID	The process ID of the c-tree Server process
cfgRECOVER_FILES	The number of files used during automatic recovery if greater than the FILES keyword. See https://docs.faircom.com/doc/ctserver/#27967.htm
cfgRSPACE_QLENGTH	Current number of entries in the space reclamation queue.
cfgSRV_MODEL	This value indicates whether the server supports only ISAM functionality (1) or SQL functionality (2).
cfgSYNC_DELAY	The number of seconds between log flushes. See https://docs.faircom.com/doc/ctserver/#57453.htm
cfgSYSLOG_QLENGTH	The current number of entries in the SYSLOG queue. This queue contains entries that the system logging thread is going to write to the SYSLOG file.

Return

Value	Symbolic Constant	Explanation
0	NO_ERROR	Successful configuration return.
47	FINT_ERR	c-tree not initialized.

See c-tree Error Codes for a complete listing of valid c-tree error values.

Example

LONG ctcfg[ctCFGLMT]; /* array of 256 longs */

SystemConfiguration(ctcfg);

printf("\nMemory Use is %ld\n", ctcfg[cfgMEMORY_USAGE]);

printf("Memory Highest is %ld\n", ctcfg[cfgMEMORY_HIGH]);

printf("Net allocation is %ld\n", ctcfg[cfgNET_ALLOCS]);

printf("Open Files level is %ld\n", ctcfg[cfgOPEN_FILES]);

printf("Physical Files is %ld\n", ctcfg[cfgPHYSICAL_FILES]);

printf("Open FCB's is %ld\n", ctcfg[cfgOPEN_FCBS]);

printf("ctLOGIDX support is %ld\n", ctcfg[cfgLOGIDX]);