source: trunk/EW_Loc_policy.txt @ 1521

Revision 1521, 3.2 KB checked in by dietz, 16 years ago (diff)

* empty log message *

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