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.