==========================================================================

                        Jet Propulsion Laboratory

                          Planetary Data System

                               PDS Toolbox

 

 

 

                                 TAB2LAB

 

                      The PDS Table to Label Generator

 

1.        Introduction

                         2.  Building TAB2LAB      

                         3.  Running TAB2LAB       

                         4.  Getting Help

                         5.  Using TAB2LAB - Examples

                         6.  How TAB2LAB Works     

                         6.1  The Description File

                         6.2  The Skeleton Label

                         6.3  Naming Output Labels

                         6.4  Special Cases

                         6.5  Limitations

                         7.  Command Reference

                         7.1  -b (Label Base Name)        

                         7.2  -c (Label Base Column)      

                         7.3  -d (Description File)       

                         7.4  -f (Data Files)             

                         7.5  -p (Enable Prompting)       

                         7.6  -r (Enable Record Formatting)

                         7.7  -s (Skeleton File Name)     

                         7.8  -t (Enable Blank Trimming)  

                         7.9  -u (Display Usage)          

==========================================================================

 

1.  Introduction

 

     The PDS Table to Label Generator (TAB2LAB) is a tool which will

     help you to generate a set of Object Description Language (ODL)

     labels, assuming that the entire set of labels is identical

     except for the values of the keywords, and that you have an ASCII

     table containing the values which vary from label to label.  It

     is very common, for instance, to have a volume index table which

     contains all the values which vary from label to label on a data

     volume, and yet all the labels basically look the same.

 

     TAB2LAB requires three inputs:

 

         o  An ASCII table containing data values to be inserted

            into the labels being generated.

 

         o  A label file for the ASCII table, called the table

            description file, which describes the rows and columns in

            the table of data, using a standard PDS TABLE description.

 

         o  A "skeleton" label which will act as a model for all

            the product labels to be generated.

 

     Given these inputs, TAB2LAB can generate one label for each row

     of data in the ASCII table.  You may generate one label file at a

     time or a large number of files all at once.

 

     This tool has a simple command line interface that will operate

     on any ASCII terminal.

 

     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 and producing PDS labels, you should

     always refer to two other documents: the PDS Data Preparation

     Workbook, and the Planetary Science Data Dictionary.  These will

     provide you with PDS definitions and information about label

     design.

 

     This utility has been tested on:

   

         A Sun SPARCstation running Sun OS 4.1 and Sun C compiler

         A VAX 11/780 running VMS 5.2 and VAX C Compiler

         An IBM AT running MS-DOS 5.0 and Borland C(++) Version 2.0

 

     The Table to Label Generator was originally developed at the

     University of Colorado, by personnel associated with the

     Atmospheres Node of the PDS. 

 

2.  Building TAB2LAB

 

     The typical toolbox delivery looks like this:

 

     [top-level directory]

        |

        +-- README (or README.TXT in VMS deliveries)

        |

        +-- Makefile (or MAKEFILE.COM in VMS deliveries)

        |

        +-- [bin]

        |

        +-- [doc]

        |

        +-- [lib]

        |

        +-- [source]

 

     If your set-up looks like this, then follow these steps:

 

         SunOS                             VMS

 

     1.  cd to the directory               set default to the directory

         containing Makefile               containing makefile.com

 

     2.  Type:  make                       Type:  @makefile

 

     That's it.  The "bin" subdirectory should contain "tab2lab.exe",

     the "lib" subdirectory should contain "lablib.olb" and

     "odlc.olb".

 

 

3.  Running TAB2LAB

 

     Running TAB2LAB on a UNIX system is simplicity itself:

 

         bin/tab2lab -s <skeleton> -d <table-desc> -np

 

     This instructs the program to use file <skeleton> as the

     skeleton, (prototype) for the labels to be generated,

     <table-desc> as the file describing the ASCII table of data from

     which label values will be extracted, and not to prompt (-np) for

     additional options.

 

     On VMS systems, you will first have to define a foreign command:

 

         tab2lab :== "$disk:[directory]tab2lab.exe"

 

     where "disk" and "directory" define the full path of the "bin"

     directory, then type

 

         tab2lab -s <skeleton> -d <table-desc> -np

 

     On Unix systems, if you use a wildcard in a file name, you may

     have to enclose it in double quotation marks.

 

 

 

4.  Getting Help

 

     If you need information that is not available in this User's

     Guide or need to obtain any of the other documents referenced

     here, you may contact the PDS Operator at the PDS Central Node in

     one of the following ways:

 

         o  The PDS Help Line: (818) 306-6130

 

         o  NSI/DECNET (SPAN): JPLPDS::PDS_OPERATOR

 

         o  Internet: pds_operator@jpl-pds.jpl.nasa.gov

 

 

 

