GemStone Configuration Options

System Configuration File

GemStone repository executables begin by attempting to find a system-wide configuration file.

1. As shown in Figure A.1, GemStone first checks to see if there is an environment variable defined for GEMSTONE_SYS_CONF.

2. If GEMSTONE_SYS_CONF is not defined, GemStone looks for a file named hostName.conf in $GEMSTONE/data and uses that file. hostName must match the results of executing the hostname command on the machine on which the executables are running.

3. If no such file exists, it looks for a file named system.conf in $GEMSTONE/data and uses that.

4. If neither of those files exist, the system defaults are used, unless the executable is Stone, in which case an error is generated.

5. If GEMSTONE_SYS_CONF is defined, GemStone checks to see if it points to a directory.

6. If GEMSTONE_SYS_CONF points to a directory, GemStone looks for a file named hostName.conf in that directory. If it finds such a file, it uses it. hostName must match the results of executing the hostname command on the machine on which the executables are running. If no hostName.conf is found, it looks in that directory for a file named system.conf and uses that. If neither of those files exist, the system defaults are used, unless the executable is Stone, in which case an error is generated.

If the GEMSTONE_SYS_CONF environment variable points to a file instead of a directory, GemStone just uses that file.

Within each file, if an option is listed more than once, then the value it is given the last time it is specified is used as its true value at executable run time.

This rule also applies between the two types of configuration files. If the same option is given a value in both the system and executable configuration files, the value in the executable configuration file overrides the system configuration file’s value.

Figure A.1   Search Path for a System Configuration File

Executable Configuration File

Ordinarily, GemStone repository executables next try to find an executable-dependent configuration file. (The exception is a Stone repository monitor that failed to find its system-wide configuration file—it exits with an error.)

1. As shown in Figure A.2, GemStone begins by checking to see if there is an environment variable defined for GEMSTONE_EXE_CONF.

2. If GEMSTONE_EXE_CONF is not defined, GemStone tries to find a file called exeName.conf in the current working directory. (For information about the naming conventions, see Naming Executable Configuration Files.)

3. If it succeeds at finding such a file, it uses that file. If such a file does not exist, it generates a warning and relies solely on the system configuration file for configuration parameters.

Figure A.2   Search Path for an Executable Configuration File

If GEMSTONE_EXE_CONF is defined, GemStone first looks to see if it points to a directory.

• If GEMSTONE_EXE_CONF points to a directory, GemStone looks for a file named exeName.conf in that directory. If such a file exists, it uses it; if not, a warning is generated and GemStone relies on the system configuration file for configuration parameters.
• If GEMSTONE_EXE_CONF points to a file, rather than to a directory, GemStone simply uses that file.
• If GEMSTONE_EXE_CONF points to a directory or file that doesn’t exist, a warning is generated and GemStone defaults to using the system configuration file for configuration parameters.

Creating or Using a System Configuration File

If you are satisfied with the standard options and the defaults, the simplest thing to do is to just use the configuration file provided in $GEMSTONE/data/system.conf. You can either copy this file and set the GEMSTONE_SYS_CONF environment variable to point to your new file, or you can do nothing and let GemStone use $GEMSTONE/data/system.conf itself.

Creating an Executable Configuration File

There are two ways to create a configuration file for a specific executable:

• You can copy the entire system-wide configuration file to a new file, name it appropriately, and change selected parameters.
• You can create a new file, give it an appropriate name, and include only those parameters that you want to differ from the default.

To make sure that GemStone is able to find and use your executable configuration file, you can set the GEMSTONE_EXE_CONF environment variable to point to your file. GEMSTONE_EXE_CONF can be either a file name or a directory name. If you set the environment variable to a directory name, be sure to name the configuration file exeName.conf so GemStone can find it at start up. (Information about the naming conventions for configuration files is just ahead.)

If you don’t set the GEMSTONE_EXE_CONF environment variable, GemStone looks for a file named exeName.conf in the current working directory at startup. If it doesn’t find one, it uses the configuration parameters set in the system configuration file, or it uses the system defaults.

NOTE
Make sure your executable-dependent file is both readable and writable by the Stone process, which will update options by writing to it if you make certain configuration changes at run time.

Nesting Configuration Files

Configuration files can include other configuration files using the option INCLUDE. This may be a more intuitive way to manage multiple configuration settings that are shared and unshared among individual clients.

The INCLUDE configuration parameter can be set to the name of a single file, which will be read, along with the configuration file itself, when a process starts. Unlike other parameters, more than one INCLUDE may be included in a configuration file, and each included file is read, not just the last one. Nesting may be up to 100 levels.

When a duplicate parameter definition is found, the last one is used. Location of the INCLUDE directive determines the last value; if the INCLUDE directive is at the end of the file, values in the nested configuration file override the current file values.

For example:

INCLUDE=config2.conf; 

INCLUDE="$GEMSTONE/data/config3.conf";

Naming Executable Configuration Files

The default name of an executable configuration file generally is determined from the name of the executable itself.

gemnetobject            $GEMSTONE/sys/gemnetobject

runadmingcgem	Starts the Admin Gem.

runcachewarmergem	Starts the cache warmer Gems.

runotcachewarmergem	Starts the Object Table cache warmer Gems.

runreclaimgcgem	Starts the Reclaim Gem.

runsymbolgem 	Starts the SymbolGem.

exeConfig="" 

exeConfig="$GEMSTONE/sys/reclaimgcgem.conf" 

runreclaimgcgem	$GEMSTONE/sys/runreclaimgcgem

#runreclaimgcgem	$GEMSTONE/sys/runreclaimgcgem

runreclaimgcgem	$GEMSTONE/sys/myrunreclaimgcgem

Naming Conventions for Configuration Options

The prefix “GEM_” indicates that the option is processed directly by Gems. Unless indicated otherwise by the phrase “used by all executables,” most other options are processed only by the Stone, which passes the information to executables as needed through network connections. Exceptions are the shared page cache configuration options (“SHR_”). The first Gem session process on a node remote from the Stone and extents reads these options, which determine the configuration of the shared page cache on that node.

All executables (that is, the Stone and Gems) understand the standard options used in the file $GEMSTONE/data/system.conf as shipped. The GemStone executables generate a warning message whenever they encounter an option that is not in the standard list.

NOTE:
If the DUMP_OPTIONS option is set to true, then once the system-wide and executable-dependent configuration files have been processed, the values of all the options understood by the executable are displayed. You can access the configuration parameters from Smalltalk by using the methods described starting here.

Errors in Configuration Files

At startup, each GemStone executable reads the configuration files. If any error is detected, information about the error is written to the standard output. This information indicates the file and line containing the error and the error’s severity.

If the CONFIG_WARNINGS_FATAL is set to true, then any errors in the configuration file/s read by the process will cause the process to terminate. This avoids inadvertently getting default configuration values. When CONFIG_WARNINGS_FATAL is false, some invalid settings will still result in execution

Two kinds of errors can be generated by the processing of configuration files: syntax errors and option value errors.

Alternate ways to specify configuration parameter values

Usually, configuration parameter values are specified in configuration files. These are found according the rules described earlier using the environment variables, default locations, or by values passed to the -e and -z arguments for GemStone utilities that accept these arguments (such as Stone and Topaz).

Configuration parameter values may also be passed in to Gem and Linked sessions using the -C argument. This is accepted by the Gem NRS and by topaz. The argument string must follow the configuration file syntax rules, and must be quoted, double quoted, and escaped as necessary.

For example, to set a configuration parameter for a RPC Gem, in Topaz:

set gemnetid 'gemnetobject -C GEM_TEMPOBJ_OOMSTATS_CSV=TRUE'

To set a configuration parameter in linked Topaz:

topaz -l -C GEM_TEMPOBJ_OOMSTATS_CSV=TRUE

CONFIG_WARNINGS_FATAL

If CONFIG_WARNINGS_FATAL is set to TRUE, then any warnings about invalid or out of range entries in a configuration file are treated as a fatal errors, terminating the Gem or Stone process that is reading the configuration file. The last occurrence of this parameter in any configuration file (in the case of multiple settings within a file, or settings in nested configuration files), will control the value used. If the last occurrence is TRUE, then any warnings from preceding configuration parameter will be treated as fatal.

Default: FALSE

DBF_ALLOCATION_MODE

DBF_ALLOCATION_MODE describes the space allocation heuristic to be used when filling repository extents.

Permissible values are either Sequential or a series of allocation weights, separated by commas. Under sequential allocation, each extent has its full resources used before the next extent’s resources are used. Under weighted allocation, those extents with a larger weight will have proportionally more of their disk resources allocated than those with smaller weights. Each weight applies to the corresponding extent in the series of extents specified in DBF_EXTENT_NAMES, and the number of elements must match. Extent allocation weights must be integers in the range 1..40 (inclusive).

Default: Sequential

DBF_EXTENT_NAMES

DBF_EXTENT_NAMES list of all repository extents, in order, primary extent first, separated by commas. Taken together, all of the listed file resources make up the logical repository. This option is required, and must contain at least one entry, the name of the primary extent. The maximum number of extents is 255.

An extent name can be a file name or the device name for a raw disk partition. The name can have an environment variable as its first component.

Default: EMPTY. The system will not run unless you define an extent list.
Initial setting: $GEMSTONE/data/extent0.dbf

DBF_EXTENT_SIZES

DBF_EXTENT_SIZES sets the maximum sizes of all repository extents, in order, primary extent first, separated by commas. Each size applies to the corresponding extent in the series of extents specified in DBF_EXTENT_NAMES.

A size entry may be empty, which indicates that the corresponding extent has no fixed maximum size. This setting allows the extent to grow until it fills the disk containing it.

The actual maximum size of an extent will always be a multiple of 16 MB. If an extent size specified by DBF_EXTENT_SIZES is not a multiple of 16 MB, then the actual maximum size will be the next lowest multiple of 16 MB. For example, an extent created with a maximum size of 260 MB, this extent really has a maximum size of only 256 MB.

When an extent is on a raw partition, for optimal performance the corresponding setting in DBF_EXTENT_SIZES should be 16MB smaller than the size of the partition. For example, set it to about 1984 MB for a 2 GB partition.

You can modify the size of an existing extent under these conditions:

• If the original maximum size was unlimited, the new maximum size must be larger than the current physical size of the extent.
• If the original maximum size was limited, the new maximum size must be larger than the original maximum size.

The Stone repository monitor is the only executable allowed to change DBF_EXTENT_SIZES. At GemStone system startup, the maximum size of each extent is written to the system log.

If no units are specified, the value is in MB (1 Megabyte = 1048576 bytes). You may also specify units as KB, MB, or GB.

Default Units: MB
Min: 16 MB
Max: 33554432 MB (subject to disk, operating system and platform limits)
Default: EMPTY (no maximum sizes)

DBF_PRE_GROW

If DBF_PRE_GROW is set to TRUE and there are extents for which a size is specified in DBF_EXTENT_SIZES, then on repository startup, each extent with a size in DBF_EXTENT_SIZES larger than the current size will be pregrown to the specified size. If the grow fails, the extent is reset to its original size and startup fails.

If DBF_PRE_GROW is set to TRUE and a new extent is added programmatically with a size specified, it will be pregrown to that size. If the extent cannot be grown to the maximum size because of disk capacity problems, then extent creation will fail.

