GemStone Utility Commands

The GemStone/S 64 Bit utility commands in this appendix are provided in the $GEMSTONE/bin directory.

copydbf – copy an extent, transaction log or backup.
gemnetobject – script that starts a Gem during RPC login.
gslist – list running GemStone server processes.
largememorypages – calculate large memory page requirements.
pageaudit – offline audit of repository pages.
printlogs – print contents of a transaction log.
pstack – get C-level and Smalltalk stack traces.
removedbf – delete an extent, transaction log or backup.
searchlogs – search for OOPs within a transaction log.
startcachewarmer – start cache warmers.
startlogreceiver – start logreceiver for hot standby system.
startlogsender – start logsender for hot standby system.
startnetldi – start a NetLDI.
startstone – start a Stone.
statmonitor – start statmonitor to record statistics.
stoplogreceiver – stop logreceiver for hot standby system.
stoplogsender – stop logsender for hot standby system.
stopnetldi – shut down a NetLDI.
stopstone – shut down a Stone.
topaz – command line scripting tool for GemStone.
vsd – graphic tool to analyze GemStone statistics files.
waitstone – verify status of a Stone.

copydbf

copydbf sourceNRS destinationNRS [ -C | -z | -Z | -c | -u ] [ -E ] [ -f filePrefix ] [ -n netLdiName ] [ -s Mbytes ] [ -l | -m | -P ]

copydbf sourceNRS -i | -I [ -n netLdiName ]

copydbf sourceNRS-W encrCertFN | -X signCertFN | -Y sigFN

copydbf -V sourceNRS [-K keyRingDirs]

copydbf -h | -v

sourceNRS	The source file or raw partition (containing an extent, a transaction log, or a backup file created by fullBackupTo:) as a GemStone network resource string.
destinationNRS	The destination file, directory, or raw partition as a GemStone network resource string. If the destination is a file system directory (the trailing / is optional), a file name is generated and appended to destinationNRS based on the type and internal fileId of the source. Use of /dev/null as the destination is supported only for files as a means of verifying that the file is readable.
-c	Write the transaction log with individual record-level compression. This option only applies to transaction logs. Used by hotstandby utilities.
-C	Write the entire output file compressed, in gzip format; the same as the -z option. The output must be a filesystem file, and you must specify the .gz in the filename.
-E	Ignore disk read errors. If the disk read error occurs while reading an extent root page, the copy will fail. Otherwise, pages of the source file that cannot be read will be replaced with an invalid-page-kind page in the destination file. The destination file may not be usable. This option only applies to extents, not to transaction logs or backup files.
-f filePrefix	If destinationNRS is a file system directory, then filePrefix overrides the filename prefix that would be generated based on the contents of sourceNRS. If destinationNRS is other than a file system directory, this option has no effect.
-h	Print usage and exit.
-i	Information only. When this option is present without destinationNRS, information about sourceNRS is printed without performing a file copy. If both -i and destinationNRS are present, an error message is printed.
-I	Full information. The same information is printed as for -i. In addition, if the file is a transaction log, all checkpoint times found are listed instead of only the last one.
-K keyRingDirs	For secure backup. List of colon-separated directories which contain keys and certificates, which is used with the -V option to verify the digital signature.
-l	Least-significant-byte ordering for the destinationNRS. This byte ordering is the native byte ordering for Intel processors.
-m	Most-significant-byte ordering for the destinationNRS. This byte ordering is the native byte ordering for Solaris SPARC, AIX POWER, and HP-UX PA-RISC and Itanium processors.
-n netLdiName	The name of the GemStone network server; the default is gs64ldi.
-P	Preserve byte ordering. This option creates the destination file using the byte ordering found in the source file. The default is to write the file using the host’s native byte ordering.
-s MB	The size (in MB) to pre-allocate the destination file. For instance, -s10 allocates at least 10 MB to the created file. If you do not specify the -s option, the output file is made as short as possible.
-u	Uncompress output records (default is to preserve record-level compression from input); used by hotstandby utilities.
-v	Print version and exit.
-V	For secure backup. Verify the digital signature of a secure backup. Secure backup must be local. This requires including either the -K command line option, or setting the GEMSTONE_KEYRING_TABS environment variable.
-W encrCertFN	For secure backup. Create a new file or files with the given name containing the encryption certificate(s) from a secure backup to file(s). Secure backup must be local. Cannot be used with other write options on a single command line.
-X signCertFN	For secure backup. Create a new file with the given name containing the signing certificate from a secure backup to a file. Secure backup must be local. Cannot be used with other write options on a single command line.
-Y sigFN	For secure backup. Create a new file with the given name containing the digital signature from a secure backup to file. Secure backup must be local. Cannot be used with other write options on a single command line.
-z	Write the output file compressed, in gzip format; the same as the -C option. The output must be a filesystem file, and you must specify .gz in the filename.
-Z	Write the output file compressed, in LZ4 format. The output must be a filesystem file, and you must specify .lz4 in the filename.

To make copies of extent files or transaction logs, the user executing copydbf must have read permission to the file. If you attempt to copy extent files that are in use, if checkpoints are not suspended the resulting repository may be corrupt and unusable. See How To Make an Extent Snapshot Backup for more information.

GemStone repository files on the UNIX file system or to an NFS-mounted drive can usually be copied using the ordinary cp command, as well as using copydbf.

If you are copying between operating systems and the source and destination have different byte ordering, you should use copydbf. You can use the copydbf for disk-to-disk copies between machines when the remote disk is not NFS-mounted; to use copydbf between remote nodes in this case, you must have a NetLDI running on both nodes, and authentication must be configured to allow access.

If the destination is a directory in a file system, copydbf generates a filename based on the type of file. The generated name includes a prefix (extent, tranlog, or backup), a fileId representing an internal sequence number that starts at 0, and the extension .dbf. You can use the -f option to change the prefix.

A message describing the source and destination files is printed to stderr before starting the copy. The size of the destination file is printed to stderr after the copy is completed.

For example:

% copydbf $GEMSTONE/bin/extent0.dbf .

Source file: /users/GemStone/data/extent0.dbf

   File type: extent  fileId: 0

   ByteOrder: Intel (LSB first)  compatibilityLevel: 844

   Last checkpoint written at: 05/27/2019 19:03:46 PDT.

Destination file:  ./extent0.dbf

   ByteOrder: Intel (LSB first)

   Clean shutdown, no tranlog needed for recovery.

   Last tranlog written to had fileId 0 ( tranlog0.dbf ).

   File contains 6144 records occupying 117.4 MBytes.

Compression of copydbf output

The output of copydbf can be compressed at the file level using gzip or LZ4 compression (-C|-z|-Z), or compressed at the record level. (-c). Tranlog restore and copydbf can read any of the compression variants.

Record-level compression is used by the hotstandby implementation. The logsender does record-level compression before sending tranlog records to the log receiver. The transmitted tranlogs that are written on the slave system by the logreceiver are record-level compressed. File-level zip/LZ4 compressed tranlogs are converted into record-level compressed tranlog records by the logsender.

Using copydbf to access information on a file

To obtain the same source file information (but not the size) without making a copy, use the second form of the command: copydbf -i sourceNRS. In this usage, you do not specify a destinationNRS.

The following copydbf -i example displays information for an extent, and indicates the oldest transaction log that would be needed to recover from a system crash:

% copydbf -i extent0.dbf

Source file: extent0.dbf

   File type: extent  fileId: 0

   ByteOrder: Intel (LSB first)  compatibilityLevel: 844

   Last checkpoint written at: 05/14/2019 19:03:46 PDT.

   Oldest tranlog needed for recovery/restore is fileId 5 ( tranlog5.dbf ).

   Extent was shutdown cleanly; no recovery needed.