5.  Using TAB2LAB - Example

 

     Suppose you want to generate a series of labels that look like

     the skeleton below, where the values that will differ from label

     to label are those for the following keywords:

 

        SPACECRAFT_NAME

        MISSION_PHASE_NAME

        TARGET_NAME

        NATIVE_START_TIME

        START_TIME

        EARTH_RECEIVED_START_TIME

        INSTRUMENT_NAME

        SECTION_ID

        ^WAVEFORM_HEADER_TABLE

 

     Other than the values of these keywords, all the resulting labels

     need to be the same.

 

     ----------------------------------------------------------------

                     Skeleton Label "pwsskel.lbl"

     ----------------------------------------------------------------

      CCSD3ZF0000100000001NJPL3IF0PDS200000001

      RECORD_TYPE                     = FIXED_LENGTH

      RECORD_BYTES                    = 1024

      FILE_RECORDS                    = 801

      ^WAVEFORM_HEADER_TABLE          = ("XXXXXXX.XXX",1)

 

      /* Observation description */

      DATA_SET_ID                     = 'VG2-N-PWS-2-WFRM-V1.0'

      SPACECRAFT_NAME                = XXXXXXXXXX

      NATIVE_START_TIME               = 0.0

      EARTH_RECEIVED_START_TIME       = 2000-01-01T01:00:00.00Z

      START_TIME                      = 2000-01-01T01:00:00.00Z

      MISSION_PHASE_NAME              = XXXXXXXXXX

      TARGET_NAME                     = XXXXXXXXXX

 

      /* Instrument description */

      INSTRUMENT_NAME                 = XXXXXXXXXX

      SECTION_ID                      = XXXXXXXXXX

 

      /* Object descriptions */

 

      OBJECT                          = WAVEFORM_HEADER_TABLE

          BYTES                          = 1024

          ^STRUCTURE                     = "EDRHDR.FMT"

      END_OBJECT

 

      END

     ----------------------------------------------------------------

 

 

     The label above can be used as the skeleton for generating the

     labels you want.  To use TAB2LAB, you also need an ASCII table of

     values to be inserted into each label as it is generated.

     Finally, you must create a table description file for the table

     of data.  In this case, the table description looks as follows:

 

     ----------------------------------------------------------------

                   Table Description Label "pwstab.lbl"

     ----------------------------------------------------------------

      CCSD3ZF0000100000001NJPL3IF0PDS200000001                            

      RECORD_TYPE                    = FIXED_LENGTH                       

      RECORD_BYTES                   = 181                                

      FILE_RECORDS                   = 237                                

      ^TABLE                         = "PWSINDEX.TAB"                     

                                                                           

      OBJECT                           = TABLE                            

          INTERCHANGE_FORMAT             = ASCII                          

          ROWS                           = 237                            

          ROW_BYTES                      = 181                            

          COLUMNS                        = 12                             

                                                                          

          OBJECT                           = COLUMN                       

              NAME                           = SPACECRAFT_NAME            

              DATA_TYPE                      = CHARACTER                  

              START_BYTE                     = 2                           

              BYTES                          = 9                          

          END_OBJECT                       = COLUMN                       

                                                                          

          OBJECT                           = COLUMN                       

              NAME                           = MISSION_PHASE_NAME         

              DATA_TYPE                      = CHARACTER                  

              START_BYTE                     = 14                          

              BYTES                          = 17                         

          END_OBJECT                       = COLUMN                       

                                                                          

          OBJECT                           = COLUMN                       

              NAME                           = TARGET_NAME                

              DATA_TYPE                      = CHARACTER                  

              START_BYTE                     = 34                         

              BYTES                          = 8                          

          END_OBJECT                       = COLUMN                       

                                                                           

          OBJECT                           = COLUMN                       

              NAME                           = NATIVE_START_TIME          

              DATA_TYPE                      = REAL                       

              START_BYTE                     = 44                         

              BYTES                          = 8                          

          END_OBJECT                       = COLUMN                       

                                                                           

          OBJECT                           = COLUMN                       

              NAME                           = START_TIME                 

              DATA_TYPE                      = TIME                        

              START_BYTE                     = 54                         

              BYTES                          = 20                         

          END_OBJECT                       = COLUMN                       

                                                                           

          OBJECT                           = COLUMN                       

              NAME                           = EARTH_RECEIVED_START_TIME  

              DATA_TYPE                      = TIME                       

              START_BYTE                     = 77                         

              BYTES                          = 20                         

          END_OBJECT                       = COLUMN                        

                                                                          

          OBJECT                           = COLUMN                       

              NAME                           = INSTRUMENT_NAME            

              DATA_TYPE                      = CHARACTER                  

              START_BYTE                     = 100                        

              BYTES                          = 20                         

          END_OBJECT                       = COLUMN                        

                                                                          

          OBJECT                           = COLUMN                       

              NAME                           = SECTION_ID                 

              DATA_TYPE                      = CHARACTER                  

              START_BYTE                     = 123                        

              BYTES                          = 8                          

          END_OBJECT                       = COLUMN                       

                                                                          

          OBJECT                           = COLUMN                       

              NAME                           = WAVEFORM_VOLUME_ID         

              DATA_TYPE                      = CHARACTER                  

              START_BYTE                     = 134                        

              BYTES                          = 8                          

          END_OBJECT                       = COLUMN                       

                                                                          

          OBJECT                           = COLUMN                       

              NAME                           = WAVEFORM_HEADER_TABLE      

              DATA_TYPE                      = CHARACTER                  

              START_BYTE                     = 145                        

              BYTES                          = 34                          

          END_OBJECT                       = COLUMN                       

                                                                          

      END_OBJECT                       = TABLE                            

                                                                           

      END                                                                 

     ----------------------------------------------------------------

 

 

     This description file will tell the program where to find the

     values it needs within the actual table of data located in file

     "PWSINDEX.TAB" (which is pointed to by the pointer keyword

     "^TABLE" in the description file).  Note that there can actually

     be more columns in your table of data than there are fields to be

     filled in the skeleton label.  This is not a problem; the extra

     fields will simply be ignored.

 

     Finally, you will need the actual table of data. (Only the first

     four lines are shown here, even though the table actually has 237

     rows.)

 

     ----------------------------------------------------------------

                        Data File "PWSINDEX.TAB"

     ----------------------------------------------------------------