The default value for DBF_PRE_GROW is FALSE. This setting indicates that extents will grow only when new space is needed. An extent without a maximum size is never pregrown.

The value of DBF_PRE_GROW may also be a list of integer sizes, which may include blanks for specific extents that will not be pregrown. Extents with an integer size specified in DBF_PRE_GROW will be pregrown to this size if needed. Extents without an entry in DBF_PRE_GROW will not be pregrown.

It is an error if the value for an extent’s DBF_PRE_GROW size is larger than the corresponding DBF_EXTENT_SIZES size; if one but not both are empty, it is not an error and the extent will not be pregrown.

Elements of DBF_PRE_GROW may be blank to specify pregrow sizes for some but not all extents, such as:

DBF_PRE_GROW = 1000, , 1000;

If no units are specified, the value is in MB (1 Megabyte = 1048576 bytes). You may also specify units as KB, MB, or GB.

Default Units: MB
Min: 1 MB
Max: 33554432 MB (limited by DBF_EXTENT_SIZES values)
Default: FALSE

DBF_SCRATCH_DIR

DBF_SCRATCH_DIR specifies a scratch directory that the Stone process can use to create “scratch” repositories for use during pageaudit. The file name is appended to the directory name without an intervening delimiter, so a trailing delimiter is necessary here.

Default: $GEMSTONE/data/

DUMP_OPTIONS

If DUMP_OPTIONS is set to true, dumps a summary of all configuration options as part of the process log file headers.

Default: true

GEM_ABORT_MAX_CRS

When a Gem is not in a transaction and aborts, GEM_ABORT_MAX_CRS specifies the maximum number of commit records to analyze to compute the writeSetUnion since the last time this session aborted. If the number of commit records would exceed this limit, the abort is treated similar to a LostOt and all in-memory copies of committed objects are marked invalid and will be re-read as needed during subsequent execution.

A value of 0 (zero) means no limit on number of commit records to analyze.

Runtime parameter: #GemAbortMaxCrs
Min: 0
Max: 2147483647
Default: 0

GEM_CACHE_WARMER_ARGS

Configures cache warming on a remote cache. If it is an empty string (the default), no cache warming is done when the remote gem starts a remote shared page cache. If it is set to a string containing spaces, a default cache warmer is started.

Otherwise, the value should contain valid startcachewarmer options and values that will be used to invoke the cache warmer on the remote cache.

The arguments used here will use to fork the startcachewarmer utility and have the same meanings. Not all startcachewarmer arguments are valid: only: -d -D -l -L -n -w. For the meanings and details for these arguments, see startcachewarmer.

This option is only used by remote gems that create a remote shared page cache. It is ignored by all other gems.

For example, to start a cache warmer with 5 threads and write the working set on cache shutdown:

GEM_CACHE_WARMER_ARGS = "-n 5 -w 0";

Default: "" (cache warmer will not be started)

GEM_CACHE_WARMER_MID_CACHE_ARGS

Configures cache warming on a mid-level cache. If it is an empty string (the default), no cache warming is done when the remote gem starts a mid-level shared page cache. If it is set to a string containing spaces, a default cache warmer is started.

Otherwise, the value should contain valid startcachewarmer options and values that will be used to invoke the cache warmer on the mid-level cache.

The arguments used here will be passed to the startcachewarmer utility and have the same meanings. Not all startcachewarmer arguments are valid: only: -d -D -l -L -n -w. For the meanings and details for these arguments, see startcachewarmer.

For example, to start a mid-level cache warmer with 5threads and write the working set on cache shutdown:

GEM_CACHE_WARMER_MID_CACHE_ARGS = "-n 5 -w 0";

Default: "" (cache warmer is not started)

GEM_COMPRESS_TRANLOG_RECORDS

If true, sessions will compress tranlog data records using lz4 compression before sending them to stone .

Default: true

GEM_FREE_FRAME_CACHE_SIZE

GEM_FREE_FRAME_CACHE_SIZE specifies the size of the Gem’s free frame cache. When using the free frame cache, the Gem removes enough frames from the free frame list to refill the cache in a single operation. When adding frames to the free list, the Gem does not add them until the cache is full.

A value of 0 disables the free frame cache (the Gem acquires frames one at a time). A value of –1 means use the default value: 0 for caches less than 100 MB and 10 for caches of 100 MB or greater.

Cache Statistic: FreeFrameCacheSize (Gem)
Units: frames
Min: –1
Max: 63
Default: –1 (see above discussion)

GEM_FREE_FRAME_LIMIT

When the number of free frames in the shared page cache is less than GEM_FREE_FRAME_LIMIT, the Gem session process scans the cache for a free frame rather than using one from the free frame list. This action is desirable for performance reasons so the remaining frames in the list are available for use by the Stone repository monitor.

If the value of GEM_FREE_FRAME_LIMIT is –1, the free frame limit is set to one of the following default values:

• For primary shared page cache that is 800 MB or smaller: 10% of the number of frames in the cache
• For primary shared page cache greater than 800 MB: 5000 frames
• For a remote shared page cache: 0

Runtime parameter: #GemFreeFrameLimit
Cache Statistic: FreeFrameLimit (Gem)
Min: 1
Max: 65536
Default: –1 (see above discussion)

GEM_FREE_PAGEIDS_CACHE

GEM_FREE_PAGEIDS_CACHE specifies the maximum number of free pageIds to be cached in Gem. Larger values reduce number of calls to Stone, at a cost of needing more free space within the extents.

Runtime parameter: #GemFreePageIdsCache
Min: 40
Max: 3500
Default: 200

GEM_HALT_ON_ERROR

GEM_HALT_ON_ERROR causes a Gem to halt and dump core if an error with the specified GemStone error number occurs. The value -1 means “never halt”. Ordinarily this option is used only to assist Technical Support in diagnosing problems.

Runtime parameter: #GemHaltOnError
Default: -1

GEM_KEEP_MIN_SOFTREFS

GEM_KEEP_MIN_SOFTREFS determines the minimum number of most recently used SoftReferences that will not be cleared by VM markSweep if startingMemUsed — the percentage of temporary object memory in use at the beginning of a VM mark/sweep — is greater than GEM_SOFTREF_CLEANUP_PERCENT_MEM but less than 80%.

In most cases, the default (0) is appropriate and should not be changed.

Runtime parameter: #GemKeepMinSoftRefs
Min: 0
Max: 10000000
Default: 0

GEM_KERBEROS_KEYTAB_FILE

Path to the Kerberos key table file. The keytab file only is required when passwordless logins to GemStone are in use. The file contains pairs of Kerberos principals and encrypted keys. In this case, the Kerberos service is the service for a GemStone repository.

Refer to the GemStone System Administration Guide for information on creating and maintaining this file.

Default: NONE

GEM_KEYRING_DIRS

A list of directories which contain keys and certificates used for secure backup and restore.

Runtime equivalent: #GemKeyRingDirs
Default: NONE

GEM_MAX_SMALLTALK_STACK_DEPTH

GEM_MAX_SMALLTALK_STACK_DEPTH determines the size of the GemStone Smalltalk execution stack space that is allocated when the Gem logs in. The unit is the approximate number of method activations in the stack. This setting causes heap memory allocation of approximately 64 bytes per activation. Exceeding the stack depth results in generation of the error RT_ERR_STACK_LIMIT.

Min: 100
Max: 1000000
Default: 1000

GEM_NATIVE_CODE_ENABLED

GEM_NATIVE_CODE_ENABLED enables or disables generation of native code. This is set to an integer 0, 1, or 2. For compatibility with configuration files from earlier versions, it may be also set to TRUE or FALSE.

Breakpoints in methods disable native code. Also, a session with a very large GEM_TEMPOBJ_CACHE_SIZE, on the Mac, may disable native code for internal reasons.

The runtime parameter #GemNativeCodeEnabled can be used to disable native code, and can be used to control whether subsequent GsProcesses start execution using interpreted or native code. Enabling generation of native code for methods as they are loaded for execution can only be controlled by the value of GEM_NATIVE_CODE_ENABLED in the configuration files at process startup.

• 0 or FALSE disables native code generation
• 1 enables native code generation
• 2 or TRUE enables native code generation, with inlining of some SmallInteger math primitives.

Runtime parameter: #GemNativeCodeEnabled
Minimum: 0
Maximum: 2
Default: 2

GEM_PGSVR_COMPRESS_PAGE_TRANSFERS

If GEM_PGSVR_COMPRESS_PAGE_TRANSFERS is true, use LZ4_compress() from the LZ4 compression library to compress page transfers between the page server on Stone's machine and Gem or mid-cache page server.

For the first Gem to login on a remote machine, that Gem's configuration file value of GEM_PGSVR_COMPRESS_PAGE_TRANSFERS is propagated to the page manager, and is used to configure the page manager's communication to the page manager's pgsvr on the new remote cache.

When a Gem triggers creation of a mid-level cache via the method midLevelCacheConnect:cacheSizeKB:maxSessions:, that Gem's current runtime value of GEM_PGSVR_COMPRESS_PAGE_TRANSFERS is propagated to the page manager, and is used to configure the page manager's communication to the page manager's pgsvr on the new mid-level cache.

Runtime parameter: #GemPgsvrCompressPageTransfers
Default: FALSE

GEM_PGSVR_FREE_FRAME_CACHE_SIZE

GEM_PGSVR_FREE_FRAME_CACHE_SIZE specifies the size of the free frame cache used by the Gem’s remote page server. This configuration option has no effect for Gems that are local to the repository extents (which have a page server).

When using the free frame cache, the page server removes enough frames from the free frame list to refill the cache in a single operation. When adding frames to the free list, the page server does not add them until the cache is full.

A value of 0 disables the free frame cache (the page server acquires frames one at a time). A value of –1 means use the default value: 0 for caches less than 100 MB and 10 for caches of 100 MB or greater.

Cache Statistic: FreeFrameCacheSize (Page Server)
Units: frames
Min: –1
Max: 63
Default: –1 (see above discussion)

GEM_PGSVR_FREE_FRAME_LIMIT

GEM_PGSVR_FREE_FRAME_LIMIT determines the free frame limit used by the Gem’s remote page server. It has no effect for Gems local to the repository extents (which do not have a page server). For a description of free frames, see the configuration option GEM_FREE_FRAME_LIMIT.

If the value of GEM_PGSVR_FREE_FRAME_LIMIT is –1, the free frame limit is set to one of the following default values:

• For primary shared page cache that is 800 MB or smaller: 10% of the number of frames in the cache
• For primary shared page cache greater than 800 MB: 5000 frames

To tune the free frame limit of a page server at runtime, use the method System class>>changeCacheSlotFreeFrameLimit: aSlot to: aValue.

Cache Statistic: FreeFrameLimit (Page Server)
Min: –1
Max: 65536
Default: –1 (see above discussion)

GEM_PGSVR_UPDATE_CACHE_ON_READ

GEM_PGSVR_UPDATE_CACHE_ON_READ determines the read behavior of the Gem’s remote page server when pages are read from disk. If this option is set to true, pages read from disk are also added to the shared page cache on the page server’s host. If this option is false, pages read are not added to the page server’s shared cache.

This option has no effect for Gems that are local to the repository extents, which do not have page servers, nor on mid-level caches.

Runtime parameter: #GemPgsvrUpdateCacheOnRead
Default: false

GEM_PGSVR_USE_SSL