The next example displays information for a backup, and indicates the oldest transaction log that would be needed to restore subsequent transactions.

% copydbf -i backup.dat

File type: backup  fileId: 0 in a backup set with 1 files

   ByteOrder: Intel (LSB first)  compatibilityLevel: 860

   The file was created at: 05/27/2019 19:03:46 PDT.

   Full backup started from checkpoint at: 05/27/2019 19:03:46 PDT.

   Oldest tranlog needed for restore is fileId 2 ( tranlog2.dbf ).

   Backup was created by GemStone Version: 3.5.0, Tue Mar 19		17:04:19 2019 64bit-45803.

To obtain the size of a repository file in a raw partition, use this form:

% copydbf sourceNRS destinationNRS

For a listing of all checkpoints recorded in a transaction log, use copydbf -I sourceNRS. This information is helpful in restoring a GemStone backup to a particular point in time. For example:

% copydbf -I tranlog5.dbf

Source file: tranlog5.dbf

   File type: tranlog  fileId: 5

   ByteOrder: Intel (LSB first)  compatibilityLevel: 940

   The file was created at: 05/27/19 11:49:05 PST.

   The previous file last recordId is  36 .

   Scanning file to find last checkpoint...

   Checkpoint 1 started at: 05/27/19 11:54:35 PST.

     oldest transaction references fileId -1 ( this file ).

   Checkpoint 2 started at: 05/27/19 11:56:17 PST.

     oldest transaction references fileId -1 ( this file ).

   Checkpoint 3 started at: 05/27/19 11:58:30 PST.

     oldest transaction references fileId -1 ( this file ).

   Checkpoint 4 started at: 05/27/19 12:03:01 PST.

     oldest transaction references fileId -1 ( this file ).

   File contains 69 records occupying 35328 bytes.

copydbf with remote nodes

You must give an NRS (network resource string) for both the source file and the destination. A local machine file specification is a valid NRS.

In the following example, the local GemStone repository file “extent0.dbf” is copied to a remote machine using a full destinationNRS. In this example, the repository file is copied to a remote machine named “node,” using remote user account “username” and “password,” with a remote filespec of “/users/path/extent0.dbf_copy,” via the standard GemStone network server gs64ldi using TCP protocol:

% copydbf $GEMSTONE/data/extent0.dbf

\!@node#auth:username@password#dbf\!/users/extent0.dbf_copy

copydbf with raw partitions

copydbf of backup files to raw partitions is not supported.

The next example copies a fresh repository extent to an existing raw disk partition. If the raw partition already contains a repository file or backup, use removedbf first to mark it as being empty.

% copydbf $GEMSTONE/bin/extent0.dbf /dev/rsd3h

Copying a transaction log from a raw partition to a file system directory generates a file name having the same form as if that transaction log had originated in a file system. If the internal fileId is 43, this example would name the destination file /dsk1/tranlogs/tranlog43.dbf:

% copydbf /dev/rsd3h /dsk1/tranlogs/

gemnetobject

The gemnetobject script is not invoked on the command line. It, and related scripts such as gemnetdebug, are used to set the environment and invoke the Gem process during an RPC login.

Some of the arguments to gemnetobject are passed in by the NetLDI process, but other arguments can be included with the gemnetobject specification during login. This allows specification of the Gem environment for a specific login without requiring the definition of a configuration file.

gemnetobject -h

gemnetobject TCP socketFD [ -T tocSizeKB ] [ -N nativeCodeArg ] [ -e exeConfPath ] [ -C configParamsString ] [ -U ignoredArg ] otherApplicationArgs

socketFD	File descriptor of client socket inherited from fork. Provided automatically by NetLDI.
-e exeConfPath	Passes in a configuration file; the settings in the specified configuration file override environment settings.
-C configParamsString	The argument is a string containing configuration value settings. Multiple configuration parameter settings are accepted, and must be separated by ‘;’ (with no additional spaces).
-h	print help text.
-N nativeCodeArg	Arguments are 0, 1, or 2. A setting overrides other settings for GEM_NATIVE_CODE_ENABLED.
-T tocSizeKB	a setting overrides other settings for GEM_TEMPOBJ_CACHE_SIZE.
-U ignoredArg	Argument to be passed to and ignored by the Gem.
otherApplicationArgs	Other application-specific arguments may be included, which are passed to the Gem without interpretation.

The user-supplied arguments -e, -C, -N, and -T may be specified in any order. If any individual argument is included twice, only the last specification is used.

Any other arguments or tokens can be included at the end or within the string passed to gemnetobject.

All arguments, including ignoredArg and otherApplicationArgs, are passed to the Gem and available to the application via System class >> commandLineArguments.

The Gem configuration parameters to be used by the Gem are determined in the following precedence order.

values in -T or -N argument
values in -C argument
values in the executable config file.
values in the system config file.

The system configuration file is the first one found when searching:

path from $GEMSTONE_SYS_CONF environment variable
$GEMSTONE/data/system.conf

The executable configuration file is the first one found when searching:

