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.
- gslist – list running GemStone server processes.
- pageaudit – offline audit of repository pages.
- pstack – get C-level and Smalltalk stack traces.
- removedbf – delete an extent, transaction log or backup.
- 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 logreceiver for hot standby system.
- 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. See also the separate manual Topaz Users’s Guide.
- vsd – graphic tool to analyze GemStone statistics files. See also the separate manual VSD Users’s Guide.
- waitstone – verify status of a Stone.
copydbf
copydbf sourceNRS destinationNRS [ -C ] [ -c | -u ] [ -E ] [ -f filePrefix ] [ -n netLdiName ] [ -p pgsvrId ] [ -s Mbytes ] [ -l | -m | -P ]
copydbf sourceNRS -i | -I [ -n netLdiName ] [ -p pgsvrId ]
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.
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.
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.
copydbf of backup files to raw partitions is not supported.
% 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: 02/27/2015 19:03:46 PST.
Destination file: ./extent0.dbf
ByteOrder: Intel (LSB first)
Clean shutdown, no tranlog needed for recovery.
Last tranlog written to had fileId 5 ( tranlog5.dbf ).
File contains 4608 records occupying 75.5 MBytes.
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: 03/04/2015 19:03:46 PST.
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
ByteOrder: Intel (LSB first) compatibilityLevel: 844
The file was created at: 02/27/2015 19:03:46 PST.
Full backup started from checkpoint at: 02/27/2015 19:03:46 PST.
Oldest tranlog needed for restore is fileId 2 ( tranlog2.dbf ).
Backup was created by GemStone Version: 3.2.0 .
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: 911
The file was created at: 02/27/15 11:49:05 PST.
The previous file last recordId is 36 .
Scanning file to find last checkpoint...
Checkpoint 1 started at: 02/27/15 11:54:35 PST.
oldest transaction references fileId -1 ( this file ).
Checkpoint 2 started at: 02/27/15 11:56:17 PST.
oldest transaction references fileId -1 ( this file ).
Checkpoint 3 started at: 02/27/15 11:58:30 PST.
oldest transaction references fileId -1 ( this file ).
Checkpoint 4 started at: 02/27/15 12:03:01 PST.
oldest transaction references fileId -1 ( this file ).
File contains 69 records occupying 35328 bytes.
To pre-allocate disk space in the destination file, use the -s option. For instance, -s50 would allocate at least 50 MB to the created file. The output file is made as short as possible by default.
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
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/
gslist
gslist [ -c ] [ -l | -p | -x ] [ -m host ]+ [ [ -n ] name ]+ [ -N netldiName ] [ -q ] [ -s key|-S key ] [ -t secs ] [ -u user ] [ -v ]
The gslist command prints information about GemStone servers. The default listing prints the following server attributes in columns:
When you include the -l or -x option, the following additional columns are printed:
The -x option prints the preceding attributes on separate lines, and adds lines for the following as appropriate:
|
The GemStone system configuration file . See System Configuration File. |
|
|
The GemStone executable configuration file. See Executable Configuration File. |
|
If many servers are reported as frozen, 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.
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 parseable but potentially less readable format, you may use the environment variable GS_GSLIST_TIME_FORMAT to specify a UNIX-style date format string.
pageaudit
pageaudit [ gemStoneName ] [ -e exeConfig ] [ -z systemConfig ] [ -f ] [ -d ] [ -l logfile ] [-h]
|
Name of the GemStone repository monitor; the default is gs64stone-audit. Network resource syntax is not permitted. |
|
|
Disable audit of data pages. Only audit Object Table pages, bitmaps, and other non-data pages. |
|
|
The GemStone executable configuration file. See Executable Configuration File. |
|
|
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. |
|
|
Run with the specified number of sessions. The default is numExtents + numCpus. |
|
|
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.
pstack
pstack [ -b | -c | -C | -h ] processPid
The pstack command attaches a debigger 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
|
The GemStone repository filename or device, as a network resource string, for the repository to be removed. |
|
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.
startcachewarmer
startcachewarmer [ -d | -D ] [ -h ] [ -l limit ] [ -L path ] [ -n numSessions ] [ -s stoneName ]
[ -W ] [ -C midCacheSizeKb ] [ -H stoneHost ] [ -H midCacheHost ] [ -M midCacheMaxProcs ]
The startcachewarmer command warms up the shared page cache on startup, by preloading object and data tables 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.
Cache warming runs in one or two phases:
- In the first phase, the object table is loaded into the shared page cache. During this phase, if any data pages will be loaded later, the data pages that are referenced by the object table lookups are recorded for use in phase 2.
- In the second phase, data pages remembered from the first phase are loaded either into the shared page cache or the file buffer. This phase runs only if data pages will be loaded into the shared page cache or the file buffer.
Cache warming writes a message to stone log when it starts, and a second message with reporting success or failure. 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 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 options in the configuration file specified by the GEMSTONE_EXE_CONF environment variable will be used to specify the attributes of the new remote cache.
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 and STN_CACHE_WARMER_SESSIONS to perform cache warming on startup. See Appendix A for more details on these parameters.
startlogreceiver
startlogreceiver -P listeningPort -A listeningAddress -T tranlogDir+ [ -l logFile ] [ -s stoneName ] [ -p alternatePort ] [ -d ] [ -t timeoutSeconds ] [ -v ] [ -h ] [ -C certFileName ] [ -J certAuthFileName ] [ -K keyFileName ] [ -Q passphrasestring ] [ -S ] [ -V ]
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 SSL mode.
startlogsender
startlogsender -P listening port -A listeningAddress+ -T tranlogDir+ [ -l logFile ] [ -s stoneName ] [ -u ] [ -d ] [ -v ] [ -h ] [ -C certFileName ] [ -J certAuthFileName ] [ -K keyFileName ] [ -Q passphrasestring ] [ -S ] [ -V ]
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 SSL mode.
startnetldi
startnetldi [ netLdiName ] [ -l logFile ] [ -t timeout ] [ -a name ] [ -P portNumber ] [ -A addresses ]+ [ -n ] [ -g | -s ] [ -b ] [ -d ] [ -D directoryPath ] [ -r ]
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 options, and configure your firewall to permit access via this port.
The locations and names of process log files are defined by NRS directives in the login parameters or by settings in the GEMSTONE_NRS_ALL; this is described under GemStone Process Logs. Using the -D logfile argument to startnetldi sets a variable within the NetLDI, which can be optionally specified in the login parameters or GEMSTONE_NRS_ALL using the %D pattern.
To start the NetLDI for password authentication, make sure that $GEMSTONE/sys/netldid is owned by root and has the S bit set. Issue this command (on some operating systems, you may have to issue it as root):
% startnetldi
Alternatively, to start the NetLDI in guest mode (authentication is not required), make sure $GEMSTONE/sys/netldid does NOT have the S bit set. Log in as the captive account name, then issue this command:
% startnetldi -g -aname
For information about authentication modes, see NetLDI configuration and Network Security. For assistance with startup failures, refer to To Troubleshoot NetLDI Startup Failures.
startstone
startstone [ gemStoneName ] [ -l logFile ] [ -e exeConfig ] [ -z systemConfig ] [ -h | -v ] [ -R ] [ -N ]
|
Name of the GemStone repository monitor, default is gs64stone. Network resource syntax is not permitted. |
|
|
startup for conversion; only applies when starting up a version that requires conversion. Refer to the Installation Guide for the specific version for details. |
|
|
The GemStone executable configuration file. See Executable Configuration File. |
|
|
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 |
|
|
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. |
|
|
Start up from the most recent checkpoint and go into restore mode. This allows transaction logs to be restored. Used when restoring from backup. |
|
|
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.
statmonitor
statmonitor stoneName [ options, see below ]
Record 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. 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.
stoplogreceiver
stoplogreceiver -P listeningPort [ -v ] [ -h ]
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 ]
|
The port on which this logsender is listening. It must be the same port as specified in the -P argument of the startlogsender. |
|
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 ]
|
The name of the GemStone network server; the default is gs64ldi. Network resource syntax is not permitted. |
|
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 ]
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 ] [ -h | -v ] [ -q ] [ -i | -I topazini ] [ -u useName ]
topaz -l [ -h | -v ] [ -q ] [ -i | -I topazini ] [ -u useName ] [ -e exeConfig ] [ -z systemConfig ] [ -T tocSizeKB ] [ -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). |
|
|
The GemStone executable configuration file (only allowed with linked sessions). See Executable Configuration File. |
|
|
Specify a complete path and file to a topazini initialization files, and use this rather then any .topazini in the default location. |
|
|
Start Topaz in quiet mode, suppressing printout of the banner and other information. |
|
|
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. |
|
|
The value is not used by the topaz executable, but may be useful in identifying processes in OS utilities such as top or ps. |
|
|
On Windows client only; forces terminal behavior regardless of I/O device. |
|
|
The GemStone system configuration file (only allowed with linked sessions). See System Configuration File. |
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 option. Several topaz arguments only apply in linked topaz. The arguments -eexeConfig and -zsystemConfig determine the configuration files that topaz -l 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 [ -h ] [ statmonDataFile ]
|
Specify the name of a data file to load into the VSD that is started. |
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 ]
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 minutes have elapsed, waitstone reports an error.
With a -1 timeout, waitstone will make one connection to the Stone or NetLDI; depending on the internal state of the Stone, it may take up to 20 seconds to timeout and return.
You may specify the gemStoneName and netLdiName arguments as a GemStone network resource string. (See Appendix C, “Network Resource String Syntax”)
This command returns 0 exit status if the operation is successful; otherwise, it returns a non-zero value.