"VOYAGER_2","NEPTUNE_ENCOUNTER","NEPTUNE ",9003.13,"1989-06-08T13:35:00Z",\

"1989-06-06T14:16:57Z","PLASMA_WAVE_RECEIVER","WFRM","VG_0013 ",\

"[PWS.NEPTUNE.C0900XXX]C0900313.DAT"

 

"VOYAGER_2","NEPTUNE_ENCOUNTER","NEPTUNE ",9061.13,"1989-06-09T15:15:15Z",\

"1989-06-08T12:17:12Z","PLASMA_WAVE_RECEIVER","WFRM","VG_0013 ",\

"[PWS.NEPTUNE.C0906XXX]C0906113.DAT"

 

"VOYAGER_2","NEPTUNE_ENCOUNTER","NEPTUNE ",9092.28,"1989-06-10T16:02:45Z",\

"1989-06-09T13:18:00Z","PLASMA_WAVE_RECEIVER","WFRM","VG_0013 ",\

"[PWS.NEPTUNE.C0909XXX]C0909228.DAT"

 

"VOYAGER_2","NEPTUNE_ENCOUNTER","NEPTUNE ",9123.43,"1989-06-14T08:40:58Z",\

"1989-06-10T14:40:56Z","PLASMA_WAVE_RECEIVER","WFRM","VG_0013 ",\

"[PWS.NEPTUNE.C0912XXX]C0912343.DAT"

 

 etc...

     ----------------------------------------------------------------

 

 

     Now you are ready to generate 237 labels, as follows.  To run

     TAB2LAB in prompt mode, enter:

 

         tab2lab

 

     The program will prompt you for the names of the skeleton label,

     the table description label, and other options, as follows:

 

     ----------------------------------------------------------------

                       Prompts Issued by TAB2LAB

     ----------------------------------------------------------------

     TAB2LAB - Generate PDS Labels From Table - Version 2.1

 

     TAB2LAB requires a correct PDS label for the table of data values

     to be inserted into the skeleton label. If this program does not work

     correctly, try verifying your data label with the PDS Table Browser.

 

     Enter name of file containing the skeleton label: pwsskel.lbl

 

     Enter name of file containing the table description label: pwstab.lbl

 

     Trim trailing blanks from character fields (y/n)? y

 

     Use file format information in label? (y/n)? n

     ----------------------------------------------------------------

 

 

     For more information about blank trimming and file formatting,

     refer to the "Command Reference" chapter.

 

     The program will now list the columns it found in the table and

     show which ones it was able to map to keywords in your skeleton

     label.  It will prompt you for the column which should be used

     for naming the label files to be generated.  If you enter a

     column number, the program will assume that the data column

     contains a file name of the form "filename.ext."  To create the

     name of the label file, TAB2LAB will strip the extension from the

     file name it finds in the data table and add extension ".lbl"

 

     The program will ask you which rows of the table you want to use

     to generate labels.  It will then generate the labels you asked

     for.

 

     ----------------------------------------------------------------

                       Prompts Issued by TAB2LAB

     ----------------------------------------------------------------

                            Information on Table Columns

 

