Earthworm Modules:
Wave_ServerV Configuration File

Below are the commands recognized by wave_serverV, grouped by the function they influence. Some of the commands are required, as noted. They may be specified in any order in the control file.

2. ALPHABETIC COMMAND LISTING & DESCRIPTION

In the following section, all configuration file commands are listed in alphabetical order. Listed along with the command (bold-type) are its arguments (in red), the name of the subroutine that processes the command, and the function within the module that the command influences. A detailed description of the command and is also given. Default values and example commands are listed after each command description.

command arg1                                       function

AbortOnSingleTankFailure M

Set to 0 to have wave_server continue even if there is a fatal error on a tank during normal processing. If this flag is not set to 0, wave_server will die if any type of IO error occurs on any tank. If set to 1 wave_server will not exit unless there is a server wide error. If not set, then the server will abort on any failure of a tank.

Default:  1
Example:  AbortOnSingleTankFailure 0

ClientTimeout M

Debug n                             Earthworm Setup

Sets the wave_serverV debug level to n. Level zero gives no debugging output; level one turns on debugging. Due to the large number of transactions that a wave server typically handles, very large amounts of debugging output may be produced.

Default:  0 (no debugging)
Example:  Debug 1

GapThresh G

Sets the gap threshold to G sample intervals. Trace data packets are timestamped with a start time and a stop time, the times of the first and last samples in that packet, respectively. Thus, the expected gap between end time of one packet and the start time of the next packet is one sample interval. Some data sources, such as older digitizers, produce data with slightly larger or smaller intervals between them. The gap threshold is intended to provide a means of detecting missing packets, without falsely declaring a missing packet because of sloppy timestamps. The preferred value for this gap threshold is 1.5. Set larger values only if you have a sloppy data source. It is not clear how wave_serverV should handle intervals of much more than one sample interval between packets if these are not caused by missing packets.

Default:  none
Example:  GapThresh 1.5

HeartBeatInt nsec                             Earthworm Setup

Defines the number of seconds, nsec between TYPE_HEARTBEAT messages issued by wave_serverV.

Default:  none
Example:  HeartBeatInt 30

IndexUpdate U

InputQueueLen M

Sets the size of the input queue to M messages. Trace_buf messages are buffered in a queue when they are pulled off of an earthworm message ring. They are removed from the queue when the main thread is ready to process them. Depending on the CPU and disk speed of the machine you are using, this number should be about twice the number of tanks you are trying to serve. Slower machines may need larger queues.

Default:  none
Example:  InputQueueLen 200

LogFile switch                                     Earthworm Setup

MaxMsgSize S

MaxServerThreads T

Sets the maximum number of server threads to T. One server thread is created for each client connected to the wave_serverV. The more server threads you allow, the more load will be placed on wave_serverV and the computer.

Default:  10
Example:  MaxServerThreads 12

MyModuleId mod_id                                  Earthworm setup

Sets the module id for labeling all outgoing heartbeat and error messages. mod_id is a character string (valid strings are listed in earthworm.d; maximum length is 29 characters) that relates to a unique single-byte number. In general, a different module ID is needed for each instance of wave_serverV.

Default:  none
Example:  MyModuleId MOD_WSV_1

PacketSyncDbFile name

PleaseContinue X

Sets the PleaseContinue flag to X. If this flag is zero and wave_serverV has errors opening and reading its tank or index files, wave_serverV will exit. If it is set to any non-zero value, wave_serverV will continue after handling those tank file errors.

Default:  0 (does not continue after tank file errors)
Example:  PleaseContinue 1

PurgePacketSyncDb U

QueueReportInterval R

Defines the number of seconds, R between queue reports. The queue report lists the high and low queue levels for the previous interval. These reports show up in the log file and on standard error output.

Default:  30
Example:  QueueReportInterval 300

ReCreateBadTanks X

RedundantIndexFiles X

Sets the RedundantIndexFiles flag to X. If this flag is set, then two index files will be created for each tank file. If not set, then only one index file is created for each tank file. The index file names are based on the tank file names with "-1.inx", and if two files, "-2.inx" appended. Only a single index file is actually open for all the tanks at any given instant. We recommend that you set this flag to 1.

Default:  0 (single index files for each tank)
Example:  RedundantIndexFiles 1

RedundantTankStructFiles X

RingName ring                                      Earthworm setup

Tells wave_serverV which shared memory region to use for input and output. ring is a character string (valid strings are listed in earthworm.d; maximum length is 19 characters) that relates to a unique number for the key to the shared memory region.

