 |
NetCDF Users Guide
v1.1
|
|
NetCDF Users Guide
v1.1
|
Beginning with netCDF version 4.1, optional support is provided fo accessing data through servers supporting the DAP2 protocol.
DAP2 support is enabled if the –enable-dap__ option is used with _./configure. If DAP2 support is enabled, then a usable version of libcurl must be specified using the LDFLAGS environment variable (similar to the way that the HDF5 libraries are referenced). Refer to the installation manual for details. By default DAP2 support is enabled if libcurl is found. DAP2 support can be disabled using the –disable-dap.
DAP2 uses a data model that is different from that supported by netCDF, either classic or enhanced. Generically, the DAP2 meta-data is encoded textually in a DDS (Dataset Descriptor Structure). There is a second textual object, the DAS (Dataset Attribute Structure), for specifying DAP2 attributes. For detailed information about the DAP2 DDS and DAS, refer to the OPeNDAP web site http://opendap.org.
In order to access an OPeNDAP data source through the netCDF API, the file name normally used is replaced with a URL with a specific format. The URL is composed of three parts.
It is possible to see what the translation does to a particular DAP2 data source by examining the DDS source through a web browser and then examining the translation using the ncdump -h command to see the netCDF Classic translation. The ncdump output will actually be the union of the DDS with the DAS, so to see the complete translation, it is necessary to view both via the browser.
For example, if a web browser is given the following, the first URL will return the DDS for the specified dataset, and the second URL will return the DAS for the specified dataset.
Then by using the following ncdump command, it is possible to see the equivalent netCDF Classic translation.
The DDS output from the web server should look like this.
The DAS output from the web server should look like this.
The output from ncdump should look like this.
Note that the fields of type String and type URL have suddenly acquired a dimension. This is because the netCDF model does not support strings, but DAP2 does support strings. So, DAP2 strings are translated to arrays of char, which requires adding an extra dimension. The size of the dimension is determined in a variety of ways and can be specified. It defaults to 64 and when read, the underlying string is either padded or truncated to that length.
Also note that the "Facility" attributes do not appear in the translation because they are neither global nor associated with a variable in the DDS.
The netCDF library DAP2 support code translate the DAP2 data model into the netCDF classic (netCDF-3) data model.
The netCDF-3 translation is designed to mimic as closely as possible the translation provided by the now obsolete libnc-dap2 system, except that some errors in that older translation have been fixed.
For illustrative purposes, the following example will be used.
The set of netCDF variables is derived from the fields with primitive base types as they occur in Sequences, Grids, and Structures. The field names are modified to be fully qualified initially. For the above, the set of variables are as follows. The coordinate variables within grids are left out in order to mimic the behavior of libnc-dap2.
In the OPeNDAP DAP2 protocol, there are a number of reserved keywords.
These keywords are case insensitive and if you use one as a netCDF variable name, you may encounter odd behavior such as case changes (depending on the client DDS/DAS parser).
The list of reserved keywords as used by the netCDF C library parser are as follows:
A variable's rank is determined from three sources.
If the type of the netCDF variable is char, then an extra string dimension is added as the last dimension.
For dimensions, the rules are as follows.
Fields in dimensioned structures inherit the dimension of the structure; thus the above list would have the following dimensioned variables.
Collect all of the dimension specifications from the DDS, both named and anonymous (unnamed) For each unique anonymous dimension with value NN create a netCDF dimension of the form "XX_\<i\>=NN", where XX is the fully qualified name of the variable and i is the i'th (inherited) dimension of the array where the anonymous dimension occurs. For our example, this would create the following dimensions.
If however, the anonymous dimension is the single dimension of a MAP vector in a Grid then the dimension is given the same name as the map vector This leads to the following.
For each unique named dimension "<name>=NN", create a netCDF dimension of the form "<name>=NN", where name has the qualifications removed. If this leads to duplicates (i.e. same name and same value), then the duplicates are ignored. This produces the following.
Note that this produces duplicates that will be ignored later.
At this point the only dimensions left to process should be named dimensions with the same name as some dimension from step number 3, but with a different value. For those dimensions create a dimension of the form "<name>M=NN" where M is a counter starting at 1. The example has no instances of this.
Finally and if needed, define a single UNLIMITED dimension name "unlimited" with value zero. Unlimited will be used to handle certain kinds of DAP2 sequences (see below).
This leads to the following set of dimensions.
The steps for variable name translation are as follows.
Take the set of variables captured above. Thus for the above DDS, the following fields would be collected.
All grid array variables are renamed to be the same as the containing grid and the grid prefix is removed. In the above DDS, this results in the following changes.
It is important to note that this process could produce duplicate variables (i.e. with the same name); in that case they are all assumed to have the same content and the duplicates are ignored. If it turns out that the duplicates have different content, then the translation will not detect this.
YOU HAVE BEEN WARNED.
The final netCDF-3 schema (minus attributes) is then as follows.
In practice, the unlimited dimension is dropped because it is unused.
There are differences with the original libnc-dap2 here because libnc-dap2 technically was incorrect. The original would have said this, for example.
Note that this is incorrect because it dimensions S1.FS2.f1(2,2) rather than S1.FS2.f1(2,3).
Any variable (as determined above) that is contained directly or indirectly by a Sequence is subject to revision of its rank using the following rules.
Let the variable be contained in Sequence Q1, where Q1 is the innermost containing sequence. If Q1 is itself contained (directly or indirectly) in a sequence, or Q1 is contained (again directly or indirectly) in a structure that has rank greater than 0, then the variable will have an initial UNLIMITED dimension. Further, all dimensions coming from "above" and including (in the containment sense) the innermost Sequence, Q1, will be removed and replaced by that single UNLIMITED dimension. The size associated with that UNLIMITED is zero, which means that its contents are inaccessible through the netCDF-3 API. Again, this differs from libnc-dap2, which leaves out such variables. Again, however, this difference is backward compatible.
If the variable is contained in a single Sequence (i.e. not nested) and all containing structures have rank 0, then the variable will have an initial dimension whose size is the record count for that Sequence. The name of the new dimension will be the name of the Sequence.
Consider this example.
The corresponding netCDF-3 translation is pretty much as follows (the value for dimension Q2 may differ).
Note that for example S1.SQ1.f1_0 is not actually used because it has been folded into the unlimited dimension.
Note that for sequences without a leading unlimited dimension, there is a performance cost because the translation code has to walk the data to determine how many records are associated with the sequence. Since libnc-dap2 did essentially the same thing, it can be assumed that the cost is not prohibitive.
In an effort to provide better performance for some access patterns, client-side caching of data is available. The default is no caching, but it may be enabled by prefixing the URL with the parameter "cache".
Caching operates as follows.
When a URL is first accessed using nc_open(), netCDF automatically does a pre-fetch of selected variables. These include all variables smaller than a specified (and user definable) size. This allows, for example, quick access to coordinate variables. This can be suppressed with the parameter "noprefetch".
Whenever a request is made using some variant of the nc_get_var() API procedures, the complete variable is fetched and stored in the cache as a new cache entry. Subsequence requests for any part of that variable will access the cache entry to obtain the data.
The cache may become too full, either because there are too many entries or because it is taking up too much disk space. In this case cache entries are purged until the cache size limits are reached. The cache purge algorithm is LRU (least recently used) so that variables that are repeatedly referenced will tend to stay in the cache.
The cache is completely purged when nc_close() is invoked.
In order to decide if you should enable caching, you will need to have some understanding of the access patterns of your program.
The ncdump program always dumps one or more whole variables so it turns on caching.
If your program accesses only parts of a number of variables, then caching should probably not be used since fetching whole variables will probably slow down your program for no purpose.
Unfortunately, caching is currently an all or nothing proposition, so for more complex access patterns, the decision to cache or not may not have an obvious answer. Probably a good rule of thumb is to avoid caching initially and later turn it on to see its effect on performance.
Currently, a limited set of client parameters is recognized. Parameters not listed here are ignored, but no error is signalled. All names are case insensitive.
The OPeNDAP support makes use of the logging facility of the underlying oc system (see http://www.OPeNDAP.org/oc). Note that this is currently separate from the existing netCDF logging facility. Turning on this logging can sometimes give important information. Logging can be enabled by using the client parameter "log" or "log=filename", where the first case will send log output to standard error and the second will send log output to the specified file.
Users should also be aware that if one is accessing data over an NFS mount, one may see some .nfsxxxxx files; those can be ignored.
Limited support for configuring the http connection is provided via parameters in the “.dodsrc” configuration file. The relevant .dodsrc file is located by first looking in the current working directory, and if not found, then looking in the directory specified by the “$HOME” environment variable.
Entries in the .dodsrc file are of the form:
That is, it consists of a key name and value pair and optionally preceded by a url enclosed in square brackets.
For given KEY and URL strings, the value chosen is as follows:
If URL is null, then look for the .dodsrc entry that has no url prefix and whose key is same as the KEY for which we are looking.
If the URL is not null, then look for all the .dodsrc entries that have a url, URL1, say, and for which URL1 has the same host and port as URL. All parts of the url's except host and port are ignored. For example, if URL = http//x.y/a, then it will match entries of the form [http//x.y/a]KEY=VALUE or [http//x.y/b]KEY=VALUE. It will not match an entry of the form _[http//x.y:8080]KEY=VALUE because the second has a port number (8080) different than the URL. Finally from the set so constructed, choose the first matching entry.
Currently, the supported set of keys (with descriptions) are as follows.
The related curl flags line indicates the curl flags modified by this key. See the libcurl documentation of the curl_easy_setopt() function for more detail (http://curl.haxx.se/libcurl/c/curl_easy_setopt.html).
For ESG client side key support, the following entries must be specified:
Additionally, for ESG, the HTTP.SSL.CERTIFICATE and HTTP.SSL.KEY entries should have same value, which is the file path for the certificate produced by MyProxyLogon. The HTTP.SSL.CAPATH entry should be the path to the "certificates" directory produced by MyProxyLogon.
-DCMAKE_USE_WINSSL=ON be used to provide SSL support.Author: Dennis Heimbigner
Email: dmh at ucar dot edu
Initial Version: 3/26/2009
Last Revised: 04/30/2020
1.9.1