GEM_PGSVR_USE SSL controls whether a remote gem uses a secure socket layer (SSL) connection to converse with its page server(s), both the page server on the stone’s host and the page server on the mid-level cache, if any.

This option has no effect local gems (i.e., gems running on the same host the stone process).

Secure sockets are slightly slower than insecure sockets due to the overhead of encrypting and decrypting data.

When enabling this option, consider also enabling the GEM_PGSVR_COMPRESS_PAGE_TRANSFERS option. SSL encodes no more than 16 KB into a single packet and some messages sent between the gem and page server may exceed this limit, causing SSL to send multiple encrypted packets to convey a single message.

Default: FALSE

GEM_PRIVATE_PAGE_CACHE_KB

GEM_PRIVATE_PAGE_CACHE_KB sets the size of the Gem’s private page cache. This setting also applies to linked Gems.

If no units are specified, the value is in KB. You may also specify units as KB, MB, or GB.

Default units: KB
Min: 128
Max: 524288
Default: 1000

GEM_READ_AUTH_ERR_STUBS

GEM_READ_AUTH_ERR_STUBS configures the behavior when a read authorization denied occurs on object fault. When FALSE (the default), a SecurityError is signalled. When set to TRUE, an in-memory instance of UnauthorizedObjectStub is constructed.

Runtime equivalent: #GemReadAuthErrStubs
Default: FALSE

GEM_REPOSITORY_IN_MEMORY

GEM_REPOSITORY_IN_MEMORY sets the performance behavior of the gem for certain operations that scan the entire repository. If set to TRUE, the gem assumes most or all of the data pages in the repository have been previously loaded into the shared page cache. If set to FALSE, the gem assumes most or all of the data pages in the repository are not in the shared page cache and must be read from disk.

This setting affects performance only. All operations affected by this setting will succeed and produce the same results.

Repository instance methods affected by this setting include:

findReferencePathToObject: (and related methods)

findAllReferencePathsToObjects: (and related methods))

Runtime parameter: #GemRepositoryInMemory
Default: FALSE

GEM_RPCGCI_TIMEOUT

GEM_RPCGCI_TIMEOUT specifies the time in minutes after which lack of an Rpc command will cause a Gem to terminate. Negative timeouts are not allowed. Resolution of timeouts is one-half the specified timeout interval.

Min: 0
Default: 0 (Gem waits forever)

GEM_RPC_KEEPALIVE_INTERVAL

GEM_RPC_KEEPALIVE_INTERVAL is the interval in seconds for the RPC GCI client to send a packet to the gem to ensure the network connection is kept alive.

With the traditional GCI interface (gci.hf), this controls how often keep-alive packets are sent during the GciPollForSignal() calls. The application needs to be calling GciPollForSignal at regular intervals at least as often as the configured value.

In the thread safe GCI (gcits.hf) , the gem will send an interrupt byte periodically, and the application must be calling GciTsWaitForEvent at least as often as this config value.

Min: 0
Max: 7200
Default: 0 (disabled)

GEM_RPC_USE_SSL

GEM_RPC_USE_SSL controls whether a remote RPC gem uses a secure socket layer (SSL) connection to converse with its RPC client. RPC sessions always establish a secure connection during the login sequence. This parameter controls whether the gem and its remote RPC client continue using the SSL connection. Otherwise, a standard TCP/IP socket connection is used.

This option has no effect for linked gems and local RPC gems (i.e., a gem running on the same host its client). Local gems always revert to a standard TCP/IP socket after login.

Secure sockets are slightly slower than insecure sockets due to the overhead of encrypting and decrypting data.

Default: TRUE

GEM_STATMONITOR_ARGS

GEM_STATMONITOR_ARGS describes a list of arguments to be passed to the statmonitor executable. If the list is not an empty string, statmonitor will be started automatically by a remote gem which creates a remote shared page cache; this setting is ignored other than by remote gems that create a remote shared page cache.

Example: start statmonitor with a 5 second sample interval with a date and timestamp included in the output file name and place the output file in the directory /statmonFiles:

GEM_STATMONITOR_ARGS = "-i5 -u5 -d /statmonFiles 

   -F'statmon_%%S_%%P_%d-%m-%y-%H:%M:%S'";

GEM_STATMONITOR_MID_CACHE_ARGS

GEM_STATMONITOR_MID_CACHE_ARGS describes a list of arguments to be passed to the statmonitor executable. If the list is not an empty string, statmonitor will be started automatically by the remote gem which creates a mid-level shared page cache; this setting is ignored other than by remote gems that create a mid-level shared page cache.

Example: start statmonitor with a 5 second sample interval with a date and timestamp included in the output file name and place the output file in the directory /statmonFiles:

GEM_STATMONITOR_MID_CACHE_ARGS = "-i5 -u5 -d /statmonFiles 

   -F'statmon_%%S_%%P_%d-%m-%y-%H:%M:%S'";

GEM_SOFTREF_CLEANUP_PERCENT_MEM

GEM_SOFTREF_CLEANUP_PERCENT_MEM controls the cleanup of SoftReferences.

If startingMemUsed — the percentage of temporary object memory in-use at the beginning of a VM mark/sweep — is less than the value of this option, no SoftReferences will be cleared.

If startingMemUsed is greater than the value of this option and less than 80%, the VM mark/sweep will attempt to clear an internally determined number of least recently used SoftReferences. Under rare circumstances, you might choose to specify a minimum number (GEM_KEEP_MIN_SOFTREFS) that will not be cleared.

If startingMemUsed is greater than 80%, VM mark/sweep will attempt to clear all SoftReferences.

Also see the statistics NumSoftRefsCleared, NumLiveSoftRefs, and NumNonNilSoftRefs.

Runtime parameter: #GemSoftRefCleanupPercentMem
Min: 10
Max: 80
Default: 50

GEM_TEMPOBJ_AGGRESSIVE_STUBBING

GEM_TEMPOBJ_AGGRESSIVE_STUBBING controls stubbing in in-memory garbage collection. If instance variable X in object A references object B, and X contains a memory pointer to B, then the reference is stubbed by storing into instance variable X the objectId of object B.

When this option is TRUE (the default), references from temporary objects to in-memory copies of committed objects are stubbed whenever possible, during both scavenge and mark/sweep. Also, references from not-dirty in-memory copies of committed objects to other committed objects are stubbed whenever possible. This reduces the number of committed objects forced to stay in-memory, but can slow down garbage collection and subsequent execution.

When this option is FALSE, references from temporary objects to in-memory copies of committed objects are never stubbed. References from not-dirty in-memory copies of committed objects to other committed objects are stubbed after the number of objects flushed during commits reaches a threshold, or if almost OutOfMemory. Performance may be faster, but there is a greater risk of OutOfMemory errors.

Stubbing is always disabled when a commit attempt is in progress, regardless of the setting of this parameter. Certain objects private to the object manager are always immune from stubbing, and so are references stored into Session State by using System class >> _sessionStateAt:put:.

Also see the statistics NumRefsStubbedMarkSweep and NumRefsStubbedScavenge.

Default: true

GEM_TEMPOBJ_CACHE_SIZE

GEM_TEMPOBJ_CACHE_SIZE sets the maximum size of the Gem’s temporary object memory. This limit also applies to memory in linked Topaz sessions and linked GemBuilder applications. This value is set when the VM is initialized and cannot be changed without restarting the VM. When you only change this setting, and the other GEM_TEMPOBJ* configuration options use default values, then all of the various spaces remain in proportion to each other.

This setting defines the maximum memory size. The initial memory allocated will be smaller, and as the actual space required for objects grows, the VM requests and allocates virtual memory as needed. As the limit is approached, in-memory garbage collection becomes more aggressive; if the limit is reached, the Gem will exit.

If no units are specified, the value is in KB. You may also specify units as KB, MB, or GB.

Statistic: GemTempObjCacheSizeKb (Gem)
Default Units: KB
Min: 2000 KB
Max: 62 GB
Default: 50000 KB

GEM_TEMPOBJ_CONSECUTIVE_MARKSWEEP_LIMIT

GEM_TEMPOBJ_CONSECUTIVE_MARKSWEEP_LIMIT controls in-memory garbage collection. If there are more consecutive in-memory mark sweeps than this value, without any intervening successful in-memory scavenges, then an OutOfMemory error will occur.

Runtime equivalent: GemTempObjConsecutiveMarksweepLimit (Gem)
Default: 50
Min: 20
Max: 5000

GEM_TEMPOBJ_MESPACE_SIZE

GEM_TEMPOBJ_MESPACE_SIZE sets the maximum size of the Map Entries space within the Gem’s temporary object memory. This value is set when the VM is initialized and cannot be changed without starting the VM.

One Map Entry is required for each faulted-in committed object, or for any temporary object that might become committed, referenced from an IdentityBag, or exported to the GCI. One Map Entry occupies approximately 24 bytes.

If a Map Entry is needed and the Map Entries Space is full, an OutOfMemory occurs, terminating the session.

Unless you are trying to minimize the memory footprint on HP-UX or AIX, you should always leave GEM_TEMPOBJ_MESPACE_SIZE at its default value (0) so that the system can calculate the size of the Map Entries space based on other memory sizes Otherwise, you are at risk of premature OutOfMemory errors.

If no units are specified, the value is in KB. You may also specify units as KB, MB, or GB.

Default units: KB
Min: 1000 KB
Max: 1000000 KB
Default: 0

GEM_TEMPOBJ_OOMSTATS_CSV

GEM_TEMPOBJ_OOMSTATS_CSV configures the production of a CSV file on an OutOfMemory error. If TRUE, then when an Error 4067/OutOfMemory occurs, the detailed statistics of instances of classes in temporary memory are written to a gemnetobjectpid.csv file in CSV format. For a topaz -l process, CSV data is written to a topazpid.csv file in the current directory.

The config parameter GEM_TEMPOBJ_OOMSTATS_CSV and the environment variable GS_DEBUG_VMGC_VERBOSE_OUTOFMEM operate independently. The environment variable GS_DEBUG_VMGC_VERBOSE_OUTOFMEM controls writing statistics in standard text to the gem log or stdout.

Runtime parameter: #GemTempObjOomstatsCsv
Default: FALSE

GEM_TEMPOBJ_OOPMAP_SIZE

GEM_TEMPOBJ_OOPMAP_SIZE sets the size of the hash table (that is, the number of 8-byte entries) in the objId-to-object map within the Gem’s temporary object memory. This value is set when the VM is initialized and cannot be changed without starting the VM.

The value specified is rounded up to the next higher power of 2.

This option should normally be left at its default value (0) so that the system can calculate the size of the map based on other memory sizes.

Min: 16384
Max: 524288000
Default: 0

GEM_TEMPOBJ_POMGEN_PRUNE_ON_VOTE

GEM_TEMPOBJ_POMGEN_PRUNE_ON_VOTE sets the percent of POM generation area to be thrown away when voting on possible dead objects.

If the value is 0, no subspaces of POM generation are cleared; if the value is 100, all subspaces are cleared. For values greater than 0 and less than 100, the number of spaces that are in use and older than 5 minutes is computed, and the specified parameter is the percentage, rounded down, of these subspaces that are discarded.

Runtime parameter: #GemPomGenPruneOnVote
Default: 50
Min: 0
Max: 100

GEM_TEMPOBJ_POMGEN_SCAVENGE_INTERVAL

