
   The STORET language has been modified to support a capability
 called INCLUDE.  Companion keywords ECHO and NOECHO may be used with
 INCLUDE (or without) to suppress unwanted echo printout from the SCAN.
 The proper use of these keywords is explained below.


                                                -----------------------
                                               |                       |
                                               |   INCLUDE=dsname,     |
                                               |                       |
                                                -----------------------

 CLASSIFICATION: General Retrieval Keyword.

 USE: This keyword is used to add lines of STORET retrieval
      specification to a retrieval from a dataset in the user's library
      or from the central STORET library.

 KEYWORD FORMAT AND VALUES:

     INCLUDE=data-set-name,

              where "data-set-name" is either the fully qualified
              name of any catalogued disk dataset, or if enclosed
              in parentheses as in
                             (dataname)
              is the name of a STORET owned library file you wish
              to use.

 DEFAULT VALUES: None.

 NOTES ON USAGE:

   The INCLUDE keyword may be inserted at any point in the retrieval
 request.  It will cause the inclusion of the entire contents of the
 given data-set at that point in the retrieval request.  The data-set
 may contain any text which is valid within the STORET retrieval
 language.  It may NOT contain another INCLUDE statement.  After all
 INCLUDE's have been resolved, the resulting retrieval is SCAN'ed as
 usual, and if found error-free, submitted for deferred batch
 processing.
   The INCLUDE statement may be specified any number of times in
 each retrieval request.  An INCLUDEd dataset may not itself contain
 an INCLUDE statement.

 EXAMPLE(S):

     The user library of user III (Account AAAA) is known to contain a
 catalogued data-set named "POLYGON.USEFUL".
     The data-set is on disk (all user libraries are on disk) and its
 full name (like any user library dataset) is constructed from the
 USERID and ACCOUNT as
               IIIAAAA.POLYGON.USEFUL
     The data-set contains a valid set of STORET polygon coordinates,
 and is line-numbered.
     A retrieval request might be

        PGM=INVENT,PURP=229/FED,
        LT=I,INCLUDE=IIIAAAA.POLYGON.USEFUL,
        PSA,AGGR=COUNTY,

    Note that it doesn't matter whether the include file is line
 numbered or not, or whether the base retrieval is line numbered or not,
 or in what sequence line numbers actually occur.

    The central STORET INCLUDE library contains a data-set named (SNAKE)
 which contains polygon coordinates that surround the Snake River basin
 in the Pacific Northwest.  The retrieval request above may be modified
 to address this polygon by a minor editing job, to wit:

        PGM=INVENT,PURP=229/FED,
        LT=I,INCLUDE=(SNAKE),
        PSA,AGGR=COUNTY,

    The central STORET library contains over 2,100 additional datasets
 each containing the polygon coordinates that surround one of the United
 States Geological Survey (USGS) cataloging unit hydrologic basins.
 Each dataset within the group is identified by the USGS designated
 eight digit numeric cataloging unit code and may be INCLUDEd by placing
 the code for the desired cataloging unit within parentheses following
 an INCLUDE keyword.  The retrieval request below inventories all STORET
 stations whose latitude/longitude coordinates fall within the polygon
 for cataloging unit 01020304:

        PGM=INVENT,PURP=229/FED,
        LT=I,INCLUDE=(01020304),

    Refer to the STORET Help dataset named PGM.LOC for a discussion of
 the cataloging unit polygon INCLUDE capability as it relates to STORET
 mapping applications.

    A complete list of centrally maintained STORET INCLUDE
 files appears below.

     INCLUDE Filename             Function
     ----------------  -------------------------------------------------
     these lines will be filled in at a later date.


   ECHO,NOECHO.
   ------------

     The ECHO and NOECHO keywords were added to ease use of the
 INCLUDE function, and a related capability, the "C" function,
 all of which may, when users are thoroughly familiar with them,
 produce volumes of unwanted printout.

     ECHO may be inserted at any point in a retrieval request,
 and causes the SCAN program to start printing all input text
 in the retrieval, even INCLUDEd text.  ECHO is the default.

     NOECHO may be inserted at any point in a retrieval request,
 and causes the SCAN program to STOP printing the usual echo
 of your input text. If it is placed before an INCLUDE keyword,
 the echo if the INCLUDEd text will also be suppressed.
 Print is suppressed until an ECHO keyword is encountered.

     These keywords may be used without limit.

     Users should note that constructing an INCLUDE file to
 begin with a NOECHO keyword makes it impossible to print the
 file contents during SCAN.  Similarly, constructing an INCLUDE
 file to begin with an ECHO keyword makes it impossible to
 suppress the echo of the INCLUDEd text.

    Retrieval requests with syntax errors may be very difficult
 to de-bug if NOECHO is in effect.  The NOECHO is, however, over-ridden
 in the event an error occurs for the line on which the error appears.