path from -e argument
path from $GEMSTONE_EXE_CONF environment variable
a file named 'gem.conf' in current directory of the gem process (the current directory is set from a #dir directive, or from a NetLDI -D argument; Controlling log file directory locations)

The higher precedence setting is used and lower precedence settings are ignored. If there are multiple settings for a specific parameter at the same level, that is in the same executable or system configuration file, or within the -C argument, the last one that is found applies and earlier settings for that parameter within the file or string are ignored.

The following variants of gemnetobject are included in the distribution. Any of these can be used in place of gemnetobject.

gemnetdebug—sets debugging environment variables that are particularly useful for debugging memory issues

gemnetobject_noop—starts a non-optimized Gem executable

gemnetobject_slow—starts a slow Gem executable with assertion checks

gemnetobject_keeplog—starts an ordinary Gem executable, configured to not delete the gem log on clean shutdown.

Examples

gemnetobject is used in topaz, GemBuilder for Smalltalk, and GemBuilder for C applications in the login parameters for gemnetid. The following examples are in topaz.

Note that single quotes may be needed when the gemnetid arguments include spaces.

topaz> set gemnetid 'gemnetobject -T 500MB -e devStone.conf'

This example passes in a temporary object cache size and a configuration file named devStone.conf with other configuration parameter settings.

topaz> set gemnetid '!#netldi:54321!gemnetobject -C GEM_RPCGCI_TIMEOUT=5;GEM_ABORT_MAX_CRS=2; -N 1 devStone'

This example specifies NetLDI port (54321) to fork the Gem. It includes two configuration parameter settings and modifies the Native Code setting. The token devStone is ignored, but visible in ps output and can be used by code that fetches the command line arguments.

Error checking

Note that minimal argument error checking is done and unrecognized tokens or invalid argument values are ignored during login. Check the gem log to ensure that intended values are used.

For example, an extra space as in the following, results in the second configuration value silently being ignored:

'gemnetobject -C GEM_RPCGCI_TIMEOUT=5; GEM_ABORT_MAX_CRS=2;'

gslist

gslist [ -c ] [ -l | -p | -x ] [ -H ] [ -m host ]+ [ [ -n ] name ]+ [ -N netldiName ] [ -q ] [ -s key|-S key ] [ -t secs ] [ -u user ] [ -v ] [ -U certFile -R keyFile -J caCertFile ]+

gslist -h | -V

-c	Removes locks left by servers that have been killed.
-h	Print usage and exit.
-H	Include HostAgent processes in the output. By default, gslist does not report HostAgent processes. HostAgents are support processes for X509-Secured GemStone.
-J caCertFile	To list processes started with X509-Secured GemStone. Specify an X509 CA certificate file. -R and -U must also be specified.
-l	Prints a long listing (includes pid and port).
-m host	Only list servers on machine host; default is ‘.’ which represents the local host. If not the local host, the machine host must be running a compatible version of NetLDI, and the -N argument is required if it is not running with the default name in the environment of gslist.
-n name	Only list the server name.
-N netldiName	When -m is used, -N specifies name of netldi to contact on remote host. Default is name specified in GEMSTONE_NRS_ALL environment variable, otherwise name is 'gs64ldi'.
-p	Prints only the pid (process id), or 0 if the server does not exist.
-q	(Quiet.) Don’t print any extra information; intended for use when the output will be processed by some other program.
-R keyFile	To list processes started with X509-Secured GemStone. Specify an X509 private host key file. -J and -U must also be specified.
-s key	Sort results by the given sort key. Legal key values:
	name sort by process name (default). owner sort by process owner. time sort by process start time. type sort by process type. version sort by process version.
-S key	Same as -s except results are sorted in reverse order.
-t secs	Wait secs seconds for server to respond (only with -v); default is 2 seconds.
-u user	Only list servers started by user.
-U certFile	To list processes started with X509-Secured GemStone. Specify an X509 public host certificate file. -J and -U must also be specified.
-v	Verify the status of each server.
-V	Print the version information and exit.
-x	Prints an exhaustive listing, with each item on a separate line.

The gslist command prints information about GemStone servers. The default listing prints the following server attributes in columns:

Status	One of the following:
	contRestore Continous restore for hot standby (-v only) exists server process exists but is not verified frozen server is not responding (-v only) full server can’t accept any more clients (-v only) killed server process does not exist OK server is accepting clients (-v only) restoreBkup server is in restore from backup (-v only) restoreLogs server is in restore from logs mode (-v only) recovery Restart after unclean shutdown in progress (-v only) startup server process is not yet accepting clients (-v only)
Version	GemStone version of the server.
Owner	The account name of the user who created the server.
Started	The date and time that the server was started.
Type	One of the following: Netldi, Stone, cache (shared page cache monitor), logsender, logreceiver, or hostagent.
Name	The server’s name.

When you include the -l or -x option, the following additional columns are printed:

Pid	The process id of the server’s main process.
Port	The port number of the server’s listening socket.

The -x option prints the preceding attributes on separate lines, and adds lines for the following as appropriate:

options	Options used when the server was started.
logfile	Full path of server’s log file, if it exists.
sysconf	The GemStone system configuration file. See System Configuration File.
execonf	The GemStone executable configuration file. See Executable Configuration File.
GEMSTONE	Root of the product tree used by the server.

If many servers are reported as frozen to gslist -v, try increasing -t secs.

By default, status is returned for all servers on the current host. To specify a particular server, use the -n switch, or just include the server name on the command line (since the -n is optional). To specify multiple server names, include the -n name option for each server.

Remote queries

The -m option allows you to list servers on a remote host. To specify more than one remote host, include the -m host option multiple times, one for each host. Names on remote hosts are prefixed by host:, where host is the name of the remote machine.

To list servers on a remote host, gslist must be able to contact a NetLDI running on the remote machine.

The remote NetLDI must be a GemStone version that is compatible with the version of gslist.

This limitation applies to the remote NetLDI, but not to the Stone and other server processes on the remote host, for which gslist fetches information.

The remote NetLDI must be named with the default name, or the -N argument should be included to specify the name.

The default name here is the default for the environment in which gslist is running. This is either “gs64ldi”, or a name specified by $GEMSTONE_NRS_ALL.

Date and Time format

The date and time that the process started is normally printed in a format specific to gslist and fitting into the table display. To get a parse-able but potentially less readable format, you may use the environment variable GS_GSLIST_TIME_FORMAT to specify a UNIX-style date format string.

Exit status

The exit status has the following values:

0       Operation was successful.
1       No servers were found.
2       A stale lock was removed (in response to -c switch).
3, 4   An error occurred.

largememorypages

largememorypages -h

largememorypages [ -e exeConfig ] [ -z systemConfig ] [ -M sharedCacheKB ] [ -P maxProcesses ] [ -C maxSharedCounters ] [ -p largeMemoryPageSize ]

-C maxSharedCounters	Overrides the setting for SHR_PAGE_CACHE_NUM_SHARED_COUNTERS in a configuration file.
-e exeConfig	The GemStone executable configuration file. See Executable Configuration File.
-h	Print usage and exit.
-M sharedCacheKB	The shared cache size. The default unit is MB, but KB or GB can also be used. Overrides the setting for SHR_PAGE_CACHE_SIZE in a configuration file.
-p largeMemoryPageSize	Used on Linux only. The intended large memory page size, legal values must resolve to 2MB or 1024MB. The default is 2MB. The default unit is MB, but KB or GB can also be used. This overrides a setting for SHR_PAGE_CACHE_LARGE_MEMORY_PAGE_SIZE_MB in a configuration file.
-P maxProcesses	Overrides the setting for SHR_PAGE_CACHE_NUM_PROCS in a configuration file.
-z systemConfig	The GemStone system configuration file. See System Configuration File.

largememorypages computes the number of large or huge memory pages that will be required for a given shared page cache size and other system requirements.

Large or huge memory pages are available for use with GemStone on Linux and AIX.

On Linux, GemStone supports 2MB and 1024 MB pages.
On AIX, 16GB large memory pages are supported.

Large pages are not supported on other platforms.

Using the largememorypages utility is described in the Installation Guide for Linux and for AIX. For example:

unix> largememorypages  -M 20GB -C 1900 -P 200

Cache config is 1310720 pages = 20480 MB,  total is 21384 MB,

overhead 4% of configured size

Large page size requested is: 2 MB.

Large page overhead: 1.12 MB

For 1310720 pages, 200 processes and 1900 shared counters,

10 pusherThreads

  required cache size is 22422749184 bytes.

Number of 2 MB large pages required: 10692

pageaudit

pageaudit -h | -v

pageaudit [ gemStoneName ] [ -e exeConfig ] [ -z systemConfig ] [ -f ] [ -d ] [ -l logfile ]

gemStoneName	Name of the GemStone repository monitor; the default is gs64stone-audit. Network resource syntax is not permitted.
-d	Disable audit of data pages. Only audit Object Table pages, bitmaps, and other non-data pages.
-e exeConfig	The GemStone executable configuration file. See Executable Configuration File.
-f	Keeps running beyond the first error, if possible
-h	Print usage and exit.
-l logfilename	Write output to the file with the given name. The file is created if it does not exist. If there is an existing file with this name, the pageaudit output is appended to the end of this file.
-n numSessions	Run with the specified number of sessions. The default is numExtents + numCpus.
-v	Print version and exit.
-z systemConfig	The GemStone system configuration file. See System Configuration File.

Audit the pages in a GemStone repository, which must not be in use. pageaudit opens the repository specified by the relevant configuration files. The arguments -e exeConfig, and -z systemConfig determine which configuration files pageaudit reads.

pageaudit by default runs aggressively, using a large number of threads (based on the number of CPUs and extents for this system), in order to complete as quickly as possible; the -n option can be used to specify fewer threads, and reduce the impact on your system.

By default, all pages in the repository are verified; this includes data pages as well as Object Table, bitmap, and other pages containing internal information. Audit of data pages can be disabled using the -d option.

An error is returned if another Stone is running as gemStoneName or has opened the same repository.

When you include the -f switch, pageaudit prints all errors possible. Without -f, the default is to stop after the first error is found.

This utility can take a long time to run, so it is best to run it as a background job.

For additional information about pageaudit and a description of its output, see Page Audit.

printlogs

print [ -h ] [filters, see below] [ full ] [ nostrings ] [ nouserinfo ] all | tlog1...tlogN

user username	Only print records for the specified GS UserProfile name.
host hostname	Only print records for the specified gem/topaz process host.
client X.X.X.X	Only print records for the specified client IP Address.
euid integer	Only print records for Gems with the specified effective UNIX user ID.
ruid integer	Only print records for Gems with the specified real UNIX user ID.
luid integer	Only print records for Gems with the specified login UNIX user ID.
euidstr string	Only print records for Gems with the specified effective UNIX user name.
ruidstr string	Only print records for Gems with the specified real UNIX user name.
luidstr string	Only print records for Gems with the specified login UNIX user name.
gempid integer	Only print records for Gems with the specified process ID.
sessionid integer	Only print records for Gems with the specified session ID.
full	More detailed logs are produced. This may produce a VERY large amount of output.
all	Print out contents of all tranlogs in this directory. You must either list specific tranlogs on the command line or give the keyword 'all'.
nostrings	Suppress the printing of String data in the output. Useful for security when sharing tranlog output.
nouserinfo	Suppress the printout of user information.
tlog1...tlogN	The specific tranlog or tranlogs to print. These must be a contiguous sequence in order. Required unless the all keyword is used.
-h	Print usage and exit.

printlogs prints out the contents of transaction logs in human-readable form. This may produce a very large amount of output; without filters, the output will be at least as large as the original and may be multiple times larger depending on the options used.

Tranlogs are by default named tranlogNNN.dbf. This can be overridden by setting $GS_TRANLOG_PREFIX to the tranlog prefix.

A maximum of 256 transaction logs can be analyzed at once.

For details on using printlogs for tranlog analysis, see: http://downloads.gemtalksystems.com/docs/Other/SDoc-TranlogAnalysis-3.5/SDoc-TranlogAnalysis-3.5.htm.

Examples

To print out the entire contents of all tranlogs in the current working directory:

printlogs all

To print out all entries in a selected number of tranlogs:

printlogs tranlog5.dbf tranlog6.dbf tranlog7.dbf

To print out all tranlog entries for the user DataCurator in any tranlog:

printlogs user DataCurator all

To print out detailed information for all entries in tranlog5.dbf for the user DataCurator:

printlogs full user DataCurator tranlog5.dbf

pstack

pstack [ -b | -c | -C | -h ] processPid

processPid	The PID of a running GemStone process.
-b	Print brief C and Smalltalk stacks.
-C	Print brief C stack, omit Smalltalk stack.
-c	Print brief and full C stack, omit Smalltalk stack.
-h	Print usage and exit.

The pstack command attaches a debugger to the process with the given pid, outputs the C and Smalltalk stacks of that process to stdout, and detaches. The Smalltalk stack is printed to the Gem log or topaz linked session console.

Execution of the running process briefly pauses while the debugger is attaching, but the process will subsequently continue running normally.

pstack is similar to functions provided with some OS platforms.

By default, the stack summary is printed with one line per frame for each thread, followed by the complete stack details. The -b and -C options allow you to specify brief format stacks.

By default, both C stack and (if there is a Smalltalk context) Smalltalk stacks are printed. The -c and -C options allow you to omit the Smalltalk stack.

removedbf

removedbf dbfNRS [ -h ]

dbfNRS	The GemStone repository filename or device, as a network resource string, for the repository to be removed.
-h	Print usage and exit.

This command removes (erases) a GemStone repository file. It is provided primarily for erasing an extent or transaction log from a raw partition, but it also works on files in the file system. It does not work for disks on remote file systems.

If you specify a file in the file system, this command is equivalent to the rm command. If you specify a raw disk partition, GemStone metadata in the partition is overwritten so that GemStone will no longer think there is a repository file on the partition.

For example, to remove an extent on the raw partition /dev/rsd3h:

removedbf /dev/rsd3h

This command does not disconnect an extent from the logical repository. To alter the configuration by disconnecting an existing extent, see To Remove an Extent.

searchlogs

searchlogs [ -h ] [ordererdFilters, see below] oop1...oop2

user username	Only print records for the specified GS UserProfile name.
host hostname	Only print records for the specified gem/topaz process host.
client X.X.X.X	Only print records for the specified client IP Address.
euid integer	Only print records for Gems with the specified effective UNIX user ID.
ruid integer	Only print records for Gems with the specified real UNIX user ID.
luid integer	Only print records for Gems with the specified login UNIX user ID.
euidstr string	Only print records for Gems with the specified effective UNIX user name.
ruidstr string	Only print records for Gems with the specified real UNIX user name.
luidstr string	Only print records for Gems with the specified login UNIX user name.
gempid integer	Only print records for Gems with the specified process ID.
sessionid integer	Only print records for Gems with the specified session ID.
-h	Print usage and exit.

Searchlogs searches all tranlogs in the current directory for selected oops, filtering results by user, host, and other criteria. The filters must be provided in the order above. Filters are optional.

Tranlogs are by default named tranlogNNN.dbf. This can be overridden by setting $GS_TRANLOG_PREFIX to the tranlog prefix.

A maximum of 256 transaction logs can be analyzed at once.

For details on using searchlogs for tranlog analysis, see http://downloads.gemtalksystems.com/docs/Other/SDoc-TranlogAnalysis-3.5/SDoc-TranlogAnalysis-3.5.htm.

Examples

To print out all entries involving OOP 1234 and OOP 5678:

searchlogs 1234 5678

To print out all entries involving OOP 1234 performed by DataCurator:

searchlogs user DataCurator 1234

To print out all entries involving OOP 1234 and OOP 5678 performed by DataCurator while logged in from client machine 10.20.30.40:

searchlogs user DataCurator client 10.20.30.40 1234 5678

startcachewarmer

startcachewarmer [ -d | -D ] [ -h ] [ -l limit ] [ -L path ] [ -n numSessions ] [ -s stoneName ] [ -w writeInterval ] [ -W ] [ -C midCacheSizeKb ] [ -e gemConfigPath ] [ -H stoneHost ] [ -M midCacheHost ] [ -N midCacheMaxProcs ]

-C midCacheSizeKb	The size of the mid-level cache in KB (default 75000). Only used if the -M option is specified and the mid-level cache does not exist.
-d	Reads data pages into the cache (default: only object table pages are read).
-D	Reads data pages into the UNIX file buffer cache and not the shared page cache.
-e gemConfigPath	path to a gem config file, by default gem.conf in the current directory. Used to specify a shared cache configuration, if the warmer starts a remote or mid-level cache.
-h	Print usage and exit.
-H stoneHost	The host name or IP address where the stone is running. This option should only be used when warming a remote cache.
-l cacheFullLimit	Stops cache warming if the number of free frames in the cache falls below the specified cacheFullLimit. If cacheFullLimit is -1 (the default), have the system compute the actual limit based on the size of the shared cache. If cacheFullLimit is 0, force cache warming to continue even if the shared cache is full.
-L path	Path to a writable log file directory (default: current directory)
-M midCacheHost	The host name or IP address where the mid-level cache is running or will be created. The -H option must also be specified with this option (default: no mid-level cache is used)
-n numSessions	Number of worker sessions to start. The default is the number of CPUs + number of Extents, plus 1 additional master session. The cachewarmer will exit if not enough sessions are available.
-N midCacheMaxProcs	The maximum number of processes that can use the mid-level cache (default: 50). Only used if the -M option is also specified and mid-level cache does not exist.
-s stoneName	Name of the running Stone (default: gs64stone).
-W	Wait for cache warming Gems to exit before exiting this script. By default, this script spawns Gems in the background and exits immediately.
-w writeInterval	Instruct the shared page cache monitor to write the ids of all data pages in the shared cache to the working set file, at the given interval in minutes. A value of 0 means write the file only when the stone is shutdown or killed. The working set is written to /opt/gemstone/locks/stoneName~hostid.workingSet.lz4

The startcachewarmer command warms up the shared page cache on startup, by preloading object table pages and optionally data pages into the cache. This allows the overhead of initial page loading to occur in a controlled way on system startup, rather than more gradually as the repository is in use.

The object table and dependency map pages are always loaded; data pages are loaded based on the -d flag or the presence of the working set file.

If the working set file /opt/gemstone/locks/stoneName~hostid.workingSet.lz4 exists, the valid data pages in this file are loaded.
If the working set file does not exist, then behavior depends on the use of the -d and -D options:
If the -d option is specified, all data pages in page order are loaded.
With the -D option, data pages are loaded into the OS file buffer but not into the shared page cache.

The -d and -D flags are mutually exclusive, if both are specified, then the later one is used.

Cache warming writes messages to stone log when it starts and with status when it completes. When the -W option is specified, it will also write the results to the console. If an error occurs during cache warming, details are preserved in a file named stonename_cachewarmer.log in the directory from which this utility was executed.

If a remote shared page cache is to be warmed (i.e., the -H option is used), then the remote cache will be created if it does not already exist. The configuration used to start the remote cache are controlled by the -e argument, a gem.conf in the current directory, or the GEMSTONE_EXE_CONF environment variable.

If a mid-level cache host name or IP address is specified (via -M), the mid-level cache will be created if it does not already exist. The -C and -N options will be used to specify the size and number of processes that can attach the mid-cache respectively. If the mid-cache already exists, the -C and -N options are ignored.

For greater efficiency, you can set the configuration file parameters STN_CACHE_WARMER_ARGS, GEM_CACHE_WARMER_ARGS, and GEM_CACHE_WARMER_MID_CACHE_ARGS to invoke cache warming automatically on startup.

startlogreceiver

startlogreceiver -v | -h

startlogreceiver -P listeningPort -A listeningAddress -T tranlogDir+ [ -l logFile ] [ -s stoneName ] [ -p alternatePort ] [ -d ] [ -t timeoutSeconds ] [ -f flushIntervalSecs ] [ -C certFileName ] [ -J certAuthFileName ] [ -K keyFileName ] [ -Q passphrasestring ] [ -S ] [ -V ]

-A listeningAddress	Address that will be used to attempt connection to a logsender.
-d	Print debug tracing of tranlog read and write operations to log file. The log file will be much larger.
-f flushIntervalSecs	Interval in seconds at which the logreceiver flushes the tranlog file. 0 means flush as often as possible (this may be very slow). -1 disables flushing (file is flushed only when closed). The default is 10.
-l logFileOrDir	The path and filename or directory for the logged output of the logreceiver process. The default is /opt/gemstone/log/logreceiver_listeningPort.log.
-h	Print usage and exit.
-P listeningPort	Port or named service that will be used to attempt connection to a logsender.
-p alternatePort	The logreceiver listens on localhost on this port for stoplogreceiver commands. If logsender and logreceiver are run on same machine, then -p must be used to specify a port different than listeningPort specified with the -P argument.
-s stoneName	The name of the slave stone. stoneName is required for the logreceiver to be able to notify a stone in continuous restore mode that new log records have arrived. Without stoneName, logreceiver will just write tranlogs to the file system.
-T tranlogDir	Directory(s) where logreceiver writes files received from the logsender, and continuousRestoreFromArchiveLogs: will read from. At least one is required, up to 20 -T may be specified.
-t timeoutSeconds	How long the logreceiver will wait for logsender to reply to commands. The default is 60; the legal range is 5 to 1000000.
-v	Print version and exit.
Additional arguments for SSL:
-C certFileName	Certificate in PEM format that will be sent to the peer upon request.
-J certAuthFileName	Certificate authority (CA) file in PEM format to use for peer certificate verification.
-K keyFileName	Private key in PEM format for the certificate (associated with the -C certificate).
-Q passphrasestring	Private key passphrase. Required if the -K option is used and the private key is encrypted.
-S	Enable SSL mode. Must be specified to use any other SSL options and must also be specified when starting the peer process.
-V	Disable verification of the peer's certificate.

This utility starts up a logreceiver process. As part of a hot standby setup, the logreceiver process runs on the slave system to receive transaction log records, as they are generated, from a logsender process that is running on a master system.

The received transaction log records are written to files in a specified directory on the slave system. The slave system can run continuousRestoreFromArchiveLogs: to restore these transaction log records.

The logreceiver writes logging output to a file with the path and name or in the directory specified by the -l argument. If this file is a directory, the file name is logreceiver_listeningPort.log. If no -l argument is used, it writes to /opt/gemstone/log/logreceiver_listeningPort.log. If a file with the specified name exists, it is appended to. It is not deleted on process exit.

The logreceiver process will continue running until explicitly stopped using the stoplogreceiver command. If connection to the stone or the logsender process is lost, it will attempt to reconnect.

gslist will report running logreceiver processes.

To start the logsender using SSL to establish a secure connection between logsender and log receiver, both startlogsender and startlogreceiver can be provided with SSL credentials. When SSL arguments are provided, startlogreceiver will start the logreceiver in secure mode, requiring an SSL connection with the logsender. This is described under Connecting using SSL Mode

startlogsender

startlogsender -P listening port -A listeningAddress+ ( -T tranlogDir+ | -s stoneName ) [ -l logFile ] [ -u ] [ -d ] [ -v ] [ -h ] [ -C certFileName ] [ -J certAuthFileName ] [ -K keyFileName ] [ -Q passphrasestring ] [ -S ] [ -V ]

-A listeningAddress	The address (es) on which the logsender will listen for connections from logreceivers. At least one is required, up to 4 may be specified.
-d	Print debug tracing of tranlog read and write operations to log file. The log file will be much larger.
-l logFileOrDir	The path and filename or directory for the logged output of the logsender process. The default is /opt/gemstone/log/logsender_listeningPort.log.
-h	Print usage and exit.
-P listeningPort	The port or named service on which on which the logsender will listen for connections from logreceivers.
-s stoneName	The name of the master stone. logsender will transmit records from the transaction logs in the tranlog directories configured for the Stone named stoneName. Either -s or -T may be used, but the use of both together is disallowed. When -s is used, transaction logs that are added to the master stone are automatically used by the logsender.
-T tranlogDir	Directory(s) where the master stone’s transaction logs are located. Normally the same as stone's STN_TRAN_LOG_DIRECTORIES but may also include archive directories. logsender will examine these directories for new files to send. Disllowed if -s is used, if -s is not used then at least one is required and up to 20 -T may be specified.
-u	Do not compress tranlog files at record level before transmission.
-v	Print version and exit.
Additional arguments for SSL:
-C certFileName	Certificate in PEM format that will be sent to the peer upon request.
-J certAuthFileName	Certificate authority (CA) file in PEM format to use for peer certificate verification.
-K keyFileName	Private key in PEM format for the certificate (-C option).
-Q passphrasestring	Private key passphrase. Required if the -K option is used and the private key is encrypted.
-S	Enable SSL mode. Must be specified to use any other SSL options and must also be specified when starting the peer process.
-V	Disable verification of the peer's certificate.

This utility starts up a logsender process. As part of a hot standby setup, the logsender process runs on the master system to transmit transaction log records, as they are generated, to a logreceiver process that is running on a slave system.

The logsender writes logging output to a file with the path and name or in the directory specified by the -l argument. If this file is a directory, the file name is logsender_listeningPort.log. If no -l argument is used, it writes to /opt/gemstone/log/logsender_listeningPort.log. If a file with the specified name exists, it is appended to. It is not deleted on process exit.

The logsender process will continue running until explicitly stopped using the stoplogsender command. If connection to the stone is lost, it will attempt to reconnect.

gslist will report running logsender processes.

To start the logsender using SSL to establish a secure connection between logsender and log receiver, both startlogsender and startlogreceiver can be provided with SSL credentials. When SSL arguments are provided, startlogsender will start the logsender in secure mode, requiring an SSL connection with the logreceiver. This is described under Connecting using SSL Mode.

startnetldi

startnetldi [ netLdiName ] [ -g | [ -s ] [ -k keytab ] ] [ -a name ] [ -A addresses ]+ [ -b ] [ -d ] [ -D directoryPath ] [ -l logFile ] [ -n ] [ -P portNumber ] [ -r ]

startnetldi [ x509NetLdiName ] [ -b ] [ -d ] [ -E configFileName ] [ -l logFile ] [ -n ] [ -P portNumber ] [-r ] -D directoryPath -S -J certAuthFileName -R keyFileName -U certFileName -L crlFileName

startnetldi -h | -v

netLdiName	The name or port number of the GemStone network server. If netLdiName is a numeric value equal to or less than 65535, it is interpreted as a port number. If the given port is in use, it will result in an error. Other values are interpreted as the netldi name. If the -P argument is omitted, this name is looked up in the network services database to determine the port number. Network resource syntax is not permitted. The default is gs64ldi.
-a name	Captive account; all child processes created by the NetLDI will belong to the account named name. By default, child processes belong to the client’s account.
-A addresses	Address to listen on. Up to 10 arguments are accepted. If no -A arguments are provided, listening is on the default wildcard address ::. If this default wildcard address is included, then other -A arguments are ignored. If the -A entry arguments do not include :: or ::1, then ::1 is also listened on.
-b	Maximum client connection backlog (default: 64).
-d	Debug mode; inserts more extensive messages in the log file.
-D directoryPath	Specifies a directory that will be used to compose log file paths for process log files. It is the default log path if the NRS does not include a #dir directive. This directory must exist and be writable, and the $GEMSTONE_NRS_ALL in the startnetldi’s environment must not include a #dir directive. If the NRS includes the %D pattern in the #dir or #log, when spawning a child process, the %D in the NRS is replaced with directoryPath before forking. A path separator is appended if necessary.
-g	Guest mode; no accesses are authenticated. This option is not allowed if the NetLDI’s effective user id is the root account. Not compatible with -k.
-h	Print usage and exit.
-k	Enable Kerberos and set the keytab file name; logins with empty host password will authenticate using Kerberos. Not compatible with -g.
-l logFile	The logged output of the NetLDI; the default is /opt/gemstone/log/NetLdiName.log
-n	Do not allow any ad hoc processes to be created (ad hoc processes are ones not listed in $GEMSTONE/sys/services.dat).
-N	Use numeric IP addresses for printing peer info in logs, do not do reverse DNS lookups to get hostnames of clients.
-P portNumber	The well-known port number that NetLDI will listen on.
-r	If there is a running NetLDI (version 3.3 or above) with this name, and that NetLDI has different version than specified in the current environment, stop the running NetLDI and restart it.
-s	Secure; require authentication for all NetLDI accesses.
-v	Print version and exit
Additional arguments for use only when starting a X509-Secured NetLDI:
-E configFileName	For use when starting a X509-Secured NetLDI on a remote node (not the Stone’s node). Provides specifications for starting the remote cache. The actual cache startup is initiated by starthostagent on the Stone's node. See the GemStone/S 64 Bit X509-Secured GemStone System Administration Guide.
-J certAuthFileName	Specifies a certificate authority certificate (CA) in PEM format to use. Requires -S.
-L crlFileName	Specifies a certificate revocation list (CRL) file in PEM format.
-R keyFileName	Specifies host private key in PEM format to use. Requires -S.
-S	start a X509-Secured NetLDI. Certificates must also be provided using -U, -R, and -J, and -E is required for remote caches. The NetLDI will do mutual authentication for all connections.
-U certFileName	Specifies a host X509 certificate in PEM format to use. Requires -S.

This command starts a GemStone network server with the specified netLdiName and timeout (given in seconds). The server spawns GemStone processes in response to login requests from remote applications and requests for remote repository access from Stone repository monitor processes. If your machine is slow or heavily loaded, and RPC logins time out before completing, specify a larger timeout value.

Legal characters in a NetLDI name are A-Z, a-z, 0-9, and the characters period, underscore, and dash (. _ -). NetLDI names with other characters are disallowed. NetLDI names should not start with period or dash, and should include at least one letter or digit. Also, NetLDI names must not match an existing system service, such as ldap, syslog, etc.

The NetLDI listens for requests, including RPC login requests, on a specified or configured port and optionally on a specific address. During the RPC login process, it uses a separate set of ports to establish communication between the Gem and its client. If you are running over a firewall, you can specify the port using the -P option, and configure your firewall to permit access via this port.

The locations and names of log files for process started by the NetLDI are defined by NRS directives in the login parameters or by settings in the GEMSTONE_NRS_ALL. Using the -D logfile argument to startnetldi sets a default log file path. For more on managing log file paths, see Controlling log file directory locations.

NetLDI can be configured to authenticate starting processes, or all accesses. It may configure to authenticate the UNIX userId (including by using Kerberos) or to run in guest mode, which does not authenticate. These options work in conjunction with permissions for the extent files to provide security while also ensuring the appropriate access to GemStone for authorized users. How to configure the NetLDI is described in Chapter 4, “NetLDI and Interprocess Access”.

To use startnetldi within an X509-Secured GemStone configuration, see the GemStone/S 64 Bit X509-Secured GemStone System Administration Guide.

For assistance with startup failures, refer to To Troubleshoot NetLDI Startup Failures.

netldid

$GEMSTONE/sys/netldid is the executable that is invoked by startnetldi. While startnetldi blocks until startup is complete, then returns control to the command line, executing netldid directly does not return. This can allow you to run the NetLDI as a background process.

The options described for startnetldi are also available for netldid, with the exception of -r.

startstone

startstone [ gemStoneName ] [ -l logFile ] [ -e exeConfig ] [ -z systemConfig ] [ -h | -v ] [ -R ] [ -N ]

gemStoneName	Name of the GemStone repository monitor, default is gs64stone. Network resource syntax is not permitted.
-C	startup for conversion; only applies when starting up a version that requires conversion. Refer to the Installation Guide for the specific version for details.
-e exeConfig	The GemStone executable configuration file. See Executable Configuration File.
-h	Print usage and exit.
-l logFile	The location (or filename) for the logged output of the stone; the default is (1) the setting of the $GEMSTONE_LOG environment variable, if defined; (2) $GEMSTONE/data/gemStoneName.log
-N	Do not replay transaction logs as part of startup. Unless used with the -R option, and transaction logs are replayed manually, work may be lost.
-R	Start up from the most recent checkpoint and go into restore mode. This allows transaction logs to be restored. Used when restoring from backup.
-v	Print version and exit
-z systemConfig	The GemStone system configuration file. See System Configuration File.

This command opens the GemStone repository specified by the configuration files. For details on how startstone determines which the configuration file/s to use, see How GemStone Uses Configuration Files.)