Col #     Column Name              Strt  Len Itms  Off Type Target Object/Group

  1      SPACECRAFT_NAME             2    9    1    0    3    SKELETON_LABEL

  2      MISSION_PHASE_NAME         14   17    1    0    3    SKELETON_LABEL

  3      TARGET_NAME                34    8    1    0    3    SKELETON_LABEL

  4      NATIVE_START_TIME          44    8    1    0    2    SKELETON_LABEL

  5      START_TIME                 54   20    1    0    7    SKELETON_LABEL

  6      EARTH_RECEIVED_START_TIME  77   20    1    0    7    SKELETON_LABEL

  7      INSTRUMENT_NAME           100   20    1    0    3    SKELETON_LABEL

  8      SECTION_ID                123    8    1    0    3    SKELETON_LABEL

  9      WAVEFORM_VOLUME_ID        134    8    1    0    0    *NONE*

  10     WAVEFORM_HEADER_TABLE     145   34    1    0    4    SKELETON_LABEL

 

     Enter number of column containing label file base name (default is 0): 10

 

     Enter number of first row to be processed [1..237]: 1

 

     Enter number of last row to be processed [1..237]: 237

 

     >>> Writing row 1 to label [PWS.NEPTUNE.C0900XXX]C0900313.lbl

     >>> Writing row 2 to label [PWS.NEPTUNE.C0906XXX]C0906113.lbl

     >>> Writing row 3 to label [PWS.NEPTUNE.C0909XXX]C0909228.lbl

     >>> Writing row 4 to label [PWS.NEPTUNE.C0912XXX]C0912343.lbl

     (etc...)

     ----------------------------------------------------------------

 

 

 

     In this case, the string in column 10 of the table was used to

     create the label file names, and all 237 labels were generated.

     Once the labels are generated, the program will ask you which

     rows of the table you want to process next.  If you enter 0 or

     your local end-of-file character at the "Enter number of first

     row . . ." prompt, the program will exit.

 

     The output files (e.g., "[PWS.NEPTUNE.C0906XXX]C0906113.lbl,"

     generated from the second row of the table) will look as follows:

 

     ----------------------------------------------------------------

            Output File "[PWS.NEPTUNE.C0906XXX]C0906113.lbl"

     ----------------------------------------------------------------

      CCSD3ZF0000100000001NJPL3IF0PDS200000001                           

                                                                          

      RECORD_TYPE          = FIXED_LENGTH                                

      RECORD_BYTES         = 1024                                        

      FILE_RECORDS         = 801                                          

      ^WAVEFORM_HEADER_TABLE = ("[PWS.NEPTUNE.C0906XXX]C0906113.DAT", 1) 

                                                                         

      /* Observation description */                                      

                                                                          

      DATA_SET_ID          = 'VG2-N-PWS-2-WFRM-V1.0'                     

      SPACECRAFT_NAME      = VOYAGER_2                                   

      NATIVE_START_TIME    = 9061.13                                      

      EARTH_RECEIVED_START_TIME = 1989-06-08T12:17:12.00Z                

      START_TIME           = 1989-06-09T15:15:15.00Z                     

      MISSION_PHASE_NAME   = NEPTUNE_ENCOUNTER                           

      TARGET_NAME          = NEPTUNE                                     

                                                                         

      /* Instrument description */                                       

                                                                          

      INSTRUMENT_NAME      = PLASMA_WAVE_RECEIVER                        

      SECTION_ID           = WFRM                                        

                                                                          

      /* Object descriptions */                                          

                                                                         

      OBJECT                 = WAVEFORM_HEADER_TABLE                     

          BYTES                = 1024                                    

          ^STRUCTURE           = "EDRHDR.FMT"                            

      END_OBJECT             = WAVEFORM_HEADER_TABLE                     

                                                                          

      END                                                                

     ----------------------------------------------------------------

 

 

6.  How TAB2LAB Works     

 

     In order to use TAB2LAB, you must define your table or data file

     using an ODL label and a PDS standard TABLE object, in addition

     to creating a skeleton label which will serve as a model for the

     labels you want to generate.  The complete PDS labelling standard

     cannot be described here, but this chapter provides some hints

     for creating your description file and skeleton label.  More

     information about PDS labels and PDS standard objects can be

     found in the PDS Data Preparation Workbook and the Planetary

     Science Data Dictionary.

 

 