GEM_TEMPOBJ_POMGEN_SCAVENGE_INTERVAL is the interval in seconds in which the oldest POM generation subspace will be discarded. Lower values may reduce Gem memory usage but may also cause objects to be re-read. Larger values may result in higher Gem memory usage and may reduce disk I/O. Setting this value to zero disables scheduled POM generation scavenges. In this case, POM generation will only be scavenged when all subspaces become full.

Runtime parameter: #GemTempObjPomgenScavengeInterval
Units: seconds
Min: 0
Max: 86400
Default: 1800

GEM_TEMPOBJ_POMGEN_SIZE

GEM_TEMPOBJ_POMGEN_SIZE sets the maximum size of the POM generation area in the Gem’s temporary object memory. This value is set when the VM is initialized and cannot be changed without starting the VM.

The POM generation area holds unmodified copies of committed objects that have been faulted into a Gem, and is divided into ten subspaces.

This option should normally be left at its default value (0) so that the POM generation area is allocated to the default, which is approximately 0.8 times the size of the GEM_TEMPOBJ_CACHE_SIZE.

If no units are specified, the value is in KB. You may also specify units as KB, MB, or GB.

Default units: KB
Min: 1000 KB
Max: 1000000 KB
Default: 0

GEM_TEMPOBJ_SCOPES_SIZE

GEM_TEMPOBJ_SCOPES_SIZE is the size of the scopes stack in Gem temporary object garbage collection. This value is set when the VM is initialized and cannot be changed without starting the VM.

The scopes stack consumes (8 bytes * GEM_TEMPOBJ_SCOPES_SIZE) of C heap memory.

The primary user-visible effect of this setting is maximum depth of nested expressions that can be compiled by the method compiler. The default setting is sufficient for expression nesting of about 200, such as in depth of nested parenthesized expressions.

Min: 1000
Max: 10000000
Default: 2000

GEM_TEMPOBJ_START_ADDR

GEM_TEMPOBJ_START_ADDR applies for AIX only. If the default mmap of temporary object memory fails, this value is used to define the starting address at which to attempt to mmap temporary object memory using MAP_FIXED at fixed addresses and munmap to simulate MAP_NORESERVE.

A config file value of zero results in an internal default of 0xA00000000000000 for AIX 7, and 0x700000000000000 for AIX 6. A non-default value must be coded as an exact address and may be affected by use of mmap by other shared libraries.

Default: 0

INCLUDE

INCLUDE specifies the name of a file to be included in this config file when parsing include files. The value must be a single string, which is a path to a file, and may include environment variables which will be expanded. INCLUDE directives may be nested up to 100 deep.

Unlike other configuration parameters, the INCLUDE parameter may be present more than once in a configuration file, and each file specified by an INCLUDE, not just the last one, is read. When other configuration parameters settings are found in more than one file, however, the last one read is the value that is used.

For example:

INCLUDE=config2.conf;   # will look in current directory

INCLUDE="$GEMSTONE/data/config3.conf";

KEYFILE

KEYFILE sets the location of GemStone licensing keyfile.

Default: $GEMSTONE/sys/gemstone.key

LOG_WARNINGS

If LOG_WARNINGS is set to true, warnings are printed for invalid configuration options.

Default: true

SHR_NUM_FREE_FRAME_SERVERS

SHR_NUM_FREE_FRAME_SERVERS specifies the number of free frame page server threads that will be started when the shared page cache is created. A value of
-1 means the default value should be used. On the primary shared page cache (the cache to which the stone attaches), the default value is equal to the value used for the STN_NUM_LOCAL_AIO_SERVERS parameter. On a remote shared page cache, the default is 1.

Min: -1
Max: 255
Default: -1

SHR_PAGE_CACHE_LARGE_MEMORY_PAGE_POLICY

SHR_PAGE_CACHE_LARGE_MEMORY_PAGE_POLICY specifies whether large memory pages will be used when creating the shared page cache. Enabling large memory pages can result in significant performance gains when large shared page caches are used. The improvement is due to a reduction in translation lookaside buffer (TLB) cache misses. The TLB is an internal structure used by the operating system to manage memory address translation.

Large memory page support is an operating system and hardware dependent feature. Currently, GemStone supports large memory pages on AIX and Linux only. This configuration option is silently ignored on all other platforms.

Three policies are available on supported operating systems:

0 - Disabled: No large memory page support.

1 - Advisory: Large memory pages are requested when the shared page cache is created. If the operating system denies the request, a warning is printed in the SPC monitor log file and the cache is started without large memory pages. It is strongly discouraged to use this setting on AIX.

2 - Mandatory: Large memory pages are requested when the shared page cache is created. If the operating system denies the request, an error is printed in the SPC monitor log file and the shared page cache fails to start.

Both Linux and AIX require operating system kernel changes in order to enable large memory pages. Refer to the Installation Guide for your platform for more information.

Default: 0
Minimum: 0
Maximum: 2

SHR_PAGE_CACHE_LARGE_MEMORY_PAGE_SIZE_MB

On Linux only, specifies the large memory page size, in megabytes, that will be used when creating the shared page cache. A value of 0 means use the default large page size for the host. This option is only supported on Linux, and any setting is ignored on other platforms.

This setting is ignored if SHR_PAGE_CACHE_LARGE_MEMORY_PAGE_POLICY is set to 0.

Valid large page sizes on Linux are 2 MB and 1024 MB; not all systems will support both large memory page sizes. Normally the default large page size on Linux is 2 MB, but that default can be changed by the system administrator.

Default: 2
Minimum: 0
Maximum: 1024

SHR_PAGE_CACHE_LOCKED

SHR_PAGE_CACHE_LOCKED specifies whether the shared page cache should be locked in memory. On systems that permit a portion of memory to be dedicated to GemStone, this option may provide higher performance.

On Solaris 10, GemStone uses Intimate Shared Memory for the shared page cache, making setting this variable unnecessary.

Other specific operating systems may restrict this action to processes running as root or may require special privileges (such as on Linux, either the capability CAP_IPC_LOCK or an RLIMIT_MEMLOCK resource limit greater than the size of the shared page cache). For further information, check the shared page cache monitor log for error messages and consult your operating system documentation.

Default: false

SHR_PAGE_CACHE_NUM_PROCS

SHR_PAGE_CACHE_NUM_PROCS sets the maximum number of processes allowed to attach to the shared page cache. This parameter is used to allocate space in the shared page cache for session information and cache statistics. This cache space is in addition to extent page space allocated by SHR_PAGE_CACHE_SIZE_KB.

The value for SHR_PAGE_CACHE_NUM_PROCS must accommodate the GcGems and various background GemStone processes, as well as user Gem and Topaz session processes. If the value is too small, sessions might be unable to login because they can’t attach to the cache. If the value is too large, space in the cache may be wasted.

It is recommended to leave this at the default value. When the default setting of –1 is specified, the value of this parameter is calculated as:

STN_MAX_SESSIONS
+ 8 (for system logins)
+ STN_MAX_GC_RECLAIM_SESSIONS
+ SHR_NUM_FREE_FRAME_SERVERS
+ STN_NUM_LOCAL_AIO_SERVERS

Cache Statistic: (SPC Monitor) SlotsTotalCount
Min: 15, or the number extents + 3, whichever is larger
Max: determined by STN_MAX_SESSIONS or file descriptor limits
Default: –1

SHR_PAGE_CACHE_NUM_SHARED_COUNTERS

SHR_PAGE_CACHE_NUM_SHARED_COUNTRERS specifies the number of shared counters available in the shared page cache. On most platforms, each counter consumes 128 bytes of shared memory. On AIX, each counter consumes 256 bytes of shared memory. Shared memory used for shared counters is in addition to the shared memory size specified in SHR_PAGE_CACHE_SIZE_KB.

Cache Statistic: NumSharedCounters (SPC Monitor)
Min: 0
Max: 500000
Default: 1900

SHR_PAGE_CACHE_PERMISSIONS

SHR_PAGE_CACHE_PERMISSIONS specifies the UNIX permission settings of the shared page cache, expressed as an octal number. The first two digits are constant and must always be 06. The 0 indicates an octal constant and 6 indicates the UNIX user which created the cache has read/write permissions.

The last two digits specifies the group and other permissions respectively. Each of the last two digits must be one of the following:

6 - read/write
4 - read only
0 - no access

By default, the shared page cache is created with group read/write permission but no access for other users.

Default: 0660

SHR_PAGE_CACHE_SIZE_KB

SHR_PAGE_CACHE_SIZE_KB sets the base size of the shared page cache. Additional shared memory is used for overhead, so the actual size of the memory segment will be somewhat larger.

If no units are specified, the value is in KB. You may also specify units as KB, MB, or GB.

Default Units: KB
Min: 16000 KB
Max: Limited by system memory and kernel configurations
Default: 75000 KB

NOTE
For information about platform-specific limitations on the size of the shared page cache, refer to Chapter 1 of your GemStone/S Installation Guide.

SHR_SPIN_LOCK_COUNT

SHR_SPIN_LOCK_COUNT specifies the number of tries to get a spin lock before the process sleeps on a semaphore. Semaphores involve a relatively time-consuming call to the operating system. Spin locks involve busy-wait loops. Efficient locking may require a combination of these methods.

In single-processor architectures, this value should always be 1 since there is no value in spinning (the lock won’t change until the process holding the lock gets scheduled). On multiple-processor architectures, a value of 5000 is recommended.

We recommend that you leave this option set to the default value of –1, which causes GemStone to use a value of either 1 or 5000, based upon the number of CPUs detected.

The runtime parameter can be changed only by SystemUser.

Runtime parameter: #SpinLockCount
Default: –1 (use either 1 or 5000, based on the number of CPUs detected)

SHR_TARGET_FREE_FRAME_COUNT

SHR_TARGET_FREE_FRAME_COUNT specifies the target number of free frames to keep in the shared cache at all times. The free frame page server process(es) will attempt to keep the number of free frames in the cache equal to or greater than this value.

If the value of the parameter is –1, the target free frame count is set to a percentage of the total frames in the shared cache. For the main shared cache (the cache to which the stone attaches), the default is 1/8 the frames in the cache. For remote caches, the default is 1/100 the frames in the cache.

For best performance, keep this setting greater than GEM_FREE_FRAME_LIMIT.

If the value of SHR_TARGET_FREE_FRAME_COUNT is –1, the target number of free frames is set to one of the following default values:

• For primary shared page cache that is 800 MB or smaller: 12.5% of the number of frames in the cache
• For primary shared page cache greater than 800 MB: 7000 frames
• For a remote shared page cache: 1% of the number of frames, or 2000 frames, whichever is smaller

Min: –1
Max: 65536
Default: –1 (see above discussion)

SHR_WELL_KNOWN_PORT_NUMBER

SHR_WELL_KNOWN_PORT_NUMBER specifies the port number that the shared page cache monitor will use as its well-known port. The well-known port is used by all Gems and page servers on this host to connect to the cache monitor.

If the specified port is in use by another process, the monitor process will not start and exits with an error. A value of zero indicates that the port number will be selected by the system.

Min: 1
Max: 65535
Default: 0

STN_ADMIN_GC_SESSION_ENABLED

STN_ADMIN_GC_SESSION_ENABLED determines whether the Admin Gem is started when the Stone is started. (The Admin Gem performs administrative garbage collection functions such as write set union sweeps; the Reclaim Gem performs dead object and page reclaim.)

Runtime parameter: #StnAdminGcSessionEnabled
Default: true

