asc2tbl Documentation

asc2tbl - Translate TABLE from ASCII format to ISIS binary format
This program translates TABLE data from an ASCII text format to the
standard ISIS binary TABLE format.  Two main parameters (DATADESC and
OMODE) specify how the input and output files are to be handled.  The
DATADESC parameter allows specifying two possible options for how the
program determines the format of the input ASCII table data.  The
OMODE parameter allows specifying whether a new output ISIS TABLE file
is to be created or whether the translated data are to be inserted
into an existing TABLE file.

DETERMINING INPUT FILE FORMAT
Specifying DATADESC=YES indicates that the input ASCII text file
contains text information that describes the format of the table
data.  This option is typically used for reading an ASCII file that was
produced by the "tbl2asc" program.  The text DATA DESCRIPTION that is
written by "tbl2asc" is in the standard format required by this program
("asc2tbl").

Specifying DATADESC=NO indicates that the format of the input ASCII text
data is to be determined by the LINLEN, COLUMNS, TYPES, SIZES, ELEMENTS,
and FORMATS parameters.  This option allows reading a file that contains
no standard text DATA DESCRIPTION information.  In this case, the first
line of the input file contains either the first row of table data or
the beginning of the optional comment sections.  This option also allows
reading a file that contains text DATA DESCRIPTION information that is
to be ignored.  In this case, a line that contains C_END is used to
mark the end of the DATA DESCRIPTION information and/or comment
information that is to be ignored.  The next line after the C_END
should then contain the first row of table data.  (Note that this option
allows reading in the old prototype text table files that were written
by programs such as the old versions of the VAX/VMS SPECAVE and CUBESPEC
programs.  The current versions of the VAX/VMS programs write standard
ISIS binary table files rather than text files.)


SELECTING OUTPUT MODE
Specifying OMODE=NEW will result in the translated table data being
written into a new ISIS binary TABLE file, which contains a HISTORY
data object and a binary TABLE data object whose name is given by the
OBJNAM parameter.  If the specified output file already exists, then
either a fatal error will be reported or the previously-existing file
will be replaced (depending upon the current value of the
ISIS_FILE_OVERWRITE environment variable).

Specifying OMODE=UPDATE will result in an existing TABLE file being
updated.  In this case, data columns from the input file are inserted
into columns of the specified TABLE data object in the output file.
Each input column will be inserted into the output column that has the
corresponding column name.  (Column names are not case-sensitive.)  If
an input column name does not appear in the output data object, then
the column data will not be inserted anywhere in the output file.
Warning messages will indicate which input columns are skipped.  For
the column names that do match in the input and output files, the data
TYPES (INTEGER, REAL or CHARACTER), binary SIZES (usually 4 bytes for
INTEGER or REAL), and the number of array ELEMENTS (usually 1) must
also match.  When using OMODE=UPDATE, the number of rows in the input
and output files must also match.  Note that the format of an input
column of text data is determined either by information in the input
file text DATA DESCRIPTION section (DATADESC=YES) or by the value
specified in the FORMATS parameter (DATADESC=NO).  In both cases, the
format recorded in the output file being updated will always remain
unchanged from its original value.


SPECIFYING LENGTH OF INPUT TEXT LINES
When DATADESC=NO is specified, then the LINLEN parameter must specify
the length of an input line of ASCII table data.  If one row of table
data is contained within one input text line, then LINLEN can specify
either the exact length of the input line or any larger value (with a
maximum value of 1024).  However, if multiple text lines are needed to
contain one row of table data, then LINLEN must exactly specify the
length of the LONGEST text line.  (Other text lines may be shorter
than the longest line.)


SPECIFYING FORMATS OF INPUT TABLE COLUMNS
When DATADESC=NO is specified, then the FORMATS parameter must list the
formats used for each column named in the COLUMNS parameter.  These are
specified in the form used for FORTRAN FORMAT statements.  It is
important to note that these describe the format of each column (or
element of a column if the column contains an array of values).  The
program assumes that there is an additional character (usually a space
or a tab) that separates each column (or element within a column that
contains an array of values).  These separator characters are not
counted in the widths that are part of the FORMATS values.


HANDLING SPECIAL PIXEL VALUES
When the TYPE and SIZE of a column is REAL*4, special 3-character codes
are recognized for indicating special pixel values in the input text
data.  These are translated into their corresponding internal binary
special pixel values as follows:
    NUL - Null
    LIS - Low Instrument Saturation
    LRS - Low Representation Saturation
    HIS - High Instrument Saturation
    HRS - High Representation Saturation