6.1  The Description File

 

     The table description file used by TAB2LAB uses a PDS standard

     TABLE object to describe the data file from which label values

     are to be extracted.  A "table" is a set of data values that are

     organized into rows and columns.  TAB2LAB creates one output

     label from each row of data in a table.

 

     It is critical that the description file be correct.  If the byte

     locations and counts in the description file are wrong, the

     values placed into the labels being generated will be wrong.  The

     Label Generators have no ability to detect errors of this type.

     If you wish to validate the description file, you should use the

     PDS Table Browser.

 

     A PDS TABLE object begins with an OBJECT = TABLE statement and

     ends with an END_OBJECT = TABLE statement.  In addition, a ^TABLE

     = "filename" statement is also included at the top of the

     description file, to indicate the name of the file that actually

     contains the tabular data. 

 

     The TABLE object must include the following keywords:

 

         o  COLUMNS, which is the number of COLUMN objects nested

            inside the TABLE object.

 

         o  ROWS, which is the number of times the data records are

            repeated (or 1, in the case of FILE2LAB).

 

         o  ROW_BYTES, which is the number of bytes in an each data

            record, or row, including all quotes, blanks, commas, line

            feeds, carriage returns, etc. For FILE2LAB, in which you

            are simply pretending that your data file is a table with

            one long row, just set ROW_BYTES large enough to include

            the last data field you are extracting from the data file.

 

         o  INTERCHANGE_FORMAT, which must have value ASCII.

 

     The TABLE object contains COLUMN objects.  A COLUMN object begins

     with an OBJECT = COLUMN statement and ends with END_OBJECT =

     COLUMN.  If you are creating a description file that will be used

     only by these tools, then all the bytes in the row do not have to

     be accounted for by COLUMNs, and some data fields may be

     described by two COLUMN objects with different names, in order to

     use them more than once.

 

     A COLUMN must contain the following keywords:

 

         o  NAME, which is used to identify the column and match it

            to a keyword in the skeleton label.  This is the most

            important aspect of the description file. Every time

            TAB2LAB or FILE2LAB encounters a COLUMN object in the

            description file, it attempts to match the NAME to a

            keyword in the skeleton label.

 

         o  START_BYTE, which indicates the starting byte of the

            data field within each row of the table.

 

         o  BYTES, which indicates the maximum length of the data

            field.

 

         o  DATA_TYPE, which is included in each COLUMN because PDS

            standards require it even though the keyword is not used

            by TAB2LAB or FILE2LAB. Give it the value INTEGER, REAL,

            UNSIGNED_INTEGER, TIME, DATE, or CHARACTER.

 

     The START_BYTE of each COLUMN should be the start byte of the

     data field, not the location of any quotation mark or delimiter

     preceding it.  Thus, in our TAB2LAB example in the previous

     chapter, the first COLUMN object in the table description file

     has a START_BYTE of 2. The BYTES keyword should be the total

     length of the data field, not including any quotation marks or

     delimiters between fields.

 

     PDS ASCII tables are usually delimited by commas, and character

     fields are quoted.  However, TAB2LAB does not require these

     things.  You can use a non-delimited table.  However, the columns

     must be regular in format.  The following table, for instance,

     cannot be used, because the columns are not regular:

 

     ----------------------------------------------------------------

                     Improper Table Format for TAB2LAB

     ----------------------------------------------------------------

      76, Jupiter, 1979, Voyager 2, Red<LF>

      92, Saturn, 1980, Voyager 2, Red<LF>

      8, Saturn, 1980, Voyager 2, Blue<LF>

      140, Neptune, 1989, Voyager 2, Green<LF>

     ----------------------------------------------------------------

 

 

To be useable, the table must look as follows:

 

     ----------------------------------------------------------------

                      Proper Table Format for TAB2LAB

     ----------------------------------------------------------------

      76 , Jupiter, 1979, Voyager 2, Red  <LF>

      92 , Saturn , 1980, Voyager 2, Red  <LF>

      8  , Saturn , 1980, Voyager 2, Blue <LF>

      140, Neptune, 1989, Voyager 2, Green<LF>

     ----------------------------------------------------------------

 

 

     You will also notice the following lines at the top of our

     example description files:

 

     ----------------------------------------------------------------

                         Additional PDS Keywords

     ----------------------------------------------------------------

      CCSD3ZF0000100000001NJPL3IF0PDS200000001    

      RECORD_TYPE                    = FIXED_LENGTH

      RECORD_BYTES                   = 17280      

      FILE_RECORDS                   = 1          

     ----------------------------------------------------------------

 

 

     These keywords are required by the PDS labelling standards.  If

     you are not going to use your description file for any purpose

     other than label generation, you can leave these lines out.  If

     you intend use the file on a data volume that must conform to PDS

     standards, then you should refer to the documents listed in the

     introduction to this chapter for more information regarding the

     keywords above.  The Label Generators, however, do not require

     them.

 

 