STN_ALLOCATE_HIGH_OOPS

STN_ALLOCATE_HIGH_OOPS instructs the Stone to skip the first 16 million object identifiers and begins to allocate object identifiers (GCI OopTypes) for non-special objects at 16r100000001.

This option is designed for testing conversion of GCI applications and user actions. Do not set this option in a production environment.

Default: FALSE

STN_ALLOW_NFS_EXTENTS

STN_ALLOW_NFS_EXTENTS allows the Stone to start up using extents and tranlogs which are on NFS-mounted filesystems. This is less reliable and less performant than locally mounted filesystems, or filesystems on storage arrays which appear as local mounts. This variable cannot be changed at runtime.

Default: FALSE

STN_ALLOW_NO_SESSION_INIT

STN_ALLOW_NO_SESSION_INIT enables bypass, and allows debugging, of GsCurrentSession>>initialize and any functions specified by UserProfile’s loginHook, which are normally always executed on login.

If false, GciLogin ignores the flag GCI_CLIENT_DOES_SESSION_INIT. All sessions perform GsCurrentSession>>initialize, and errors are fatal to the session logging in.

If true, GciLogin uses the setting for the flag GCI_CLIENT_DOES_SESSION_INIT. GsCurrentSession>>initialize is executed unless this flag is set or topaz executes the SET SESSIONINIT OFF command. If GsCurrentSession>>initialize is executed, errors in execution are reported, but are not fatal errors.

See also the topaz command set sessioninit off in the Topaz Programming Guide.

Runtime parameter: #StnAllowNoSessionInit (may only be set by SystemUser)
Default: FALSE

STN_CACHE_WARMER

Legacy; replaced by STN_CACHE_WARMER_ARGS. Specifies the type of cache warming to perform on startup.

The STN_CACHE_WARMER has the following possible values:

0 - Disabled; with STN_CACHE_WARMER_ARGS, specify ""

1 - Warm only object table pages; with STN_CACHE_WARMER_ARGS to " ".

2 - Warm object table and data pages; with STN_CACHE_WARMER_ARGS, include the flag "-d".

STN_CACHE_WARMER_ARGS

This configuration option can be used to have the stone automatically start a cache warmer process on its cache. The options that can be specified here are:

-d read data pages into the cache.

-D read data pages into the UNIX file system buffers

-l stop cache warming if the free frame count falls below <cacheFullLimit>.

-n the number of warmer threads to use

-w enable saving and restoring a workingSet of data pages

The complete description of the options and default values can be obtained by invoking the command: $GEMSTONE/bin/startcachewarmer -h

The other options if specified are ignored by the cache warmer when starting from this configuration. The -s stoneName argument is automatically provided, so it is not required.

If this configuration option is specified with a non empty string, it overrides any settings for STN_CACHE_WARMER and STN_CACHE_WARMER_SESSIONS

Example: Start a cachewarmer to load only the object table into the cache using 4 warmer threads.

STN_CACHE_WARMER_ARGS = "-n 4"

Default: "" (cachewarmer is not started)

STN_CACHE_WARMER_SESSIONS

Legacy; replaced by STN_CACHE_WARMER_ARGS. Specifies the number of worker sessions (threads) to use to perform cache warming on startup. A value of 0 means to compute the default based on (numberOfCPUs + numberOfExtents).

Equivalent to using -n numSessions in the STN_CACHE_WARMER_ARGS.

STN_CACHE_WARMER_WAIT_MODE

Determines if and when startstone waits until cache warming has finished. The following values are allowed:

0 - disabled. startstone does not wait until cache warming has finished.

1 - startstone waits until cache warming has finished but only if stone is starting after a clean shutdown, or without tranlogs (i.e., startstone with -N option). Otherwise startstone does not wait for cache warming to finish. This is the default setting.

2 - startstone always waits until cache warming has finished.

Has no effect and is ignored if cache warming is not enabled.

Minimum: 0
Maximum: 2
Default: 1

STN_CHECKPOINT_INTERVAL

STN_CHECKPOINT_INTERVAL sets the maximum interval between checkpoints. Checkpoints may be written more often, depending on other factors. The unit is seconds.

This can be changed at runtime only by SystemUser.

Runtime parameter: #StnCheckpointInterval
Units: seconds
Min: 5
Max: 1800
Default: 300

STN_COMMIT_QUEUE_THRESHOLD

STN_COMMIT_QUEUE_THRESHOLD determines whether the Stone defers the disposal of commit records, based on the number of sessions in the commit queue and the run queue. If the size of either of these queues exceeds this threshold, the Stone defers commit record disposal until all queues have sizes less than or equal to the value.

This setting is ignored if the commit record backlog exceeds the value of STN_CR_BACKLOG_THRESHOLD.

Runtime parameter: #StnCommitQueueThreshold
Default: -1 (never defer commit record disposal)
Min: -1
Max: 1024

STN_COMMIT_RECORD_BM_CACHING

When true, enables caching at the commit point of page allocation information needed when disposing a commit record. This option can reduce I/Os during commit record dispose when the commit record backlog is high, or when there is a lot of page preemption occurring in the shared cache.

When enabled, the maximum commit rate is slightly lower and commit latency is slightly higher because more work is done in the commit critical region in stone.

Default: true

STN_COMMIT_RECORD_QUEUE_SIZE

STN_COMMIT_RECORD_QUEUE_SIZE determines the size of the Stone's internal commit record cache. The Stone will keep copies of up to this many commit records in heap memory. Stone is able to dispose commit records more quickly when a copy of the commit record is found in this cache.

When the default value of -1 is specified, Stone sets this value to be twice the value of the STN_SIGNAL_ABORT_CR_BACKLOG option.

Units: Commit Record Pages
Default: -1
Min: 16
Max: 1000000

STN_COMMIT_TOKEN_TIMEOUT

STN_COMMIT_TOKEN_TIMEOUT sets the maximum interval (in seconds) that a session may possess the commit token. If the session possesses the token for longer than this period, the session will be logged off the system and an error message written to the Stone log. If the value is non zero, GcGems of all types will have a timeout of twice the configured value.

Default: 0 (Stone waits forever)
Min: 0
Max: 86400

STN_COMMITS_ASYNC

If STN_COMMITS_ASYNC is set to TRUE, it causes the stone to acknowledge each commit or persistent shared counter update to the requesting session without waiting for the tranlog writes for that commit to complete.

Default: FALSE

STN_CR_BACKLOG_THRESHOLD

STN_CR_BACKLOG_THRESHOLD sets the size of the commit record backlog above which the Stone aggressively disposes of commit records. This setting overrides the deferral of commit record disposal provided by the STN_COMMIT_QUEUE_THRESHOLD parameter.

The default setting of -1 causes the Stone to use a setting equal to (2 * STN_MAX_SESSIONS). A setting of 0 disables this threshold.

Runtime parameter: #StnCrBacklogThreshold
Default: -1
Min: -1
Max: 500000

STN_DISABLE_LOGIN_FAILURE_LIMIT

STN_DISABLE_LOGIN_FAILURE_LIMIT is the number of failed login attempts, within the time limit set by STN_DISABLE_LOGIN_FAILURE_TIME_LIMIT, that result in the user account being disabled. When an account exceeds these limits, the user account is disabled (the system changes the password on the account to one that is invalid) and a record of the event is written to the Stone log file. The user account can only be restored by another user with OtherPassword privileges.

Changes to the runtime parameter requires the OtherPassword privilege.

Runtime parameter: #StnDisableLoginFailureLimit
Units: login attempts
Default: 15
Min: 0
Max: 65536

STN_DISABLE_LOGIN_FAILURE_TIME_LIMIT

STN_DISABLE_LOGIN_FAILURE_TIME_LIMIT is the period of time in which if STN_DISABLE_LOGIN_FAILURE_LIMIT number of failed login attempts are made, the user account will be disabled (the system changes the password on the account to one that is invalid) and a record of the event is written to the Stone log file. The user account can only be restored by another user with OtherPassword privileges.

Changes to the runtime parameter requires the OtherPassword privilege.

Runtime parameter: #StnDisableLoginFailureTimeLimit
Units: Minutes
Default: 15
Min: 1
Max: 1440 (24 hours)

STN_DISKFULL_TERMINATION_INTERVAL

STN_DISKFULL_TERMINATION_INTERVAL specifies how soon (in minutes) the Stone should start terminating sessions holding on to the oldest commit record when the repository free space is below the value set for STN_FREE_SPACE_THRESHOLD. Such sessions are sent the fatal diskfull error.

The runtime parameter can be changed only by SystemUser.

Runtime parameter: #StnDiskFullTerminationInterval
Units: Minutes
Min: 0 (no sessions are terminated)
Max: 1440 (24 hours)
Default: 3

STN_EPOCH_GC_ENABLED

STN_EPOCH_GC_ENABLED determines if epoch garbage collection can be run on the system. Leave this value set to FALSE unless you plan to run epoch garbage collection on the system. Setting this to TRUE adds a small amount of overhead to commit processing.

Runtime parameter: #StnEpochGcEnabled
Default: FALSE

STN_EXTENT_IO_FLAGS

STN_EXTENT_IO_FLAGS specifies what (if any) special I/O flags will be used to open the database extents. Two kinds of special I/O are supported: direct I/O and concurrent I/O.

Direct I/O tells the operating system avoid caching extent data in the file system cache. Enabling direct I/O tells the operating system to treats the database extents as if they were on raw partitions. Direct I/O may greatly improve database performance in some cases. Concurrent I/O is only available to extents running on the Enhanced JFS file system (aka JFS2) on AIX. Setting this flag has no effect on other operating systems.

STN_EXTENT_IO_FLAGS has the following possible values:

0 - no special I/O flags. This is the default.
1 - enable Direct I/O on all extents on file systems.
2 - enable concurrent I/O (AIX only)

If the requested I/O mode is not available, the stone will fail to start and an error message will be printed in the stone log. If this happens, change this option back to zero and restart the stone.

STN_EXTENT_IO_FLAGS has no effect on extents which reside on raw partitions.

Once the stone starts, all processes which open the database extents (gems and page servers) will open the extents using the same I/O flags. This behavior is required by some operating systems.

Default: 0
Min: 0
Max: 2 (AIX only), 1 (All Others)

STN_FREE_FRAME_CACHE_SIZE

STN_FREE_FRAME_CACHE_SIZE specifies the size of the Stone’s free frame cache. When using the free frame cache, the Stone removes enough frames from the free frame list to refill the cache in a single operation.

Units: frames
Default: 1 (disables the free frame cache; Stone acquires frames one at a time)
Min: 1
Max: 1% of the frames in the cache

STN_FREE_SPACE_THRESHOLD

STN_FREE_SPACE_THRESHOLD sets the minimum amount of free space to be available in the repository. If the Stone cannot maintain this level by growing an extent, it begins to take action to prevent the shutdown of the system. If the amount of free space remains below this level for more than the number of minutes specified by STN_DISKFULL_TERMINATION_INTERVAL, the stone will start terminating sessions. For more information, see Repository Full.

The default value of 0 specifies a varying STN_FREE_SPACE_THRESHOLD that is computed when needed as the current size of the repository divided by 1000, with a minimum value of 5 MB.

If no units are specified, the value is in MB. You may also specify units as KB, MB, or GB.

The runtime parameter can be changed only by SystemUser.