Default:  none
Example:  RingName WAVE_RING

SecondsBetweenQueueErrorReports Q                             Earthworm Setup

Defines the number of seconds, Q between error reports about the internal message queue. Normally when the message queue gets full, an error message would be generated for each new trace_buf2 message that was supposed to go in the queue. This could be many messages per second. To limit the number of error messages to a more reasonable frequency this parameter should be set to the desired interval. The error messages indicate the number of trace_buf2 messages that failed to enter the full queue during the last reporting interval. If you get queue full error messages very often, it means that wave_serverV, and probably your computer, is not keeping up with its assigned load.

Default:  60
Example:  SecondsBetweenQueueErrorReports 30

ServerIpAdr addr

Specifies the IP address, addr to which wave_serverV will listen for client connections. This must be the IP address of (one of) your computer's network interface(s), and it must be an numeric IP address, not a host or domain name.

Default:  none
Example:  ServerIpAdr 192.168.7.13

ServerPort nnn

SocketDebug D

Sets the socket debug level, D for earthworm's socket library functions. Level 0 turns debugging off, level one is full socket debug logging.

Default:  0 (no socket debug output)
Example:  SocketDebug 1

SocketTimeout m

Sets the socket timeout interval to m milliseconds. This is for calls sending responses back to the client. Values should be a few seconds, certainly less than one minute. If the timeout is exceeded, the client is disconnected and the socket is closed.

Default:  none
Example:  SocketTimeout 10000   # timeout of ten seconds

Tank station channel net loc recsize inst_id mod_id tanksize indexsize tankfile-name                             Required

TankStructFile name                             Required

TankStructFile2 name

TankStructUpdate U                             Required

Defines the number of seconds, U between tank structure file updates. The TANK structure is maintained in memory, and periodically written to disk. The TANK structure tracks the status of the all the tank files. Any data written to the tanks since the last time the TANK structure was written to disk is effectively lost if wave_serverV crashes. The larger the interval, the more tank data is potentially lost in a crash; the smaller the update interval the more disk I/O that is required for wave_server to operate. We recommend a structure file update interval of one second.

Default:  none
Example:  TankStructUpdate 1

UsePacketSyncDb U

3. Sample Configuration File

#
#         Wave ServerV Configuration File
#
#	Note:  All directories defined in this configuration file must already
#		exit or WaveServerV will die.
#
MyModuleId    MOD_WAVESERVERV # wave_server's module id
RingName      WAVE_RING        # name of transport ring to get data from
LogFile       1                # 1=write log file to disk; 0=don't
                               # 2=write to module log but not stderr/stdout
HeartBeatInt  15               # seconds between heartbeats to statmgr
ServerIPAdr   192.168.1.5      # address of machine running wave_server: geops.geophys
ServerPort    16022            # port for receiving requests & sending waves
GapThresh     1.5              # threshhold for gap declaration
                               # (in sampling periods)

#

SocketTimeout 11000  # Timeout length in MILLISECONDS for socket calls
                     # This is for calls sending responses back to the
                     # client. Values should be a few seconds, certainly
                     # less than one minute.


ClientTimeout  60000 # Optional.  Not recommended feature but it does work.
                     # Timeout in MILLISECONDS for response from client.
                     # Threads that have not heard anything from their client
                     # in this period will exit.
                     # Comment out or set to -1 if you don't want to
                     # kill threads of silent clients.


# Each tank file has an associated in-memory index.  On re-start, the
# index image on disk must be updated to match the tank.  The more out
# of date the on-disk index is, the longer it takes to rebuild.  Rebuild
# times can be from milliseconds to minutes per tank, depending how large
# the tank is and how old the index is.
# Set IndexUpdate to the length in time in seconds between
# updates to disk.  The larger the update interval, the longer
# a crash recovery will take.  The smaller the update interval
# the more disk I/O that is required for wave_server to operate,
# and thus the slower it will operate, once it has reached I/O
# saturation.

IndexUpdate   10


# Similar to an Index, each tank has TANK structure that depicts the tank.
# The tank structure is maintained in memory, and periodically written to
# disk.  The TANK structure tracks the status of the tank.  Any data written
# to the tank since the last time the TANK structure was written to disk
# is effectively lost.  TankStructUpdate is the interval in seconds that the
# Tank Structure file on disk is updated.  The higher the interval, the more
# the tank data is that is potentially lost in a crash, the lower the interval
# the more the disk I/O that is required for wave_server to operate.

