Manual .edu
UAH
The University of Alabama in Huntsville
The University of Alabama in Huntsville
Information Technology and Systems Center
SPOT Subsettability Checker
Version Description V2.4
The University of Alabama in Huntsville
Information Technology and Systems Center
SPOT Subsettability Checker
Version Description V2.4
April 25, 2008
( 2008 by the University of Alabama in Huntsville. All rights reserved.
Huntsville, Alabama 35899
Phone +1.256.824.6868
Table of Contents
Introduction and Purpose 1
Requirements for Subsetting 3
What is “Subsettable”? 3
Requirements Imposed by HDF-EOS Subsetting Calls 3
Requirements Imposed by HEW 4
Further Subsetting Requirements 4
Version Description 7
Enhancements in this Version 7
Known Restrictions in this Version 7
Problem Reports Addressed by this Version 7
Problem Reports Outstanding in this Version 7
Release Contents 9
Documents 9
Software 9
Installation 11
Required Software 11
Site Preparation 11
Installation Procedures 11
Periodic Maintenance 15
Usage Instructions 17
Invoking SPOT 17
Messages 17
Exit Codes 35
REGIS 37
Purpose 37
Installation 37
Usage 37
Output 38
Notes 39
JABBER 41
Purpose 41
Installation 41
Customization 41
Execution 41
Chapter
1
Introduction and Purpose
S
POT is a companion program to HEW, the HDF-EOS Web-based Subsetter. SPOT checks files for being properly formatted for subsetting by HEW. It can also determine if the file is a valid HDF-EOS file even if it isn’t suitable for subsetting by HEW.
This document contains a description of Version 2.4 of SPOT and installation and usage instructions.
Chapter
2
Requirements for Subsetting
What is “Subsettable”?
A properly-formatted HDF-EOS file contains one or more objects. These objects can be one of the abstract datatypes swath, point, or grid, as defined by the HDF-EOS library. Each object contains one or more fields.
A field is subsettable if a portion of it can be extracted on geographic (latitude and longitude) or temporal (date/time) criteria, or both.
An object is subsettable if it consists of valid fields. The fields need not all be subsettable. Unsubsettable fields (known as “also includes”) can be included or excluded from the output file in toto by HEW.
A file may be completely subsettable (meaning it consists of all subsettable objects), partially-subsettable (meaning that only some objects are subsettable) or unsubsettable (meaning that it consists of all unsubsettable objects).
In order for an HDF-EOS field to be subsettable, certain requirements have been imposed on the structure of its parent object. Some of these requirements have been imposed by the HDF-EOS subsetting calls; others have been imposed by the design of the subsetter.
Requirements Imposed by HDF-EOS Subsetting Calls
Swath Objects
▪ The swath object must contain “geo” fields for latitude and longitude to be subsetted on geographic criteria, and a time geo field to be subsetted on date/time criteria.
▪ The latitude geo field, if present, must be named “Latitude” or “Colatitude”.
▪ The longitude geo field, if present, must be named “Longitude”.
▪ The latitude and longitude geo fields, if present:
▪ Must be of the same data type and shape
▪ Must be one- or two-dimensional
▪ Must have a data type of FLOAT32 or FLOAT64
▪ The time geo field, if present
▪ Must be named “Time”
▪ Must have a data type of FLOAT64
▪ Must contain data in TAI seconds from 1993-01-01 at 00:00:00
Grid Datasets
▪ Must use one of the projections supported by the HDF-EOS library
Requirements Imposed by HEW
Swath Objects
▪ The latitude and longitude geo fields, if present:
▪ Must be in decimal degrees
▪ The latitude geo field, if present:
▪ Must increase northward with 0.0 at the equator (latitude)
▪ Must increase southward with 0.0 at the North Pole (colatitude)
▪ The longitude geo field, if present
▪ Must increase eastward with 0.0 at Greenwich
▪ Data fields must not be “index” mapped to geo fields
Further Subsetting Requirements
Swath Objects
Swath objects have “geo” fields and “data” fields. This is an important distinction. “Geo” fields contain geotemporal information such as latitude, longitude, and time. To be subsettable on geographic bounds, a swath object must have a properly-defined “Latitude” (or “Colatitude”) and “Longitude” geo field, as described above. To be subsettable on time, a swath object must have a properly-defined “Time” geo field. Geo fields other than “Latitude”, “Colatitude”, “Longitude”, and “Time” are valid in HDF-EOS, but are not useful for subsetting. Geo fields are never subsettable by themselves.
For a data field to be subsettable, it must have some relationship to the geo fields. Often, the data producer will generate two-dimensional arrays for the latitude and longitude information, and correspondingly-dimensioned arrays for the data fields. In this situation, the names of the dimensions provide the relationship of a datum to its corresponding latitude and longitude information. This is called “direct” or “implicit” mapping.
HDF-EOS supports two additional types of mapping, “mapped” and “indirect”. In “mapped” mapping, a relationship (origin and stride) between a geo and data dimension is defined. HDF-EOS supports the two cases of more field data than geo data and more geo data than field data. In the former case, the data producer must ensure that each data index can be mapped to a geo index, or some data will not be geolocatable. In “indirect” mapping, a simple origin-and-stride relationship does not exist between data indices and geo indices, so a table must be provided by the data producer. HEW does not support the subsetting of index-mapped fields.
Data fields that do not have a recognizable mapping to geo fields cannot be subsetted, but they can be extracted from the file in toto. These fields are called “also include” fields by HEW.
Grid Objects
When a grid object is defined, the HDF-EOS library implicitly defines two dimension objects, “XDim” and “YDim”. These dimensions must not be explicitly defined by the data producer.
A grid data field can be subsetted by HDF-EOS only if it has “XDim” and “YDim” as two of its dimensions. Although it should be possible to subset a one-dimensional field which only has an “XDim” or “YDim” dimension, HDF-EOS does not support this option.
Chapter
3
Version Description
This is a new release of SPOT. It offers the following features:
▪ Standalone operation (does not require ECS software)
▪ Can run in “verbose” mode or “silent” mode
▪ Input is any HDF-EOS 2 or HDF-EOS 5 file
▪ Output is via stdout, with exit codes reflecting overall status
Enhancements in this Version
▪ This version of SPOT contains "jabber", a companion program which generates ECHO FORMS documents from a sample granule.
▪ Also included in this release is a minor tool, “whatzit” which can be used to determine if a file is HDF, HDF-EOS, or neither.
Known Restrictions in this Version
Due to problems with HDF-5, SPOT is linked with dynamic libraries for both HDF libraries. You must install the correct versions of HDF-4 and HDF-5 prior to executing SPOT and make sure that the paths to the libraries are in the LD_LIBRARY_PATH environment symbol..
Since “point” HDF-EOS objects are not subsettable by HEW, SPOT makes only cursory checks on the names of point objects found in the file.
SPOT does not support CEA or BCEA grid projections in HDFEOS-5 files.
Problem Reports Addressed by this Version
None.
Problem Reports Outstanding in this Version
None.
Chapter
4
Release Contents
This release of SPOT consists of the following components:
Documents
SPOT Subsettability Checker Version Description V2.4, April 25, 2008.
Software
File SPOT-V2.4-bin.tar.gz. This file contains binary executable and ancillary files needed to run SPOT under SGI Irix 6.5, SunOS 5.9, or Linux (RHEL4). The file is delivered as a gzipped tape archive (tar) file. This file contains the following directories and files:
bin Subdirectory
This directory contains the executable for SPOT, REGIS, and JABBER:
bin/spot – SPOT executable
bin/regis - REGIS executable
bin/jabber - JABBER executable
bin/whatzit - WHATZIT executable
etc Subdirectory
This directory contains non-volatile support files used by SPOT:
etc/leapsec.dat – Leap-second data for time computations
etc/EWOCBaseForm.tpl - Base form for FORMS document
etc/EWOCDateTimeBounds.tpl - Date/time widget
etc/EWOCLatLonBounds.tpl - Lat/lon widget
etc/EWOCParameterSelection.tpl - Field name widget
etc/EWOC/XYBounds.tpl - X/Y bounds widget
Chapter
5
Installation
Required Software
The following software is required for the installation, execution, and maintenance of SPOT:
▪ Unix operating system, SGI Irix 6.x, SunOS 5.x, or Linux (RHEL4)
▪ C shared run-time libraries
▪ HDF 4 and HDF 5 shared run-time libraries (Irix and Linux)
▪ HDF-EOS 2 and HDF-EOS 5 shared run-time libraries (Irix and Linux)
▪ The utility programs gzip and tar
▪ SDP toolkit version 5.1 or later for periodic updates to leapsec.dat
Site Preparation
None required.
Installation Procedures
Unpack the Distribution File
Logon to the account in which SPOT is to be installed. Create, if necessary, an empty top-level directory into which the extracted SPOT files will be placed, then extract the files. For example
(login)
mkdir spot
cd spot
gzip –dc path/SPOT-V2.4-bin.tar.gz | tar xvf –
where path is the location of the SPOT release file. This process will create subdirectories bin and etc in the current directory.
Define the LEAPSEC Environment Variable
SPOT uses a single external environment variable, LEAPSEC, to locate the leapsec.dat file. A static copy of this file is provided with the SPOT distribution in the etc subdirectory. This file should be valid for at least one year from the last entry in the file. Thereafter, periodic updates are required to make time calculations accurate.
It is recommended that the LEAPSEC environment variable be defined in the system startup script that is executed whenever a user logs on. Note, however, that batch and cron jobs do not normally execute this script at startup; in this case, the LEAPSEC environment variable must be explicitly defined by the job being executed.
The command should look like
setenv LEAPSEC path/leapsec.dat (csh)
LEAPSEC=path/leapsec.dat; export LEAPSEC (sh)
where path is the path to the leapsec.dat file.
If the SDP Toolkit is in use at the site, the dynamic copy of the leapsec.dat file should be used in place of the static version delivered with SPOT. In this case, define LEAPSEC to point to the leapsec.dat file in the SDP Toolkit directory and remove the copy in the SPOT etc subdirectory to avoid confusion.
Test the Installation
Invoke SPOT thusly:
cd path/bin
spot filename
where path is the path to the SPOT directory and filename is the name of the HDF-EOS file to be scanned. More information may be found in the next chapter.
Installation Notes
SPOT does not have to reside in any particular directory. The spot executable may be placed in /usr/local/bin for ease of access.
Similarly, the leapsec.dat file does not need to reside in any particular directory. If the version from the SDP Toolkit is not used, leapsec.dat can be placed in any convenient directory such as /usr/etc. Be sure to define the LEAPSEC environment variable appropriately.
If the operating system produces a message indicating that one or more shared libraries cannot be found, examine the value of the global symbol $LD_LIBRARY_PATH. It must include the paths to any libraries that cannot be located.
Chapter
6
Periodic Maintenance
None required.
Chapter
7
Usage Instructions
Invoking SPOT
SPOT is invoked using the following syntax:
spot [-v|-r] [-n] filename
where
-v specifies that “verbose” mode should be used. SPOT will print out detailed information as it examines the specified file. This information is printed via stdout.
-r specifies that REGIS output should be produced. This option and the –v (“verbose”) option are mutually exclusive. This option is not designed to be used only by the REGIS script, described later in this document.
-n specifies that no “warning” messages should be displayed.
filename specifies the name of the single file to be processed, including path and extension.
Messages
During operation, SPOT produces error messages when it finds problems or descriptive text if the “verbose” option has been specified. All messages are written via stdout. These messages are divided into four categories, as described below.
Terminal Messages
“Terminal” messages indicate a severe problem from which SPOT cannot recover. As the name suggests, terminal messages always cause an immediate termination of the program. These messages are written via stderr and are prefixed with “****Terminal:”.
Error return while counting HDF-EOS objects
This message will be displayed if the HDF-EOS routines SWinqswath, PTinqpoint, and/or GDinqgrid return –1 while counting HDF-EOS objects in the given file. This is an error internal to HDF-EOS or the file from which SPOT cannot recover.
Inconsistent results while getting object names
This message will be displayed if two successive calls to SWinqswath, PTinqpoint, and/or GDinqgrid return inconsistent values. This is an error internal to HDF-EOS or the file from which SPOT cannot recover.
Out of memory [while] allocating ...
This indicates that SPOT’s memory quota has been exceeded. SPOT cannot continue. This generally only occurs while trying to process extremely large files.
Usage is spot [-v] [-n] filename
This message indicates that the user has invoked SPOT incorrectly.
Severe Messages
“Severe” messages indicate an error in the input file which makes it unsuitable for subsetting via HEW. These messages are written via stderr and are prefixed with “**Error:”.
filename is not in HDF format
The file named on the command line is not in HDF format. No further checking can be performed.
filename is not in HDF-EOS format
The file named on the command line is not in HDF-EOS format. No further checking can be performed.
name value is invalid in 'object'
The indicated value exceeds the expected range.
name value is not in packed degrees in 'object'
The indicated value was expected to be in packed decimal degrees (DDDMMMSSS.TT).
'name' contains an invalid character (character)
Although undocumented, names of any entity in HDF-EOS may not contain colons or commas, as these characters are used internally as a name delimiter. A slash is used internally in geo/data dimension mappings for swath data, so SPOT flags swath data dimensions with slashes as invalid, even if there are no dimension mappings.
'object' dimension 'name' value (value) is invalid
The dimension value is negative.
Albers Conical Equal Area projection in 'object' is not supported by HDF-EOS
This grid file is in a projection unsupported by HDF-EOS.
Azimuthal Equidistant projection in 'object' is not supported by HDF-EOS.
This grid file is in a projection unsupported by HDF-EOS.
'Colatitude' geo field in 'object' must be float32 or float64
To be subsettable, geo fields such as Colatitude must be of type float32 or float64.
'Colatitude' geo field in 'object' must be of rank 1 or 2
To be subsettable, geo fields such as Colatitude must be 1- or 2-dimensional.
Data dimension in 'geo/data' index mapping is undefined in 'object'
The specified data dimension in the index mapping is undefined.
Data dimension in 'geo/data' mapping is undefined in 'object'
The specified data dimension in the mapping is undefined.
Dimension value in 'Longitude' and '[Co]latitude' fields does not match in 'object'
To be subsettable, the longitude and latitude geo fields must have identical dimensions.
Dimension 'geo' in 'geo/data' index mapping is not a geo dimension in 'object'
The specified dimension is not a defined geo dimension.
Dimension 'geo' in 'geo/data' mapping is not a geo dimension in 'object'
The specified dimension is not a defined geo dimension.
Duplicate 'geo/data' mapping found in 'object'
The swath object contains two or more mappings with identical names.
Duplicate indexed mapping 'geo/data' found in 'object'
The swath object contains two or more indexed mappings with identical names.
Equidistant Conic projection in 'object' is not supported by HDF-EOS.
This grid file is in a projection unsupported by HDF-EOS.
Equirectangular projection in 'object' is not supported by HDF-EOS.
This grid file is in a projection unsupported by HDF-EOS.
Error getting index count on 'object'
HDF-EOS returned an error while attempting to count the number of indexed dimensions.
Error getting index maps in 'object'
HDF-EOS returned an error while attempting to retrieve the index maps.
Error getting map count on 'object'
HDF-EOS returned an error while attempting to count the number of dimension maps.
Error reading 'field' from 'object'
HDF-EOS returned an error from SWreadfield while attempting to read the data from the indicated field. This normally indicates that the field was never properly written, or that the field is in an external file. HEW does not support externally-stored fields.
Error reading first element from GDreadfield on 'field' in 'object'
HDF-EOS returned an error from GDreadfield while attempting to read the first datum from the indicated field. This normally indicates that the field was never properly written, or that the field is in an external file. HEW does not support externally-stored fields.
Error reading first element from SWreadfield on 'field' in 'object'
HDF-EOS returned an error from SWreadfield while attempting to read the first datum from the indicated field. This normally indicates that the field was never properly written, or that the field is in an external file. HEW does not support externally-stored fields.
Error reading last element from GDreadfield on 'field' in 'object'
HDF-EOS returned an error from GDreadfield while attempting to read the last datum from the indicated field. This normally indicates that the field was never completely written, or that the field is in an external file. HEW does not support externally-stored fields.
Error reading last element from SWreadfield on 'field' in 'object'
HDF-EOS returned an error from SWreadfield while attempting to read the last datum from the indicated field. This normally indicates that the field was never completely written, or that the field is in an external file. HEW does not support externally-stored fields.
Error return from GDattach on 'object'
GDattach returned an error code while attempting to attach to the object.
Error return from GDattrinfo on 'attr' in 'object'
GDattrinfo returned an error code while attempting to read attribute information.
Error return from GDcompinfo on 'field' in 'object'
GDcompinfo returned an error code while attempting to get compression information.
Error return from GDfieldinfo on 'field' in 'object'
GDfieldinfo returned an error while attempting to get field information.
Error return from GDgetdefaults on 'object'
GDgetdefaults returned an error while attempting to get upper-left and lower-right corner information about the grid. This will only occur if the values were set to DEFAULT (0.0).
Error return from GDgridinfo on 'object'
GDgridinfo returned an error while attempting to get information about the grid.
Error return from GDinqattrs on 'object'
GDinqattrs returned an error while attempting to get attribute information.
Error return from GDinqdims on 'object'
GDinqdims returned an error while attempting to get dimension information.
Error return from GDinqfields on 'object'
GDinqfields returned an error while attempting to get field information.
Error return from GDorigininfo on 'object'
GDorigininfo returned an error while attempting to get grid origin information.
Error return from GDpixreginfo on 'object'
GDpixreginfo returned an error while attempting to get pixel registration information.
Error return from GDprojinfo on 'object'
GDprojinfo returned an error while attempting to get projection information.
Error return from GDreadattr reading 'attr' in 'object'
GDreadattr returned an error while attempting to read the specified attribute.
Error return from SWattach on 'object'
SWattach returned an error while attempting to attach to the specified swath.
Error return from SWattrinfo on 'field' in 'object'
SWattrinfo returned an error while attempting to get attribute information.
Error return from SWcompinfo on 'field' in 'object'
SWcompinfo returned an error while attempting to get compression information.
Error return from SWfieldinfo on 'field' in 'object'
SWfieldinfo returned an error while attempting to get field information
Error return from SWinqattrs on 'object'
SWinqattrs returned an error while attempting to get attribute counts.
Error return from SWinqdatafields on 'object'
SWinqdatafields returned an error while attempting to get field counts.
Error return from SWinqdims on 'object'
SWinqdims returned an error while attempting to get dimension counts.
Error return from SWinqgeofields on 'object'
SWinqgeofields returned an error while attempting to get field counts.
Error return from SWinqmaps in 'object'
SWinqmaps returned an error while attempting to get map counts.
Error return from SWreadattr reading 'attr' in 'object'
SWreadattr returned an error while attempting to read attribute information.
Expected value grids, found value
The expected number of grid objects found does not match the actual number. This could indicate that one or more of the grid names contained an invalid character, such as a comma.
Expected value points, found value
The expected number of point objects found does not match the actual number. This could indicate that one or more of the point names contained an invalid character, such as a comma.
Expected value swaths, found value
The expected number of swath objects found does not match the actual number. This could indicate that one or more of the swath names contained an invalid character, such as a comma.
Fewer attributes were retrieved than expected for 'object'
The expected number of attribute objects found does not match the actual number. This could indicate that one or more of the attribute names contained an invalid character, such as a comma.
Fewer data fields were retrieved than expected in 'object'
The expected number of data field objects found does not match the actual number. This could indicate that one or more of the data field names contained an invalid character, such as a comma.
Fewer dimensions were retrieved than expected in 'object'
The expected number of dimension objects found does not match the actual number. This could indicate that one or more of the dimension names contained an invalid character, such as a comma.
Fewer geo fields were retrieved than expected in 'object'
The expected number of geo field objects found does not match the actual number. This could indicate that one or more of the geo field names contained an invalid character, such as a comma.
Fewer index mappings found than expected in 'object'
The expected number of index mapping objects found does not match the actual number. This could indicate that one or more of the index mapping names contained an invalid character, such as a comma.
Fewer mappings found than expected in 'object'
The expected number of mapping objects found does not match the actual number. This could indicate that one or more of the mapping names contained an invalid character, such as a comma.
Field 'field' in 'object' has invalid rank (value)
HDF limits object ranks to 1-8.
File 'name' is inaccessible
The specified file is either read-protected or the name or path is incorrectly specified.
File contains two objects named 'name' of the same type
Two objects of the same type have the same name. Although it is permissible (but confusing) to have two objects of different types having the same name, two objects of the same name and same type cannot be differentiated.
Format code (value) in 'object' is invalid
The projection parameter value for 'Format' is invalid for this projection.
General Vertical Near-Side Perspective projection in 'object' is not supported by HDF-EOS.
This grid file is in a projection unsupported by HDF-EOS.
Geo dimension in 'geo/data' index maping is undefined in 'object'
The specified geo dimension is not defined as a dimension.
Geo dimension in 'geo/data' mapping is undefined in 'object'
The specified geo dimension is not defined as a dimension.
Geo field 'field' in 'object' has invalid rank (value)
HDF limits object ranks to 1-8
Gnomonic projection in 'object' is not supported by HDF-EOS
This grid file is in a projection unsupported by HDF-EOS.
Grid 'object' contains no data fields
This grid object contains no defined data fields and hence cannot be subsetted.
Grid 'object' contains two or more attributes named 'attr'
Two attributes have the same name. This could indicate that one or more of the attribute names contained an invalid character, such as a comma.
Grid 'object' contains two or more data fields named 'data'
Two data fields have the same name. This could indicate that one or more of the field names contained an invalid character, such as a comma.
Grid 'object' contains two or more dimensions named 'dim'
Two dimensions have the same name. This could indicate that one or more of the dimension names contained an invalid character, such as a comma.
Grid origin code (value) is invalid in 'object'
The grid origin code returned by HDF-EOS is not one of the valid values.
HEW cannot subset Space Oblique Mercator grids ('object')
Although the SOM projection is supported by HDF-EOS, HEW cannot subset data in the projection at the moment, as it requires special-case code.
Hammer projection in 'object' is not supported by HDF-EOS
This grid file is in a projection unsupported by HDF-EOS.
Inclination angle (value) in 'object' must be positive
The projection parameter value for 'IncAng' is invalid for this projection.
Increment for 'geo/data' mapping is zero in 'object'
The increment value for the specified mapping is zero, which is not permitted.
Interrupted Mollweide projection in 'object' is not supported by HDF-EOS
This grid file is in a projection unsupported by HDF-EOS.
Invalid datatype for 'field' in 'object'
The datatype specified for this field is not supported by HDF-EOS.
Invalid pixel registration code (value) in 'object'
The pixel registration code returned by HDF-EOS is not valid.
'Latitude' geo field in 'object' must be float32 or float64
To be subsettable, geo fields such as Latitude must be of type float32 or float64.
'Latitude' geo field in 'object' must be of rank 1 or 2
To be subsettable, geo fields such as Latitude must be 1- or 2-dimensional.
'Longitude' and '[Co]Latitude' fields in 'object' are not the same data type
To be subsettable, geo fields for latitude and longitude must be identical in rank and type.
'Longitude' and '[Co]Latitude' fields in 'object' are not the same rank
To be subsettable, geo fields for latitude and longitude must be identical in rank and type.
'Longitude' geo field in 'object' must be float32 or float64
To be subsettable, geo fields such as Longitude must be of type float32 or float64.
'Longitude' geo field in 'object' must be of rank 1 or 2
To be subsettable, geo fields such as Longitude must be 1- or 2-dimensional.
Mapping in 'geo/data' in 'object' is invalid; some data indices do not map to geo indices
According to the mapping information, one or more of the elements from the data dimension cannot be mapped to the corresponding geo dimension. For example, if 'geodim' has value 10 and 'datadim' has value 22 and the mapping is defined as offset 0, increment 2, the last element of 'datadim' cannot be mapped to an element of 'geodim'.
Mercator projection in 'object' is not supported by HDF-EOS.
This grid file is in a projection unsupported by HDF-EOS.
Miller Cylindrical projection in 'object' is not supported by HDF-EOS.
This grid file is in a projection unsupported by HDF-EOS.
Modified Stereographic Conformal Alaska projection is not supported by HDF-EOS.
This grid file is in a projection unsupported by HDF-EOS.
Mollweide projection in 'object' is not supported by HDF-EOS.
This grid file is in a projection unsupported by HDF-EOS.
More attributes found than expected in 'attr' of 'object'
The expected number of attribute names found does not match the actual number. This could indicate that one or more of the attribute names contained an invalid character, such as a comma.
More dimensions found than expected in 'field' of 'object'
The expected number of dimension names found does not match the actual number. This could indicate that one or more of the dimension names contained an invalid character, such as a comma.
More fields found than expected in 'object'
The expected number of field objects found does not match the actual number. This could indicate that one or more of the field names contained an invalid character, such as a comma.
More geo fields found than expected in 'object'
The expected number of geo field objects found does not match the actual number. This could indicate that one or more of the geo field names contained an invalid character, such as a comma.
More index mappings found than expected in 'object'
The expected number of index mapping objects found does not match the actual number. This could indicate that one or more of the index mapping names contained an invalid character, such as a comma.
More mappings found than expected in 'object'
The expected number of mapping objects found does not match the actual number. This could indicate that one or more of the mapping names contained an invalid character, such as a comma.
No subsettable data fields found
There are either no data fields or none of the data fields are subsettable (by HEW) in this file.
No user-defined dimensions found in 'object'
Although grid objects contain by default dimensions XDim and YDim, there are no pre-defined dimensions for swaths. If there are no defined dimensions, there can be no defined fields.
NZone value (value) in 'object' must be a positive, non-zero integer
The projection parameter value for 'NZone' is invalid for this projection.
Oblated Equal Area projection in 'object' is not supported by HDF-EOS
This grid file is in a projection unsupported by HDF-EOS.
Orthographic projection in 'object' is not supported by HDF-EOS
This grid file is in a projection unsupported by HDF-EOS.
Path number (value) in 'object' is invalid
The projection parameter value for 'Path' is invalid for this projection.
Point objects are not supported by this program
HEW cannot subset HDF-EOS "point" objects; therefore, SPOT does not handle them either.
Projection code value in 'object' is invalid
The projection code returned by HDF-EOS is not recognized as a valid GTCP projection code.
RFlag value (value) in 'object' is invalid
The projection parameter value for 'RFlag' is invalid for this projection.
Robinson projection in 'object' is not supported by HDF-EOS
This grid file is in a projection unsupported by HDF-EOS.
Satellite revolution period (value) in 'object' is
The projection parameter value for 'PSRev' is invalid for this projection.
Satnum value (value) in 'object' is invalid
The projection parameter value for 'Satnum' is invalid for this projection.
Scale factor (0.0) in 'object' is invalid
The projection parameter value for 'Factor' is invalid for this projection.
Sinusoidal projection in 'object' is not supported by HDF-EOS
This grid file is in a projection unsupported by HDF-EOS.
SMajor projection parameter (value) in 'object' is invalid
The projection parameter value for 'SMajor' is invalid for this projection.
SMinor projection parameter (value) in 'object' is invalid
The projection parameter value for 'SMinor' is invalid for this projection.
SPCS projection in 'object' is not supported by HDF-EOS
This grid file is in a projection unsupported by HDF-EOS.
Sphere value (value) in 'object' is invalid
The projection parameter value for 'Sphere' is invalid for this projection.
Stereographic projection in 'object' is not supported by HDF-EOS
This grid file is in a projection unsupported by HDF-EOS.
Swath 'object' contains no data fields
No data fields were defined for this swath; the swath, therefore, is unsubsettable.
Swath 'object' contains no geo fields
No geo fields were defined for this swath; the swath, therefore, cannot be subsetted geographically.
Swath 'object' contains two or more attributes named 'attr'
Two attributes have the same name. This could indicate that one or more of the attribute names contained an invalid character, such as a comma.
Swath 'object' contains two or more data fields named 'data'
Two data fields have the same name. This could indicate that one or more of the field names contained an invalid character, such as a comma.
Swath 'object' contains two or more dimensions named 'dim'
Two dimensions have the same name. This could indicate that one or more of the dimension names contained an invalid character, such as a comma.
Swath 'object' contains two or more geo fields named 'geo'
Two geo fields have the same name. This could indicate that one or more of the field names contained an invalid character, such as a comma.
This file contains no HDF-EOS objects
The file appears to be in HDF-EOS format, but no swath, grid, or point objects were found in the file.
'Time' geo field in 'object' must be float64
To be subsettable, the Time field must be float64 (TAI93).
'Time' geo field in 'object' must be of rank 1 or 2
To be subsettable, the Time field must be 1- or 2-dimensional.
Too many grid names found
More grid names were found than expected. This could indicate that one or more of the names contained an invalid character, such as a comma.
Too many point names found
More point names were found than expected. This could indicate that one or more of the names contained an invalid character, such as a comma.
Too many swath names found
More swath names were found than expected. This could indicate that one or more of the names contained an invalid character, such as a comma.
Unable to determine attribute count in 'object'
An error was returned while trying to determine the attribute count using HDF-EOS calls.
Unable to determine data field count in 'object'
An error was returned while trying to determine the data field count using HDF-EOS calls.
Unable to determine geo field count in 'object'
An error was returned while trying to determine the geo field count using HDF-EOS calls.
Unable to find delimiter (/) in index mapping in 'object'
The mapping string returned by HDF-EOS does not contain a slash when expected.
Unable to find delimiter (/) in mapping in 'object'
The mapping string returned by HDF-EOS does not contain a slash when expected.
Unable to retrieve dimension count for 'object'
An error was returned while trying to determine the dimension count using HDF-EOS calls.
Undefined dimension 'dim' referenced by 'field' in 'object'
The given field uses the given dimension in its dimension list, but that dimension has not been defined.
Van der Grinten projection in 'object' is not supported by HDF-EOS
This grid file is in a projection unsupported by HDF-EOS.
Wagner IV projection in 'object' is not supported by HDF-EOS
This grid file is in a projection unsupported by HDF-EOS.
Wagner VII projection in 'object' is not supported by HDF-EOS
This grid file is in a projection unsupported by HDF-EOS.
XDim value (value) is invalid
The XDim value returned by HDF-EOS is zero or negative.
YDim value (value) is invalid
The YDim value returned by HDF-EOS is zero or negative.
Zone code (value) is invalid in 'object'
The projection parameter value for 'Zonecode' is invalid for this projection.
Warning Messages
“Warning” messages indicate an error in the input file which may cause HEW to perform incorrectly or may restrict HEW’s capabilities. These messages are written via stderr and are prefixed with “*Warning:” unless suppressed by the –n option.
value out-of-range 'field' values were found in 'object'
SPOT checks latitude, longitude, and time values for valid ranges, ignoring instances of the fill value.
name value may not be in packed degrees in 'object'
The indicated parameter value does not appear to be in packed degrees (DDDMMMSSS.TT).
'field' in 'object' is NOT subsettable using HDF-EOS calls due to lack of XDim in the dimension list
The specified field cannot be subsetted using HDF-EOS calls because it shares only one of the defined grid dimensions.
'field' in 'object' is NOT subsettable using HDF-EOS calls due to lack of YDim in the dimension list
The specified field cannot be subsetted using HDF-EOS calls because it shares only one of the defined grid dimensions.
'dimension/dimension' dimension mapping is superfluous in 'object'
Either the geo or data dimension (or both) are unused in the object. The dimension mapping is therefore useless.
Attribute count of value for 'name' in 'object' is invalid
The attribute count is negative or zero.
'Colatitude' has been defined as a data field in 'object'; this may be confusing
The geo field names 'Latitude', 'Colatitude', 'Longitude', and 'Time' should be reserved for geo fields to avoid confusion.
Datatype for name (value) is not portable
The datatype for the indicated object is not one of the portable datatypes supported by HDF.
Dimension 'dimension' is defined but never used in 'object'
The indicated dimension is defined but never used by any data or geo field. If “dimension” is “XDim” or “YDim”, then no grid fields in the file use the default dimensions created for the grid. While this is not an error, it is a questionable practice.
False easting value in 'object' (value) appears to be invalid
False easting and northing values must be expressed in meters. The specified value appears to be too large.
False northing value in 'object' (value) appears to be invalid
False easting and northing values must be expressed in meters. The specified value appears to be too large.
File contains two objects named 'name' of different types
Although it is permissible to have two objects of different types (swath, point, or grid) in a single file, such usage can lead to confusion.
File may be too large for subsetter front-end
Large swath files and large grid files using certain projections can take too long to scan. This will cause the browser to time out. The absence of this message does not imply that a timeout will not occur. Note that the subsetter back-end has no timeout problems.
Geo fields in 'object' other than "Latitude", "Colatitude", "Longitude", and "Time" are not generally useful
Although such fields are valid, they are of no intrinsic meaning to HDF-EOS.
Landsat path flag (value) in 'object' may be invalid
The 'Path' projection parameter may be invalid.
'Latitude' has been defined as a data field in 'object'; this may be confusing
The geo field names 'Latitude', 'Colatitude', 'Longitude', and 'Time' should be reserved for geo fields to avoid confusion.
'Longitude' has been defined as a data field in 'object'; this may be confusing
The geo field names 'Latitude', 'Colatitude', 'Longitude', and 'Time' should be reserved for geo fields to avoid confusion.
Lower-right X coordinate value (value) may be invalid
Except for the GEO projections, corner coordinate values must be expressed in meters. The specified value appears to be too large.
Lower-right Y coordinate value (value) may be invalid
Except for the GEO projections, corner coordinate values must be expressed in meters. The specified value appears to be too large.
Mapping 'geo/data' in 'object' may be incorrect; some data indices do not map to geo indices
This message may appear if “reverse” mapping (negative increment) has been specified. It indicates that there are more data values than geo values. This may or may not be an error. Check to ensure that the mapping direction (reverse) is what was intended.
Mapping 'geo/data' in 'object' may be incorrect; some geo indices do not map to data indices
This message may appear if “normal” mapping (positive increment) has been specified. It indicates that there are more geo values than data values. This may or may not be an error. Check to ensure that the mapping direction (normal) is what was intended.
No subsettable data fields found in 'object'
The file either does not contain any data fields, or all the fields encountered cannot be subsetted by HEW.
Projection code in 'object' is 'user-defined'; assuming Integerized Sinusoidal Projection
A projection code of '99' is "user-defined". HDF-EOS assumes that '99' is Integerized Sinusoidal, and so do HEW and SPOT.
Projection parameter number for the projection in 'object' should be zero
The projection parameter table says this projection parameter is unused; therefore, it should be zero. If it isn't, then it might be out of place.
SOM parameter values do not match recommended values for Landsats n-m
The projection parameters do not match the recommended values for the indicated range of Landsat satellites. If the grid does not represent Landsat data, ignore this message.
Satellite ratio value (value) in 'object' does not match recommended value for Landsat
The 'SRat' projection parameter value does not match the recommended value for Landsat. If the grid does not represent Landsat data, ignore this message.
The sphere code for the projection in 'object' should be zero
The sphere code parameter is rarely used and should be either unspecified (-1) or zero.
The zone code for the projection in 'object' should be zero
The zone code parameter is used only for UTM projections and should otherwise be unspecified (-1) or zero.
'Time' has been defined as a data field in 'object'; this may be confusing
The geo field names 'Latitude', 'Colatitude', 'Longitude', and 'Time' should be reserved for geo fields to avoid confusion.
Unknown option 'option' ignored
An unrecognized option was specified on the command line.
Upper-left X coordinate value (value) may be invalid
Except for the GEO projections, corner coordinate values must be expressed in meters. The specified value appears to be too large.
Upper-left Y coordinate value (value) may be invalid
Except for the GEO projections, corner coordinate values must be expressed in meters. The specified value appears to be too large.
Valid 'Latitude' and/or 'Longitude' geo fields were not found in 'object'; no data fields can be subsetted on lat/lon
Geographic subsetting requires the definition of valid latitude and longitude fields. These fields must have the correct type and dimensionality.
Valid 'Time' geo field was not found in 'object'; no data fields can be subsetted on time
Time subsetting requires the definition of a valid time field. This field must have the correct type and dimensionality.
'XDim' has been defined as a data field as well as a dimension in '%s'; this may be confusing
The geo dimensions explicitly defined in a grid should not be defined as data fields to avoid confusion.
XDim should not be explicitly defined as a dimension in 'object'
Older versions of HDF-EOS explicitly defined XDim and YDim as dimensions. If the file was created with a pre-2.1 version of HDF-EOS, ignore this message. The presence of XDim and/or YDim as explicitly-defined dimensions in files created with later versions of HDF-EOS may cause HDF-EOS to perform incorrectly.
'YDim' has been defined as a data field as well as a dimension in '%s'; this may be confusing
The geo dimensions explicitly defined in a grid should not be defined as data fields to avoid confusion.
YDim should not be explicitly defined as a dimension in 'object'
Older versions of HDF-EOS explicitly defined XDim and YDim as dimensions. If the file was created with a pre-2.1 version of HDF-EOS, ignore this message. The presence of XDim and/or YDim as explicitly-defined dimensions in files created with later versions of HDF-EOS may cause HDF-EOS to perform incorrectly.
Zone code should be zero if Lat/Z and Lon/Z are specified in 'object'
The zone code value should either be explicitly specified or a non-zero lat/lon value should be entered into the projection parameters, not both.
Information Messages
“Information” messages are only produced if the “verbose” option was specified on the command line. These messages are written via stdout. These messages are self-explanatory.
Exit Codes
To make SPOT usable in a batch environment, SPOT exits with one of the following exit codes. A batch script can check the value of the exit code to determine a course of action:
0 Everything is OK; the file should be subsettable by HEW. However, there may be situations where the HEW back-end can subset a file that can’t be handled by the HEW front-end. This normally occurs only in very large files or grids using Integerized Sinusoidal Projection.
1 The file is valid HDF-EOS, but it is only partially subsettable by HEW. Depending on the error messages that were displayed, it may also not be subsettable by HDF-EOS.
2 The file is valid HDF-EOS, but it is not subsettable by HEW. Depending on the error messages that were displayed, it may also not be subsettable by HDF-EOS.
3 The file is not valid HDF-EOS.
4 The file is not valid HDF.
255 A terminal error occurred.
Any other exit code indicates a problem with SPOT and is usually accompanied by a core dump.
Chapter
8
REGIS
Purpose
REGIS is a simple front-end script which may be used with SPOT versions 1.3 and above to produce “registry patch” information for sites which have implemented the HEW Subsetting Appliance as part of their ECS installation.
REGIS is run on one representative HDF-EOS file for each data type to produce the output, which consists of ASCII text to be input to the RGYPATCH process. It is vital that the file selected be representative, or a superset, of all of the fields that will be present in granules from the data type. For example, if the data type typically has 28 pass fields in each daily file, but some files have 29, then a file with 29 fields should be used as the representative sample.
Installation
REGIS consists of a simple C-shell script, “regis”. Simply copy the file to any convenient directory which is on the user’s path, such as /usr/local/bin.
REGIS assumes that the SPOT executable (spot) is on the user’s path. If this is not so, and if SPOT is not in the current directory, then the last line of the regis script must be modified to include the full path to SPOT.
Usage
REGIS is invoked using the following syntax:
regis site hostpath filename >output
where
site is the “site name” to use in the RGYPATCH commands
hostpath is the host name and path for the RGYPATCH commands
filename is the name of a typical HDF-EOS file for this data type
For example,
regis PVC MOD10_L2/VersionID/3/Subsetter01 \
MOD10A1.A1999054.h34v09.02.1999237153001.hdf
The output consists of a sequence of RGYPATCH “ADD” commands in the format
site ADD ExternalSubsetters/ESDTs/hostpath/SUBSET_OPTIONS/...
where “site” and “hostpath” are the values from the command line, and “...” is the specific RGYPATCH command parameter and value.
Use of RGYPATCH is out of the scope of this document. Consult your ECS documentation.
Output
Output is written via stdout, which should be redirected to a file.
“Spatial” RGYPATCH commands are written if the file can be subsetted spatially on latitude and longitude.
“Temporal” RGYPATCH commands are written if the file can be subsetted by date and time.
“Parameter” RGYPATCH commands are written if the file can be subsetted by parameter (HDF-EOS field).
“Also_include” RGYPATCH commands are written if the file contains unsubsettable fields that can be included in the output file in toto.
Do not attempt to “fool” the HEW Subsetting Appliance by declaring a data type to be subsettable in a way different from what REGIS reports. (For example, don’t add commands to make it spatially subsettable when REGIS says it isn’t.)
REGIS may behave badly if passed an invalid file, such as one that is not valid HDF-EOS.
Notes
REGIS does not generate all of the commands needed to implement an external subsetter in the ECS registry.
Chapter
9
JABBER
Purpose
JABBER is a program similar to the REGIS shell script which can be used by a site to generate ECHO FORMS documents for datasets.
The ECHO FORMS document for any particular dataset is most likely unique from any other dataset due to the inclusion of allowed subsetting criteria, such as lat/lon, X/Y, and/or date/time subsetting, as well as the dataset-specific field names that might be found in a file. JABBER can ease the creation of the XML files.
Installation
The JABBER executable ("jabber") can be placed in any convenient directory.
Customization
As delivered, the EWOC*.tpl files in the "etc" subdirectory are valid, but they may not provide the formatting desired by the site in the section. The template files can be carefully edited to change the display in the section. Consult the ECHO Forms Specification document for details.
Note, however, that no changes may be made to the names of the subsetting options tags or datatypes. Many of the "ecs" tags are fixed as well.
Execution
Before executing JABBER, it is necessary to set up the following environment symbols:
$SPOT - This is the full, rooted path to the SPOT executable
$JABBERTPLDIR - This is the full, rooted path to the SPOT "etc" subdirectory which contains the EWOC*.tpl files.
$HSAURL - This is the endpoint of the HSA subsetter's EWOC interface service. This typically begins with "http://" and must be a valid URL.
$LEAPSEC - This is the full, rooted path to the "leapsec.dat" file, including the file name.
Thereafter, invoke JABBER thusly:
jabber inputfilename >outputfilename
inputfilename is the name of a representative granule from the dataset for which you want an EWOC FORMS document to be generated. outputfilename is the name of the FORMS file to which the XML is to be written. Note that JABBER writes to stdout, so the redirection is necessary. Be sure to use a unique name for each output file. ".xml" is the recommended file extension.
The output can be tested using the ECHO FORMS viewer.
Chapter
10
WHATZIT
Purpose
WHATZIT is a minor command-line tool which may be used to identify the type of a file, which could be HDF-4, HDF-5, HDF-EOS 2, HDF-EOS 5, or none of the above.
Installation
The WHATZIT executable ("whatzit") can be placed in any convenient directory.
Execution
Thereafter, invoke WHATZIT thusly:
whatzit [-s] filename
The “-s” (silent) may be specified to suppress most output. This can be useful for scripts which only need the exit code.
filename is the name of the file to examine.
The script will report via STDOUT the type of file filename is, which can be HDF-4, HDF-5, HDF-EOS 2, HDF-EOS 5, or none of the above. This output can be suppressed by using the -s option. The script exits with one of the following codes:
0 - File is “none of the above”
1 - File is HDF-4
2 - File is HDF-EOS 2
3 - File is HDF-5
4 - File is HDF-EOS 5
255 - Error
................
................
In order to avoid copyright disputes, this page is only a partial summary.
To fulfill the demand for quickly locating and searching documents.
It is intelligent file search solution for home and business.