Runtime parameter: #StnFreeSpaceThreshold
Default units: MB
Default: 0 (system computes based on repository size)
Min: 0
Max: 65536 MB

STN_GEM_ABORT_TIMEOUT

STN_GEM_ABORT_TIMEOUT sets the time in minutes that the Stone will wait for a Gem running outside of a transaction to abort (in order to release a commit record), after Stone has signaled that Gem to do so. If the time expires before the Gem aborts, the Stone sends the Gem the error ABORT_ERR_LOST_OT_ROOT, and then either stop the Gem or force it to completely reinitialize its object caches, depending on the value of the related configuration parameter STN_GEM_LOSTOT_TIMEOUT. Negative timeouts are not allowed. Resolution of timeouts is one half the specified time-out interval.

The runtime parameter can be changed only by SystemUser.

Runtime parameter: #StnGemAbortTimeout
Default: 1
Min: 1
Max: 1440

STN_GEM_LOSTOT_TIMEOUT

STN_GEM_LOSTOT_TIMEOUT sets the time in seconds that the Stone will wait after signaling the Exception RepositoryViewLost, before retracting the Gem’s commit record and forcibly stopping the session.

If set to zero, no signal is sent; the stone immediately stops the session.

The runtime parameter can be changed only by SystemUser.

Runtime parameter: #StnGemLostOtTimeout
Default: 60
Min: 0
Max: 5000000

STN_GEM_PGSVR_CONNECT_TIMEOUT

The time in seconds that a remote gem will wait for a connection to a pgsvr on stone's machine to complete.

Runtime equivalent: #StnGemPgsvrConnectTimeout (may only be set by SystemUser)
Default: 20
Min: 5
Max: 3600

STN_GEM_PRIVATE_PGSVR_ENABLED

A Boolean , TRUE means a remote gem will start a private pgsvr process if the attempt to connect to a multi-threaded pgsvr on stone's machine fails.

Runtime equivalent: #StnGemPrivatePgsvrEnabled (may only be set by SystemUser)
Default: FALSE

STN_GEM_TIMEOUT

STN_GEM_TIMEOUT sets the time in minutes after which lack of interaction with the Gem causes the Stone to terminate the session. Negative timeouts are not allowed. Resolution of timeouts is one half the specified time-out interval. If non-zero, this timeout is also the maximum time allowed for a Gem to complete processing of its login to the Stone. If this timeout is 0, the maximum time for login processing is set to five minutes.

The runtime parameter can be changed only by SystemUser.

Runtime parameter: #StnGemTimeout
Min: 0
Default: 0 (Stone waits forever)

STN_GROUP_COMMITS

A value greater than 1, specifies maximum number of commits to group into a tranlog write. Grouping is performed only if another session is waiting to commit while stone is processing a session's commit.

Default: 10
Min: 1
Max: 20

STN_HALT_ON_FATAL_ERR

If STN_HALT_ON_FATAL_ERR is set to true, the Stone will halt and dump core if it receives notification from a Gem that the Gem died with a fatal error that would cause Gem to dump core. By stopping the Stone at this point, the possibility of repository corruption is minimized. true is the recommended setting for systems during development.

If STN_HALT_ON_FATAL_ERR is set to false, the Stone will attempt to keep running if a Gem encounters a fatal error. false is the recommended setting for systems in production use.

Internally, the setting 0 = false, 1 = true. The runtime parameter can be changed only by SystemUser.

Runtime parameter: #StnHaltOnFatalErr
Default: false

STN_LISTENING_ADDRESSES

STN_LISTENING_ADDRESSES is a list of 0 to 10 addresses upon which stone should listen for login connections. If list is empty, the default address "::" is used , which means listen on any active network interfaces, plus the loopback ("::1") interface .

Each element of the list may be a name or a numeric IPv6 address. Each named address must resolve via getaddrinfo() to at least one address legal to listen on, i.e. resolve to the loopback or wildcard address, or to an address assigned to a network interface on this machine. Each numeric address must be an address legal to listen on.

Numeric IPv6 addresses may be any form recognized by inet_pton(AF_INET6, address, etc.) or by inet_pton(AF_INET, address, etc.) on the host operating system. Per RFC 2373 this includes these forms:

• IPv4 dotted-decimal format, d.d.d.d
• IPv6 hex format x:x:x:x:x:x:x:x where x is a 16 bit hexadecimal number
• IPv4-mapped IPv6 ::FFFF:d.d.d.d where d is an 8 bit decimal number

IPv6 format may contain at most one :: which is a contiguous group of zeros. The loopback address 0:0:0:0:0:0:0:1 can be written as ::1. The wildcard address 0:0:0:0:0:0:0:0 can be written as ::.

If the list contains the wildcard address ::, the other elements of the list are ignored.

If the list does not contain ::, then the loopback addresses ::1 and 127.0.0.1 are always listened on, even if not explicitly in the list, to support logins from system gems.

See public documents RFC 4291 and RFC 4038 for more information on IPV6 addressing.

Default: An empty list, "::"

STN_LOGIN_LOG_DIR

STN_LOGIN_LOG_DIR specifies a directory where the login log is located when the STN_LOGIN_LOG_ENABLED option is set to TRUE. If STN_LOGIN_LOG_ENABLED is false, this option is ignored. If STN_LOGIN_LOG_DIR is not specified and STN_LOGIN_LOG_ENABLED is set to TRUE, then the login log will be placed in the same directory as the stone log. It is a fatal error if the directory specified is not writable by the stone process.

Default: Stone log’s directory
Min: 0 entries
Max: 1 entry

STN_LOGIN_LOG_ENABLED

STN_LOGIN_LOG_ENABLED enables the logging of all session login and logout events to s separate log file owned by the stone. The file will be named stoneName_login_timestamp.log and will be placed in the same directory as the stone log, unless a directory is specified using STN_LOGIN_LOG_DIR.

When this feature is enabled, logins and logouts are recorded for all sessions by default. Logging may by disabled for a UserProfile by sending the #disableLoginLogging message to a UserProfile instance and committing the transaction.

The login log file is a text file that contains one line per event. Fields within a line are separated by spaces; the Timestamp String is quoted. The fields logged in each line are:

• Timestamp String - time in human-readable form
• Timestamp Seconds - seconds from the epoch (January 1, 1970, 00:00 UTC)
• Event Kind - one of STARTUP, SHUTDOWN, LOGIN, LOGIN_FAIL, LOGOUT, or COMMIT_RESTORE.
• UserName - the UserProfile’s userId, or "Stone" for the stone process.
• SessionId
• ProcessId
• Real UNIX user ID - numeric value
• Effective UNIX user ID - numeric value.
• Host Name - node name where the gem process is running.
• Gem IP Address - IP Address of the gem.
• Client IP Address - IP Address of the gem's client.
• NumCommits - number of commits performed by the session.
• Login UNIX user ID - numeric value
• KerberosPrincipal - the name of the principal used for passwordless login, or ''.

STARTUP and SHUTDOWN records are written to indicate when the stone was started and stopped and do not indicate a session login or logout.

Login failures are written for non-exempt sessions that fail a login attempt, usually due to specifying a bad password.

Default: FALSE

STN_LOGIN_LOG_HALT_ON_ERROR

STN_LOGIN_LOG_HALT_ON_ERROR specifies the behavior of the stone if a write to the login log file fails. If this option is set to TRUE, the Stone will shutdown if the login log file cannot be written, due to lack of disk space or any other error. If this option is set to FALSE, the Stone does not halt but a warning message is printed to the Stone log.

Default: FALSE

STN_LOGIN_LOG_MAX_SIZE

STN_LOGIN_LOG_MAX_SIZE specifies the maximum size of the login log file in megabytes. Once the login log file reaches this size, it will be closed and a new login log file will be created. 0 means no file size limitation and the file size is not monitored by GemStone.

If no units are specified, the value is in KB. You may also specify units as KB, MB, or GB.

Default Units: MB
Default: 0 (no size limit)
Min: 0
Max: 1024 MB

STN_LOG_IO_FLAGS

STN_LOG_IO_FLAGS specifies what (if any) special I/O flags will be used to open the database transaction logs.

This configuration is only applicable for Solaris.

Direct I/O tells the operating system avoid caching extent data in the file system cache. Enabling direct I/O tells the operating system to treats the database tranlogs as if they were on raw partitions. Direct I/O may greatly improve database performance in some cases.

STN_LOG_IO_FLAGS has no effect for tranlogs on raw partitions.

STN_LOG_IO_FLAGS has the following possible values:

0 - no special I/O flags. This is the default.
1 - enable Direct I/O on all tranlogs on file systems (Solaris only).

If the requested I/O mode is not available, the stone will fail to start and an error message will be printed in the stone log. If this happens, change this option back to zero and restart the stone.

STN_LOG_IO_FLAGS has no effect on tranlogs which reside on raw partitions.

Min: 0
Max: 1 (Solaris only), 0 (All Others)
Default: 0

STN_LOG_LOGIN_FAILURE_LIMIT

If a user has greater than or equal to the STN_LOG_LOGIN_FAILURE_LIMIT number of login failures within the time in minutes specified by STN_LOG_LOGIN_FAILURE_TIME_LIMIT, a message is written to the Stone log file.

Changes to the runtime parameters require the OtherPassword privilege.

Runtime parameter: #StnLogLoginFailureLimit
Units: login attempts
Min: 0
Max: 65536
Default: 10

STN_LOG_LOGIN_FAILURE_TIME_LIMIT

If a user has greater than or equal to the STN_LOG_LOGIN_FAILURE_LIMIT number of login failures within the time in minutes specified by STN_LOG_LOGIN_FAILURE_TIME_LIMIT, a message is written to the Stone log file.

Changes to the runtime parameters require the OtherPassword privilege.

Runtime parameter: #StnLogLoginFailureTimeLimit
Units: Minutes
Min: 1
Max: 1440 (24 hours)
Default: 10

STN_LOOP_NO_WORK_THRESHOLD

STN_LOOP_NO_WORK_THRESHOLD indicates the maximum number of times the stone will continue executing its main service loop when there is no work to do. If the stone loops more than this number of times and finds no work, the stone will sleep for up to one second. The stone will immediately wake up when there is any work to be done.

Setting this value to zero disables this feature. Setting this value to a non-zero setting, in addition to causing the above behavior, will also cause the stone to not sleep whenever any of the following conditions are true and the no work threshold has not been exceeded:

• a session holds the commit token
• one or more sessions are waiting in the commit queue
• one or more sessions are waiting in the run queue.

Setting this parameter to a non-zero value will always cause the stone to consume more CPU.

Runtime parameter: #StnLoopNoWorkThreshold
Default: 0
Min: 0
Max: 536870911

STN_MAX_AIO_RATE

STN_MAX_AIO_RATE specifies the maximum I/O rate that each AIO page server thread is allowed when performing asynchronous writes. Since the I/O rate specified is applied to each thread, the total maximum I/O rate on the disk system is this value multiplied by STN_NUM_LOCAL_AIO_SERVERS.

The page server uses this maximum I/O rate for both dirty page and checkpoint writes.

Runtime parameter: #StnMntMaxAioRate
Min: 20
Max: 1000000
Default: 3000

STN_MAX_AIO_REQUESTS

STN_MAX_SESSIONS specifies the maximum number of asynchronous write requests the stone can have pending. If more than this number of asynchronous writes are requested, the stone will wait (sleep) until one or more of the pending requests have completed. Asynchronous write requests are only used to write to the current tranlog.