Legal characters in a Stone name are A-Z, a-z, 0-9, and the characters period, underscore, and dash (. _ -). Stone names with other characters are disallowed. Stone names should not start with period or dash, and should include at least one letter or digit. Also, Stone names must not match an existing system service, such as ldap, syslog, etc.

The -N option is intended for use when the repository needs recovery, but the transaction logs specified in the configuration file cannot be found or have become corrupted. The -N forces the repository to start up anyway, even though transactions committed since the last checkpoint will be lost.A new transaction log will be initialized as part of the startup.

The -R option is used when restoring from backup. This starts up the repository at the point of the most recent checkpoint in the extents, and puts the repository into restore mode. You can then invoke Topaz to restore from transaction logs and commit the restored state.

If the extents against which Stone is being started require recovery, or if you are restoring from online extent backups, then you must specify the -N option along with the -R option; otherwise, an error will result and the repository monitor will not start.

For startup failures, refer to To Troubleshoot Stone Startup Failures.

stoned

$GEMSTONE/sys/stoned is the executable that is invoked by startstone. While startstone blocks until startup is complete, then returns control to the command line, executing stoned directly does not return. This can allow you to run the Stone as a background process.

The options described for startstone are also available for stoned.

statmonitor

statmonitor stoneName [ options, see below ]

