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