Min: (2 * STN_NUM_AIO_WRITE_THREADS)
Max: 4096
Default: the lower of SHR_PAGE_CACHE_NUM_PROCS and 128

STN_MAX_GC_RECLAIM_SESSIONS

The maximum number of page reclaim garbage collector sessions which are expected to be used on the system. When the default is specified, the actual value used is the number of extents defined in DBF_EXTENT_NAMES configuration.

Default: 0
Minimum: 0
Maximum: 256

STN_MAX_LOGIN_LOCK_SPIN_COUNT

Maximum number of times a session will attempt to write lock its user security data object at login time before raising a fatal error and failing the login. The session will sleep for 100 milliseconds between retries.

Enabling certain UserProfile security features (password aging, etc) causes each session to update its user security data object at login time and commit. A write lock must be acquired on this object to guarantee the commit succeeds.

Each UserProfile has a unique user security data object. Lock retries may be required when 2 sessions attempt to login with the same user ID at nearly the same instant. Simultaneous logins that user different user IDs never require lock retries.

Repositories that do not enable UserProfile security features are not affected by this parameter because the write-lock and commit described above are not required at login time.

Runtime parameter: #StnMaxLoginLockSpinCount
Default: 100
Minimum: 1
Maximum: 36000

STN_MAX_REMOTE_CACHES

STN_MAX_REMOTE_CACHES specifies the maximum number of remote shared page caches that the system may have.

Min: 0
Max: 10000
Default: 255

STN_MAX_SESSIONS

STN_MAX_SESSIONS limits the number of simultaneous sessions (number of Gem logins to Stone). The actual value used by Stone is the value of this parameter or the number of sessions specified by the software license key file, whichever is less. Using a value that is larger than needed will result in wasted space in the cache.

The number of logins may also be limited by changes in SHR_PAGE_CACHE_NUM_PROCS, or by the setting for the maximum number of file descriptors per process (imposed by the operating system kernel).

Recommended: 40 or more, depending on your requirements
Min: 1
Max: 32767
Default: 40

STN_MAX_VOTING_SESSIONS

STN_MAX_VOTING_SESSIONS specifies the maximum number of sessions that can simultaneously vote on possible dead objects, at the end of a markForCollection or epoch garbage collection. To help prevent the voting on possible dead objects from causing large increases in response time of the system, set this to a value substantially lower than STN_MAX_SESSIONS.

Runtime parameter: #StnMaxVotingSessions
Min: 1
Max: 1000000
Default: 100

STN_NUM_AIO_WRITE_THREADS

STN_NUM_AIO_WRITE_THREADS specifies the number of native threads the Stone will start to perform writes to the tranlog. In commit-intensive systems, this should be increased, generally to 8 or 16.

Cache Statistic: StnAioNumWriteThreads (Stone)
Min: 4
Max: 256
Default: 4

STN_NUM_GC_RECLAIM_SESSIONS

STN_NUM_GC_RECLAIM_SESSIONS specifies the number of page reclaim garbage collector sessions (Reclaim Gem sessions) that will be started when the Stone starts. This value must be less than or equal to STN_MAX_GC_RECLAIM_SESSION.

Runtime parameter: #StnNumGcReclaimSessions
Default: 1
Min: 0
Max: 256

STN_NUM_LOCAL_AIO_SERVERS

STN_NUM_LOCAL_AIO_SERVERS is the number of threads to be started in the AIO page server process on the Stone’s machine. AIO page server threads write dirty pages from the shared page cache to the repository extents on disk.

For systems with two or more extents, in which the disk drive hardware allows concurrent writes to disk, multiple AIO page server threads can improve performance. You may not specify a number of AIO page server threads greater than the number of extents.

Min: 1
Max: 256
Default: 4 or the number of extents, whichever is smaller

STN_OBJ_LOCK_TIMEOUT

STN_OBJ_LOCK_TIMEOUT specifies the time in seconds that a session is allowed to wait to obtain one of the special single object write locks. For more information, see System >> waitForApplicationWriteLock:queue:autoRelease:.

Runtime parameter: #StnObjLockTimeout
Min: 0
Max: 86400
Default: 0 (stone waits forever)

STN_PAGE_MGR_COMPRESSION_ENABLED

STN_PAGE_MGR_COMPRESSION_ENABLED determines if the page manager thread in Stone will compress the list of pages that it sends to remote shared page caches for removal. If set to TRUE, all lists of pages larger than 50 will be compressed before transmission using the > LZ4_compress() function from the LZ4 compression library.

The same compressed list is used to send to all remote shared page caches; i.e., the compression operation is performed no more than once for each list of pages to be sent.

This option has no effect on systems that do not use remote shared page caches.

Runtime parameter: #StnPageMgrCompressionEnabled
Cache Statistic: PageMgrCompressionEnabled (Stone)
Default: FALSE

STN_PAGE_MGR_MAX_WAIT_TIME

Maximum time the Stone will defer servicing the page manager thread because the Stone is busy with other tasks. Normally the Stone services the page manager thread whenever it has idle time and no session is performing a commit. If the time the page manager thread has been waiting for service exceeds this value, the stone will service the page manager unconditionally and increment the cache statistic PageManagerStarvedCount.

Runtime parameter: #StnPageMgrMaxWaitTime
Units: Milliseconds
Default: 200
Min: 1
Max: 1000

STN_PAGE_MGR_PRINT_TIMEOUT_THRESHOLD

STN_PAGE_MGR_PRINT_TIMEOUT_THRESHOLD is the threshold in real seconds used by the page manager thread in Stone to determine if a slow response from a remote shared page cache should be printed to the page manager log file. If a remote cache takes longer than this number of seconds to respond to the page manager, the page manager will print a message to the log file. If a remote cache takes less than this number of seconds to respond, no message is printed.

Note that this value controls the writing of log messages only. The connection to the remote cache will not be terminated by page manager unless STN_REMOTE_CACHE_PGSVR_TIMEOUT is exceeded.

Runtime parameter: #StnPageMgrPrintTimeoutThreshold
Cache Statistic: PageMgrPrintTimeoutThreshold (Stone)
Min: 0
Max: 3600
Default: 5

STN_PAGE_MGR_REMOVE_MAX_PAGES

STN_PAGE_MGR_REMOVE_MAX_PAGES sets the maximum batch size for the Page Manager thread in Stone. This is the maximum number of pages in a single request to the stone. Must be greater than or equal to STN_PAGE_MGR_REMOVE_MIN_PAGES

Runtime parameter: #StnPageMgrRemoveMaxPages
Cache Statistic: PageMgrRemoveMaxPages (Stone)
Min: 1
Max: 16384
Default: 16384

STN_PAGE_MGR_REMOVE_MIN_PAGES

STN_PAGE_MGR_REMOVE_MIN_PAGES sets the minimum batch size for the Page Manager gem. When the number of pages waiting to be processed by the Page Manager is greater than this value, then the Page Manager will request the pages from the stone and process them. Otherwise the Page Manager will wait until this threshold is exceeded before requesting pages from the stone. Must be less than or equal to STN_PAGE_MGR_REMOVE_MAX_PAGES

Runtime parameter: #StnPageMgrRemoveMinPages
Cache Statistic: PageMgrRemoveMinPages (Stone)
Min: 0
Max: 1792
Default: 40

STN_PGSVR_PORT_RANGE

A list of two integers specifying the minimum and maximum port range to be used for listening sockets in pgsvr processes on the stone machine. Such pgsvr processes will listen on the first available port from this range, using the address that was used by the remote gem when it contacted the netldi to start the pgsvr, i.e. one of the addresses from the -A argument to that netldi's startnetldi command.

Both elements on the list must be between 1 and 65535, and the second element must be greater than the first.

Default: empty (random ports above 10000 will be used)

STN_PRIVATE_PAGE_CACHE_KB

STN_PRIVATE_PAGE_CACHE_KB sets the default size of the Stone page cache.

If no units are specified, the value is in KB. You may also specify units as KB, MB, or GB.

Default units: KB
Min: 128 KB
Max: 524288 KB
Default: 2000 KB

STN_REMOTE_CACHE_PGSVR_TIMEOUT

STN_REMOTE_CACHE_PGSVR_TIMEOUT specifies the maximum time in seconds that the page manager session will wait for a response from a page server on a remote shared page cache. If no response is received within the timeout period, all Gems attached to that cache are logged off and a message is written to the Stone and page manager logs. Negative timeouts are not allowed. A timeout value of zero causes the page manager to wait forever.

Runtime parameter: #StnRemoteCachePgsvrTimeout
Cache Statistic: PageMgrRemoteCachePgsvrTimeout (Stone)
Min: 0
Max: 3600
Default: 15

STN_REMOTE_CACHE_STARTUP_TIMEOUT

STN_REMOTE_CACHE_STARTUP_TIMEOUT is the time in seconds allowed for startup of a remote shared cache. This is time from when first Gem on the remote machine connects to the Stone process until the remote cache completes its connection to the pagemanager thread in the Stone. Within this interval the first Gem forks the remote cache and that cache has to create its shared memory.

A scaledTimeout is also computed based on size of a shared cache

scaledTimeout := cacheSize <= 32GB 

	ifTrue:[ (cacheSize / 32GB)  * 120]

	ifFalse:[ 120 + ((cacheSize - 32GB / 268GB) * 300) ]

If the scaledTimeout exceeds the configured value of STN_REMOTE_CACHE_STARTUP_TIMEOUT , the scaledTimeout is used for that cache.

Runtime equivalent: #StnRemoteCacheStartupTimeout
Default: 60
Min: 10
Max: 1800

STN_REMOTE_CACHE_TIMEOUT

STN_REMOTE_CACHE_TIMEOUT sets the time in minutes after the last active process on a remote node logs out before the Stone shuts down the shared page cache on that node.

A value of 0 causes the Stone to shut down the remote cache as soon as possible.

The runtime parameter can be changed only by SystemUser.

Runtime parameter: #StnRemoteCacheTimeout
Min: 0
Max: 5000000
Default: 5

STN_SHR_TARGET_PERCENT_DIRTY

STN_SHR_TARGET_PERCENT_DIRTY specifies the maximum percentage of the Stone’s shared page cache that can contain dirty pages without AIO page server increasing its IO rates.

Runtime parameter: #StnShrPcTargetPercentDirty
Min: 1
Max: 90
Default: 20

STN_SIGNAL_ABORT_AGGRESSIVE

If the number of outstanding commit records exceeds STN_SIGNAL_ABORT_CR_BACKLOG, then STN_SIGNAL_ABORT_AGGRESSIVE is the maximum number of sessions which will receive SignalAbort when those sessions reference a commit record beyond STN_SIGNAL_ABORT_CR_BACKLOG and newer than the oldest commit record.

Changing the runtime parameter requires GarbageCollection privilege.

Runtime equivalent: #StnSignalAbortAggressive
Default: 0
Min: 0
Max: 500

STN_SIGNAL_ABORT_CR_BACKLOG

STN_SIGNAL_ABORT_CR_BACKLOG sets the number of old transactions (commit records) above which the Stone will start to generate SignalAbort messages to Gems. The Gem receives these as a TransactionBacklog exception.

