UNIX-Based Setup

This section details the environment setup for UNIX-based machines. The preferred method is to specify the shell script, Validate, on the command-line. Setting the PATH environment variable to the location of the script, enables the shell script to be executed from any location on the user's machine.

The following command demonstrates how to set the PATH environment variable, by appending to its current setting:

% setenv PATH ${PATH}:$HOME/validate-0.3.0/bin
        

The tool can now be executed via the shell script as demonstrated in the following example:

% Validate <targets> <command-line arguments>
        

Additional methods for setting up a UNIX-based environment can be found in the UNIX Setup Options section. If viewing this document in PDF form, see the appendix for details.

Windows Setup

This section details the environment setup for Windows machines. The preferred method is to specify the batch file, Validate.bat, on the command-line. Setting the PATH environment variable to the location of the file, enables the batch file to be executed from any location on the user's machine.

The following command demonstrates how to set the PATH environment variable, by appending to its current setting:

C:\> set PATH = %PATH%;C:\validate-0.3.0\bin
        

The tool can now be executed via the batch file as demonstrated in the following example:

C:\> Validate <targets> <command-line arguments>
        

Additional methods for setting up a Windows environment can be found in the Windows Setup Options section. If viewing this document in PDF form, see the appendix for details.

UNIX-Based Users

Open the Validate shell script and go to the last line in the file. It should look like the following:

java -jar ${VALIDATE_JAR} "$@"
        

Add the core.schema.dir Java system property using the -D Java flag option and set it to the location of the schemas. For example, making the following change to the launch script allows the Validate Tool to load core schemas from a directory named /home/pds/schemas:

java -Dcore.schema.dir="/home/pds/schemas" -jar ${VALIDATE_JAR} "$@"
        

Windows-Based Users

Open the Validate batch and go to the last line in the file. It should look like the following:

java -jar "%VALIDATE_JAR%" $*
        

Add the core.schema.dir Java system property using the -D Java flag option and set it to the location of the schemas. For example, making the following change to the launch script allows the Validate Tool to load core schemas from a directory named c:\pds\schemas:

java -Dcore.schema.dir="c:\pds\schemas" -jar "%VALIDATE_JAR%" $*
        

Command-Line Options

The following table describes the command-line options available:

Running the Validate Tool

This section demonstrates some of the ways that the tool can be executed using the command-line option flags:

• Validating a Target File
• Validating a Target Directory
• Validating Against User-Specified Schemas
• Validating Specific Files in a Target Directory
• Ignoring Sub-Directories During Validation
• Changing Tool Behaviors With The Configuration File

Validating a Target File

The following command demonstrates the validation of a single data product label against the core PDS schemas:

% Validate product.xml
        

Validating a Target Directory

The following command demonstrates the validation of a target directory against the core PDS schemas:

% Validate /home/pds/collection
        

Validating Against User-Specified Schemas

Specifying schemas on the command line will allow the Validate Tool to validate against the user-specified schemas instead of the schemas that come with the tool. The following command demonstrates the validation of a single product label against a user-specified schema:

% Validate product.xml -x product.xsd
        

The following command demonstrates the validation of a set of target files against a set of user-specified schemas:

% Validate producta.xml, productb.xml -x producta.xsd, productb.xsd
        

Validating Specific Files in a Target Directory

The following command demonstrates the validation of any file that has a .xml extension in a target directory:

% Validate /home/pds/collection -e "*.xml"
        

Note: File patterns should be surrounded in quotes to avoid having the system shell mistakingly interpreting them. In addition, pattern matching is case-insensitive in Windows, but case-sensitive for other systems.

Ignoring Sub-Directories During Validation

By default, the Validate Tool will recursively traverse a target directory during validation. The local flag option is used to tell the Validate Tool to not perform recursion. The following command demonstrates the validation of a target directory without directory recursion:

% Validate /home/pds/collection -L
        

Changing Tool Behaviors With The Configuration File

A configuration file can be passed into the command-line to change the default behaviors of the tool and to also provide users a way to perform validation with a single flag. For more details on how to setup the configuration file, see the Using a Configuration File section.

The following command demonstrates performing validation using a configuration file:

% Validate -c config.txt
        

Specifying Targets

Targets are validated in the order in which they are specified on the command-line. They can be specified implicitly and explicitly.

To specify targets implicitly, it is best to specify them first on the command-line before any other command-line option flags. The following command demonstrates the validation of an implicitly defined, single target product label:

% Validate product.xml
        

The following command demonstrates the validation of implicitly defined, multiple targets:

% Validate product.xml, /home/pds/collection
        

Implicit targets should not be specified after option flags that allow multiple arguments (see example below). Unexpected results can occur.

% Validate -x product.xsd product.xml
        

In this example, the Validate Tool will inadvertently treat the implicit target, product.xml, as a schema file.

Targets can be specified both implicitly and explicitly at the same time. Targets specified implicitly are validated first, followed by those that are specified explicitly with the target flag.

The following command demonstrates the validation of multiple product labels, specified both implicitly and explicitly:

