Changes between Initial Version and Version 1 of Location_Code_Policy

Timestamp:

01/19/12 18:21:48 (9 years ago)

Author:

branden

Comment:

--

Location_Code_Policy

@@ +1 @@
+{{{
+
+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
+
+
+
+
+}}}