Search:
wiki:programmer_notes
Last modified 20 months ago Last modified on 01/17/12 12:48:49

    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

### Download in other formats:

- Plain Text