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.
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.
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.