Keeping files separate with XML includes

Question:

How can I keep the XML manageable when I have many data sets?

Explanation:

In most cases it will be convenient to have a separate XML file describing each dataset on your server. This can be achieved with XML "include" syntax. Using XML includes will allow you to add and delete datasets easily and will make hand editing the XML and debugging those edits much simpler.

XML has a (rather ugly) include syntax which lets you create an XML file which includes the contents of other XML files. The file doing the including will begin by defining an 'entity' like this:

<?xml version='1.0' ?>
<!DOCTYPE spec SYSTEM "spec.dtd" [
<!ENTITY coads_climatology SYSTEM "coads_climatology.xml">
]>

and will include the file "coads_climatology.xml" when the following entity appears:

&coads_climatology;

Note 1: The included .xml files must all exist in the same directory.

Note 2: The Makefile in the lasxml/server/ directory only checks whether the file named las.xml has changed. To update the interface after you have made changes to one of the included files you must 'touch las.xml'.

Solution:

In the context of LAS and the las.xml file you should start by creating XML files for the datasets you will use. They will be just like the standard las.xml file except that they should only contain the datasets, grids and axes elements. They must not contain the <lasdata></lasdata> or <operations></operations> tags.

The script addXml.pl, which generates XML files from netCDF files, has an --out_inc flag which causes output to be written in a format suitable for inclusion in a master XML file. It is used like this:

addXml.pl --out_inc template.xml my_data.xml my_data.nc

As an example, here is the complete coads_climatology.xml file:

<datasets>
 <coads_climatology_nc
   name="COADS Climatology"
   url="file:coads_climatology.nc"
   doc="doc/coads_climatology.nc.html">
  <institution name="NOAA/PMEL" url="http://www.pmel.noaa.gov"/>
  <variables>
   <airt name="AIR TEMPERATURE" units="DEG C">
    <link match="/lasdata/grids/coads_climatology_nc_grid"/>
   </airt>
   <sst name="SEA SURFACE TEMPERATURE" units="Deg C">
    <link match="/lasdata/grids/coads_climatology_nc_grid"/>
   </sst>
  </variables>
  </coads_climatology_nc>
</datasets>
<grids>
 <coads_climatology_nc_grid>
  <link match="/lasdata/axes/coads_climatology_nc_COADSX"/>
  <link match="/lasdata/axes/coads_climatology_nc_COADSY"/>
  <link match="/lasdata/axes/coads_climatology_nc_TIME"/>
 </coads_climatology_nc_grid>
</grids>
<axes>
 <coads_climatology_nc_COADSX type="x" units="degrees_east">
  <arange start="21" step="2" size="180"/>
 </coads_climatology_nc_COADSX>
 <coads_climatology_nc_COADSY type="y" units="degrees_north">
  <arange start="-89" step="2" size="90"/>
 </coads_climatology_nc_COADSY>
 <coads_climatology_nc_TIME type="t" units="month">
  <arange start="1-1-16" step="1" size="12"/>
 </coads_climatology_nc_TIME>
</axes>

And here is a complete las.xml file which includes coads_climatology.xml and levitus_climatology.xml:

<?xml version='1.0' ?>
<!DOCTYPE spec SYSTEM "spec.dtd" [
<!ENTITY coads_climatology SYSTEM "coads_climatology.xml">
<!ENTITY levitus_climatology SYSTEM "levitus_climatology.xml">
]>

<lasdata>
 <institution name="Pacific Marine Environmental Lab"
   url="http://www.pmel.noaa.gov"/>
 <!-- Define properties -->
 <!-- Define properties -->
  <properties>
   <ferret>
    <land_type>shade        
    </land_type>
    <fill_type>fill        
    </fill_type>
    <view_centered>no        
    </view_centered>
    <fill_levels/>
    <format>netcdf        
    </format>
   </ferret>
  </properties>

  <operations url="http://ferret.wrc.noaa.gov/las/LASserver.pl">
   &StdOperations;
  </operations>

&coads_climatology;
&levitus_climatology;

</lasdata>

Jonathan Callahan: Jonathan.S.Callahan@noaa.gov
Last modified: August 8, 2000