If the Gem is not in transaction, this is received if the Gem has enabled receipt of sigAborts by invoking System >> enableSignaledAbortError. If the Gem that is out of transaction does not respond within the time allowed by STN_GEM_ABORT_TIMEOUT, the Gem will receive a ABORT_ERR_LOST_OT_ROOT.

If the Gem is in transaction, it will receive finishTransaction if it has invoked System >> enableSignaledFinishTransactionError. No further signals are sent to a Gem that is in transaction, whether or not it responds to the signal.

You may need to tune this option according to your application’s commit rate and repository free space.

Changing the runtime parameter requires GarbageCollection privilege.

Runtime parameter: #StnSignalAbortCrBacklog
Default: 20
Min: 2
Max: 65536

STN_SMC_SPIN_LOCK_COUNT

STN_SMC_SPIN_LOCK_COUNT specifies the number of times a process (gem or page server) that is waiting for a response from the stone will check a variable in shared memory before sleeping on a semaphore. Higher values can lead to higher throughput on performance-intensive systems, at the expense of higher CPU consumption.

Setting this value to 0 disables this feature, which causes the client process to always wait on the semaphore without checking the variable in shared memory.

Runtime equivalent: #StnSmcSpinLockCount
Cache Statistic: StnSmcSpinLockCount (Stone)
Min: 0
Max: 10000000
Default: 5000

STN_STATMONITOR_ARGS

STN_STATMONITOR_ARGS provides a way to automatically start statmonitor when the stone is started. If it is set to a non-empty list of arguments, these argument are passed to the statmonitor executable and statmonitor will be started automatically by the stone when it starts.

The list of possible arguments can be obtained by invoking statmonitor with only the "-h" argument. The first argument to statmonitor (the name of the stone) is automatically passed to statmonitor and must not be included here.

For example, to start statmonitor with a 5 second sample interval, with a date and timestamp included in the output file name, and with the resulting output file placed in the directory /statmonFiles, the following setting would be configured:

STN_STATMONITOR_ARGS = 

"-i5 -u5 -d /statmonFiles -F'statmon_%%S_%%P_%d-%m-%y-%H:%M:%S'";

Default: "" (statmonitor will not be started)

STN_STONE_CACHE_STARTUP_TIMEOUT

STN_STONE_CACHE_STARTUP_TIMEOUT specifies the time in seconds allowed for the startup of the shared cache on the Stone’s machine. This is time from when the Stone forks the page cache monitor process until it is able to complete its connection to that process.

A scaledTimeout is also computed based on the size of the shared cache

scaledTimeout := cacheSize <= 32GB 

	ifTrue:[ (cacheSize / 32GB)  * 120]

	ifFalse:[ 120 + ((cacheSize - 32GB / 268GB) * 300) ]

If the computed scaledTimeout exceeds the configured value of STN_STONE_CACHE_STARTUP_TIMEOUT, the scaledTimeout is used.

Min: 10
Max: 1800
Default: 60

STN_SYMBOL_GC_ENABLED

STN_SYMBOL_GC_ENABLED determines if symbol garbage collection is allowed to run on the system. Setting this value to true enables symbol garbage collection.

Updating the runtime parameter requires the GarbageCollection privilege.

Runtime parameter: #StnSymbolGcEnabled
Default: FALSE

STN_SYMBOL_GEM_TEMPOBJ_CACHE_SIZE

STN_SYMBOL_GEM_TEMPOBJ_CACHE_SIZE specifies the temporary object memory size of the Symbol Gem. The Stone's runtime parameter #StnSymbolGemTocSize is initialized from STN_SYMBOL_GEM_TEMPOBJ_CACHE_SIZE at stone startup. If the Symbol Gem dies (other than from an explicit execution of System stopSymbolGem), and is automatically restarted, then the setting for #StnSymbolGemTocSize setting will be doubled.

This doubling only occurs for the first restart since either Stone startup or an runtime change to #StnSymbolGemTocSize.

While the default is normally 20MB, if repository conversion is detected at stone startup (startstone -C) the default is 200MB.

Runtime equivalent: #StnSymbolGemTocSize
Min: 10000KB
Max: 10GB
Default: 20MB

STN_TRAN_FULL_LOGGING

If STN_TRAN_FULL_LOGGING is set to true, all transactions are logged, and log files are not deleted by the system. This is full transaction logging mode. In this mode, the transaction logs are providing real-time incremental backup of the repository. If no disk space is available for logs, Gem session processes may appear to “hang” until space becomes available.

If STN_TRAN_FULL_LOGGING is set to false, only transactions smaller than STN_TRAN_LOG_LIMIT are logged; larger transactions cause a checkpoint, which updates the extent files. This is partial transaction logging mode. Log files are deleted by the system when the circular list of log directories wraps around. This setting allows a simple installation to run unattended for extended periods of time, but it does not provide real-time backup.

Once you have started the Stone on a repository with STN_TRAN_FULL_LOGGING = true, then the true state will persist in the repository; any subsequent changes to this parameter in the configuration file are ignored. To change the repository back to partial logging, you must do a Smalltalk full backup and then restore the backup into a copy of $GEMSTONE/bin/extent0.dbf.

For further information, see Chapter 10, “Managing Transaction Logs”.

Default: NONE. The system will not run unless you specify the logging type.

STN_TRAN_LOG_DEBUG_LEVEL

This option is only for GemStone internal use. Customers should not change the default setting unless directed to do so by GemStone Technical Support.

Runtime parameter: #StnTranLogDebugLevel
Default: 0

STN_TRAN_LOG_DIRECTORIES

STN_TRAN_LOG_DIRECTORIES lists the directories or raw disk partitions to be used for transaction logging. This list defines the maximum number of log files that will be online at once. Each entry must be a directory or a raw disk partition. Directories may appear multiple times in the list. A given raw disk partition may appear only once. If raw partitions are used or if STN_TRAN_FULL_LOGGING is false, at least two entries should be included.

STN_TRAN_LOG_DIRECTORIES may be set to /dev/null in development systems; this means that no tranlog records at all are written. If the repository shuts down unexpectedly, committed work done since the last checkpoint is irretrievably lost.

Min: 1 entry
Max: 231 entries
Default: Empty (the system will not run without at least one entry)
Initial setting: $GEMSTONE/data/

STN_TRAN_LOG_LIMIT

STN_TRAN_LOG_LIMIT sets the maximum transaction log entry size limit in KB. Successful commits of transactions consuming more than this amount of log file space when STN_TRAN_FULL_LOGGING is set to false will cause a checkpoint. This option has no effect when STN_TRAN_FULL_LOGGING is set to true.

If no units are specified, the value is in KB. You may also specify units as KB, MB, or GB.

The runtime parameter can be changed only by SystemUser.

Default units: KB
Runtime parameter: #StnTranLogLimit
Min: 25 KB
Max: 1000 KB
Default: 1000 KB

STN_TRAN_LOG_PREFIX

STN_TRAN_LOG_PREFIX sets file name prefixes for transaction log files. A sequence number and “.dbf” is added to the prefix; for example, “tranlog” produces “tranlog0.dbf, tranlog1.dbf, ...”. You can set this configuration option to permit multiple repository monitors to share a log directory without conflict.

Default: tranlog

STN_TRAN_LOG_SIZES

STN_TRAN_LOG_SIZES sets the maximum sizes of all transaction log files, in order and separated by commas. Each size applies to a corresponding log file specified in STN_TRAN_LOG_DIRECTORIES, and the number of entries must match.

If no units are specified, the value is in MB. You may specify units as KB, MB, or GB.

Default units: MB
Min: 10 MB
Max: 16384 MB
Default: Empty (the system will not run unless sizes are specified)
Initial setting: 100 MB

STN_TRANQ_TO_RUNQ_THRESHOLD

The number of sessions in the commit queue (waiting for the commit token) that are allowed to simultaneously process unions (read old commit records) while waiting for the commit token.

For example, if this parameter is set to 2, then sessions commitQueue[1], and commitQueue[2] (if they exist) will process unions. The first session in the commit queue , commitQueue[0], will never process unions since it will receive the token when the current commit completes.

Cache Statistic: (Stone) StnTranQToRunQThreshold
Runtime equivalent: #StnTranqToRunqThreshold (may only be set by SystemUser)
Default: 2
Min: 1
Max: 20

STN_WELL_KNOWN_PORT_NUMBER

STN_WELL_KNOWN_PORT_NUMBER is the port number that the Stone will use as its well-known port. The well-known port is used by all Gems while establishing their initial connection to the Stone during the login sequence.

If the specified port is in use by another process, the Stone will not start and exits with an error.

A value of zero indicates the port number will be selected by the system.

Min: 1
Max: 65535
Default: 0

GemConvertArrayBuilder

If True, allows old style Array Builder syntax #[ a, b] to be parsed correctly. The compiler converts this syntax to the new form { a . b }, and updates method source as well as compiled code.

Default: false

GemDropCommittedExportedObjs

If this configuration parameter is true, clean, committed objects may be dropped from RAM. This reduces demand on memory in the Gem, but there is the small cost of an additional bitmap lookup when the object is faulted, to detect if this object is in the Pure Export Set.

Default: false

GemExceptionSignalCapturesStack

If this configuration parameter is true, invocations of AbstractException>>_signalWith: fill in the gsStack instance variable of the receiver, allowing subsequent calls to Exception >> stackReport.

Default: false

LogOriginTime

#LogOriginTime is the time the current sequence of Stone logs was started. It is the same value returned by Repository>>logOriginTime. For information about when a new sequence is started, see the method comment for Repository>>commitRestore in the image.

This should not be modified.

SessionInBackup

#SessionInBackup is the GemStone session number of the session performing a full backup, or –1 if a backup is not in progress.

This should not be modified by the user.

StnCurrentTranLogDirId

#StnCurrentTranLogDirId is the one-based offset of the current transaction log into the list of log directory names, STN_TRAN_LOG_DIRECTORIES. It is the same value returned by Repository>>currentLogDirectoryId.

This should not be modified.

StnCurrentTranLogNames

#StnCurrentTranLogNames is an Array containing up to two Strings: the name of the transaction log to which records currently are being appended, and the name of the current replicated log. These are the same values returned by Repository>>currentLogFile and currentLogReplicate, respectively.

StnLogFileName

The stone log file path and name.

This is a read-only value.

StnLogGemErrors

#StnLogGemErrors is intended for internal debugging use. When it is set to 1, the Stone logs error messages it sends to Gems.

StnLoginsSuspended

#StnLoginsSuspended ordinarily has the values 0 (false) and 1 (true) as set by System class>>suspendLogins and resumeLogins.

Changing this parameter requires the SystemControl privilege.

StnMaxReposSize

#StnMaxReposSize is the maximum size of the repository for your GemStone license, as set by the GemStone keyfile. The value of this parameter is 0 when not limited by the keyfile.

This should not be modified.

StnMaxSessions

#StnMaxSessions is the maximum allowed number of sessions for your GemStone license, as set by the GemStone keyfile. It is not related to the STN_MAX_SESSIONS configuration option. The value of this parameter is 0 when not limited by the keyfile.

This should not be modified.

StnStandbyRole

#StnStandbyRole reflects the role of this stone in a hot standby system. It should not be modified.

StnSunsetDate

#StnSunsetDate is the sunset date for your GemStone license, as set by the GemStone keyfile. The value of this parameter is 0 when not limited by the keyfile.

This should not be modified.

StnTranLogOriginTime

#StnTranLogOriginTime is the time when the current transaction log was started.

This should not be modified.