JPL D-10264
The PDS Table Browser (TBTOOL)
User's Guide
Version 1.7
March 15, 2006
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
K –- DISPLAY a
container
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
K --
DISPLAY a container
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.
k –- Display a container
The K command displays the first column in a
container. By default,
entering K will bring you to the first container.
Entering a number
before or after the command displays that particular
container. For
example, entering 4K or K4 displays the first column in
container four.
The container name is displayed at the top right corner
of the screen
where it says "A COLUMN x of y" where A = the
CONTAINER name, x = what
column is being displayed, and y = the number of columns
in that
container. The current repetition is also shown when
displaying
container columns
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.