6.2  The Skeleton Label

 

     The skeleton label can contain any keywords and objects you need

     to describe the data products you are labelling.  If you don't

     know how to design a PDS label for your data products, you should

     contact the PDS for help.  The Label Generators will not design

     your labels for you; they will only generate them once you have

     created the skeleton.

 

     Whenever a keyword in the skeleton matches the NAME of a COLUMN

     object in the description file, then that keyword's value is

     marked for replacement in the skeleton label.  The Label

     Generators will extract the data described by the COLUMN object

     from the table or data file, assign the extracted value to the

     associated keyword in the skeleton, and write the new output

     label.

 

     All keywords in your skeleton label must have values.  It is not

     acceptable, for instance, to do this:

 

     ----------------------------------------------------------------

                        Improper Skeleton Label

     ----------------------------------------------------------------

      OBJECT          = IMAGE

          LINES       =

          SAMPLES     =

          SAMPLE_BITS = 8

          SAMPLE_TYPE =

      END_OBJECT      = IMAGE

     ----------------------------------------------------------------

 

 

     Instead, you must supply dummy values for all values to be

     replaced. The Label Generators do not care what values you use,

     as long as they have the correct format.  It may be wise to use

     values you can recognize as dummy values:

    

     ----------------------------------------------------------------

                         Proper Skeleton Label

     ----------------------------------------------------------------

      OBJECT          = IMAGE

          LINES       = 999

          SAMPLES     = 999

          SAMPLE_BITS = 8

          SAMPLE_TYPE = XXXXXXXX

      END_OBJECT      = IMAGE

 

 

     The important thing about the dummy values you use is their data

     type and format.  If the data value to be inserted for LINES is

     an integer, then the dummy value should be an integer.  If you

     want the value in single quotes or double quotes in the final

     output label, you should use such a value in the skeleton:

 

         SPACECRAFT_NAME = 'XXXXXXX'

 

     It is important to remember quote marks where they are needed,

     based on what type of values are to be inserted in the output

     labels.  If quote marks were left out of the statement above, and

     then one of the Label Generators extracted the value "VOYAGER 2"

     from your data file and inserted it, the result would be

 

         SPACECRAFT_NAME = VOYAGER 2

 

     which is incorrect.  Unquoted values must start with a letter,

     and must contain only letters, numbers, and underscores.

 

     Note that dummy values for dates and times are rather limited by

     the Object Description Language (ODL) standard for date/time

     values.  You cannot use 0000-00-00 as a dummy date value, for

     instance, because it will be flagged as an invalid date.

 

 

6.3  Naming Output Labels

 

     TAB2LAB will either:

 

         o  Name output labels automatically, given a base name

            that you have provided at the "Enter label file base name"

            prompt or using the -b command line option.

 

         o  Name output files by taking the name from one of the

            columns in the table of data.  If you provide a column

            number, either at the "Enter column number" prompt or

            using the -c command line option, the value extracted from

            the column is assumed to be a file name.  The extension is

            removed and replaced with ".lbl" in order to create the

            current output file name.

 

            If you enter 0 at the "Enter column number" prompt, then

            TAB2LAB defaults to the previous behavior: automatic file

            naming.

 

     Be careful that you do not already have files which will be

     overwritten by these programs.  Check your directory for files

     with extension ".lbl" which may become victims.  The Label

     Generators will not warn you!

 

 

