>  Docs Center  >  Libraries  >  JHU/APL/S1R  >  TXTDB_RD

TXTDB_RD

TXTDB_RD

Name


      TXTDB_RD

Purpose


      Read a text file data base.

Category


Calling Sequence


      s = txtdb_rd(file)

Inputs


      file = name of text file with data base. in
        File may instead be the text array that would have
        been read from the file (same format).

Keyword Parameters


Keywords


        ERROR=err Error flag: 0=ok.
        /QUIET do not show warning and error messages.
        TAB=tab Spaces/tab (def=8).
        /DEBUG use debug mode. Shows how text is processed.
          May also do DEBUG=n to show details for n'th data item.
        DROP=com_chars List of comment characters (def=';*').
            Any line starting with any will be dropped. By default
            drops lines with ; or * in column 1.
        /NODROP do not drop any lines.
        /NOHEADERS exclude header (or trailer) lines in output.
            Any header variables will still be included.
        /NOHVARS do not include header variables in output.
        /NO_NULL do not replace <NULL> with a null string.
          txtdb_wr uses <NULL> for null strings.
        /EXECUTE Execute a statement (see below). This allows
          values that are functions of other values in the file.
        /REFOPT Reference lines are optional, consider all header.
          This is useful to use only header variables. Do not
          use /NOHEADERS with this option.

Outputs


      s = returned structure with data. out

Common Blocks


Notes


      Note: The text file with the data to read must have a
      certain layout. It is an ordinary text file, perhaps
      wider than normal if that is needed. It can have the
      following sections:
        Header lines (n lines, optional) |
        Data decription (3 lines, required) > This group may be
        Data lines (n lines, required) | repeated any number
        Blank line (1 line, required) | of times.
        Trailer lines (n lines, optional)
      An example: (The string "<--" below is not part of file):
      Header line 1 <-- Header lines
      Header line 2 ...
      code length weight color <-- Tag line
        int flt flt str <-- Type line
      ----- ------ ------ ----- <-- Reference line
        1 2.34 32.7 Red <-- data lines
        2 3.17 25.5 Blue ...
        3 1.42 14.3 Green
                                    <-- Blank line, end of data
      Trailer line 1 <-- Trailer lines
      Trailer line 2 ...
     
      Blank data entries are allowed and will be returned as 0 or
      null strings. However each data line must have at least
      one entry since a blank line terminates the data block.
     
      After the blank line at the end of the data lines, the
      pattern: header lines, tag line, type line, reference line,
      data lines may be repeated any number of times. Just
      make sure each group of data lines is followed by a
      blank line. Header lines are optional as before.
     
      The reference line is the key line. It defines the column
      locations for the data, tag names, and data types, so those
      items must all fall within the width defined in the
      reference line. The reference line must use groups of dashes
      to specify these positions. Do help,typ2num() to see
      how to specify the data types. Also * or ; as data type
      will ignore that column, useful for row labels.
     
      The column data will be in arrays with names given in the
      tag line.
     
      Text before the data lines are returned in items named
      __textxxx where xxx is a 3 digit count.
      Any trailer text will be returned the same way.
     
      VARIABLES:
      Headers and the trailer may contain optional variables in
      the form: tag = value
      (Comment lines are ignore and will not be processed)
      The tags/values will be added to the output structure.
      Header (Trailer) variable values are returned as string type.
      Numeric strings may be converted by the user in their code.
      Repeated header variables are allowed and return arrays:
        tag1 = val1
        tag1 = val2
     
      EXECUTE:
      Header and trailer variables may contain expressions,
      including values that have already been read from the
      text file. Add the string EXECUTE_ (case ignored) at the
      front of the tag. Values that have already been read from
      the file are in the internal structure s, they may be used
      from this structure. For example:
        execute_lat10 = 10*s.lat
      will return a structure element lat10 that is 10 times
      the structure element lat.
      --> Executed variables may only reference values that
      have been defined above in the file. They are in the
      internal structure named s. Header variables will be strings
      so must be converted to numeric if needed.
      --> Must use the keyword /EXECUTE to process these variables.
      The added item will normally be placed at the end of the
      current structure. It may be placed after a specified tag
      by adding ; @ tag at the end of the line, where tag is the
      name of the tag to follow. Use ^ for tag to add it to the
      front of the structure: @ ^. The target tag must be the next
      item after @ but the trailing comment may contain other text.
      This is useful when resulting structure will be written
      out using txtdb_wr.

Modification History


      R. Sterner, 2003 Aug 26
      R. Sterner, 2003 Aug 28 --- Allowed multiple data blocks.
      R. Sterner, 2003 Sep 02 --- Renamed from rd_txtdb.pro.
      R. Sterner, 2003 Sep 03 --- Allowed ignored data columns.
      R. Sterner, 2003 Dec 09 --- Did strtrim on each item, instead of
      strcompress,/remove_all. That allows spaces in strings.
      R. Sterner, 2004 Feb 25 --- Allowed text array to be given.
      R. Sterner, 2006 Mar 21 --- Added new data type: DMS.
      R. Sterner, 2006 Mar 27 --- Added new keywords: DROP=drop, /NODROP.
      R. Sterner, 2006 Jun 08 --- Fixed loop limits to be long int.
      R. Sterner, 2007 Dec 25 --- Allowed header variables.
      R. Sterner, 2007 Dec 27 --- Check for blank headers, don't add.
      R. Sterner, 2007 Dec 27 --- Added /NOHEADERS and /NOHVARS.
      R. Sterner, 2008 Jan 04 --- Handled <NULL> for null strings.
      R. Sterner, 2008 Jan 23 --- Header tag=val kept only if tag first item.
      R. Sterner, 2008 Apr 14 --- Fixed minor problem with trailer vars.
      R. Sterner, 2008 Apr 14 --- Added EXECUTE variables.
      R. Sterner, 2008 Nov 20 --- Allowed placement of execute variables.
      R. Sterner, 2009 Jun 02 --- Added /REFOPT to consider all one header.
      R. Sterner, 2009 Jun 29 --- Now by default gives error if file not read.
      R. Sterner, 2010 May 03 --- Converted arrays from () to [].
      R. Sterner, 2010 May 03 --- DMS now uses llsigned instead of dms2d.
      R. Sterner, 2012 Sep 10 --- Checks for blank line after reference line.
      R. Sterner, 2013 Nov 19 --- Allowed repeated header variables (arrays).
      R. Sterner, 2014 Jan 27 --- Allowed repeated trailer variables (arrays).
      R. Sterner, 2014 Jan 27 --- Added CODE_BLOCKS=list, allowed merged lines ($).
      R. Sterner, 2014 Apr 04 --- Cleaned up help text.
  Copyright (C) 2003, Johns Hopkins University/Applied Physics Laboratory
  This software may be used, copied, or redistributed as long as it is not
  sold and this copyright notice is reproduced on each copy made. This
  routine is provided as is without any express or implied warranties
  whatsoever. Other limitations apply as described in the file disclaimer.txt.



© 2019 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us