This is a quick and dirty guide to what you need to know to migrate from V6.3 to V7.X in Earthworm. The biggest change in this migration is that stations are now not just identified by a 3 tuple of Station, Channel, Network, but by a 4 tuple which also includes Location code. You will hear this referred to as SCN vs SCNL. Location code is simply a 2 character "tie-breaker" for when you have multiple channels of the same type at a given station. Location codes can be any convention that the operators desire, but the location code must be limited to numbers or letters. If location codes are not being used, the operator should use dash dash as a placeholder for any configuration files "--". Refer to the SEED manual at the IRIS DMC.  Refer to the programmer notes for which earthworm messages changed to accomodate SCNL vs  SCN.

In addition to the SCNL change, there were 2 new features added in the v7.X release that require new message types be added to the earthworm.d file. The first feature, introduced in v7.0 is the reconfigure command which requires a TYPE_RECONFIGURE message type be added in. This feature allows an operator to modify a startstop.d file with new modules or new rings, and have those changes be effected without having to stop and restart all of Earthworm. The second feature, added in v7.1, allows an operator to stop a given module using the stopmodule command. The stopmodule implementation requires that a TYPE_STOP  message be added to your earthworm.d. See the documentation on startstop for more information on how to use these new features.

It is okay to run v6.3 and v7.X modules together, but if you plan on running new modules in an old configuration you will not be able to take advantage of the new features. Further, if you run new modules on the old system, you will need to bring in any new message types to your earthworm_global.d and into your earthworm.d files.

Frequently Asked Questions:

1. Which modules care about SCNL vs SCN?
• The simple answer is any module that deals with Tracebuf, Pick, or Coda messages cares. Thus, you will need to review the documentation for each module and see how it is affected. In short, look at your data_source modules and make sure that you have decided on a SCNL scheme and get them configured first. Then work your way downstream through your processing chain. The fir and pick_ew modules are next, followed by the binder module, and ultimately hypoinverse (aka hyp2000). Note that example SCNL .d files are provided in the src dir with each module.
  
2. Can I use v7.X modules in a v6.3 environment?
• Yes, you can intermix messages since all V7.X messages are new types, so old and new can reside on the same rings. However you need to take care that you rename module names so that they do not collide with old versions. It is best to  limit those running newer versions of the modules and newer messages to reside on different rings.
  
3. Can I use my old v6.X module in a v7.0 environment?
• Yes, you can intermix, but realize that the v6.X module will only look for SCN message types and thus you will need to use a converter (scnl2scn) to get the SCNL data onto a separate ring in SCN format so that the v6.X module can operate.
  
4. How can I get old messages into the new format?
• Easy, there are 2 converters that go forward and backward: scn2scnl and scnl2scn that will map all messages to the new or old format. They can be found in the data_exchange module directory.
  
5. How can I import v7.X waveform data into my v6.X environment?
• Simply grab the v7.X module you need to use to import the data (any of the data_exchange modules or data_source modules) and make sure it is named uniquely (so that it doesn't overwrite a v6.X version) and install it on your v6.3 system in the bin directory. Also grab the scnl2scn converter from v7.X and install that. Then, update your earthworm_global.d with the new message types found in v7.X (see the earthworm_global.d from the distro). Import the data into a new ring called WAVE_RING_SCNL and then setup scnl2scn to convert the data to where you want the waveforms.
  
6. startstop v7.X won't work with my old configuration because it complains about missing messages, what did I miss?
• Because new features were added into startstop, Earthworm's core module, you need to add in new message types to your old earthworm.d and earthworm_global.d files. Add in the new message types, by doing a diff on the files
7. How do I deal with my old v6.X SCN wave_serverV tanks?
• If you have only a small amount of data you need to move from v6.X to v7.X, you can use waveman2disk to write the section of data you need in tankplayer format, then use the tankplayer module to replay that data back into a ring. Once it's in a ring, you can convert it with scn2scnl, and then import the converted tracebufs into a v7.X wave_serverV tank. Tankplayer doesn't have a fast forward mode, so this may take some time.
• If you have months or years worth of data in a v6.X wave_serverV tank, you may want to keep running your v6.X wave_serverV, and start a new wave_serverV recording v7.X SCNL tracebufs in parallel. Once the v7.X wave_serverV has been running long enough for you to be able to search for all the historical data you need, you can turn off your v6.X wave_serverV. Note that the wave viewer application Swarm is one of the few wave server clients that will allow accessing either SCN or SCNL packets, and therefore can talk to a v6.X or a v7.X wave_serverV server. Almost all of the earthworm modules will only deal with with SCN if they're from v6.X and SCNL if they're from v7.X. So if you do run with dual waveservers, you'll probably need two different versions of each earthworm module.