Earthworm Location Code Policy                           2004/03/05:LDD
------------------------------

These rules are based on the SEED and CISN conventions referenced below, 
with a nod to current practices and software logic simplification.

1. We will follow the SEED convention of allowed characters
   (A-Z, 0-9, space).  In apparent contradiction to the previous 
   statement, we will use the character '-' to represent 'space' 
   in all Earthworm I/O. Just remember to think 'space' when you
   see '-'. Lower case alphanumerics are not permitted.

2. The location code will always contain 2 characters, either
   two alpha-numeric characters or two spaces ('--'). The use 
   of a single space (or '-') adjacent to an alpha-numeric is not 
   permitted. 

3. The default location code in SEED is "  " (space-space).
   We'll call this the "blank" location code.  While there are no rules 
   on how EW software should represent a blank location code for its own  
   internal manipulations, all software must obey the following rules  
   for all of its Input/Output, including its log files:
   a. For all ASCII I/O, both column-oriented and whitespace-delimited,
      a blank location code will be written as "--".  We recognize that 
      "  " could be interpreted properly by software in column-oriented
      ASCII, but we feel that it is easier for humans reading the data
      to have a single convention for all ASCII information.
      When parsing any ASCII input, software will interpret "-" or "--" 
      as the blank location code.
   b. In binary I/O, currently only the Earthworm tracedata messages,
      the blank location code will also be represented by "--".
   c. In the Earthworm DBMS, the blank location code will be represented
      as the string "--".

4. When Earthworm data is converted to SEED format, all blank location
   codes will be converted from "--" to "  " (space-space).

5. Software should *never* assume that the location code has any
   meaning. It should be used exclusively as a tie-breaker when
   multiple channels of data have the same SCN.  This will allow
   allow each network to use their own convention for assigning 
   the location code and to process data from another network whose
   convention is different.


Current Practices
-----------------
In the EW database, blank location codes are stored as NULLs. Queries
for a blank location code must have extra logic to check the DBMS for a 
blank string or a NULL field.  When we switch to storing blank location 
codes as "--" everywhere, no extra logic would be required for 
string-matching.

In the NCEDC database, blank location codes are stored as "space-space".

In SEED, fields are blank padded, so a blank or NULL location code is 
always stored as "space-space".  IRIS DMC software maps a "-" in a 
data request to a "space" in the location code.  Therefore, if data 
were stored with a "-" in the location code, there would be no way to 
request it explicitly.  Therefore, when Earthworm data is converted to
SEED format, we must revert to "space-space".


References
----------
SEED convention:
http://www.iris.edu/news/newsletter/vol1no1/page1.htm

CISN convention:
http://www.cisn.org/standards/reports.2003-11-05/wg_loc.03.11.20.final.doc