HANDLING LABEL AND HISTORY INFORMATION
When OMODE=NEW is specified, the label in the output ISIS TABLE file
will contain only the "required" keywords that describe the TABLE data
object.  Thus, if "tbl2asc" is used to translate an ISIS binary TABLE
object into ASCII format and then "asc2tbl" is used to translate it back
into binary format, any optional keywords present in the original file
will be lost.  These will include keywords such as the optional xxx_NOTE
keywords in the AUX_ROW_DEFINITION GROUP, which describe the meanings of
the table columns.  If it is necessary to preserve all the label
keywords when translating back to binary, then this can be accomplished
by using the OMODE=UPDATE option to insert the (possibly edited) data
back into a copy of the original binary file.

In a similar manner, using OMODE=NEW will create a new output TABLE file
whose HISTORY object contains only a HISTORY entry for the current run
of the "asc2tbl" program.  Using OMODE=UPDATE to insert into a copy of
the original binary file will preserve all the HISTORY of the original
file.


LIMITS ON SIZES THAT CAN BE HANDLED
The program has several built-in limits on the sizes of tables that can
be handled.  These limits can easily be increased if necessary.  The
current limits are:
    Maximum number of columns in an input or output file = 100
    Maximum number of bytes in a binary TABLE row = 32768
    Maximum number of text characters used for a table row = 12800

Programmer: Jim Torson, U.S.G.S., Flagstaff, AZ

Input ASCII table file name
  (default extension is .dat)

NONE

Output TABLE file name
  (default extension is .tbl)

NONE

Name of output TABLE object

"TABLE"

OBJECT_DATA_TYPE for label

"UNKNOWN"

Whether input file has DATA
  DESCRIPTION info (YES or NO)

YES

Output file mode
  (NEW or UPDATE)

NEW

Length of ASCII text lines

--

Names of table columns

--

Data types for table columns
  (INTEGER, REAL, or CHARACTER)

--

Number of bytes for each output
  binary table column value

4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,	         4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4

Number of array elements in
  each table column

1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,	         1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1

Formats for data values in each
  table column element

--

User comment

" "

ADDITIONAL NOTES:

Parm	Description
FROM	Input ASCII TABLE file name. If the file extension is omitted, then ".dat" will be assumed.
TBLTO	Output binary ISIS TABLE file name. If the file extension is omitted, then ".tbl" will be assumed.
OBJNAM	Name of output TABLE object that is to be created (or updated) in the output binary ISIS TABLE file. If a null string (all blanks) is specified, then "TABLE" will be assumed.
ODTYPE	The value of the OBJECT_DATA_TYPE keyword that will be recorded in the label of the output file when a new file is being created. If a null string (all blanks) is specified, then "UNKNOWN" will be assumed.
DATADESC	Indicates whether the input ASCII file includes a text DATA DESCRIPTION section at the beginning of the file. If DATADESC=YES is specified, then the text DATA DESCRIPTION information at the beginning of the file will be used for determining the format of the ASCII table data. This option is typically used for reading a file that has been created by the "tbl2asc" program. If DATADESC=NO is specified, then the text DATA DESCRIPTION information in the file (if present) will be ignored and the LINLEN, COLUMNS, TYPES, SIZES, ELEMENTS, and FORMATS parameters will be used for determining the format of the ASCII table data.
OMODE	Specifies whether a new output TABLE file is to be created (OMODE=NEW) or an existing file is to be updated (OMODE=UPDATE).
LINLEN	Used only when DATADESC=NO is specified. Gives the line length of the input ASCII table data. If one row of table data fits within one text line, then this can be greater than the actual line lengths. However, if multiple text lines are required to hold one table row, then this must exactly specify the length of the LONGEST line. (Other text lines may be shorter than the longest line.)
COLUMNS	Used only when DATADESC=NO is specified. Lists the names of the table columns. The column names are not case-sensitive, i.e., any lowercase characters are automatically converted to uppercase.
TYPES	Used only when DATADESC=NO is specified. Lists the data types for the table columns. The supported types include INTEGER, REAL, or CHARACTER.
SIZES	Used only when DATADESC=NO is specified. Lists the number of bytes for storing each output table column value. (If a single column contains an array of values, then this specifies the size of a single element of the array.) Note that this refers to the storage sizes for the binary output data, not the width of the input text data, which is specified in the FORMATS parameter values. A size of 4 bytes should normally be used for INTEGER or REAL column TYPES.
ELEMENTS	Used only when DATADESC=NO is specified. Lists the number of array elements in each table column.
FORMATS	Used only when DATADESC=NO is specified. Lists the formats for the data values in each table column in the ASCII file. These are specified in the form used for FORTRAN FORMAT statements.
USERNOTE	Comment from the user. This will be recorded in the ISIS session log file and also in the History entry that is put into the History object of the output file.