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.