6.4  Special Cases

 

         o  If you need to use the same data value to replace the

            value of two different keywords in your skeleton label,

            then define two COLUMN objects in your description file,

            both pointing to the same data field.  Give one the NAME

            of the first keyword and one the NAME of the second.

 

         o  If your skeleton label contains the same keyword in two

            places -- for instance, contains the keyword ROWS in two

            separate objects -- then define two COLUMN objects called

            ROWS in your description.  The Label Generators will match

            the first instance of ROWS in the skeleton to the first

            COLUMN called ROWS in the description file, and so on.

 

         o  If your skeleton label contains the same keyword in two

            places -- for instance, contains the keyword ROWS in two

            separate objects, one called LINE_PREFIX_TABLE and one

            called ENGINEERING_TABLE -- and you only want to replace

            the second one, define a COLUMN object in your description

            file as follows:

 

     ----------------------------------------------------------------

               Replacing a Keyword in a Particular Object

     ----------------------------------------------------------------

         OBJECT          = COLUMN

             NAME        = 'ENGINEERING_TABLE.ROWS'

             DATA_TYPE   = INTEGER

             START_BYTE  = 10

             BYTES       = 3

         END_OBJECT      = COLUMN

     ----------------------------------------------------------------

 

 

            The Label Generators will now know which occurrence of

            ROWS you wish to replace.

 

         o  If your data or table file contains the value

            "UNKNOWN", "N/A", or "UNK:" in a field that is supposed to

            be a date or time, the Label Generators will still

            recognize the value as a date or time and will place the

            value UNKNOWN or 'N/A' (but not 'UNK:') in the output

            label.

 

         o  If the value of a keyword in the skeleton label is a

            set or sequence, e.g., SPACECRAFT_ID = (VG1, VG2) or

            SPACECRAFT_ID = {VG1, VG2}, and the entire value needs to

            be replaced by the Label Generator in order to create an

            output label, a COLUMN object that contains multiple items

            must be defined in the description file, as follows:

 

     ----------------------------------------------------------------

                        Replacing a Set or Sequence

     ----------------------------------------------------------------

         OBJECT            = COLUMN

             NAME          = SPACECRAFT_ID

             DATA_TYPE     = CHARACTER

             START_BYTE    = 1

             BYTES         = 3

             ITEMS         = 2

             ITEM_OFFSET   = 4

         END_OBJECT        = COLUMN

     ----------------------------------------------------------------

 

 

            This describes a field in the table which contains 2

            values, each 3 bytes long, with a space between them (thus

            the offset of 4).  The actual table or data file might

            then contain something like this in its SPACECRAFT_ID

            field:

 

                VG1 VG2

 

            If there is no space between the items, ITEM_OFFSET is the

            same as BYTES.

 

         o  Fixed length label files can be generated.  See the -r

            command line option in the "Command Reference" chapter.

 

 

