GemStone Configuration Options

Previous chapter

Next chapter

This appendix describes the GemStone/S 64 Bit configuration settings that control many facets of the GemStone system. It covers:

How GemStone Uses Configuration Files
describes system-wide and executable-dependent configuration files, how the system locates configuration files, and how to setup customized configuration files

Configuration File Syntax
lists syntax used within configuration files.

Configuration Options
describes of all options that can be used within configuration files

Runtime-only Configuration Options
lists configurations options that do not have settings for a configuration file, but have runtime settings that can be used in a running system.

A.1  How GemStone Uses Configuration Files

A GemStone/S 64 Bit configuration file is a file containing information that, when read at startup time, can control the configuration, behavior, and functionality of the system at run time. Some of these configuration settings can be modified dynamically by sending messages in GemStone Smalltalk.

The Stone, Gem, and linked applications (collectively, the repository executables) are able to read two different types of configuration files: system-wide configuration files and executable-dependent configuration files.

System-wide configuration files are found in a default location, passed by the -z argument, or located by a GEMSTONE_SYS_CONF environment variable.

Executable-dependent configuration files are found by name, passed by the -e argument, or located by a GEMSTONE_EXE_CONF environment variable.

These environment variables can be set in the usual way. For example:

$ GEMSTONE_EXE_CONF=$HOME/myFile.conf
$ export GEMSTONE_EXE_CONF

Both GEMSTONE_SYS_CONF and GEMSTONE_EXE_CONF can be defined to point to either a file or a directory.

At startup time, GemStone repository executables attempt to find and read both a system-wide and an executable-dependent configuration file, searching for these files in the following manner.

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.

Naming Executable Configuration Files

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

Application Gems

Stand-alone (RPC) Gems look for a file named gem.conf in the current working directory unless GEMSTONE_EXE_CONF is defined. The working directory by default is the user’s home directory, unless the gemnetobject script has been customized. The file $GEMSTONE/sys/gemnetobject is a script that a NetLDI invokes to start a GemStone session process. This script can be edited to define the name of the Gem to execute, the directory where the Gem resides, and the GEMSTONE_SYS_CONF and GEMSTONE_EXE_CONF environment variables.

System Gems

It is sometimes useful to change the parameters in a configuration file specific to a system Gem, such as the Admin or Reclaim Gem. This allows customized configuration settings that remain in effect if the system is stopped and restarted.

To do so:

Step 1. Copy $GEMSTONE/data/system.conf.

Step 2. Edit the copy, setting the values you want.

Step 3. Save your changes, renaming the file appropriately (for example, admingcgem.conf, reclaimgcgem.conf, etc., depending on which system Gem the new configuration file is for). Place the file in GemStone’s sys directory.

Step 4. Make a copy of the appropriate script/s.

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.

These scripts are located in $GEMSTONE/sys/. Name the copy appropriately; for example, $GEMSTONE/sys/myrunreclaimgcgem

Step 5. Edit myrunreclaimgcgem to specify the customized configuration file.

For example, to use a Reclaim Gem configuration file named $GEMSTONE/sys/reclaimgcgem.conf, locate the lines:

exeConfig="" 

and change to:

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

Step 6. Edit the file $GEMSTONE/sys/services.dat. Comment out the existing line:

runreclaimgcgem	$GEMSTONE/sys/runreclaimgcgem

and add an entry specifying the new script to be executed for the runreclaimgcgem service.

#runreclaimgcgem	$GEMSTONE/sys/runreclaimgcgem
runreclaimgcgem	$GEMSTONE/sys/myrunreclaimgcgem
Stone

Stone looks for a file named stoneName.conf in the current working directory.

Linked Topaz

The linked version of Topaz looks for the configuration file gem.conf in the current working directory, so, by default, Gem and Topaz can share the same options.

Linked GemBuilder for Smalltalk (GBS)

Linked GBS logins by default look for a file named gbs.conf in the current working directory.

Linkable GemBuilder for C Applications

Linkable GemBuilder for C applications look for a file named gci.conf in the current working directory unless the application has provided a different name by calling GciInitAppName().

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.

A.2  Configuration File Syntax

The following section describes the rules of grammar to be used in editing configuration files.

White space
Leading white space is ignored in the parsing of configuration files. Trailing white space is ignored if it follows the statement termination symbol (;).

New lines
New lines within a statement are allowed only after an equal sign or after a comma within a list of values.