% Validate producta.xml, productb.xml -t productc.xml, /home/pds/collection
        

In this example, producta.xml and productb.xml will get validated first, then productc.xml and the product labels in /home/pds/collection will get validated next.

Using a Configuration File

A configuration file is an alternative way to set the different behaviors of the tool instead of the command-line option flags. It consists of a text file made up of keyword/value pairs. The configuration file follows the syntax of the stream parsed by the Java Properties.load(java.io.InputStream) method.

Some of the important syntax rules are as follows:

• Blank lines and lines which begin with the hash character "#" are ignored.
• Values may be separated on different lines if a backslash is placed at the end of the line that continues below.
• Escape sequences for special characters like a line feed, a tabulation or a unicode character, are allowed in the values and are specified in the same notation as those used in Java strings (e.g. \n, \t, \r).

Since backslashes (\) have special meanings in a configuration file, keyword values that contain this character will not be interpreted properly by the Validate Tool even if it is surrounded by quotes. A common example would be a Windows path name (e.g. c:\pds\collection). Use the forward slash character instead (c:/pds/collection) or escape the backslash character (c:\\pds\\collection).

Note: Any flag specified on the command-line takes precedence over any equivalent settings placed in the configuration file.

The following table contains valid keywords that can be specified in the configuration file:

The following example demonstrates how to set a configuration file:

# This is a Validate Tool configuration file

validate.target = ./collection
validate.report = report.txt
validate.regexp = "*.xml"
        

This is equivalent to running the tool with the following flags:

-t ./collection -e "*.xml" -r report.txt
        

The following example demonstrates how to set a configuration file with multiple values for a keyword:

# This is a Validate Tool configuration file with multiple values

validate.target = product.xml, ./collection
vtool.regexp = "*.xml", "Mars*"
        

This is equivalent to running the tool with the following flags:

-t product.xml, ./collection -e "*.xml", "Mars*"
        

The following example demonstrates how to set a configuration file with multiple values that span across multiple lines:

# This is a Validate configuration file with multiple values
# that span across multiple lines

validate.target = product.xml, ./collection
validate.regexp = "*.xml", "Mars*"
        

As previously mentioned, any flag options set on the command-line will overwrite settings set in the configuration file. The following example demonstrates how to override a setting in the configuration file.

Suppose the configuration file named config.txt is defined as follows:

validate.target = ./collection
validate.regexp = "*.xml"
        

This configuration allows the tool to validate files with a .xml extension in the collection directory. To change the behavior to validate all files instead of just files ending in .xml, then specify the regexp flag option on the command-line to overwrite the validate.regexp property:

% Validate -c config.txt -e "*"
        

Report Format

This section describes the contents of the Validate Tool report. At this time, the Validate Tool outputs a series of log messages. A log message consists of the severity level, file name, line number, and a message. The following is an example of some of the log messages that can be expected from the Validate Tool:

PDS Validate Tool Report

Configuration:
  Version                  0.1.0
  Time                     Thu, Oct 28 2010 at 10:05:03 AM
  Core Schemas             [a.xsd, b.xsd, c.xsd]

Parameters:
  Target(s)                [C:\pds4]
  User-Specified Schemas   [C:\pds4\element-definitions\schemas\ \
                           Product_Data_Element_Definition_2010-04-22B.xsd]
  Severity Level           Warnings
  Recurse Directories      true

Validation Details:

  ERROR  [file:/C:/pds4/coordinate_system_positive_azimuth_direction_0111c.xml] \
  line 8, 66: cvc-elt.5.2.2.2.2: The value 'Product_Element_Definition' of \
  element 'product_class' does not match the {value constraint} value \
  'Product_Data_Element_Definition'.
  ERROR  [file:/C:/pds4/coordinate_system_positive_azimuth_direction_0111c.xml] \
  line 24, 34: cvc-complex-type.2.4.a: Invalid content was found starting with \
  element 'Reference_Entry_Generic'. One of \
  '{"http://pds.nasa.gov/schema/pds4/pds":data_reference, \
  "http://pds.nasa.gov/schema/pds4/pds":Bibliographic_Reference, \
  "http://pds.nasa.gov/schema/pds4/pds":Observing_System}' is expected.
  ERROR  [file:/C:/pds4/coordinate_system_positive_azimuth_direction_0111c.xml] \
  line 29, 25: cvc-complex-type.2.4.a: Invalid content was found starting with \
  element 'Element_Definition'. One of \
  '{"http://pds.nasa.gov/schema/pds4/pds":File_Area}' is expected.

  ERROR  [file:/C:/pds4/test/ \
  0001_NASA_PDS_1_img_Az_el_coordinate_system_reference_coordinate_\
  system_name_0111c.xml] \
  line 5, 26: cvc-complex-type.2.4.a: Invalid content was found starting with \
  element 'Identification_Area'. One of \
  '{"http://pds.nasa.gov/schema/pds4/pds":Product_Identification_Area}' is expected.


End of Report