.\" Manual page for the PDS Table Verifier (pdstv) Utility
.\"
.\" 13 Apr 2001, acr: created from 'atv' and 'btv' merge and expansion
.\" 14 Jan 2002, acr: Update for new batch mode.
.\" 14 Mar 2002, acr: Added '-t' option
.\" 01 Feb 2003, acr: Updated for recent tweaking
.\" 06 Dec 2006, acr: Updated for new "-v" option
.\"
.TH PDSTV L "06 December 2006"
.SH NAME
pdstv \- PDS/SBN table verifier tool
.SH SYNOPSIS
.B pdstv
.RB "[\| " \-v " \|] "
.RB "[\| " \-b " \|] [\| " \-f " \|] "
.RB "[\| " \-t " \|] [\| " \-d 
.I directory
.RB " \|] [\| " \-o 
.I report
.B " \|]"
.I label
.SH DESCRIPTION
.LP
.B pdstv
performs two verification tasks. First, it verifies the logical
content of a PDS label file describing one or more 
TABLE-type objects. 
Second, it uses the object definitions in the label to read the 
associated data file, making sure that all values fit the parameters given
in the label.
Label syntax should be verified (using lvtool, sbnlv, etc.) prior to 
running
.B pdstv.
The routine may be run in batch mode, in which it produces a simplified 
list of errors and no informational tables, by using the "\-b" option.
.LP
.B pdstv
can handle any TABLE-type object (TABLE, SPECTRUM, SERIES, etc.), in both
ASCII and binary formats. It can handle CONTAINER objects, nested CONTAINERs,
and tables with ROW_PREFIX_BYTES and ROW_SUFFIX_BYTES.
PDS labels may be attached or detached.
.LP
The Small Bodies Node label style sheet is used for checking label syntax.
In some cases this is more restrictive than the general PDS guidelines.
.SH OPTIONS
.TP
.B \-v
Version number.  Prints the version information and exits.  Any other options
are ignored.
.TP
.B \-b
Batch mode. When invoked in batch mode, the output to the report file will
be a series of lines, one for each error. Each error line has four fields,
separated by a colon character. The first field contains "L" if the error
applies to the label, or "T" if the error was discovered while reading 
the table data. The second field is the record number (in either the label
or data file, as appropriate). The third field is the error code number.
The fourth field is a human-readable error message string.
At the end of the run a single line containing the string "OK" is output
to indicate the end of messages.
.TP
.BI \-d " directory"
This option provides the name of the directory, other than the current default
directory, in which to search for the data file(s).
This option is provided because
the \^TABLE pointer does not usually include a path.  
If the label file is not found in the default path, this path
name is prepended to the given file name and a second attempt is made to find 
it in this directory.
.TP
.B \-f
Flag blank fields.  When this option is included fields in ASCII 
table objects are checked
to see if all characters are blank, and flagged if this is found to be true.
The usual case is to ignore blank numeric fields (which are read as zero);
blank date and time fields are also ignored.
.TP
.BI \-o " report"
Use this option to direct the output report to a file.  
The default is to send the report to stdout. 
Any error messages from the program itself are directed to stderr.
.TP
.B \-t
Include processing time in report file. The CPU seconds used as calculated
by calls to the "clock" function is reported as total seconds. 
Used internally for testing and debugging.
.SH REPORT FILE
.LP
A human-readable report file is generated when running in command-line mode.
This is the default mode (see the \-b option for batch mode).
The report file is structured as follows:
.LP
The top section lists labelling errors discovered in the top-level keywords,
before any object definition.
This is followed by a 3-part breakdown for each table object found 
in the label. The first part lists labelling errors in the object definition
in the same format as used for the top-level keywords.
The second part lists errors encountered trying to read the data file
using the label definitions.
The third section summarizes various parameters for each column, including
maximum and minimum values, occurences of flag values like INVALID_CONSTANT,
and a total count of read problems. 
For ASCII tables this is then followed by two tables which 
tally the number of non-blank and special (i.e., non-printing) characters
found as a function of the location within the table row (i.e., prefix and
suffix bytes are not included in the tallies).
.LP
Errors are flagged by record number and column.
Numeric fields are checked against any stated MAXIMUM/MINIMUM, 
DERIVED_MAXIMUM/MINIMUM, and VALID_MAXIMUM/MINIMUM values, 
ignoring values equal to any of the figurative constant values
(INVALID_CONSTANT, MISSING_CONSTANT and NOT_APPLICABLE_CONSTANT), 
where these are included in the label.
Fields with types of DATE and TIME are checked against the PDS required format
for those data types.
Character fields are checked for extrema, flag values, and non-printable 
characters.
.LP
In reading ASCII data,
attempts are made to convert all numeric fields to the appropriate integer or
real form.  If a FORMAT is specified, alignment (decimal for real, 
right-justified for integer) is also checked.
.\"
.SH NOTES
.LP
Fields with types of DATE or TIME which are truncated on the right
at valid points less 
than the full field width are passed without comment.
.LP
.B pdstv
will note when the table record size (ROW_PREFIX_BYTES + ROW_BYTES + 
ROW_SUFFIX_BYTES) and RECORD_BYTES do not contain the same value,
but this is not necessarily wrong.
.LP
Math on real number fields is necessarily imprecise.  
Although all numerical calculations and
comparisons are done in double precision, 
there is a 1.e-06 tolerance
included in all checks for equality between real numbers not equal to 0.0.
Therefore, it is possible that a real value may be mistaken for a 
MISSING_CONSTANT or INVALID_CONSTANT data flag if the flag values are within 
1.e-06 of valid data values.
Consequently, it is highly recommended that any INVALID_CONSTANT or 
MISSING_CONSTANT flag 
values be as far away from valid data values as possible.
.LP
Any COLUMN object identified as containing spare bytes (by having the 
name "SPARE" or a name ending with "_SPARE") will be checked to make sure
it has a DATA_TYPE of "CHARACTER", but will be otherwise ignored.
Specifially, it will not show up in the summary value tables in the 
report listing, nor will the contents of the SPARE column be checked 
for non-printing characters.