TankStructUpdate 1

# The file where TANK structures are stored

TankStructFile  j:\data\usgs\datafiles\p1000-1.str

# I open many files, one tracedata file for each SCNL channel to serve
# At 500 bytes/second, 1 channel requires 41.2 megabytes per day.
# NOTE: Record size must be multiple of 4 bytes or wave_serverV will crash
# with data misalignment.
# Also, record size must not be greater than MAX_TRACEBUF_SIZ, currently 4096,
# (defined in tracebuf.h)
#
#           SCNL    Record       Logo                  File Size   Index Size       File Name	    New
#          names   size  (TYPE_TRACEBUF2 only)         (megabytes) (max breaks)     (full path)      Tank

Tank    GUID EAG NC -- 528   INST_MENLO    MOD_WILDCARD       1         10000        j:\data\usgs\datafiles\p1001.tnk
Tank    IRG1 EAT NC --  528   INST_MENLO    MOD_WILDCARD       1         10000         j:\data\usgs\datafiles\p1002.tnk
Tank    IRG2 EAT NC --  528   INST_MENLO    MOD_WILDCARD       1         10000         j:\data\usgs\datafiles\p1003.tnk


# Advanced Options
# YES = 1, NO = 0, NO = (default)

#RedundantTankStructFiles  Set to 1 to use redundant tank struct files. (Recommended)
RedundantTankStructFiles 1

#RedundantIndexFiles  Set to 1 to use redundant tank index files. (Recommended)
RedundantIndexFiles      1


# Must be set if RedundantTankStructFiles = 1
#TankStructFile2  /tmp/p1000-2.str
TankStructFile2  j:\data\usgs\datafiles\p1000-2.str


#InputQueueLen:  The number of messages to buffer.  Messages are buffered
#in a queue.  They are added to the queue when they are pulled off of an
#earthworm message ring, they are removed from the queue when the main
#thread is ready to process them.  Depending on the CPU and disk speed
#of the machine you are using, this number should be about twice the
#number of tanks you are trying to serve.  Slower machines may need
#larger queues.
InputQueueLen 30


###################################
#           Other Optional Commands


#MaxMsgSize: Optional command to tell wave_server about TRACEBUF2 messages
# that could be larger than any going to tanks for this server. This
# may happen if you have two wave_servers and TRACEBUF2 sources that
# produce different size messages, e.g., ref2ew messages are 1064 bytes.
MaxMsgSize 1064

#Debug  Generates VERYVERYVERY large log files.
#Debug 1

#SocketDebug Set to 1 to get SOCKET_ew debug statements
SocketDebug 0

#PleaseContinue  Set to 1 to have wave_server continue, even if
#  there are errors during initialization
# PleaseContinue 1

#ReCreateBadTanks Set to 1 to have bad tanks re-created from scratch.
#ReCreateBadTanks 1

#SecondsBetweenQueueErrorReports   Minimum period of time between error
#  reports to statmgr due to the internal message queue being lapped,
#  and thus messages being lost.  Default is 60 seconds
#SecondsBetweenQueueErrorReports 30

#MaxServerThreads  Maximum of server threads to deploy to handle client
#  requests.  Default is 10.
#MaxServerThreads 10

#QueueReportInterval  The minimum number of seconds between
#  reports on internal queue high and low water marks.  The default is 30.
#QueueReportInterval 5

#AbortOnSingleTankFailure  Set to 0 to have wave_server continue even
#if there is a fatal error on a tank during normal processing.
#if this flag is not set to 0, wave_server will die if any type of
#IO error occurs on any tank.  If set to 1, wave_server will not exit
#unless there is a server wide error.
#AbortOnSingleTankFailure 1

#UsePacketSyncDb Uncomment entry and set to 1 to use embedded db functionality
# to manage asychronous trace buffer packets. Currently this is either on or off
# for all SNCLs.
#UsePacketSyncDb 1

#PacketSyncDbFile - Specifies name of database file to use. If not specified
# and UsePacketSyncDb == 1 then the default PCKTSYNC.SL3DB is used.
#PacketSyncDbFile "TB2PACKETS.SL3DB"

#PurgePacketSyncD Uncomment and specify one of the following to control
# how long out of sync data is kept in the database if UsePacketSyncDb=1.
# 1 : Purge data on startup
# 0 : Do not purge data on startup. Obsolete data is intermittently purged
# during the operation of wave_serverV is UsePacketSyncDb is 1.
#PurgePacketSyncDb 1