Comments
The comment symbol for GemStone configuration files is the pound sign (#).
Comments can be embedded in a configuration file using the following rules:

Lists
Lists are separated by commas; list elements can be empty, for example:

DBF_EXTENT_SIZES = 2GB, , 2GB;

Within lists of values, leading and trailing white space is ignored.

Strings
Strings are encased in quotes. An empty string is acceptable in the grammar, and may be expressed by either two double quotes ("") or by no value at all (for instance, OPTION = ;).

Within strings, the escape character is the backslash (\). It can be used as follows:

To generate:

Use the sequence:

backslash (\)

\\

quote (")

\"

statement termination symbol (;)

\;

list separation character (,)

\,

control characters

\ followed by decimal representation of
the character as a zero-padded 3-digit
decimal number. For example, the string
control-N would read \014, because
control-N is ASCII 14.

Case-sensitivity
String option values are case-sensitive; boolean option names are not case-sensitive.

Maximum Sizes
The maximum number of characters allowed for a GemStone configuration option name is 64. The maximum length of a string option is 1024 characters. There is no limit on the number of elements within a list.

Use of Environment Variables In Options
Options that are either file names or directories may have environment variables as the first part of their value or the entire value.

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.

Syntax Errors

Syntax errors are generated whenever a grammatical error is detected in the configuration file. All syntax errors are warnings; they do not cause execution to terminate unless CONFIG_WARNINGS_FATAL is true. These errors include:

  • End-of-line or end-of-file detected before expected
  • Invalid starting character for an option name or invalid character within an option name
  • Equals or semicolon sign expected
  • Invalid 3-digit escape sequence
  • Invalid escape character
  • Terminating quote missing in a quoted string

Option Value Errors

Option value errors are generated when the value assigned to an option has no meaning or is of the wrong type. For example, an option value error is generated when an option defined to need a boolean for its value has been set to an integer.

Option value errors vary in severity. Some options, such as not specifying the list of files that make up a logical repository, will necessarily terminate execution. Other option value errors, such as a invalid cache size, might only generate warnings, unless CONFIG_WARNINGS_FATAL is true. When a warning is issued and CONFIG_WARNINGS_FATAL is false, the executable ignores the given value and use the option’s default value.

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

A.3  Configuration Options

The system configuration file contains the following standard configuration options. In this discussion, default refers to the value that results when an option is not explicitly set by a statement in the configuration file. Initial setting refers to an explicit setting in the initial system.conf file that differs from the default.

Some configuration options have an internal runtime parameter that can be changed while GemStone is running. Where such a parameter exists, its name is given as part of the entry. For more information, see To Change Settings at Run Time.

The $GEMSTONE/bin directory contains a write-protected file named initial.config that is an exact replicate of $GEMSTONE/data/system.conf as it was originally shipped. After modifying system.conf, you can always recover its original condition.

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 earlier 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_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_GCI_LOG_ENABLED

This option has no effect in customer executables.

Default: false

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_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 config 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 are:

findReferencePathToObject: (and related methods)
findAllReferencePathsToObjects: (and related methods)
pagesWithPercentFree: (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)
DefaultUnits: 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 temp obj 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_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_CACHE_WARMER

Specifies if the cache warmer should be run when the Stone is started and whether to load just the object table pages or both the object table and the data pages.

STN_CACHE_WARMER has the following possible values:
0 - Disabled, the stone does not start the cache warmer. This is the default.
1 - Start the cache warmer and load only the object table pages.
2 - Start the cache warmer and load the object table and data pages.

Default: 0

STN_CACHE_WARMER_SESSIONS

Specifies the number of worker sessions (threads) to use by the cache warmer Gem to perform cache warming on startup, if STN_CACHE_WARMER is not set to 0. In addition to the specified number of threads, there is one additional "master" session allocated. The warmer will exit with an error if not enough sessions are available.

With a default setting of 0, the warmer will run with the number of sessions computed by (numberOfCPUs + numberOfExtents).

Cache Statistic: NumCacheWarmers (Stone)
Units: sessions
Min: 0
Max: 256
Default: 0 (see discussion above)

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_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_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_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

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.

The maximum value allowed depends on the maximum allowed by the UNIX kernel. The maximum value for this parameter allowed by GemStone is the value of _SC_AIO_MAX or 4096, whichever is lower. On some systems (such as Solaris), it is not possible to determine the value of _SC_AIO_MAX. In that case, GemStone will impose a maximum value of 128. Otherwise the maximum is 4096 or _SC_AIO_MAX, which ever is lower.

For further information on the _SC_AIO_MAX kernel parameter, refer to the UNIX documentation for your system and/or the UNIX man page for the sysconf() call.

Min: 100
Max: the minimum of 4096 or _SC_AIO_MAX; or 128 (see above)
Default: 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 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: 1

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 the methods System >> waitForRcWriteLock: and 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 8, “Managing Transaction Logs”.

Default: true.

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.

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: 3 MB
Max: 16384 MB
Default: Empty (the system will not run unless sizes are specified)
Initial setting: 100 MB

STN_TRAN_Q_TO_RUN_Q_THRESHOLD

STN_TRAN_Q_TO_RUN_Q_THRESHOLD specifies the number of sessions in the commit queue (waiting for the commit token) above which the stone will allow the remaining sessions in the queue to process unions (read old commit records) while waiting for the commit token.

For example, if this parameter is set to 6 and there are 9 sessions in the commit queue, the 3 last sessions will be allowed to process unions while waiting for the token. If there are 6 or fewer sessions in the queue, no sessions will process unions.

The first session in the commit queue never processes unions since it will receive the token when the current commit completes.

Runtime parameter: #StnTranQToRunQThreshold
Min: 1
Max: 1024
Default: 6

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

A.4  Runtime-only Configuration Options

The parameters described in this section are similar to the configuration options above, but can only be read or modified at runtime.

The process for modifying is similar to that for the runtime parameter equivalents for the configuration options listed in the configuration files.

The runtime parameters are read using the method System class>>configurationAt:, and updating using System class>>configurationAt:put:.

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.

 

Previous chapter

Next chapter