stoneName	Required; the name of the Stone to monitor.
-A	Collect all available system statistics.
-B count	Number of persistent shared counters to sample. Maximum is 1536, default is 0.
-C	Collect system statistics for each individual CPU.
-d directory	Directory where output files are written. Cannot be used with the -f or -F options; to specify a directory with those options, include it in the filename or pattern.
-D	Collect system statistics for all disks and partitions.
-f fileName	The output file name. By default, the output filename is statmonN.out, where N is the process ID. If this file already exists, statmonitor will append an -N to the filename, where N starts at 1 and increments as needed. To send output to stdout instead of a file, specify -f stdout. May not be used with the -d option.
-F pattern	Pattern used to generate the file name. Values in the pattern starting with a single '%' character have the meaning described in the strftime(3) function call. Additionally, the following patterns which start with double '%' characters are also accepted: %%C - name of the shared page cache %%H - name of the host %%i - sample interval in seconds %%I - sample interval in milliseconds %%P - process ID of statmonitor %%S - name of the stone May not be used with the -d option. %%C and %%S cannot be used when statmonitor is started with the -X argument.
-h	With no argument, print usage and exit.
-h hours	The number of hours (default: forever).
-i interval	The interval in seconds (default: 20). Select either -i or -I.
-I intervalMs	The interval in milliseconds (default 20000; minimum 10). Select either -i or -I.
-J	Sample the Stone, shared cache monitor, and page manager only.
-k listOfTimes	List of times at which statmonitor should be restarted. The restart is performed at the next sample interval after the specified time has passed. Either the -r or -R command must also be specified. List must start and end with a single quote. times include hours and minutes, colon separated. hours are in 24-hour format. Multiple times are comma separated. Duplicates should not be included.
-K numOldFilesLimit	Tells statmonitor to automatically delete old output files as new ones are created. numOldFilesLimit specifies how many old files to keep (excluding the current file). Files are deleted in order of age, oldest files first. Requires either -r or -R.
-n numAppStats	The number of application statistics (default: 0).
-N	Collect system statistics for all network interfaces.
-p sessionId	A GemStone sessionId to monitor. You may specify multiple sessions. (Default: monitor all sessions.)
-P	Sample the Stone, shared cache monitor and AIO page server threads only.
-q	Quiet mode. Only print messages if an error occurs.
-Q pid1,pid2,...	Record statistics for a list of process IDs.
-r	Restart a new output file when the current one completes. Each file will be given a unique name. This option may only be used with the -h or -t switches, which control when a restart is done.
-R	Same as -r except the output file name is regenerated for each restart if the -F option is used.
-S	Sample only the Stone and shared cache monitor.
-t times	The maximum number of samples to collect before starting a new output file (default is forever). Select either -h or -t.
-u seconds	The maximum number of seconds to wait before flushing the cached information to the output file (default: 60). If 0 then the flush will be done every interval.
-Uuid1,uid2,...	Record statistics for all processes owned by one or more UNIX user IDs.
-v	Print version and exit
-W	Collect system statistics for system memory pages (Solaris only).
-X	Run in host-only mode. Sample host system statistics only and do not attach to a shared page cache. May be combined with other flags EXCEPT: -m, -n, -p, -P, -S, or -Y. There are some limitations in log file name patterns in this mode; see -F.
-Y	Disable collection of all system statistics, including per-process data.
-z	Write the output in compressed gzip format.
-Z	Write the output in compressed lz4 format.

