Changes between Initial Version and Version 1 of programmer_notes


Ignore:
Timestamp:
01/17/12 12:48:49 (10 years ago)
Author:
branden
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • programmer_notes

    v1 v1  
     1{{{ 
     2Earthworm Location Code Policy                           2004/03/05:LDD 
     3------------------------------ 
     4 
     5These rules are based on the SEED and CISN conventions referenced below,  
     6with a nod to current practices and software logic simplification. 
     7 
     81. We will follow the SEED convention of allowed characters 
     9   (A-Z, 0-9, space).  In apparent contradiction to the previous  
     10   statement, we will use the character '-' to represent 'space'  
     11   in all Earthworm I/O. Just remember to think 'space' when you 
     12   see '-'. Lower case alphanumerics are not permitted. 
     13 
     142. The location code will always contain 2 characters, either 
     15   two alpha-numeric characters or two spaces ('--'). The use  
     16   of a single space (or '-') adjacent to an alpha-numeric is not  
     17   permitted.  
     18 
     193. The default location code in SEED is "  " (space-space). 
     20   We'll call this the "blank" location code.  While there are no rules  
     21   on how EW software should represent a blank location code for its own   
     22   internal manipulations, all software must obey the following rules   
     23   for all of its Input/Output, including its log files: 
     24   a. For all ASCII I/O, both column-oriented and whitespace-delimited, 
     25      a blank location code will be written as "--".  We recognize that  
     26      "  " could be interpreted properly by software in column-oriented 
     27      ASCII, but we feel that it is easier for humans reading the data 
     28      to have a single convention for all ASCII information. 
     29      When parsing any ASCII input, software will interpret "-" or "--"  
     30      as the blank location code. 
     31   b. In binary I/O, currently only the Earthworm tracedata messages, 
     32      the blank location code will also be represented by "--". 
     33   c. In the Earthworm DBMS, the blank location code will be represented 
     34      as the string "--". 
     35 
     364. When Earthworm data is converted to SEED format, all blank location 
     37   codes will be converted from "--" to "  " (space-space). 
     38 
     395. Software should *never* assume that the location code has any 
     40   meaning. It should be used exclusively as a tie-breaker when 
     41   multiple channels of data have the same SCN.  This will allow 
     42   allow each network to use their own convention for assigning  
     43   the location code and to process data from another network whose 
     44   convention is different. 
     45 
     46 
     47Current Practices 
     48----------------- 
     49In the EW database, blank location codes are stored as NULLs. Queries 
     50for a blank location code must have extra logic to check the DBMS for a  
     51blank string or a NULL field.  When we switch to storing blank location  
     52codes as "--" everywhere, no extra logic would be required for  
     53string-matching. 
     54 
     55In the NCEDC database, blank location codes are stored as "space-space". 
     56 
     57In SEED, fields are blank padded, so a blank or NULL location code is  
     58always stored as "space-space".  IRIS DMC software maps a "-" in a  
     59data request to a "space" in the location code.  Therefore, if data  
     60were stored with a "-" in the location code, there would be no way to  
     61request it explicitly.  Therefore, when Earthworm data is converted to 
     62SEED format, we must revert to "space-space". 
     63 
     64 
     65References 
     66---------- 
     67SEED convention: 
     68http://www.iris.edu/news/newsletter/vol1no1/page1.htm 
     69 
     70CISN convention: 
     71http://www.cisn.org/standards/reports.2003-11-05/wg_loc.03.11.20.final.doc 
     72}}}