Changes between Version 4 and Version 5 of wave_serverV


Ignore:
Timestamp:
02/27/12 18:41:29 (8 years ago)
Author:
branden
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • wave_serverV

    v4 v5  
    3333Following is a description of the process wave_serverV goes through when it starts up. This is intended to give users an understanding of how configuration changes are implemented by wave_serverV. 
    3434 
    35 When wave_serverV first starts up, it reads the configuration file, and then starts a three-stage process of opening and checking tank and index files. In the first stage, it reads one of the `tank structure' files (an *.str file) if they exist. If no tank structure files are found, wave_serverV proceeds to the second stage, below. 
    36  
    37 Wave_serverV assumes that the tank structure file has the most up-to-date information about existing tank files (*.tnk) and their indexes (*.inx), especially tank file size, record size, and tank insertion position. This last crucial bit of information tells the `starting point' in the tank. Data just behind this point is the most recent information in the tank. Data after the insertion point is the oldest and will be overwritten as new data is added to the tank in circular fashion. 
     35When wave_serverV first starts up, it reads the configuration file, and then starts a three-stage process of opening and checking tank and index files. In the first stage, it reads one of the 'tank structure' files (an *.str file) if they exist. If no tank structure files are found, wave_serverV proceeds to the second stage, below. 
     36 
     37Wave_serverV assumes that the tank structure file has the most up-to-date information about existing tank files (*.tnk) and their indexes (*.inx), especially tank file size, record size, and tank insertion position. This last crucial bit of information tells the 'starting point' in the tank. Data just behind this point is the most recent information in the tank. Data after the insertion point is the oldest and will be overwritten as new data is added to the tank in circular fashion. 
    3838 
    3939The server runs through the list of tanks from the structure file, verifying that each SCNL is listed in the config file. The one piece of information that wave_serverV takes from the config file in this stage is the index file size. Wave_serverV tries to open each the tank file and its index. If index files are missing or out of date, they are recreated by reading through the tank file. Depending on the amount of reconstruction needed for an index, this process may take several minutes for each tank. Note that there is no provision for checking the insertion point, read from the structure file, against the tank file. 
     
    5151As of Earthworm version 5.1, wave_serverV has a signal handler that allows graceful shutdowns (without having to stop all of earthworm.) 
    5252 
    53 '''WindowsNT:''' this shutdown mechanism can be invoked in only one way: you must give the Control-C interrupt to the console window where wave_serverV is running. '''DO NOT''' try using `restart <pid>', as this will terminate wave_serverV immediately without sending a signal to it. Once wave_serverV has terminated and its console window is gone, you can start a new instance of wave_serverV by using `restart <pid>' or by letting statmgr send a restart request. This last method requires that the `restartMe' command was set in wave_serverV's .desc file. 
    54  
    55 '''Solaris:''' (unix) wave_serverV can be terminated using the `kill <pid>' command. To stop and immediately restart wave_serverV, you can use `restart <pid>'. 
     53'''WindowsNT:''' this shutdown mechanism can be invoked in only one way: you must give the Control-C interrupt to the console window where wave_serverV is running. '''DO NOT''' try using 'restart <pid>', as this will terminate wave_serverV immediately without sending a signal to it. Once wave_serverV has terminated and its console window is gone, you can start a new instance of wave_serverV by using 'restart <pid>' or by letting statmgr send a restart request. This last method requires that the 'restartMe' command was set in wave_serverV's .desc file. 
     54 
     55'''Solaris:''' (unix) wave_serverV can be terminated using the 'kill <pid>' command. To stop and immediately restart wave_serverV, you can use 'restart <pid>'. 
    5656 
    5757With earlier versions of wave_serverV (Earthworm V5.0 and earlier) the only way to shut down wave_serverV is to shut down earthworm, using the '''pau''' command or entering "quit" at the '''startstop''' window. 
     
    7575 * '''Change the sample rate for an SCNL?''' The sample rate is a critically important value that wave_serverV reads from the trace_buf messages it records. It uses this number for its conversions between time and sample number when wave_serverV responds to requests for trace data in ASCII format. So it is important not to mix trace data of different sample rates within one tank file. Usually, a change of sample rate will require a change in the component designation (such as is specified by Appendix A of the SEED manual); but this may not always be true. 
    7676 
    77  * '''Change recsize (record size) of a tank?''' Wave_serverV considers a tank file to be made up of a sequence of records, all of them `recsize' bytes long. One of these records holds one trace_buf message. If you need to change the records size, you must get rid of the old tank file and the information for that tank in the structure file(s). You must shut down wave_serverV, remove the tank and index file(s) for that SCNL, and then start wave_serverV. That will remove the old information from the structure file(s). To get the new tank going with the new information, you change the recsize value in the config file, and then restart wave_serverV. 
    78  
    79  * '''Change tank file size?''' The tank file has a moving `starting point': as new data is added within the tank, old data is overwritten. So there is no way to extend the size of an existing tank. If you need to change the tank size, you must get rid of the old tank file and the information for that tank in the structure file(s). You must shut down wave_serverV, remove the tank and index file(s) for that SCNL, and then start wave_serverV. That will remove the old information from the structure file(s). To get the new tank going with the new information, you change the recsize value in the config file, and then restart wave_serverV. 
     77 * '''Change recsize (record size) of a tank?''' Wave_serverV considers a tank file to be made up of a sequence of records, all of them 'recsize' bytes long. One of these records holds one trace_buf message. If you need to change the records size, you must get rid of the old tank file and the information for that tank in the structure file(s). You must shut down wave_serverV, remove the tank and index file(s) for that SCNL, and then start wave_serverV. That will remove the old information from the structure file(s). To get the new tank going with the new information, you change the recsize value in the config file, and then restart wave_serverV. 
     78 
     79 * '''Change tank file size?''' The tank file has a moving 'starting point': as new data is added within the tank, old data is overwritten. So there is no way to extend the size of an existing tank. If you need to change the tank size, you must get rid of the old tank file and the information for that tank in the structure file(s). You must shut down wave_serverV, remove the tank and index file(s) for that SCNL, and then start wave_serverV. That will remove the old information from the structure file(s). To get the new tank going with the new information, you change the recsize value in the config file, and then restart wave_serverV. 
    8080 
    8181 * '''Change installation ID or module ID for a tank?''' The installation ID and module ID in the Tank command are used as filters to select which source module should be used for trace data. This information is stored in the tank structure file(s) for wave_serverV. There is currently no way to change this information without effectively destroying the information in the tank file. You must shut down wave_serverV, remove the tank and index file(s) for that SCNL, and then start wave_serverV. That will remove the old information from the structure file(s). To get the new tank going with the new information, you change the installation or module ID values in the config file, and then restart wave_serverV. 
     
    8787 * '''Change structure file name or location?''' The pathname of the structure file is recorded only in the configuration file, so changing it is possible. Make the change in the config file, shut down wave_serverV, move or rename the structure file to the desired location, and start wave_serverV. Make sure when you rename the structure file that it exactly matches the name that you give in the config file. Also note there is one command to name each of the structure files (if you are using two of them.) 
    8888 
    89  * Change the number of index files? Changing the number of index files is simple: make the change to the config file and restart wave_serverV. If you have turned on redundant index files, new ones will be created for each tank. If you have turned off redundant index files, the second file for each tank will be ignored. But why would you want to do that? 
     89 * '''Change the number of index files?''' Changing the number of index files is simple: make the change to the config file and restart wave_serverV. If you have turned on redundant index files, new ones will be created for each tank. If you have turned off redundant index files, the second file for each tank will be ignored. But why would you want to do that? 
    9090 
    9191 * '''Change the number of structure files?''' There is no provision in wave_serverV to generate a structure file from existing tank tiles. If you need to add a redundant structure file, make the changes to the config file. This requires both setting !RedundantTankStructFiles to 1, and specifying the name with !TankStructFile2. Then shut down wave_serverV, copy the existing tank structure file to the new name, and start wave_serverV. 
     
    195195=== HISTORY === 
    196196 
    197 The original Wave_server module was written by Will Kohler in a rather spectacularly short time: We came in on a Monday to find Will comatose, all waste cans full of espresso cups, and a working wave server. The motivation was to support the effort with the Alaska Geophysical Institute to integrate Earthworm with DataScope and to provide a playback facility for testing real-time algorithms. Lynn Dietz then proceeded to add numerous enhancements. It stores all trace data messages received, and servers all trace data received during a specified time interval. It can thus be used to recreate the the pattern of trace data messages inside an Earthworm system during a specified period of time. This has proven to be valuable for testing and debugging, and this module still exists as "wave_server". 
     197The original Wave_server module was written by Will Kohler in a rather spectacularly short time: We came in on a Monday to find Will comatose, all waste cans full of espresso cups, and a working wave server. The motivation was to support the effort with the Alaska Geophysical Institute to integrate Earthworm with !DataScope and to provide a playback facility for testing real-time algorithms. Lynn Dietz then proceeded to add numerous enhancements. It stores all trace data messages received, and servers all trace data received during a specified time interval. It can thus be used to recreate the the pattern of trace data messages inside an Earthworm system during a specified period of time. This has proven to be valuable for testing and debugging, and this module still exists as "wave_server". 
    198198Kent Lindquist then produced an enhanced version, including the idea of segmenting the tank into one partition for each trace. Since then, several authors were involved in wave_server development: Alex Bittenbinder wrote the main thread; Mac !McKenzie wrote the parser of the client thread (server_thread.c); Eureka Young wrote the server routines; Dave Kragness pretty much re-wrote the main thread while implementing crash-recovery, and Pete Lombard produced the suite of associated client routines. 
    199199 
     
    324324Function: Earthworm Setup 
    325325 
    326 Sets the on-off switch for writing a log file to disk. If switch is 0, no log file will be written. If switch is non-zero, wave_serverV will write daily log file(s) called nnnnnxx.log_yyyymmdd where nnnnn is the name of the configuration file (with the suffix `.d' removed), xx is wave_serverV's module id (set with !MyModuleId command) and yyyymmdd is the current UTC date (ex: 19960123) on the system clock. The file(s) will be written in the EW_LOG directory (environment variable). 
     326Sets the on-off switch for writing a log file to disk. If switch is 0, no log file will be written. If switch is non-zero, wave_serverV will write daily log file(s) called nnnnnxx.log_yyyymmdd where nnnnn is the name of the configuration file (with the suffix '.d' removed), xx is wave_serverV's module id (set with !MyModuleId command) and yyyymmdd is the current UTC date (ex: 19960123) on the system clock. The file(s) will be written in the EW_LOG directory (environment variable). 
    327327{{{ 
    328328Default:  none