statmonitor records statistics for a repository and/or the operating system to a disk file.

statmonitor runs in the background, sampling specified data at a specified interval and recording the data to a text file. The data in this file can be viewed by the graphical application VSD. See vsd and the VSD Users Guide for more information.

Statistics are collected from the shared page cache and directly from the OS. Only data for GemStone processes attached to the shared page cache on the host on which statmonitor is running are collected. To monitor Gems on systems with remote Gem servers, you must run statmonitor both on the Stone’s machine and on the Gem server machine.

The stonename argument is used to specify the cache to monitor, both for caches that are local to the Stone and caches that are remote from the Stone with that name. Configurations in which a single machine is hosting remote caches for multiple stones that are running with the same Stone name are ambiguous and will not work correctly; this configuration is strongly discouraged.

In addition to running statmonitor from the command line, you can also specify that statmonitor be automatically started at stone startup, and the startup for remote gem caches and remote mid-level caches, to ensure statmonitor data is collected. See the configuration parameters STN_STATMONITOR_ARGS, GEM_STATMONITOR_ARGS, and GEM_STATMONITOR_MID_CACHE_ARGS.

stoplogreceiver

stoplogreceiver -P listeningPort [ -v ] [ -h ]

-h	Print usage and exit.
-P listeningPort	The port that the logreceiver is listening on for stoplogreceiver connections. If -p was used in the startlogreceiver command, that port must be specified here; otherwise the port specified by the -P argument to startlogreceiver.
-v	Print version and exit.

