JPL
D-10264
The PDS Table Browser
User's
Guide
Version BETA
November
1, 1992
Jet Propulsion
Laboratory
California Institute of Technology
Pasadena, CA
Introduction
The
Planetary Data System (PDS) Table Browser is a utility for validating,
browsing,
and summarizing data that is organized by rows and columns and is
described
by a PDS label file. These data include
PDS Tables, Spectra, and
Series, in both ASCII and binary format. The PDS Table Browser is part of the
PDS
Toolbox of utilities and software systems designed to assist data
producers
in preparing planetary data for archival within the Planetary
Data System.
The PDS Table Browser User's Guide explains the various
uses of the Table
Browser Tool (TBTOOL).
It is meant to serve as a guide for prospective and
experienced
users.
For general release information, see the
"RELEASE_NOTES" file.
For an overview of how PDS tools
handle PDS labels and SFDU
labels, see the "pds_labels.doc"
file.
When you are designing, producing, or using PDS labels and the
PDS Toolbox, you
should always refer to these documents.
. PDS Data Preparation Workbook (DPW), JPL
Document D-7669
. Planetary
Science Data Dictionary (PSDD), JPL Document D-6184
. The PDS Toolbox Overview, JPL Document
D-10263
Before you use the PDS Table Browser, you should test all
your label files
using the PDS Label Verifier, another PDS Toolbox
utility. For more
information
about the PDS Label Verifier, you may reference the following
document:
. PDS Label Verifier User's Guide, Version
1.2, JPL Document D-8923
What is the Table
Browser?
The PDS Table Browser is a tool which provides the ability
to display data from
a table, series, or spectra in a variety of formats
in order to allow the user
to visually verify the accuracy of the PDS
label, and to ``sanity" check the
data values. It is important that the PDS label is
validated since it will be
used by software programs to locate, display,
and manipulate the data
identified by the label.
The Table
Browser allows you to validate labels by:
. Performing ODL Language Checking
PDS
Labels are written using the PDS Object Description Language (ODL). (See
the
PDS Data Preparation Workbook.) ODL
checking detects syntax errors in the
usage of ODL, such as missing quote
marks, invalid characters in names, etc.
. Displaying Tabular Data in a Variety of Formats
The
TBTOOL displays the table data from the requested column in a variety of
formats
(text, binary, hex, and octal), and allows browsing through the table
by
stepping through the tables identified by the label file, stepping
through
the columns of each table, or maneuvering directly to a particular
table or
column.
.
Allowing Dynamic Alteration of Label Keywords
Keywords in the
label that describe the data object can be displayed and
edited. This allows changing label information in
order to immediately see the
effects in the data display.
. Summarizing Columns of Data
A
column of data values can be summarized to obtain minimums, maximums,
averages,
and value counts.
The Table Browser has a simple command line
interface which will operate on any
ASCII computer terminal. You may only verify one label file at a
time, but the
label may point to one or more data objects.
Getting
Started
In order to introduce the Table Browser and to help you
familiarize yourself
with the TBTOOL's functionality and command line
interface, the remainder of
this chapter describes how to start the Table
Browser on your system, and then
gives you one example of how the TBTOOL
can be used.
Starting the Table Browser
Before
starting the Table Browser, copy your PDS label file and associated data
file
or files into the same directory as the TBTOOL. On VMS, UNIX ,and PC
systems, type the following
command:
tbtool | -f
<input-file> |
where <input-file> is the name of the
label file for your table, series, or
spectrum. The filename is optional.
If you do not specify a filename on the
command line, you will be
prompted for one. Note that VMS systems
will not
allow you to provide a filename on the command line unless you
first define a
foreign command:
tbtool :==
``$[directory]tbtool.exe"
where directory is the location of
the Table Browser executable.
Getting Help
On-Line Help
You
may request on-line help at any time during your session by typing the
Help
command, h or ?, at the Table Browser prompt.
PDS TABLE BROWSER> h
These are the commands that can be entered
at the prompt:
? or H --
HELP
E or Q -- EXIT the program
B -- DISPLAY a bit
column
C -- DISPLAY a column
N -- Display the NEXT
table, column, item, or bit column of data
P -- Display the
PREVIOUS table, column, item, or bit column of data
U
-- Move UP through the rows of data in a table
D -- Move DOWN through
the rows of data in a table
F -- Select a LABEL FILE to verify
L
-- Display and edit the KEYWORD VALUES (label) used to display the data
S
-- Display a SUMMARY of the data in a column, item, or bit column
Press RETURN for more, or E to exit
help:
You may see detailed help information for each Table Browser
command by
pressing RETURN at the prompt.
This detailed help is given in the Table
Browser Reference chapter
of this User's Guide.
Contacting the PDS Operator
If
you need information that is not available in this User's Guide or in the
on-line
help, or need to obtain any of the documents referenced here, you may
contact
the PDS Operator at the PDS Central Node in one of the following ways:
. The PDS Help Line: (818) 306-6130
. NSI/DECNET (SPAN): JPLPDS::PDS_OPERATOR
. Internet:
pds_operator@jpl-pds.jpl.nasa.gov
Using the Table
Browser - Example
So that you can begin using the TBTOOL
immediately, the following example will
acquaint you with it. Even though
the following example does not explore every
command of the Table Browser,
if you are experienced with PDS labels and label
software, you may find
that it, plus the contents of the reference sections,
contains more than
enough information for you to use the Table Browser from now
on.
As
you go through the following example, you may want to refer to the Table
Browser
Reference chapter, which explains the commands available.
The
Label File
Assume you have a label file called ``test.lbl" that
describes data organized
in rows and columns and identified as a PDS Table
data object, as shown below:
CCSD3ZF0000100000001NJPL3IF0PDS200000001
= SFDU_LABEL
RECORD_TYPE =
FIXED_LENGTH
RECORD_BYTES
= 202
FILE_RECORDS = 10
TARGET_NAME =
MARS
^TABLE
= "TEST.TAB"
OBJECT = TABLE
NAME = "PLANETARY NOMENCLATURE
GAZETTEER"
INTERCHANGE_FORMAT =
ASCII
ROWS = 10
COLUMNS =
6
ROW_BYTES = 202
DESCRIPTION = "The gazetteer (file:
etc."
OBJECT = COLUMN
NAME
= TARGET_NAME
DATA_TYPE = CHARACTER
START_BYTE =
2
BYTES = 20
FORMAT
= "A20"
UNIT =
"N/A"
DESCRIPTION = "The planet or satellite on
which the feature is
located."
END_OBJECT = COLUMN
OBJECT =
COLUMN
NAME = SEARCH_FEATURE_NAME
DATA_TYPE =
CHARACTER
START_BYTE = 25
BYTES = 50
FORMAT
= "A50"
UNIT =
"N/A"
DESCRIPTION = "The geographical feature
name
etc."
END_OBJECT = COLUMN
OBJECT =
COLUMN
NAME = DIACRITIC_FEATURE_NAME
DATA_TYPE =
CHARACTER
START_BYTE = 78
BYTES = 100
FORMAT
= "A100"
UNIT = "N/A"
DESCRIPTION =
"The geographical feature name
containing standard diacritical information."
END_OBJECT = COLUMN
OBJECT = COLUMN
NAME
= MINIMUM_LATITUDE
DATA_TYPE =
REAL
START_BYTE = 180
BYTES = 7
FORMAT
= "F7.2"
UNIT = DEGREE
DESCRIPTION
= "The minimum_latitude
element
specifies the
southernmost latitude of a spatial area, such
as a map, mosaic, bin, feature, or region."
END_OBJECT = COLUMN
OBJECT
= COLUMN
NAME
= MAXIMUM_LATITUDE
DATA_TYPE =
REAL
START_BYTE = 188
BYTES = 7
FORMAT
= "F7.2"
UNIT =
DEGREE
DESCRIPTION = "The maximum_latitude element
specifies the northernmost latitude of
a spatial area, such
as a
map, mosaic, bin, feature, or region."
END_OBJECT =
COLUMN
OBJECT = COLUMN
NAME
= CENTER_LATITUDE
DATA_TYPE =
REAL
START_BYTE = 196
BYTES = 7
FORMAT = "F7.2"
UNIT = DEGREE
DESCRIPTION
= "The center latitude of the
feature."
END_OBJECT = COLUMN
END_OBJECT = TABLE
END
Does the label file
``test.lbl" correctly identify and describe the data file
``test.tab"?
Running
the TBTOOL
At your system prompt, type the following command to
start the Table Browser
and to load the label ``test.lbl."
>tbtool
test.lbl
Or, you could invoke TBTOOL by simply typing:
>tbtool
in
which case the TBTOOL would prompt you for a filename:
Please enter
the file name: test.lbl
Once a filename has been provided, the
TBTOOL will respond with its startup
message:
Welcome to the
BETA version of the PDS Table Browser
Parsing the label file: test.lbl
Fetching the label
information
File Conversion
If you are
running the TBTOOL on a VMS system and your data file consists of
VMS
variable-length records, the TBTOOL will inform you and prompt you to
convert
the format of the data file to an accessible format.
Your data file is in VMS variable-length
record format.
It must be
converted to Stream_LF format in order to view the data.
Is it ok to proceed with the
conversion?
Type y at the prompt.
PDS TABLE BROWSER> y
The new data file will be called
ZTEST.TAB Converting the file . .
.
The Table Keywords Menu
Once the label file
is loaded, the Table Browser will display the Table
Keywords Menu. This menu lists the keywords associated with
the first table
object identified in the label. In ``test.lbl," there is only one table
identified.
1) Table name = PLANETARY
NOMENCLATURE GAZETTEER TABLE
2)
Rows = 10
3) Columns = 6
4) Row bytes =
202
5) Interchange format =
ASCII
6) Data file = ZTEST.TAB
7)
Data byte location = 1
PDS TABLE BROWSER>
We now know the name of the
table, the number of rows and columns and row bytes
in the table, its
interchange format, its filename, and the table's location in
the data
file.
Displaying Data in a Column
As our
first action in browsing the table, let's look at the first column of
data,
by typing the Column command, a c, at the PDS TABLE BROWSER prompt.
PDS TABLE BROWSER> c
------------------------------------------------------------------------------
TARGET_NAME COLUMN (CHARACTER-20)
1) MARS
2)
"MARS
3) ."MARS
4) 0."MARS
5)
20."MARS
6) .70."MARS
7)
4.60."MARS
8) 45.00."MARS
9)
36.50."MARS
10) 31.30."MARS
(Column 1 of
6) (Item 1 of 1) (0 rows left)
PDS TABLE BROWSER>
Altering
the Table Keyword Values
We can see immediately that one of the
keywords in our label does not
accurately describe the format of our data
file. We can now edit the table
keyword
values by returning to the Table Keywords Menu by typing the Label
Table
command, lt, at the prompt.
PDS TABLE BROWSER> lt
Keywords
for table 1 of 1:
1) Table name = PLANETARY NOMENCLATURE GAZETTEER
TABLE
2) Rows = 10
3)
Columns = 6
4) Row bytes =
202
5) Row prefix bytes = 0
6)
Row suffix bytes = 0
7) Interchange format = ASCII
8) Data file =
ZTEST.TAB
9)
Data byte location = 1
PDS TABLE BROWSER>
Let's add 1 to the value of Row
bytes and then see the effects.
Type 4 at the prompt, since this is
the number of the keyword we would like to
change.
PDS TABLE BROWSER> 4
Type 203
at the prompt for Row bytes.
Row bytes : 203
Keywords for table 1 of 1:
1) Table name = PLANETARY
NOMENCLATURE GAZETTEER TABLE
2) Rows = 10
3) Columns =
6
4) Row bytes =
203
5) Row prefix bytes = 0
6)
Row suffix bytes = 0
7) Interchange format = ASCII
8) Data file =
ZTEST.TAB
9)
Data byte location = 1
PDS TABLE BROWSER>
Let's look at the first column
again by typing c at the prompt.
PDS TABLE BROWSER> c
------------------------------------------------------------------------------
TARGET_NAME COLUMN (CHARACTER-20)
1) MARS
2)
MARS
3) MARS
4) MARS
5)
MARS
6) MARS
7) MARS
8)
MARS
9) MARS
10) MARS
(Column 1 of
6) (Item 1 of 1) (0 rows left)
The first column is
now accessed accurately.
Browsing the Columns of a
Table
Let's now browse
through the columns by typing the Next command, an n, at the
prompt
through all 6 columns.
PDS
TABLE BROWSER> n
------------------------------------------------------------------------------
SEARCH_FEATURE_NAME COLUMN (CHARACTER-50)
1) ABALOS
UNDAE
2) ABUS VALLIS
3) ACHAR
4) ACHERON CATENA
5) ACHERON
FOSSAE
6) ACIDALIA PLANITIA
7) ACIDALIUM, MARE
8) ADAMAS
LABYRINTHUS
9) ADAMS
10) AEOLIS
(Column 2 of 6) (Item 1 of 1) (0 rows left)
PDS TABLE BROWSER> n
------------------------------------------------------------------------------
DIACRITIC_FEATURE_NAME COLUMN (CHARACTER-100)
1) Abalos
Undae
2) Abus Vallis
3) Achar
4) Acheron Catena
5) Acheron Fossae
6) Acidalia
Planitia
7) Acidalium, Mare
8) Adamas
Labyrinthus
9) Adams
10) Aeolis
(Column 3 of 6) (Item 1 of 1) (0 rows left)
PDS TABLE BROWSER> n
------------------------------------------------------------------------------
MINIMUM_LATITUDE COLUMN (REAL-7)
1) 80.36
2)
-7.37
3) 45.70
4) 33.78
5)
32.39
6) 49.66
7) 45.00
8)
31.40
9) 31.30
10) -5.00
(Column 4 of
6) (Item 1 of 1) (0 rows left)
PDS TABLE BROWSER>
Changing
the Mode of Display
It is important to remember that the TBTOOL
reacts to commands dependent on
where you are in the table and which mode
of display you are currently using.
During the previous list of commands,
the Next command, an n, applied to the
display of column information. In the next series of commands, you will
see
how you can now switch the mode of display back to the keywords in the
label.
To see the Column Keywords from the label, type the Label
Column command, an
lc, at the prompt.
PDS TABLE BROWSER> lc
Keywords for Column 4 of 6:
1) Name = MINIMUM_LATITUDE COLUMN
2)
Displayed =
Yes
3) Display Format = TEXT
4) Data type = REAL
5) Bytes = 7
6) Start byte = 180
7) Items = 1
8) Item Offset = 7
9) Has Bit Columns = No
PDS TABLE BROWSER>
Now that
you have switched to this mode of display, the Next (n) command will
display
the label keywords for the next column in the table.
PDS TABLE BROWSER> n
Keywords for Column 5 of 6:
1) Name
= MAXIMUM_LATITUDE
COLUMN
2)
Displayed =
Yes
3) Display Format =
TEXT
4) Data type = REAL
5) Bytes = 7
6) Start byte = 188
7) Items = 1
8) Item Offset = 7
9) Has Bit Columns = No
PDS TABLE BROWSER>
To see the
data from the table for this particular column, type the Column (c)
command
at the prompt.
PDS TABLE
BROWSER> c
------------------------------------------------------------------------------
MAXIMUM_LATITUDE COLUMN (REAL-7)
1) 82.64
2)
-5.42
3) 45.70
4) 42.39
5)
33.16
6) 56.22
7) 45.00
8)
41.74
9) 31.32
10) -5.00
(Column 5 of 6) (Item 1 of 1) (0 rows
left)
PDS TABLE BROWSER>
The
Next (n) command will now display the values from the table for the next
column
since you are now using that mode of display.
PDS TABLE BROWSER> n
------------------------------------------------------------------------------
CENTER_LATITUDE COLUMN (REAL-7)
1) 81.00
2)
-6.30
3) 45.70
4) 38.20
5)
38.70
6) 54.60
7) 45.00
8)
36.50
9) 31.30
10) -5.00
(Column 6 of 6) (Item 1 of 1) (0 rows
left)
PDS TABLE BROWSER>
Displaying a Particular Column
To
display a column directly, type the number of the column you wish
displayed
before the Column (c) command.,
PDS TABLE BROWSER> 4c
------------------------------------------------------------------------------
MINIMUM_LATITUDE COLUMN (REAL-7)
1) 80.36
2)
-7.37
3) 45.70
4) 33.78
5)
32.39
6) 49.66
7) 45.00
8)
31.40
9) 31.30
10) -5.00
(Column 4 of
6) (Item 1 of 1) (0 rows left)
PDS TABLE BROWSER>
The
Summary Display
The TBTOOL also provides a utility to summarize the
information relevant to the
current column. The summary display will provide minimum and maximum
values,
along with an average, if the data in the column is numeric, or a
frequency
analysis if the data is text based and less than 80 characters
wide.
To display a summary of the current column, type the Summary command,
an s, at
the prompt.
PDS TABLE BROWSER> s
------------------------------------------------------------------------------
MINIMUM_LATITUDE COLUMN (REAL-7)
Minimum:
-7.370000e+00
Maximum:
8.036000e+01
Approximate
Average: 3.372200e+01
(Column 4 of 6) (Item 1 of 1)
Now typing the Next
(n) command will give you a summary of the next column.
PDS TABLE BROWSER> n
------------------------------------------------------------------------------
MAXIMUM_LATITUDE COLUMN (REAL-7)
Minimum:
-5.420000e+00
Maximum:
8.264000e+01
Approximate Average: 3.677500e+01
(Column 5 of 6) (Item 1 of 1)
PDS TABLE BROWSER> n
------------------------------------------------------------------------------
CENTER_LATITUDE COLUMN (REAL-7)
Minimum:
-6.300000e+00
Maximum:
8.100000e+01
Approximate Average: 3.597000e+01
(Column 6 of 6) (Item 1 of 1)
Exiting
the Table Browser
To exit the TBTOOL, type the Exit command, an e or
a q, at the prompt.
PDS
TABLE BROWSER> e
What the Table Browser Does
The
PDS Table Browser, or TBTOOL, helps the data producer in visually
verifiying
the accuracy of a PDS label in describing PDS TABLE, SERIES, and
SPECTRUM
data objects. The TBTOOL provides this
ability by providing the
functions described below.
ODL
Syntax Checking
The TBTOOL begins its task by detecting errors in
the syntax of the ``KEYWORD =
VALUE" statements, Object Description
Language (ODL), of the PDS Label.
The
language checking procedure does not have knowledge of the Data
Dictionary,
therefore, it does not know what each value should be, only
how it should look.
If there are
syntax errors in the label, the TBTOOL will inform you and give
you the
option of displaying the error messages.
These error messages are
documented in the PDS Label Verifier
User's Guide.
Although you may sometimes be able to continue with
TBTOOL if the ODL checking
errors do not interfere with the interpretation
of the display keywords, it is
recommended that if you do receive ODL
syntax errors that you test the label
with the PDS Label Verifier and
eliminate errors before proceeding.
Label Keywords and
Display Formats
Keywords in the label that describe the data object
can be displayed and
dynamically edited.
This allows changing label information in order to
immediately see its
effects in the data display. This is
accomplished by using
the Label (l) command to display and edit keyword
values. (These edits are
dynamic. The actual label file is NOT updated.)
Four
menus within the TBTOOL provide the ability to change the format of the
data
display.
File Keywords Menu
The Label File
(lf) command displays the File Keywords Menu.
PDS TABLE BROWSER> lf
Keywords for the data file:
1) Record type = FIXED LENGTH
2) Record bytes = 202
3) File records = 10
4) Blocking type = Unknown
5) Block bytes = Unknown
6) Block records = Unknown
PDS
TABLE BROWSER>
Typing the number of the keyword you wish to
change allows you to change the
value for that keyword.
The keywords
in the File Keywords Menu are:
. Record
type - the record type of the data
file, FIXED, STREAM, or
VARIABLE. Changing this value has no effect.
. Record bytes - the number of bytes (used per row when neither Bytes
nor Row bytes are present in a table).
Changing this value will affect
how the beginning of each row is calculated. More specifically:
Used to calculate the start of the data
when the location is specified
in
records rather than bytes. (See Data
byte location, Table Keywords Menu.)
Used to calculate the number of bytes of padding to skip
between rows
when blocking type
is UNSPANNED. (See Blocking
type.)
. File records - the number of records in the file. This value is not
used by the TBTOOL currently. Changing its value has no effect.
. Blocking type - Some data files require
that records always
start on
block boundaries. These are called
SPANNED records and may
have
some padding at the end of each record to fill out the block.
The Record bytes, Block bytes, and Block
records keywords are used to
calculate
the number of bytes of padding that must be skipped when
locating the start of the next row of
data. This calculation is only
performed when the Blocking type keyword
is explicitly set to SPANNED.
The
default is UNSPANNED
. Block
bytes - The number of bytes in a
block. This is only used when
a data file requires that records always
begin on block boundaries.
. Block
records - The number of blocks in the
data file.
Table Keywords Menu
The Label
Table (lt) command displays the Table Keywords Menu.
PDS TABLE BROWSER> lt
Keywords for table 1 of 1:
1) Table name = PLANETARY
NOMENCLATURE GAZETTEER TABLE
2)
Rows =
10
3) Columns =
6
4) Row bytes = 202
5)
Row prefix bytes = 0
6)
Row suffix bytes = 0
7) Interchange format = ASCII
8)
Data file =
ztest.tab
9)
Data byte location = 1
PDS TABLE BROWSER>
Typing the
number of the keyword you wish to change allows you to change the
value
for that keyword.
The keywords in the Table Keywords Menu are:
. Table name - The name of the table as
specified in the label. Changing
this value has no effect.
. Rows - The number of rows in the table. Changing this value
will affect the number of rows
displayed. If the value is less
than
the actual number of rows,
then all rows will not be displayed.
If
the value is greater
than the actual number of rows, and data exists
between the actual last row and the end-of-file, data beyond
the
actual last row of the
table will be displayed.
. Columns
- The number of columns in the table.
Changing this
value has
no effect since the TBTOOL calculates the number of columns
from the actual data.
. Row bytes - The number of bytes in each
row. Changing this
value affects the accessing and locating
of columns. This value
should include carriage returns and line
feeds that separate records.
. Row
prefix bytes - The number of bytes of prefix information
that the software needs to skip over at
the start of each row in order
to
find the start of the data.
. Row
suffix bytes - The number of bytes suffix information that
the software must skip over at the end of
each row in order to find
the
start of the data.
. Interchange
format - The interchange format of the table.
When you select to change this value, the following interchange
format
menu will be
displayed:
PDS TABLE
BROWSER> 5
Interchange format (Must be one of the
following) :
1)
ASCII 2)
BINARY
:
If the interchange format is ASCII, then
the data type of each
column is
informational only. If the interchange
format is BINARY,
then the
TBTOOL will try to interpret the binary data values based on
the data type of the applicable
column.
. Data file - The
data file being described by the label.
. Data byte location - This depends on how the data file is
specified in the label. There are three ways of indicating the
name
of the data file and the
location of the data in that file in a PDS
label.
The
file name by itself:
^TABLE =
``test.dat"
In this
case, the software will assume that the data begins at the first byte
in the data file (data byte location =
1).
The file name
accompanied by a starting byte location:
^TABLE =
(``test.dat", 135 <bytes>)
In this case, the software now knows that the data begins at
byte 135 in the
data file (data
byte location = 135).
The
file name accompanied by a record number:
^TABLE =
(``test.dat", 87)
In
this case, the software assumes that the number 87 is the
number of the record where the data
begins. It must perform a
calculation to determine the location of
the data in bytes:
data byte location = 1 + (<record bytes> * (<record_number>
- 1))
Column Keywords Menu
The Label Column
(lc) command displays the Column Keywords Menu.
PDS TABLE BROWSER> lc
Keywords for Column 1 of 6:
1)
Name =
TARGET_NAME COLUMN
2)
Displayed =
Yes
3) Display Format =
TEXT
4) Data type = CHARACTER
5) Bytes = 20
6) Start byte = 2
7) Items =
1
8) Item Offset = 20
9) Has Bit Columns = No
PDS TABLE
BROWSER>
Typing the number of the keyword you wish to change
allows you to change the
value for that keyword.
The keywords
in the Column Keywords Menu are:
. Name
- The name of the column as specified in the label.
. Displayed - Whether or not you wish to
display this particular
column
during the TBTOOL session. Changing
this value to No will
result in
Next (n) and Previous (p) commands skipping over this
column.
. Display Format - Indicates how the data
will be interpreted
for
display. When you elect to change this
keyword value, you will
receive
the following submenu:
PDS
TABLE BROWSER> 3
Display format (Must be one of the
following) :
1) BINARY 2)
HEX
3) OCTAL 4) TEXT :
. Data Type - The data type of the
column. Note that changing
this value affects the display of BINARY
data only, not ASCII data.
When
you elect to change this keyword value, the following submenu
will be displayed:
Data
type (Must be one of the following)
:
1) ASCII COMPLEX 2) ASCII INTEGER
3) ASCII REAL 4) BOOLEAN
5) CHARACTER 6) COMPLEX
7) DATE 8) FLOAT
9) IBM COMPLEX 10)
IBM INTEGER
11) IBM REAL 12)
IBM UNSIGNED INTEGER
13) IEEE COMPLEX 14)
IEEE REAL
15) INTEGER 16)
LSB BIT STRING
17) LSB IEEE COMPLEX 18) LSB IEEE
REAL
19) LSB INTEGER 20)
LSB UNSIGNED INTEGER
21) MAC COMPLEX 22)
MAC INTEGER
23) MAC REAL 24)
MAC UNSIGNED INTEGER
25) MSB BIT STRING 26) MSB
IEEE COMPLEX
27) MSB IEEE REAL 28)
MSB INTEGER
29) MSB UNSIGNED INTEGER 30)
PC COMPLEX
31) PC INTEGER 32)
PC REAL
33) PC UNSIGNED INTEGER 34)
REAL
35) SUN COMPLEX
36) SUN INTEGER
37)
SUN REAL 38) SUN UNSIGNED INTEGER
39)
TIME 40) UNSIGNED INTEGER
41)
VAX COMPLEX 42) VAX DOUBLE
43) VAX INTEGER 44)
VAX REAL
45) VAX UNSIGNED INTEGER 46) VAXG COMPLEX
47)
VAXG REAL
Definitions of
these data types are provided in the PDS Data Preparation
Workbook (DPW).
. Bytes - The number of bytes in the column. Changing this
value will affect how many bytes are fetched and processed as a
column. The effect of the change will depend on
whether the data
value is ASCII
or BINARY.
ASCII - The
number of bytes displayed will be affected; e.g.,
4 characters may be displayed rather than 2.
BINARY - The data displayed will be
interpreted using a
different
number of bytes; e.g., the data value may be interpreted as
a 4-byte integer rather than a 2-byte
integer
. Start byte - The
start byte of the column. Changing
this
value will affect the byte
location of the column within a row of
data.
. Items - If the value is greater than one,
this description is
used as the
label for the number of column items indicated. (See
``About
Items" below.)
. Item
offset - Between items, there may be delimiters or
padding. This value
indicates the number of bytes used for this
purpose.
. Has
Bit Columns - This ``Yes" or ``No" value indicates whether
or not the column object has bit
columns. These are columns made
up
of a certain number of bits
contained within a column. If the
value
is ``Yes," you can
use the Bit-Column (b) command to view the
individual bit-columns.
Changing this value has no effect: TBTOOL
uses the label itself as an indicator of whether or not there
are bit
column objects.
Bit
Column Keywords Menu
The Label Bit Column (lb) command displays the
Bit-Column Keywords Menu.
PDS TABLE BROWSER> lb
Keywords for Bit Column 1 of 6:
1) Name = WAVEFORM_SAMPLES BIT_COLUMN
2) Displayed = Yes
3) Display Format = TEXT
4) Data type = UNSIGNED_INTEGER
5) Bits = 4
6) Start bit = 1
7) Items = 2
8) Item Offset = 1
9) Has Bit Columns = No
PDS TABLE
BROWSER>
The Bit Column keywords are essentially the same as the
Column keywords, except
when dealing with Bit Columns, the keywords refer
to bits rather than bytes.
Also, the ``Has Bit Columns" keyword is always
set to ``No."
Summarizing Column Data
To
help you verify the data in the data file, the TBTOOL provides a summary
capability. Using the Summary (s) command, you can
summarize the values in a
column of data and display the maximum, minimum,
and average values, in a
numeric column, or a frequency analysis, how many
times did a certain character
value appear, for a character column.
A
detailed description of the Summary command is given in the Table Browser
Reference
chapter.
About Items
Items are a shorthand
method for describing mutltiple columns, located
contiguously, all having
the same structure. For example, a
thousand columns,
each of which contains a wavelength, can be represented
by a single COLUMN
object with ITEMS = 1000 and a sampling parameter of
wavelength. Item offset
is the
amount of padding in each item that must be skipped to locate the start
of
the next item.
About ``Old" PDS Labels
In
older PDS labels, COLUMNs looked like:
OBJECT = VOLUME_ID
START_BYTE = 7
etc.
rather than:
OBJECT
= COLUMN
NAME =
VOLUME_ID
START_BYTE = 7
etc.
TBTOOL
is not able to use these labels. If you
need to use such a label, the
PDS Add Columns to Table (addcols) utility
can convert them to the new format.
However, the utility does not function
for SERIES and SPECTRUM objects at this
time.
Table
Browser Reference
The following is a command reference for the PDS
Table Browser (TBTOOL), i.e.,
commands that can be typed at the PDS TABLE
BROWSER> prompt. This section
is
organized by command type.
Table Browser Command
Summary
PDS TABLE
BROWSER> h
These are the
commands that can be entered at the prompt:
? or H -- HELP
E or Q -- EXIT the program
B
-- DISPLAY a bit column
C
-- DISPLAY a column
N
-- Display the NEXT table,
column, or bit column of data
P -- Display the PREVIOUS table, column, or bit column of data
U
-- Move UP through the rows of
data in a table
D --
Move DOWN through the rows of data in a table
F -- Select a LABEL FILE to
verify.
L --
Display and edit the KEYWORD VALUES used to display the data
S
-- Display a SUMMARY of the data
in a column or bit column
Press
RETURN for more, or E to exit help:
Label File
Selection
The File (f)
command parses a label file and locates any table and column
objects. You may include a file name after the F, or
be prompted for one. For
example,
entering F test.lbl, causes the file test.lbl to be parsed. You must
use this command first in order
to view the data.
Data Display Commands
b
-- Display a bit column
c --
Display a column
These commands control the display of the
data.
The C command displays a column, while the B command displays
a bit column
within a column.
Entering a number before or after either of these commands
displays
the data in that column or bit column.
For example, entering 5C
displays the data in column five. Entering 3B would display the data in
the third bit column inside the
current column, not the third bit column in the
label.
Navigation
Commands
u --
Move up through the rows of data in a table
d --
Move down through the rows of data in a table
n
-- Display the next column of
data
p --
Display the previous column of data
The u, d, n, and p commands allow you to move through the rows
and columns
of data in a table.
They behave like arrow keys.
Here is how they relate to
each other:
u
^
p < > n
v
d
Row
Navigation
The commands u and d move up and down through the
rows. Entering a number
before or
after the u or d commands causes the data to scroll up or down by
that
many rows. For instance, d15 moves down
15 rows in a table. If you want
to
jump directly to a particular row in the table, just enter the row number
and
press return.
Bit Column, Column, and Table
Navigation
The commands p and n move left and right through the
tables, columns, or bit
columns depending on what is currently
displayed. If you are looking at
table
information and type n, you will see the next table. If you are looking at a
column and type
n, you will see the next column. And
finally, if you are
looking at a bit column and type n, you will see the
next bit column. The p
command
displays the previous table, column, or bit column in the same way.
You
may switch between table, column, and bit column display by typing nt to
move
to the next table, nc to move to the next column, or nb to move to the
next bit column. pt, pc, and pb move back through tables,
columns, or bit
columns in the same way.
The t, c, and b
options will skip over any items in the columns or bit columns.
If you want to see each item, type ni to set
the item display.
Finally, entering a number before or after the p
or n commands moves that many
tables, columns, or bit columns to the left
or right. For instance, n4 moves
4
columns to the right.
Label Keyword Display
Commands
l -- Shows the label information used to display the data
The
l command can show the table, column, or bit column label information
used
to display the data, plus other information which is used to control
the
appearance of the data.
Entering lf shows the keywords that
relate to the entire file, lt shows the
keywords extracted from the TABLE,
SERIES, or SPECTRUM object, lc shows the
column object keywords, and lb
shows the bit column keywords. Once the
menu of
keywords is displayed, you may modify any of them by typing the
number to the
left of the keyword.
You will either be prompted for input or be presented
with a list
of standard values to select from.
In addition to the keywords
extracted from the label, there are two values
displayed with the column and
bit column information that control the display
of the data. These are ``Displayed" and ``Display Format." The first allows
you to decide which
columns you want to see at any particular time. The second
determines how the data is to be interpreted for
display. The bytes of data
can be
interpreted and displayed in BINARY,
HEX, or OCTAL format, or in the
format of the particular data type
specified in the label (TEXT format).
Summarize
Command
s -- Summarize
the data in a column, column item, or bit column
The s command
summarizes the data values in a column, item, or bit column by
displaying
minima, maxima, averages, or value counts of the data values in the
column
or bit column. If you are looking
at a column (or column item) and
you type s, you will receive a summary of
the data in the column. If you are
looking at a bit column and you
type s, you will receive a summary of the data
in the current bit
column.
The type of summary you will receives depends on the data
type of the column
(see the l (Label) command). Numeric data types (INTEGER, UNSIGNED INTEGER,
and REAL)
will result in a summary that includes minimum, maximum, and average
values. CHARACTER types will result in a summary
that includes only value
counts: a table of data values and the number of
times each occurred in the
column.
DATE and TIME data types will result in a summary that includes
minimum
and maximum values, plus an occurrence count table for values that did
not
appear to be dates or times. BOOLEAN data types will result in occurence
counts.
Summaries
only make sense if the column display format is TEXT (see l command).
Occurrence
tables which exceed 500 entries will be truncated. Columns which
are too wide (greater than 60 bytes for
CHARACTER columns, greater than 4 bytes
for INTEGERs, or greater than 8
bytes for REALs) cannot be summarized.
Exit
Commands
Typing e or q at the Table Browser prompt exits the
TBTOOL. TBTOOL deletes any
temporary
files it has created. The TBTOOL does
not delete the converted data
file, if a conversion took place during your
session, nor does it update the
original label file.
Table
Browser Messages
This section will describe the most common messages
issued by the Table
Browser. ODL
syntax error messages are listed in the PDS Label Verifier User's
Guide.
Column
Display Error
The column cannot be displayed
Something
has gone seriously wrong: some piece of
information the software
needs to display the data was missing, or the
file could not be opened, or the
ODL syntax errors in the label were too
severe, or there aren't any columns
or
bit columns in the label, etc.
Data Filename
Error
The name of the data file is invalid or missing
Missing
pointer to a data file in the label (e.g. no keyword like
^TABLE = ``file.dat"
was
found in the label), or the ODL syntax of the file pointer keyword was
incorrect.
Data
File Open Error
Unable to open the data file
There's a
serious problem here. The data file
can't be opened for reading.
This sometimes results because values in PDS
labels which are unquoted, or
converted to upper case, and filenames on
Unix systems are cases sensitive.
Use double quotes around filenames in
PDS labels.
File Format Error
Your data file is in
VMS variable-length record format.
It must be converted to Stream_LF
format in order to view the data.
Is it ok to proceed with the
conversion?
On VAX/VMS systems, data files sometimes get converted
to VARIABLE length
record format
(e.g. there are no record terminators, just a two byte field at
the start
of each record that contains the record's size). This often happens
when the data file is transferred from a
UNIX or DOS system to the VAX via
KERMIT or some other transfer
program. The software cannot seek to a
specific
byte in these files, so they must be converted to STREAM_LF
format before the
data can be displayed.
If you respond with "Y", the software will convert your
data
file for you.
CAUTION: THIS
CREATES A COPY OF YOUR DATA FILE. IF
THIS FILE IS LARGE, YOU
MAY HAVE A PROBLEM.
File Open
Error
Unable to open the file: <fname>
The label
file name you provided does not exist or can't be opened.
Incorrect
Values Summary Warning
WARNING: Computed values may be
incorrect.
Something went wrong during the summary: overflow,
underflow, or non-numeric
characters in a numeric field.
Large
Occurrence Summary Warning
Occurrence table is large (%ld
rows).
Do you want to see it (Y/N)?
There are many, many unique
values in this column and it may take quite a
while to page through them
all. Are you sure you want to see the
summary?
Missing Bits
The bit column's BITS field
is invalid or missing
``BITS" is a required keyword in a
BIT_COLUMN object. Either this keyword
was
not found in a BIT_COLUMN or there were ODL syntax errors that prevented
the
value from being read. The
software can't display a bit column without knowing
how many bits to
extract.
Missing Bytes
The column's BYTES field is
invalid or missing
``BYTES" is a required keyword in a COLUMN
object. Either this keyword was
not
found in a COLUMN or there were ODL syntax errors that prevented the
value from
being read. The
software can't display a column without knowing how many bytes
to
extract.
Missing Row_Bytes
The table's ROW_BYTES
field is invalid or missing
There wasn't a ROW_BYTES keyword for the
table and there was no RECORD_BYTES
keyword in the label to use
instead. One or both of these must be
present in
order for the software to know how long a row is supposed to
be.
Missing Start_Bytes
The column's START_BYTES
field is invalid or missing
``START_BYTES" is a required
keyword in a COLUMN object. Either this
keyword
was not found in a COLUMN or there were ODL syntax errors that
prevented the
value from being read.
The software can't display a column without knowing
where the
column begins.
Missing Start_Bit
The bit column's
START_BIT field is invalid or missing
``START_BIT" is a
required keyword in a BIT_COLUMN object.
Either this keyword
was not found in a BIT_COLUMN or there were ODL
syntax errors that prevented
the value from being read. The software can't display a bit column
without
knowing where the column begins.
No Columns
There
aren't any columns to display
You have chosen the C or B option to
display a column or bit column, but
there
aren't any of these objects in the table.
No
Filename Given
You must specify a label file to process.
You
chose the F option, but did not provide the name of a file to open.
No
More Tables
You've reached the end of the table list
You
tried to advance to the next table using n or nt, but there are no more
tables
in the label to view. You may use the P
command to view a previous
table.
No Previous
Tables
You've reached the beginning of the table list
You
tried to back up to the previous table using p or pt, but there are no
more
tables to move backwards through.
You may use the N command to view the next
table.
Number
of Columns Warning
WARNING:
The number of COLUMN objects found in the file does not
agree with the information
in the label.
This lets you know that the COLUMNS keyword in the
table does not agree with
the number of columns actually found when the
label was parsed. Either this
number
is wrong, or there were ODL syntax errors in the label.
ODL
Syntax Errors Warning
There were problems parsing the label
file.
Would you like to see the ODL syntax errors? (Enter Y or N)
There were ODL
syntax errors in your label file. You
may view these errors and
decide whether or not they are too severe to
proceed.
Occurrence Summary Warning
WARNING:
Occurrence table exceeded maximum size.
All values will not be counted in the
table.
There are too many unique values in the CHARACTER or BOOLEAN
column you have
chosen to summarize.
This should only occur if your table is really big.
Overflow
Summary Warning
WARNING: Overflow occurred during computation of
average.
The values in this column exceed the capacity of the
machine.
Suspicious Numeric Column Warning
WARNING:
Numeric column contains suspicious characters.
The data type says
that this is a numeric column, but there are non-numeric
characters
present in some rows.
Unable to Display Summary
Unable
to display a summary for this data type and/or column size.
Columns
cannot be summarized under these conditions:
- If the size of a
column does not fit with the acceptable sizes allowed for a
particluar
data type (e.g. MSB_INTEGER data types come in three flavors, one,
two,
and four bytes. Any other size is
considered an error).
- The data type is UNKNOWN
- The
data type is CHARACTER and it's more than sixty bytes long
- The
ability to read and interpret a particular data type has not been
implemented
in the software
- It's a VAXG_FLOAT type. This requires that the entire program be compiled
and linked
differently and therefore cannot be summarized.
Underflow
Summary Warning
WARNING: Underflow occurred during computation of
average.
The numeric values in this column exceed the capacity of
the machine.