6.5  Limitations

 

         o  The Label Generators will not warn you if you are

            overwriting an existing label file.

 

         o  The Label Generators cannot process binary data files.

 

         o  If you have two occurrences of ROWS in the same object,

            and you want to replace only the value of the second one,

            you cannot.  Duplicate keywords in the same object are

            illegal under PDS standards.

 

         o  Due to software oddities, the values "UNKNOWN" and

            "N/A" for dates and date/times can only be processed by

            temporarily storing these values as dates with years 1700

            and 2200, respectively, and then converting them back to

            "UNKNOWN" and "N/A" before the output label is written.

            Any "genuine" dates with these years will also be

            modified.  A warning is displayed when these values are

            encountered.

 

         o  If the value of a keyword in the skeleton label is a

            set or sequence and you do not provide an ITEMS field in

            the COLUMN object that maps to it, the first value in the

            set or sequence will be replaced and all other values will

            be thrown away.  File pointer keywords (keywords that are

            preceded by a caret (^) are an exception to this rule, so

            that record and byte location indicators can be

            maintained.

 

         o  In a pointer keyword whose value is both a file name

            and a location, e,g.

 

                ^TABLE = ("filename.dat", 2)

 

            you cannot replace the location value, only the filename.

 

         o  You cannot replace partial values, i.e., change only

            the year in a date/time value in the skeleton label.  The

            entire value is always replaced, with the exception for

            pointer keywords mentioned above.

 

         o  Unquoted values and values enclosed by single quotes in

            the skeleton label will be converted to upper case in the

            output labels.  If you do not want case conversion to

            occur, use double quotation marks.

 

         o  A "Z" will be appended to local times when they are

            written to the output labels, because according to PDS

            standards, all local times are assumed to be Zulu.

 

 

 

7.  Command Reference

 

 

7.1  -b (Label Base Name)

 

     Used by: TAB2LAB Default: -nb

 

     If you wish TAB2LAB to name your output label files

     automatically, you must provide a base name using the -b <name>

     command line option, or by entering it at the "Enter label file

     base name" prompt.  TAB2LAB will then take the base name, add a

     number, and then add a ".lbl" extension to create each label file

     name.  For instance, if you start the program as follows:

 

         tab2lab -b pws ....

 

     The label files will be named pws1.lbl, pws2.lbl, pws3.lbl, etc,

     where the number appended to the file name is the row number in

     the data table from which label values are being extracted.

 

     If you enter the command option -c 0 then you must provide a

     label file base name.

 

 

7.2  -c (Label Base Column)

 

     Used by: TAB2LAB Default: -nc

 

     If you want TAB2LAB to use one of the columns in your data table

     when creating output label file names, you need to use the -c

     <column> command line option, or enter the column number at the

     "Enter number of column containing label file base name" prompt.

     (For more information, see "Naming Output Files" in the previous

     chapter.)

 

     For instance, if the fourth column of your table contains values

     of the form:

 

        IMG0xxxx.dat

 

     Then you can specify -c 4 as a command line option, and the label

     file names will be of the form:

 

         IMG0xxxx.lbl

 

     Entering -c 0 is the same as specifying automatic file naming,

     and you will have to supply a label file base name.

 

 

7.3  -d (Description File)

 

     Used by: TAB2LAB and FILE2LAB Default: None

 

     You must specify the name of the description file for the table

     or data file(s) from which the label values are to be extracted.

     You may do this either using the -d <file name> command line

     option, or by entering the description file name when prompted

     for it.

 

 

7.4  -f (Data Files)

 

     Used by: FILE2LAB Default: None

 

     You must specify the file(s) from which FILE2LAB is supposed to

     extract label values when generating output labels.  You may do

     this either using the -f <file name> command line option or by

     supplying the file specification when prompted for it.  Wild

     cards may be used. However, on Unix systems, wildcarded values

     generally have to be enclosed in double quotation marks.

 

 

7.5  -p (Enable Prompting)

 

     Used by: TAB2LAB and FILE2LAB Default: -p

 

     In order to make the Label Generators useable in both interactive

     and batch (background) mode, the -p and -np switches can be used

     on the command line.  If -p (the default) is used, then:

 

         o  The program will prompt for missing arguments.

 

         o  Syntax errors in the skeleton and description files

            will be reported and the user given a chance to continue

            or not continue.

 

         o  Column/Field summaries will be displayed.

 

     If -np is used, then:

 

         o  Missing required arguments will cause the program to

            stop.

 

         o  Missing optional arguments will assume their default

            states.

 

         o  Errors in the skeleton and description files will cause

            the program to stop.

 

         o  Column/Field summaries will not be displayed.

 

     If you want the Label Generators to run in background or script

     mode without interrupting you, you must use -np.  However, if you

     use -np with TAB2LAB, then all the rows in the data table will be

     used to create labels.  You will not have the options of

     generating only some of the labels.

 

 

7.6  -r (Enable Record Formatting)

 

     Used by: TAB2LAB and FILE2LAB Default: -nr

 

     The Label Generators can generate output labels using several

     record formats.  The default record format, used when the -nr

     command line option is specified, is a stream format consistent

     with the computing environment being used.

 

     If -r is used, then the values of the RECORD_TYPE and

     RECORD_BYTES keywords in the output label will be examined, and

     the output label will be formatted accordingly.  Available record

     types are:

 

         o  STREAM: Records will be written in stream format, with

            each label statement terminated by the local end-of-line

            character: line-feed, carriage-return, or the

            carriage-return/line-feed pair.

 

         o  FIXED_LENGTH: Fixed length records will be written,

            using the value of RECORD_BYTES as the record length.

            Each label statement will be terminated with a

            carriage-return/line-feed pair, and the label statements

            will be packed into fixed length records.  The whole label

            will be padded with blanks at the end, in order to fill

            out the last record.

 

         o  VARIABLE_LENGTH: The option is available only on VMS.

            Variable length records will be written using the VMS

            variable length record format and carriage return carriage

            control.

 

     You can also specify this option at the "Use file format

     information in label" prompt.

 

 

7.7  -s (Skeleton File Name)

 

     Used by: TAB2LAB and FILE2LAB Default: None

 

     You must specify the skeleton label from which the output labels

     are to be created.  You may do this using either the -s <file

     name> command line option, or by entering the skeleton file name

     when prompted for it.

 

 

7.8  -t (Enable Blank Trimming)

 

     Used by: TAB2LAB and FILE2LAB Default: -nt

 

     With the exception of values used for file pointers, blanks found

     in values extracted from the data file will be maintained when

     transferred to the output label.  For instance, if you have the

     following table for use by TAB2LAB:

 

     ----------------------------------------------------------------

                        Table Containing Blanks

     ----------------------------------------------------------------

      76 , Jupiter, 1979, Voyager 2, Red  <LF>

      92 , Saturn , 1980, Voyager 2, Red  <LF>

      8  , Saturn , 1980, Voyager 2, Blue <LF>

      140, Neptune, 1989, Voyager 2, Green<LF>

     ----------------------------------------------------------------

 

     and the second column is to be used to provide values for the

     following keyword in the skeleton label:

 

         TARGET_NAME = "XXXX"

 

     then the result in the label generated from row 2 of this table

     will be:

 

         TARGET_NAME = "SATURN "

 

     with an extra blank in the value, unless the -t option is used,

     because the TARGET_NAME COLUMN was, by necessity, defined with

     BYTES = 7 in the table description file.  You can also specify

     this option by answering "y" at the "Trim blanks from character

     fields" prompt.

 

 

7.9  -u (Display Usage)

 

     Used by: TAB2LAB and FILE2LAB Default: -nu

 

     Specifying -u on the command line will display a list of

     available command line options.  All other command line options

     will be ignored, and the program will stop after the usage text

     has been displayed.