This utility stops a logreceiver process that was started by a previous startlogreceiver command. This may only be executed on the same node as the logreceiver is running.

stoplogsender

stoplogsender -P listeningPort [ -v ] [ -h ]

-h	Print usage and exit.
-P listeningPort	The port on which this logsender is listening. It must be the same port as specified in the -P argument of the startlogsender.
-v	Print version and exit

This utility stops a logsender process that was started by a previous startlogsender command. This may only be executed on the same node as the logsender is running.

stopnetldi

stopnetldi [ netLdiName ] [ -h ] [ -v ]

netLdiName	The name of the GemStone network server; the default is gs64ldi. Network resource syntax is not permitted.
-h	Print usage and exit.
-v	Print version and exit

Gracefully stop a GemStone network server.

If name is not specified, the name of the NetLDI to stop is taken from GEMSTONE_NRS_ALL environment variable, if defined there. If GEMSTONE_NRS_ALL does not define a NetLDI name, then a NetLDI with the default name gs64ldi is stopped.

If a portNumber was used to start the netldi process, then the portNumber can be used to stop the netldi process.

stopstone

stopstone [ gemStoneName [ gemStoneUserName [ gemStonePassword ] ] ] [ -i ] [ -t ] [ -h ]

gemStoneName	The name of the GemStone repository monitor, commonly gs64stone. Network resource syntax is not permitted.
gemStoneUserName	A privileged GemStone user account name, such as “DataCurator” or “SystemUser”.
gemStonePassword	The GemStone password for the specified gemStoneUserName.
-h	Print usage and exit.
-i	Causes any current GemStone sessions to be terminated immediately.
-t	Specifies how long to wait for other processes to detach from the cache. Default is -1, wait forever.

