source: trunk/ewdoc/WEB_DOC/cmd/wave_serverV_cmd.html @ 3167

Revision 3167, 37.5 KB checked in by paulf, 11 years ago (diff)

mods for sqlite feature

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1<HTML>
2<HEAD>
3<TITLE>Earthworm Modules: Wave_ServerV commands</TITLE>
4</HEAD>
5
6<BODY TEXT="#000000" BGCOLOR="#FADFAF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
7
8<CENTER><H1>Earthworm Modules: <BR>Wave_ServerV Configuration File </H1>
9<I>(last revised 27 June, 2000)</I></CENTER>
10
11Page Index:<BR>
121.  <A HREF="#function">Functional command listing</A><BR>
132.  <A HREF="#alphabet">Alphabetic command listing & description</A><BR>
143.  <A HREF="#sample_config">Sample Configuration File</A><BR>
15<P>
16<!-- ADD HERE: Paragraph "On startup, xxxx reads the..." -->
17On startup, wave_serverV reads the configuration file named on the command
18line. Commands in this file set all the parameters used for configuring
19the Earthworm wave_serverV module. In the control file, lines may begin with a
20valid wave_serverV command (listed below) or with one of 2 special characters:
21
22<BLOCKQUOTE><PRE>
23#  marks the line as a comment (example: # This is a comment).<BR>   
24@  allows control files to be nested; one control file can be
25   accessed from another with the command "@" followed by
26   a string representing the path name of the next control file
27   (example: @model.d).
28</BLOCKQUOTE></PRE>
29Command names must be typed in the control file exactly as shown in this
30document (upper/lower case matters!). Blank lines are also permitted in the
31control file.
32<P>
33<A NAME="function">
34<H2>1.  FUNCTIONAL COMMAND LISTING</H2>
35<P> 
36<!-- ADD HERE: Paragraph "Below are the commands recognized..." -->
37Below are the commands recognized by wave_serverV, grouped by the function
38they influence.  Some of the commands are required, as noted. They may be
39specified in any order in the control file.
40
41<!-- ADD HERE: The pre-formatted functional command listing      -->
42<!-- To make an anchor for each command, surround it with these: -->
43<PRE>   Earthworm system setup:
44                <A HREF="#MyModuleId">MyModuleId</A>                required
45                <A HREF="#RingName">RingName</A>                required
46                <A HREF="#LogFile">LogFile</A>                 required
47                <A HREF="#HeartBeatInt">HeartBeatInt</A>            required
48
49        Wave Server Required Commands:
50                <A HREF="#ServerIpAdr">ServerIpAdr</A>
51                <A HREF="#ServerPort">ServerPort</A>
52                <A HREF="#Tank">Tank</A>
53                <A HREF="#GapThresh">GapThresh</A>
54                <A HREF="#IndexUpdate">IndexUpdate</A>
55                <A HREF="#TankStructUpdate">TankStructUpdate</A>
56                <A HREF="#InputQueueLen">InputQueueLen</A>
57                <A HREF="#TankStructFile">TankStructFile</A>
58                <A HREF="#SocketTimeout">SocketTimeout</A>
59
60        Wave Server Optional Commands:
61                <A HREF="#AbortOnSingleTankFailure">AbortOnSingleTankFailure</A>
62                <A HREF="#ClientTimeout">ClientTimeout</A>       
63                <A HREF="#RedundantTankStructFiles">RedundantTankStructFiles</A>
64                <A HREF="#RedundantIndexFiles">RedundantIndexFiles</A>
65                <A HREF="#TankStructFile2">TankStructFile2</A>
66                <A HREF="#MaxMsgSize">MaxMsgSize</A>
67                <A HREF="#PleaseContinue">PleaseContinue</A>
68                <A HREF="#ReCreateBadTanks">ReCreateBadTanks</A>
69                <A HREF="#SecondsBetweenQueueErrorReports">SecondsBetweenQueueErrorReports</A>
70                <A HREF="#MaxServerThreads">MaxServerThreads</A>
71                <A HREF="#QueueReportInterval">QueueReportInterval</A>
72                <A HREF="#Debug">Debug</A>
73                <A HREF="#SocketDebug">SocketDebug</A>
74                <A HREF="#UsePacketSyncDb">UsePacketSyncDb</A>
75                <A HREF="#PacketSyncDbFile">PacketSyncDbFile</A>
76                <A HREF="#PurgePacketSyncDb">PurgePacketSyncDb</A>
77</PRE>
78
79<A NAME="alphabet">
80<H2>2.  ALPHABETIC COMMAND LISTING & DESCRIPTION</H2>
81<P>
82In the following section, all configuration file commands are listed
83in alphabetical order.  Listed along with the command (bold-type) are
84its arguments (in red), the name of the subroutine that processes the
85command, and the function within the module that the command influences.
86A detailed description of the command and is also given.  Default values
87and example commands are listed after each command description.
88<PRE><B>
89command <font color=red>arg1</font>                                       function
90</PRE></B>
91<HR>
92
93<!-- ADD HERE: all commands; below is a sample command blank: -->
94
95<A NAME="AbortOnSingleTankFailure">  <!-- command name as anchor inside quotes -->   
96<PRE><B>AbortOnSingleTankFailure <font color=red>M</font>
97</B><!-- command args ... -->           
98</PRE>
99<BLOCKQUOTE> <!-- command description goes here -->
100Set to 0 to have wave_server continue even
101if there is a fatal error on a tank during normal processing.
102If this flag is not set to 0, wave_server will die if any type of
103IO error occurs on any tank.  If set to 1 wave_server will not exit
104unless there is a server wide error.
105<PRE><!-- Default and example go here   -->
106Default:  none
107Example:  AbortOnSingleTankFailure 0
108</PRE>
109</BLOCKQUOTE>
110<HR>
111
112<A NAME="ClientTimeout">  <!-- command name as anchor inside quotes -->   
113<PRE><B>ClientTimeout <font color=red>M</font>
114</B><!-- command args ... -->           
115</PRE>
116<BLOCKQUOTE> <!-- command description goes here -->
117Sets the timeout of <font color=red>M</font> milliseconds for response from
118a client. If there are no idle server threads (set by
119<A HREF="#MaxServerThreads">MaxServerThreads</A>), the server manager will
120disconnect clients and kill server threads that have not heard anything from
121their client in this period. Comment out or set to -1 if you don't want to
122kill threads of silent clients.
123<PRE><!-- Default and example go here   -->
124Default:  -1 (client timeout disabled)
125Example:  ClientTimeout 60000
126</PRE>
127</BLOCKQUOTE>
128<HR>
129
130<A NAME="Debug">  <!-- command name as anchor inside quotes -->   
131<PRE><B>Debug <font color=red>n</font>                             Earthworm Setup
132</B><!-- command args ... -->           
133</PRE>
134<BLOCKQUOTE> <!-- command description goes here -->
135Sets the wave_serverV debug level to <font color=red>n</font>. Level zero gives
136no debugging output; level one turns on debugging. Due to the large number of
137transactions that a wave server typically handles, very large amounts of
138debugging output may be produced.
139<PRE><!-- Default and example go here   -->
140Default:  0 (no debugging)
141Example:  Debug 1
142</PRE>
143</BLOCKQUOTE>
144<HR>
145
146<A NAME="GapThresh">  <!-- command name as anchor inside quotes -->   
147<PRE><B>GapThresh <font color=red>G</font> 
148</B><!-- command args ... -->           
149</PRE>
150<BLOCKQUOTE> <!-- command description goes here -->
151Sets the gap threshold to <font color=red>G</font> sample intervals. Trace data
152packets are timestamped with a start time and a stop time, the times of the
153first and last samples in that packet, respectively. Thus, the expected gap
154between end time of one packet and the start time of the next packet is one
155sample interval. Some data sources, such as older digitizers, produce data
156with slightly larger or smaller intervals between them. The gap threshold is
157intended to provide a means of detecting missing packets, without falsely
158declaring a missing packet because of sloppy timestamps. The preferred value
159for this gap threshold is 1.5. Set larger values only if you have a sloppy
160data source. It is not clear how wave_serverV should handle intervals of much
161more than one sample interval between packets if these are not caused by
162missing packets.
163<PRE><!-- Default and example go here   -->
164Default:  none
165Example:  GapThresh 1.5
166</PRE>
167</BLOCKQUOTE>
168<HR>
169
170<A NAME="HeartBeatInt">  <!-- command name as anchor inside quotes -->   
171<PRE><B>HeartBeatInt <font color=red>nsec</font>                             Earthworm Setup
172</B><!-- command args ... -->           
173</PRE>
174<BLOCKQUOTE> <!-- command description goes here -->
175Defines the number of seconds, <font color=red>nsec</font> between
176TYPE_HEARTBEAT messages issued by wave_serverV.
177<PRE><!-- Default and example go here   -->
178Default:  none
179Example:  HeartBeatInt 30
180</PRE>
181</BLOCKQUOTE>
182<HR>
183
184<A NAME="IndexUpdate">  <!-- command name as anchor inside quotes -->   
185<PRE><B>IndexUpdate <font color=red>U</font>
186</B><!-- command args ... -->           
187</PRE>
188<BLOCKQUOTE> <!-- command description goes here -->
189Defines the interval in seconds <font color=red>U</font> between which
190the index files are written to disk. Decreasing this number will keep the
191index file closer to the conditions in the tank file, but will increase disk
192activity. Each index file update involves opening the file, writing the new
193index, and closing the file. If
194<A HREF="#RedundantIndexFiles">RedundantIndexFiles</A> are being used, then the
195update is alternated between the two index files for each tank.
196<PRE><!-- Default and example go here   -->
197Default:  none
198Example:  IndexUpdate 10
199</PRE>
200</BLOCKQUOTE>
201<HR>
202
203<A NAME="InputQueueLen">  <!-- command name as anchor inside quotes -->   
204<PRE><B>InputQueueLen <font color=red>M</font>
205</B><!-- command args ... -->           
206</PRE>
207<BLOCKQUOTE> <!-- command description goes here -->
208Sets the size of the input queue to <font color=red>M</font> messages.
209Trace_buf messages are buffered in a queue when they are pulled off of an
210earthworm message ring. They are removed from the queue when the main
211thread is ready to process them.  Depending on the CPU and disk speed
212of the machine you are using, this number should be about twice the
213number of tanks you are trying to serve.  Slower machines may need
214larger queues.
215<PRE><!-- Default and example go here   -->
216Default:  none
217Example:  InputQueueLen 200
218</PRE>
219</BLOCKQUOTE>
220<HR>
221
222<A NAME="LogFile">  <!-- command name as anchor inside quotes -->     
223<PRE><B>LogFile <font color=red>switch</font>                                     Earthworm Setup
224</B><!-- command args ... -->           
225</PRE>
226<BLOCKQUOTE> <!-- command description goes here -->
227Sets the on-off switch for writing a log file to disk. If
228<font color=red>switch</font> is 0, no log file will be written. If
229<font color=red>switch</font> is non-zero, wave_serverV will write daily log file(s)
230called nnnnnxx.log_yyyymmdd where nnnnn is the name of the configuration file
231(with the suffix `.d' removed), xx is wave_serverV's module id (set with
232<A HREF="#MyModuleId">MyModuleId</A> command) and yyyymmdd is the current UTC
233date (ex: 19960123) on the system clock. The file(s)
234will be written in the EW_LOG directory (environment variable).
235<PRE><!-- Default and example go here   -->
236Default:  none
237Example:  LogFile   1
238</PRE>
239</BLOCKQUOTE>
240<HR>
241
242<A NAME="MaxMsgSize">  <!-- command name as anchor inside quotes -->   
243<PRE><B>MaxMsgSize <font color=red>S</font>
244</B><!-- command args ... -->           
245</PRE>
246<BLOCKQUOTE> <!-- command description goes here -->
247Optional command to set the maximum trace_buf2 message size to
248 <font color=red>S</font> bytes. Normally, wave_serverV calculates the maximum
249expected message size from the record size values given in
250<A HREF="#Tank">Tank</A> commands. But if larger trace_buf2 messages are found
251on wave_serverV's transport ring, such as SCNL's destined for a different
252wave_serverV, their size must be set here. This is because wave_serverV must
253allocate a buffer for examining each trace_buf2 message it finds on the
254transport ring, and this command is the only way it knows how large to make
255that buffer. If trace_buf2 messages are found with a larger size than given
256here or in the Tank commands, wave_serverV will send an error message to
257statmgr. If in doubt, you can set this command to 4096, the largest trace_buf2
258message allowed in earthworm.
259<PRE><!-- Default and example go here   -->
260Default:  same as largest record size in Tank commands
261Example:  MaxMsgSize 1064
262</PRE>
263</BLOCKQUOTE>
264<HR>
265
266<A NAME="MaxServerThreads">  <!-- command name as anchor inside quotes -->   
267<PRE><B>MaxServerThreads <font color=red>T</font>
268</B><!-- command args ... -->           
269</PRE>
270<BLOCKQUOTE> <!-- command description goes here -->
271Sets the maximum number of server threads to <font color=red>T</font>.
272One server thread is created for each client connected to the wave_serverV. The
273more server threads you allow, the more load will be placed on
274wave_serverV and the computer.
275<PRE><!-- Default and example go here   -->
276Default:  10
277Example:  MaxServerThreads 12
278</PRE>
279</BLOCKQUOTE>
280<HR>
281
282<A NAME="MyModuleId">  <!-- command name as anchor inside quotes -->   
283<PRE><B>MyModuleId <font color=red>mod_id</font>                                  Earthworm setup
284</B><!-- command args ... -->           
285</PRE>
286<BLOCKQUOTE> <!-- command description goes here -->
287Sets the module id for labeling all outgoing heartbeat and error
288messages. <font color=red>mod_id</font> is a character string (valid strings
289are listed in earthworm.d; maximum length is 29 characters) that relates to a
290unique single-byte number. In
291general, a different module ID is needed for each instance of wave_serverV.
292<PRE><!-- Default and example go here   -->
293Default:  none
294Example:  MyModuleId MOD_WSV_1
295</PRE>
296</BLOCKQUOTE>
297<HR>
298
299<A NAME="PacketSyncDbFile">  <!-- command name as anchor inside quotes -->   
300<PRE><B>PacketSyncDbFile <font color=red>name</font> 
301</B><!-- command args ... -->           
302</PRE>
303<BLOCKQUOTE> <!-- command description goes here -->
304Defines the filename of the database to use for asynchronous packet buffering.
305The argument <font color=red>name</font> may contain path information in addition
306to the name of the file. This setting is only valid if
307<A HREF="#UsePacketSyncDb">UsePacketSyncDb</A> is set to 1.
308<PRE><!-- Default and example go here   -->
309Default:  TB2PACKETS.SL3DB
310Example:  PacketSyndDbFile "FOO.DB"
311</PRE>
312</BLOCKQUOTE>
313<HR>
314
315<A NAME="PleaseContinue">  <!-- command name as anchor inside quotes -->   
316<PRE><B>PleaseContinue <font color=red>X</font>
317</B><!-- command args ... -->           
318</PRE>
319<BLOCKQUOTE> <!-- command description goes here -->
320Sets the PleaseContinue flag to <font color=red>X</font>. If this flag is zero
321and wave_serverV has errors opening and reading its tank or index files,
322wave_serverV will exit. If it is set to any non-zero value, wave_serverV will
323continue after handling those tank file errors.
324<PRE><!-- Default and example go here   -->
325Default:  0 (does not continue after tank file errors)
326Example:  PleaseContinue 1
327</PRE>
328</BLOCKQUOTE>
329<HR>
330
331<A NAME="PurgePacketSyncDb">  <!-- command name as anchor inside quotes -->   
332<PRE><B>PurgePacketSyncDb <font color=red>U</font>
333</B><!-- command args ... -->           
334</PRE>
335<BLOCKQUOTE> <!-- command description goes here -->
336Defines whether wave_serverV should purge all asynchronous trace buffer
337packet data on startup. If the argument <font color=red>U</font> = 1 then the
338packet data is deleted on startup. If it is 0 then packet data is not purged on
339startup. Note that packet data is purged periodically during the operation of
340wave_serverV if <A HREF="#UsePacketSyncDb">UsePacketSyncDb</A> is set to 1.
341<PRE><!-- Default and example go here   -->
342Default:  0
343Example:  PurgePacketSyncDb 1
344</PRE>
345</BLOCKQUOTE>
346<HR>
347
348<A NAME="QueueReportInterval">  <!-- command name as anchor inside quotes -->   
349<PRE><B>QueueReportInterval <font color=red>R</font> 
350</B><!-- command args ... -->           
351</PRE>
352<BLOCKQUOTE> <!-- command description goes here -->
353Defines the number of seconds, <font color=red>R</font> between
354queue reports. The queue report lists the high and low queue levels for the
355previous interval. These reports show up in the log file and on standard
356error output.
357<PRE><!-- Default and example go here   -->
358Default:  30
359Example:  QueueReportInterval 300
360</PRE>
361</BLOCKQUOTE>
362<HR>
363
364<A NAME="ReCreateBadTanks">  <!-- command name as anchor inside quotes -->   
365<PRE><B>ReCreateBadTanks <font color=red>X</font>
366</B><!-- command args ... -->           
367</PRE>
368<BLOCKQUOTE> <!-- command description goes here -->
369Sets the ReCreateBadTanks flag to <font color=red>X</font>. If this flag is
370set, then any tanks that were listed in the tank structure file and had
371errors will be recreated using the parameters in the structure file.
372Any tanks that were listed only in the config file and had errors will not
373be constructed. See <A HREF="../ovr/wave_serverV_ovr.html#wsv_su">Wave Server Startup</A> in the overview file for more details. It is very unlikely
374that setting this flag will help you. Usually it will "recreate bad tanks".
375<PRE><!-- Default and example go here   -->
376Default:  0 (bad tanks are not recreated)
377Example:  ReCreateBadTanks 1
378</PRE>
379</BLOCKQUOTE>
380<HR>
381
382<A NAME="RedundantIndexFiles">  <!-- command name as anchor inside quotes -->   
383<PRE><B>RedundantIndexFiles <font color=red>X</font>
384</B><!-- command args ... -->           
385</PRE>
386<BLOCKQUOTE> <!-- command description goes here -->
387Sets the RedundantIndexFiles flag to <font color=red>X</font>. If this flag is
388set, then two index files will be created for each tank file. If not set,
389then only one index file is created for each tank file. The index file names
390are based on the tank file names with "-1.inx", and if two files, "-2.inx"
391appended. Only a single index file is actually open for all the tanks at any
392given instant. We recommend that you set this flag to 1.
393<PRE><!-- Default and example go here   -->
394Default:  0 (single index files for each tank)
395Example:  RedundantIndexFiles 1
396</PRE>
397</BLOCKQUOTE>
398<HR>
399
400<A NAME="RedundantTankStructFiles">  <!-- command name as anchor inside quotes -->   
401<PRE><B>RedundantTankStructFiles <font color=red>X</font>
402</B><!-- command args ... -->           
403</PRE>
404<BLOCKQUOTE> <!-- command description goes here -->
405Sets the RedundantTankStructFiles flag to <font color=red>X</font>. If this
406flag is set then two tank structure files will be used. If this flag is zero,
407then only one tank structure file will be used. The first tank structure name
408is given with the <A HREF="#TankStructFile">TankStructFile</A> command.
409If two tank structure files are to be used, then you must also specify the
410second structure file name with the
411<A HREF="#TankStructFile2">TankStructFile2</A> command. Because of the
412importance of the tank structure file for restarting wave_serverV, it is
413strongly recommended that you use two tank structure files, by setting the
414RedundantTankStructFiles flag.
415<PRE><!-- Default and example go here   -->
416Default:  0 (single tank structure file)
417Example:  RedundantTankStructFiles 1
418</PRE>
419</BLOCKQUOTE>
420<HR>
421
422<A NAME="RingName">  <!-- command name as anchor inside quotes -->       
423<PRE><B>RingName <font color=red>ring</font>                                      Earthworm setup
424</B><!-- command args ... -->           
425</PRE>
426<BLOCKQUOTE> <!-- command description goes here -->
427Tells wave_serverV which shared memory region to use for input and output.
428<font color=red>ring</font> is a character string (valid strings are listed
429in earthworm.d; maximum length is 19 characters) that relates to a
430unique number for the key to the shared memory region.
431<PRE><!-- Default and example go here   -->
432Default:  none
433Example:  RingName WAVE_RING
434</PRE>
435</BLOCKQUOTE>
436<HR>
437
438<A NAME="SecondsBetweenQueueErrorReports">  <!-- command name as anchor inside quotes -->   
439<PRE><B>SecondsBetweenQueueErrorReports <font color=red>Q</font>                             Earthworm Setup
440</B><!-- command args ... -->           
441</PRE>
442<BLOCKQUOTE> <!-- command description goes here -->
443Defines the number of seconds, <font color=red>Q</font> between
444error reports about the internal message queue. Normally when the message
445queue gets full, an error message would be generated for each new trace_buf2
446message that was supposed to go in the queue. This could be many messages per
447second. To limit the number of error messages to a more reasonable frequency
448this parameter should be set to the desired interval. The error messages
449indicate the number of trace_buf2 messages that failed to enter the full queue
450during the last reporting interval. If you get queue full
451error messages very often, it means that wave_serverV, and probably your
452computer, is not keeping up with its assigned load.
453<PRE><!-- Default and example go here   -->
454Default:  60
455Example:  SecondsBetweenQueueErrorReports 30
456</PRE>
457</BLOCKQUOTE>
458<HR>
459
460<A NAME="ServerIpAdr">  <!-- command name as anchor inside quotes -->   
461<PRE><B>ServerIpAdr <font color=red>addr</font>
462</B><!-- command args ... -->           
463</PRE>
464<BLOCKQUOTE> <!-- command description goes here -->
465Specifies the IP address, <font color=red>addr</font> to which wave_serverV
466will listen for client connections. This must be the IP address of (one of)
467your computer's network interface(s), and it must be an numeric IP address,
468not a host or domain name.
469<PRE><!-- Default and example go here   -->
470Default:  none
471Example:  ServerIpAdr 192.168.7.13
472</PRE>
473</BLOCKQUOTE>
474<HR>
475
476<A NAME="ServerPort">  <!-- command name as anchor inside quotes -->   
477<PRE><B>ServerPort <font color=red>nnn</font>
478</B><!-- command args ... -->           
479</PRE>
480<BLOCKQUOTE> <!-- command description goes here -->
481Specifies the TCP port, <font color=red>nnn</font> on which wave_serverV will
482listen for client connections. It must be a port number not used by any other
483service on the assigned <A HREF="#ServerIpAdr">IP address.</A>
484<PRE><!-- Default and example go here   -->
485Default:  none
486Example:  ServerPort 16021
487</PRE>
488</BLOCKQUOTE>
489<HR>
490
491<A NAME="SocketDebug">  <!-- command name as anchor inside quotes -->   
492<PRE><B>SocketDebug <font color=red>D</font>
493</B><!-- command args ... -->           
494</PRE>
495<BLOCKQUOTE> <!-- command description goes here -->
496Sets the socket debug level, <font color=red>D</font> for earthworm's
497socket library functions. Level 0 turns debugging off, level one is full
498socket debug logging.
499<PRE><!-- Default and example go here   -->
500Default:  0 (no socket debug output)
501Example:  SocketDebug 1
502</PRE>
503</BLOCKQUOTE>
504<HR>
505
506<A NAME="SocketTimeout">  <!-- command name as anchor inside quotes -->   
507<PRE><B>SocketTimeout <font color=red>m</font>
508</B><!-- command args ... -->           
509</PRE>
510<BLOCKQUOTE> <!-- command description goes here -->
511Sets the socket timeout interval to <font color=red>m</font> milliseconds.
512This is for calls sending responses back to the client. Values should be a
513few seconds, certainly less than one minute. If the timeout is exceeded, the
514client is disconnected and the socket is closed.
515<PRE><!-- Default and example go here   -->
516Default:  none
517Example:  SocketTimeout 10000   # timeout of ten seconds
518</PRE>
519</BLOCKQUOTE>
520<HR>
521
522<A NAME="Tank">  <!-- command name as anchor inside quotes -->   
523<PRE><B>Tank <font color=red>station channel net loc recsize inst_id mod_id tanksize indexsize tankfile-name</font>                             Required
524</B><!-- command args ... -->           
525</PRE>
526<BLOCKQUOTE> <!-- command description goes here -->
527Specifies the parameters for one wave_serverV tank. This command is the heart
528of wave_serverV configuration. Use one <B>Tank</B> for each tank to be
529managed by this wave server, up to a maximum of 512 tanks. Computer systems
530limit this to a smaller value: on Unix (Solaris), the limit is about 220,
531based on the stdio limit of 256 open files. On WindowsNT, the limit is about
532200.
533 <P>
534The wave trace data is selected for a Tank by the <font color=red>station</font>,
535<font color=red>channel</font>, <font color=red>net</font>, and
536<font color=red>loc</font> values (the
537SCNL); these names must match exactly the names found in the trace data.
538 <P>
539The amount of space alloted for each wave trace (trace_buf2) packet in the
540tank file is given by <font color=red>recsize</font>. This value, in bytes,
541must be at least as large as the largest trace_buf2 packet expected for this
542SCNL, and must be a multiple of 4. Trace_buf packets consist of a 64-byte
543header, plus the trace data samples in binary format (either 2 or 4 bytes
544per sample.) A handy tool for seeing the size of trace_buf2 packets is the
545earthworm utility sniffwave. If trace_buf2 messages for this SCNL are found to
546be larger than <font color=red>recsize</font>, they will be skipped and and
547error message will be sent to statmgr.
548 <P>
549To further specify which trace_buf2 packets are read by wave_serverV, you can
550set the <font color=red>inst_id</font> and <font color=red>mod_id</font> to
551specific values (found in earthworm_global.d in the params directory.)
552Trace_buf that have been produced at the earthworm installation with
553<font color=red>net_id</font> and the module with <font color=red>mod_id</font>
554will be selected; all others will not. Often it is more convenient to allow
555trace data from any installation; in that case, <font color=red>inst_id</font>
556would be set to <B>INST_WILDCARD.</B> Likewise for the moduleId, using
557<B>MOD_WILDCARD.</B>
558 <P>
559The <font color=red>tanksize</font> parameter sets the size of the tank in
560millions of bytes (ten to the sixth power, not 2 to the 20th power!). To
561figure out how large to make your tank files, multiply these quantities
562together: <font color=red>recsize</font>, number of trace packets per second
563for this SCNL, and required duration of the tank in seconds. Be sure to allow
564sufficient disk space for this and all the other tank files!
565 <P>
566The size of the index file (or files if
567<A HREF="#RedundantIndexFiles">RedundantIndexFiles</A></A> is set to 1) is
568specified as <font color=red>indexsize</font> entries. Each index entry is
569about 20 bytes, not large. Each index entry records the start time, tank
570file location (offset) and endtime of a "chunk" of trace data. A new "chunk"
571of trace data is started whenever there is a gap larger than
572<A HREF="#GapThresh">GapThresh</A> sample intervals between the end time of
573one trace_buf2 packet and the start of the next one in the tank. So if you
574have lots of gaps in trace data for one SCNL (due to telemetry problems, for
575example) be sure to make the index files large enough. If wave_serverV runs
576out of index entry for an tank, it will send an error message to statmgr. Then
577it will overwrite the oldest index entry with new information. The result will
578be that the trace_data referenced by that just erased index entry will no
579longer be accessible from the tank file.
580 <P>
581If you find that you need to increase the size of your index files, you can
582do so by changing <font color=red>indexsize</font> and restarting wave_serverV.
583Do not remove the old index files; they will be extended with new, blank
584entries for later use.
585 <P>
586If you have valuable old data in a tank file that has become inaccessible
587because of index file problems, it is possible to reconstruct the index file,
588using either wave_serverV or the utility <B>inspect_tank</B>. If you need
589assistance with this, ask for help from the earthworm mailing list or
590Earthworm Central. Naturally, your need will likely come in the heat of battle,
591so don't panic and delete files that might be useful.
592 <P>
593The last parameter in the Tank command is the
594<font color=red>tankfile-name</font>; this gives the full pathname for the tank
595file. We recommend that you make the tank name similar to the SCNL to aid in
596file manipulation.
597<PRE><!-- Default and example go here   -->
598Default:  none
599Example:  Tank    SEA BHZ UW --  264   INST_UW    MOD_WILDCARD       10         100         /earthworm/run/tanks/SEA_BHZ.tnk
600</PRE>
601</BLOCKQUOTE>
602<HR>
603
604<A NAME="TankStructFile">  <!-- command name as anchor inside quotes -->   
605<PRE><B>TankStructFile <font color=red>name</font>                             Required
606</B><!-- command args ... -->           
607</PRE>
608<BLOCKQUOTE> <!-- command description goes here -->
609Specifies the <font color=red>name</font> of the first tank structure file.
610This should be a full pathname, not a simple file name. This structure file
611name traditionally ends in "-1.str", but this is not required.
612The tank structure file
613contains configuration parameters for all existing tank files. It also contains
614the location in the tank file where new trace data is to be added. This
615data insertion point (a file offset) is updated in the tank structure file at
616the interval specified by <A HREF="#TankStructUpdate">TankStructUpdate.</A>
617<PRE><!-- Default and example go here   -->
618Default:  none
619Example:  TankStructFile j:\data\usgs\datafiles\p1000-1.str
620</PRE>
621</BLOCKQUOTE>
622<HR>
623
624<A NAME="TankStructFile2">  <!-- command name as anchor inside quotes -->   
625<PRE><B>TankStructFile2 <font color=red>name</font>
626</B><!-- command args ... -->           
627</PRE>
628<BLOCKQUOTE> <!-- command description goes here -->
629Specifies the <font color=red>name</font> of the second tank structure file.
630This command is required if <A HREF="#RedundantTankStructFiles">RedundantTankStructFiles</A>
631is set to 1; otherwise it is ignored. This should be a full pathname, not a
632simple file name. This structure file name traditionally ends in "-2.str",
633but this is not required.
634<PRE><!-- Default and example go here   -->
635Default:  none
636Example:  TankStructFile2 j:\data\usgs\datafiles\p1000-2.str
637</PRE>
638</BLOCKQUOTE>
639<HR>
640
641<A NAME="TankStructUpdate">  <!-- command name as anchor inside quotes -->   
642<PRE><B>TankStructUpdate <font color=red>U</font>                             Required
643</B><!-- command args ... -->           
644</PRE>
645<BLOCKQUOTE> <!-- command description goes here -->
646Defines the number of seconds, <font color=red>U</font> between
647tank structure file updates. The TANK structure is maintained in memory, and
648periodically written to disk.  The TANK structure tracks the status of the
649all the tank files.  Any data written to the tanks since the last time the
650TANK structure was written to disk is effectively lost if wave_serverV crashes.
651The larger the interval, the more tank data is potentially lost in a crash;
652the smaller the update interval the more disk I/O that is required for
653wave_server to operate. We recommend a structure file update interval of
654one second.
655<PRE><!-- Default and example go here   -->
656Default:  none
657Example:  TankStructUpdate 1
658</PRE>
659</BLOCKQUOTE>
660<HR>
661
662<A NAME="UsePacketSyncDb">  <!-- command name as anchor inside quotes -->   
663<PRE><B>UsePacketSyncDb <font color=red>U</font>   
664</B><!-- command args ... -->           
665</PRE>
666<BLOCKQUOTE> <!-- command description goes here -->
667Defines whether to buffer asynchronous trace buffer packets to a database and
668resynchronize them into the client streams. This feature may be turned on by
669specifing 1 for <font color=red>U</font>. This feature is off by default. If specied the
670configuration parameters <A HREF="#PacketSyncDbFile">PacketSyncDbFile</A> and
671<A HREF="#PurgePacketSyncDb">PurgePacketSyncDb</A> may be used to
672configure its behavior but are not required.
673<PRE><!-- Default and example go here   -->
674Default: 0
675Example: UsePacketSyncDb 1
676</PRE>
677</BLOCKQUOTE>
678<HR>
679
680<A NAME="sample_config">
681<H2><BR>3. Sample Configuration File </H2>
682<pre>
683#
684#         Wave ServerV Configuration File
685#
686#       Note:  All directories defined in this configuration file must already
687#               exit or WaveServerV will die.
688#
689MyModuleId    MOD_WAVESERVERV # wave_server's module id
690RingName      WAVE_RING        # name of transport ring to get data from
691LogFile       1                # 1=write log file to disk; 0=don't
692                               # 2=write to module log but not stderr/stdout
693HeartBeatInt  15               # seconds between heartbeats to statmgr
694ServerIPAdr   192.168.1.5      # address of machine running wave_server: geops.geophys
695ServerPort    16022            # port for receiving requests & sending waves
696GapThresh     1.5              # threshhold for gap declaration
697                               # (in sampling periods)
698
699#
700
701SocketTimeout 11000  # Timeout length in MILLISECONDS for socket calls
702                     # This is for calls sending responses back to the
703                     # client. Values should be a few seconds, certainly
704                     # less than one minute.
705
706
707ClientTimeout  60000 # Optional.  Not recommended feature but it does work.
708                     # Timeout in MILLISECONDS for response from client.
709                     # Threads that have not heard anything from their client
710                     # in this period will exit.
711                     # Comment out or set to -1 if you don't want to
712                     # kill threads of silent clients.
713
714
715# Each tank file has an associated in-memory index.  On re-start, the
716# index image on disk must be updated to match the tank.  The more out
717# of date the on-disk index is, the longer it takes to rebuild.  Rebuild
718# times can be from milliseconds to minutes per tank, depending how large
719# the tank is and how old the index is.
720# Set IndexUpdate to the length in time in seconds between
721# updates to disk.  The larger the update interval, the longer
722# a crash recovery will take.  The smaller the update interval
723# the more disk I/O that is required for wave_server to operate,
724# and thus the slower it will operate, once it has reached I/O
725# saturation.
726
727IndexUpdate   10                       
728                               
729
730# Similar to an Index, each tank has TANK structure that depicts the tank.
731# The tank structure is maintained in memory, and periodically written to
732# disk.  The TANK structure tracks the status of the tank.  Any data written
733# to the tank since the last time the TANK structure was written to disk
734# is effectively lost.  TankStructUpdate is the interval in seconds that the
735# Tank Structure file on disk is updated.  The higher the interval, the more
736# the tank data is that is potentially lost in a crash, the lower the interval
737# the more the disk I/O that is required for wave_server to operate.
738
739TankStructUpdate 1
740
741# The file where TANK structures are stored
742
743TankStructFile  j:\data\usgs\datafiles\p1000-1.str
744
745# I open many files, one tracedata file for each SCNL channel to serve
746# At 500 bytes/second, 1 channel requires 41.2 megabytes per day.
747# NOTE: Record size must be multiple of 4 bytes or wave_serverV will crash
748# with data misalignment.
749# Also, record size must not be greater than MAX_TRACEBUF_SIZ, currently 4096,
750# (defined in tracebuf.h)
751#
752#           SCNL    Record       Logo                  File Size   Index Size       File Name       New       
753#          names   size  (TYPE_TRACEBUF2 only)         (megabytes) (max breaks)     (full path)      Tank     
754
755Tank    GUID EAG NC -- 528   INST_MENLO    MOD_WILDCARD       1         10000        j:\data\usgs\datafiles\p1001.tnk
756Tank    IRG1 EAT NC --  528   INST_MENLO    MOD_WILDCARD       1         10000         j:\data\usgs\datafiles\p1002.tnk
757Tank    IRG2 EAT NC --  528   INST_MENLO    MOD_WILDCARD       1         10000         j:\data\usgs\datafiles\p1003.tnk
758
759
760# Advanced Options
761# YES = 1, NO = 0, NO = (default)
762
763#RedundantTankStructFiles  Set to 1 to use redundant tank struct files. (Recommended)
764RedundantTankStructFiles 1
765
766#RedundantIndexFiles  Set to 1 to use redundant tank index files. (Recommended)
767RedundantIndexFiles      1
768
769
770# Must be set if RedundantTankStructFiles = 1
771#TankStructFile2  /tmp/p1000-2.str
772TankStructFile2  j:\data\usgs\datafiles\p1000-2.str
773
774
775#InputQueueLen:  The number of messages to buffer.  Messages are buffered
776#in a queue.  They are added to the queue when they are pulled off of an
777#earthworm message ring, they are removed from the queue when the main
778#thread is ready to process them.  Depending on the CPU and disk speed
779#of the machine you are using, this number should be about twice the
780#number of tanks you are trying to serve.  Slower machines may need
781#larger queues.
782InputQueueLen 30
783
784
785###################################
786#           Other Optional Commands
787
788
789#MaxMsgSize: Optional command to tell wave_server about TRACEBUF2 messages
790# that could be larger than any going to tanks for this server. This
791# may happen if you have two wave_servers and TRACEBUF2 sources that
792# produce different size messages, e.g., ref2ew messages are 1064 bytes.
793MaxMsgSize 1064
794
795#Debug  Generates VERYVERYVERY large log files.
796#Debug 1
797
798#SocketDebug Set to 1 to get SOCKET_ew debug statements
799SocketDebug 0
800
801#PleaseContinue  Set to 1 to have wave_server continue, even if
802#  there are errors during initialization
803# PleaseContinue 1
804
805#ReCreateBadTanks Set to 1 to have bad tanks re-created from scratch.
806#ReCreateBadTanks 1
807
808#SecondsBetweenQueueErrorReports   Minimum period of time between error
809#  reports to statmgr due to the internal message queue being lapped,
810#  and thus messages being lost.  Default is 60 seconds
811#SecondsBetweenQueueErrorReports 30
812
813#MaxServerThreads  Maximum of server threads to deploy to handle client
814#  requests.  Default is 10.
815#MaxServerThreads 10
816
817#QueueReportInterval  The minimum number of seconds between
818#  reports on internal queue high and low water marks.  The default is 30.
819#QueueReportInterval 5
820
821#AbortOnSingleTankFailure  Set to 0 to have wave_server continue even
822#if there is a fatal error on a tank during normal processing.
823#if this flag is not set to 0, wave_server will die if any type of
824#IO error occurs on any tank.  If set to 1, wave_server will not exit
825#unless there is a server wide error.
826#AbortOnSingleTankFailure 1
827
828#UsePacketSyncDb Uncomment entry and set to 1 to use embedded db functionality
829# to manage asychronous trace buffer packets. Currently this is either on or off
830# for all SNCLs.
831#UsePacketSyncDb 1
832
833#PacketSyncDbFile - Specifies name of database file to use. If not specified
834# and UsePacketSyncDb == 1 then the default PCKTSYNC.SL3DB is used.
835#PacketSyncDbFile "TB2PACKETS.SL3DB"
836
837#PurgePacketSyncD Uncomment and specify one of the following to control
838# how long out of sync data is kept in the database if UsePacketSyncDb=1.
839# 1 : Purge data on startup
840# 0 : Do not purge data on startup. Obsolete data is intermittently purged
841# during the operation of wave_serverV is UsePacketSyncDb is 1.
842#PurgePacketSyncDb 1
843</pre>
844</BLOCKQUOTE>
845<HR>
846
847<CENTER> 
848<A HREF="../modules.html">Module Index</A> |
849<A HREF="../ovr/wave_serverV_ovr.html">Wave_ServerV Overview</A>
850</CENTER>
851
852<!-- USGS-required stuff at the end -->
853<HR>
854<ADDRESS>
855Contact: <B><address> Questions? Issues? <a href="http://lyris.nmt.edu/read/all_forums/subscribe?name=earthw" target="_blank">Subscribe to the Earthworm List (earthw). </a></address></B><BR>
856</ADDRESS>
857</BODY>
858</HTML>
859
Note: See TracBrowser for help on using the repository browser.