The validator in its current state does only a little bit more than what is required to validate Aura files. For instance, there is no support for Grid or Point files. Such support can be added as needed in the future.
The HDF-EOS API calls used to inquire about the data types of attributes and fields are inadequate for this task (or for any task that requires completely self-describing files). These APIs will likely change in the near future, so this program will also have to change. Currently the validator uses modified copies of several HDF-EOS API functions to extract the metadata it needs. For more on this subject, see ValidatorIssues on the shiraz whiteboard.
Installation
The second and third set of sources are open source XML parsing software. expat-1.95.5.tar.gz is James Clark's stream-oriented XML parser. No changes were made to the sources downloaded from http://www.libexpat.org. To install it, just unpack it, go to its main directory, type ./configure, make, and make install to install it in /usr/local. If you want to install it elsewhere, read the README file.
scew-0.1.1.tar.gz is the Simple C Expat Wrapper, a library that uses expat to generate an in-memory tree of an XML document similar to a Domain Object Model (DOM) structure. No changes were made to the sources downloaded from http://www.nongnu.org/scew/. It installs the same way that expat (above) does.
validate-hdfeos5.tar.gz is the source for the validator. Unpack it and edit the Makefile - you will have to change the values of HDFROOT and SCEW_ROOT. Before building, you will have to set up the HDF-EOS 5 environment by sourcing the appropriate environment script. Once all that is done, you can build the validator by typing make, which will compile and link all the sources to create the executable validate_hdfeos5.
Running the validator
validate_hdfeos5 -h file-to-validate -x XML-definition
where file-to-validate is the HDF-EOS 5 file being validated, and XML-definition is a file containing an XML document with a top-level <HDF-EOS-Validation-Definition> element. If there are any errors, the validator will print one or more error report messages to standard error and exit with a non-zero error code. If everything is OK, the validator will print nothing and exit with a normal (zero) error code.
Validator error messages
A fatal error is any message beginning with "FATAL ERROR:". Fatal errors are caused by file system errors (inability to open/read one of the input files) or syntactic errors in the XML definition file.
Normal error reports are of the form:
ERROR LOCATION description of the error...
Here is an example error report:
SWATH HIRDLS GEOLOCATION_FIELD Pressure ATTRIBUTE Units
string "km "
doesn't match <StringValue value="hPa *"/>
Writing HDF-EOS 5 Validation Definitions
As mentioned previously, the validator compares an HDF-EOS 5 file against a definition file, which is an XML document consisting of an <HDF-EOS-Validation-Definition> element. A Document Type Definition (DTD) for those definition files is in the validator sources as validate-hdfeos5.xml. Example definition files are in the validator sources as HIRDLS-definition.xml, MLS-definition.xml, OMNI-definition.xml, and TES-definition.xml
The structure of an HDF-EOS 5 definition file at a high level is as follows:
<HDF-EOS-Validation-Definition>
<Attributes>
<!-- Definitions for global (file-level) attributes -->
<Mandatory>
<!-- Attribute definitions go here (see below> -->
<!-- These attributes must be found -->
</Mandatory>
<Optional>
<!-- More Attribute definitions go here -->
<!-- These attributes must match the specification if they are found-->
</Optional>
</Attributes>
<Swaths>
<!-- Definitions for Swaths -->
<Every-Swath>
<!-- Every Swath must match these specifications -->
<Attributes>
<!-- Mandatory and Optional Attributes for all Swaths -->
</Attributes>
<Swath-Dimensions>
<Mandatory-Dimensions>
<!-- These dimensions must be defined for this Swath -->
<Swath-Dimension name="nTimes"/>
</Mandatory-Dimensions>
<Optional-Dimensions>
<!-- Other Dimension definitions go here -->
<!-- If these dimensions are defined, they must match these specifications -->
</Optional-Dimensions>
</Swath-Dimensions>
<GeolocationFields>
<Every-GeolocationField>
<Attributes>
<!-- Mandatory and Optional Attributes for all GeolocationFields -->
</Attributes>
</Every-GeolocationField>
<GeolocationField-Named name="Time">
<!-- There must be a geolocation field named Time -->
<Attributes>
<!-- Mandatory and Optional Attributes for Time -->
</Attributes>
<!-- Time must have exactly one dimension, named nTimes -->
<Dimensions><d>nTimes</d></Dimensions>
</GeolocationField-Named>
</GeolocationFields>
<DataFields>
<Every-DataField>
<!-- Every data field must match these specifications -->
<Attributes>
<!-- Mandatory and Optional Attributes for all data fields -->
</Attributes>
</Every-DataField>
</DataFields>
</Every-Swath>
<Swath-Named name="HIRDLS">
<!-- There must be a swath named HIRDLS -->
<GeolocationFields>
<GeolocationField-Named name="Latitude">
<Dimensions><d>nTimes</d></Dimensions>
<Attributes>
<!-- Mandatory and Optional attributes for HIRDLS Latitude -->
</Attributes>
<DataType type="float" min="-90" max="90"/>
</GeolocationField-Named>
</GeolocationFields>
<DataFields>
<DataField-Named name="Temperature">
<!-- The usual Dimensions/Attributes/DataType -->
</DataField-Named>
</DataFields>
</Swath-Named>
</Swaths>
</HDF-EOS-Validation-Definition>
Attribute Definitions
<Attribute name="InstrumentName"> <!-- value specification goes here --> </Attribute>
There are four different possible value specifications:
StringValue
Here are the possible ways to specify a string attribute value:
IntValue
Here are the possible ways to specify an integer attribute value:
FloatValue
Here are the possible ways to specify a floating-point attribute value:
SameDataTypeAsField
This specification is useful for specifying that an attribute must have the same data type as the field it is attached to.
Data type definitions
Dimension definitions