Gracefully shut down a GemStone repository monitor. In the process, a checkpoint is performed in which all committed transactions are written to the extents. If you specify the -i (immediate) option, the repository monitor is shut down even if there are GemStone users logged in. The -t option specifies how long to wait for all session to detach from the cache before returning; if omitted, stopstone will wait forever. If you do not supply the gemStoneName, gemStoneUserName, and gemStonePassword on the command line, this command will prompt you for them.

Because this command uses a Gem session process to connect to gemStoneName, it fails if the Gem is unable to connect for any reason, such as inability to attach a shared page cache. For assistance, refer to To Troubleshoot Session Login Failures.

topaz

topaz [ -r ] [ -q ] [ -i | -I topazini ] [ -S scriptFile ] [ -n hostName:netldiName ] [ -u useName ] [ -X caCertPaths ] [ -- other args ]

topaz -l | -L [ -q ] [ -i | -I topazini ] [ -S scriptFile ] [ -u useName ] [ -e exeConfig ] [ -z systemConfig ] [ -T tocSizeKB ] [ -C configParams ] [ -- other args ]

topaz -h | -v

-C configParams	Provides configuration parameters, in configuration file syntax, that override settings in the configuration files. Only applies to linked sessions (RPC sessions may use the -C syntax in the Gem’s NRS).
-e exeConfig	The GemStone executable configuration file (only allowed with linked sessions). See Executable Configuration File.
-h	Print usage and exit.
-i	Ignore the initialization file, .topazini.
-I topazini	Specify a complete path and file to a topazini initialization files, and use this rather then any .topazini in the default location.
-l	Invoke the linked version of Topaz.
-L	Invoke the linked version of Topaz, and do not apply any command set gemnetid that may appear in the .topazini file or a file passed in using -I.
-n hostName:netldiName	For a login using X509-Secured GemStone, to specify the NetLDI to spawn the Gem, part of the X509-secured GemStone login parameters. The host name or IP, and the netldi name or listening port, for an X509-secured NetLDI.
-q	Start Topaz in quiet mode, suppressing printout of the banner and other information.
-r	Invoke the RPC (remote procedure call) version of Topaz.
-S scriptFile	Specifies a script file that will be processed with INPUT, suppressing output except if an error occurs.
-T tocSizeKB	The GEM_TEMPOBJ_CACHE_SIZE that will be used. Overrides any settings provided in configuration files passed as arguments with the -e or -z options. Only applies to linked sessions.
-u useName	Sets the cache name, as recorded by statmonitor for viewing in VSD. This is also useful for identifying processes in OS utilities such as top or ps.
-v	Print version and exit.
-w	On Windows client only; forces terminal behavior regardless of I/O device.
-X caCertPaths	For a login using X509-Secured GemStone, to set certificates. Requires additional infrastructure to be running, including X509-secured NetLDIs and caches. The argument specifies the CA cert, user cert, and user private key with 3 paths in this order: 'stoneCA-dev.cert.pem;DataCurator.chain.pem;DataCurator.privkey.pem'
-z systemConfig	The GemStone system configuration file (only allowed with linked sessions). See System Configuration File.
-- otherArgs	Arbitrary text arguments otherArgs may be included after the “--” end of arguments marker, which must follow any of the above topaz arguments are included.

This command invokes various forms of topaz. The default is to invoke the remote procedure call (RPC) version of topaz; to do this explicitly, use the -r option.

To invoke the linked version of topaz, which is recommended or required for some maintenance operations, use the -l or -L option. The advantage of the -L option is that .topazini initialization file command cannot inadvertently configure the login to be RPC rather than linked.

Several topaz arguments only apply in linked topaz. The arguments -eexeConfig and -zsystemConfig determine the configuration files that linked topaz reads. For more information about this, see How GemStone Uses Configuration Files.

Settings within topaz can allow linked topaz to perform RPC logins.

Topaz is available for Windows, in addition to regular server platforms, as part of the Windows Client installation. Options are more limited since linked logins are not possible.

For further information, see the Topaz Programming Environment.

vsd

vsd [ -b color ] [ -u ] [ [ -a ] statmonDataFile+ ] [ directory ]

vsd -h | -v

-a	Append mode. Files following the -a are appended to the first one; the data in these files is merged so statistics are viewed as if they were a single file.
-b color	Set the master background color. Color may be a hex RGB value (e.g.: #d3d3ff) or a valid color name (e.g.: white). The list of recognized color names may be found at: http://www.tcl.tk/man/tcl8.6/TkCmd/colors.htm
-h	Displays a usage line and exits.
-v	Print version information and exit.
statmonDataFile	The name of a statistics data file to load into the VSD as it is started.
directory	directory is the name of a directory; VSD will set this as the working directory for the executable, and after startup, opens the Open Statmonitor File dialog on this directory.

This command starts VSD, the graphical tool to view and analyze statmonitor data. The default is to open an empty instance of VSD, into which you can then load one or multiple statmonitor data files. After loading data files, you may select one or multiple GemStone processes, and view charts on one or multiple statistics for these processes.

VSD is available for Windows, in addition to regular server platforms, as part of the Windows Client installation.

For a complete description of VSD, see the VSD User’s Guide.

waitstone

waitstone [ -h ] [ gemStoneName | netLdiName ] [ timeout ] [ waitForWarming ]

-h	Display a usage line and exits
gemStoneName	The name of the GemStone repository monitor.
netLdiName	The name of the GemStone netldi service.
timeout	How many seconds to wait for GemStone to initialize before reporting a problem. The default (0) means wait forever; -1 means don’t wait, try once and return the result. Only valid when specifying either gemStoneName or netLdiName.
waitForWarming	If larger than 0, block until cache warmers finish.

This command reports whether the GemStone repository gemStoneName is ready to accept logins or whether netLdiName is ready to accept requests. If neither gemStoneName nor netLdiName are specified, waitstone will report on the default stone name, gs64stone.

Waitstone checks every 0.5 seconds to see if the Stone or NetLDI is ready. When the service is ready, waitstone issues a message to stdout. If the service is not ready by the time the specified number of seconds have elapsed, waitstone reports an error.

With a -1 timeout, waitstone will make one connection attempt to the Stone or NetLDI. Note that if the stone is inaccessible, the timeout may be longer, since the configured TCP/IP timeout may apply. This can result in a 20 second timeout regardless of the specified timeout value.

Use of timeout requires that the Stone or NetLDI name is also specified.

If a positive value for the waitForWarming argument is specified, waitstone will block until cache warming completes; this is useful when cache warming is automatically run on startup. The specific value of the waitForWarming is not important. Use of the waitForWarming positional argument requires specifying each of the preceding arguments.

You may specify the gemStoneName and netLdiName arguments as a GemStone network resource string. (See Appendix C, “Network Resource Strings (NRS)”)

This command returns 0 exit status if the operation is successful; otherwise, it returns a non-zero value.