"SfR Fresh" - the SfR Freeware/Shareware Archive

Member "libdap-3.8.2/README" of archive libdap-3.8.2.tar.gz:

    1 
    2 $Id: README 18929 2008-06-23 19:56:53Z jimg $
    3 
    4 Updated for version 3.8.2 (23 June 2008)
    5 
    6 HTTP Cache and win32 installer fixes (the latter are actually in the 3.8.1
    7 installer for winXP). API change: The functions used to merge ancillary data
    8 have been moved to their own class (Ancillary).
    9 
   10 Updated for version 3.8.1 (10 June 2008)
   11 
   12 The syntax for PROXY_SERVER in the .dodsrc file was relaxed. See the .dodsrc
   13 file for more information.
   14 
   15 Updated for Version 3.8.0 (29 February 2008)
   16 
   17 The libdap classes and code are now inside of the libdap namespace. In order
   18 to access any of the classes, for example, you will need to do one of the
   19 following. After including the libdap headers you can:
   20 
   21 1. add a using statement for the entire libdap namespace:
   22 
   23 using namespace libdap ;
   24 
   25 2. add a using statement for the classes that you will be using:
   26 
   27 using libdap::DAS ;
   28 
   29 3. inside your code scope the use of libdap classes.
   30 
   31 libdap::DAS *das = code_to_get_das() ;
   32 
   33 Added method to HTTPCache to return not only the FILE pointer of a cached
   34 response but also the name of the file in the cache, to allow for this file
   35 name to be passed to data handlers in the BES to be read.
   36 
   37 See NEWS for more information about changes for this version and ChangeLog
   38 for the gory details.
   39 
   40 Updated for Version 3.7.10 (28 November 2007)
   41 
   42 A bug fix release. See NEWS.
   43 
   44 Updated for Version 3.7.9 (13 Novenber 2007)
   45 
   46 This release is a bug fix and refactoring release. Old classes which were no
   47 longer used have been removed, the FILE* output methods are slated to be
   48 replaced with ones which will use iostream and will support a chucked
   49 transfer 'Marshaller,' and the transfer_data() methods have been made a
   50 formal part of the library, implemented for all classes, fixed and renamed to
   51 intern_data(). Many bugs in the library were also fixed.
   52 
   53 Updated for version 3.7.8 (26 June 2007)
   54 
   55 The major fixes in this version are memory errors found and fixed in the
   56 Regex class and HTTP header processing software. This version also supports
   57 pkg-config on hosts that have that installed.
   58 
   59 See NEWS for more information about changes for this version and ChangeLog
   60 for the gory details.
   61 
   62 Notes for version 3.7.7 (2 May 2007)
   63 
   64 The major fix here is to the source build. We've fixed the issue where source
   65 builds failed to make the dapserver and dapclient libraries.
   66 
   67 Notes for version 3.7.6 (12 March 2007)
   68 
   69 Two bug fixes, both minor. Problems in the linear_scale() constraint
   70 expression function and a bad/missing #include in GNURegex.h were fixed.
   71 
   72 There was an error in the INSTALL file sent out in the previous release. It
   73 said this library implemented DAP version 3.2, but in fact it implements
   74 version 3.1. The version 3.2 release will be along soon (RSN).
   75 
   76 Notes for version 3.7.5 (7 Feb 2007)
   77 
   78 This version includes many fixes from the first Server4 beta release
   79 plus fixes for the server-side functions. It also includes a smoother
   80 Win32 build.
   81 
   82 Notes for version 3.7.4 (2 Jan 2007)
   83 
   84 Release for the Server4 beta release.
   85 
   86 Notes for version 3.7.3 (24 Nov 2006)
   87 
   88 This version of libdap contains a beta release of the server-side functions
   89 geogrid(), geoarray(), linear_scale() and version(). These can be used to
   90 select parts of Grids and Arrays using latitude and longitude values instead
   91 of array position indexes. The linear_scale() function can be used to scale
   92 variables (including those return by other function) using 'y = mx + b'. The
   93 version() function can be used to find out which versions of the functions are
   94 installed.
   95 
   96 EXAMPLES
   97 
   98 To get version information use the 'version()' function. Currently, version()
   99 can only be called when asking for data, and you must give the name of a data
  100 source, although in the default version of version() the data source is not
  101 used. The version function takes one optional argument which may be the strings
  102 'help' or 'xml'. Use 'help' to get help on using the function; use 'xml' to get
  103 version information encoded using XML instead of plain text:
  104 
  105 <code>
  106 [jimg@zoe libdap]$ url=http://test.opendap.org/dap/data/nc/coads_climatology.nc
  107 [jimg@zoe libdap]$ ./getdap -D "$url?version()"
  108 The data:
  109 String version = "Function set: version 1.0, grid 1.0, geogrid 1.0b2, 
  110 		          geoarray 0.9b1, linear_scale 1.0b1";
  111 
  112 [jimg@zoe libdap]$ ./getdap -D "$url?version(help)"
  113 The data:
  114 String version = "Usage: version() returns plain text information about ...
  115 
  116 [jimg@zoe libdap]$ ./getdap -D "$url?version(xml)"
  117 The data:
  118 String version = "<?xml version=\"1.0\"?>
  119     <functions>
  120         <function name=\"version\" version=\"1.0\"/>
  121         <function name=\"grid\" version=\"1.0\"/>
  122         <function name=\"geogrid\" version=\"1.0\"/>
  123         <function name=\"geoarray\" version=\"1.0\"/>
  124         <function name=\"linear_scale\" version=\"1.0\"/>
  125     </functions>";
  126 
  127 The geogrid function can only be used with variables that are Grids:
  128 
  129 [jimg@zoe libdap]$ getdap -d "$url"
  130 Dataset {
  131     Float64 COADSX[COADSX = 180];
  132     Float64 COADSY[COADSY = 90];
  133     Float64 TIME[TIME = 12];
  134     Grid {
  135       Array:
  136         Float32 SST[TIME = 12][COADSY = 90][COADSX = 180];
  137       Maps:
  138         Float64 TIME[TIME = 12];
  139         Float64 COADSY[COADSY = 90];
  140         Float64 COADSX[COADSX = 180];
  141     } SST;
  142     Grid {
  143     .
  144     .
  145     .
  146 </code>
  147     
  148 Pass the name of the Grid variable and the upper-left and lower-right corners 
  149 of the lat/lon rectangle to geogrid. Optionally, pass one or more relational
  150 expressions to select parts of dimensions that are not lat/lon. 
  151 
  152 Note: in libdap 3.7.3 calling geogrid with a constraint on each dimension
  153 may return incorrect values that indicate missing data even though data should
  154 have been returned.
  155 
  156 <code>
  157 [jimg@zoe libdap]$ getdap -D "$url?geogrid(SST,30,-60,20,-60,\"TIME=366\")"
  158 The data:
  159 Grid {
  160   Array:
  161     Float32 SST[TIME = 1][COADSY = 7][COADSX = 2];
  162   Maps:
  163     Float64 TIME[TIME = 1];
  164     Float64 COADSY[COADSY = 7];
  165     Float64 COADSX[COADSX = 2];
  166 } SST = {  Array: {{{24.4364, 25.0923},{23.7465, 24.4146},{19.843, 23.6033},
  167 {16.8464, 17.7756},{16.65, 16.818},{-1e+34, 15.3656},{18.7214, 13.1286}}}  
  168 Maps: {366}, {19, 21, 23, 25, 27, 29, 31}, {-61, -59} };
  169 </code>
  170 
  171 The geoarray() function works like geogrid() except that it's used to select
  172 from an Array variable and not a Grid. In addition to the four lat/lon values
  173 for selection rectangle, the caller must supply the data's corner points. A 
  174 subsequent release of libdap will include a version that reads the data extent
  175 from the data source when possible so caller's won't normally have to know the
  176 data's extent ahead of time.
  177 
  178 The linear_scale() function take either one or three arguments. The first
  179 (only) argument is the name of a variable or the return from another
  180 function. This variable will be scaled using the 'y = mx + b' equation where
  181 'x' is the value(s) of the input variable and 'm' and 'b' are read from the
  182 data source using the values of attributes name 'scale_factor' and
  183 'add_offset.' If these are not present, or to over ride their values, m and b
  184 can be supplied using the second and third arguments.
  185 
  186 Note that there are still some problems with linear_scale() in this release.
  187 
  188 See NEWS and ChangeLog for information about other changes
  189 
  190 Notes for version 3.7.2
  191 
  192 This version of libdap is required for the 9/15/06 alpha release of Server4.
  193 The library now contains software which enables Server4 to build the ASCII
  194 data response for all types of variables, including Sequence and nested
  195 Sequence variables. These features are additions to the API, so older code
  196 will work just fine with the new library. See NEWS for more specific info
  197 about bug fixes.
  198 
  199 Notes for version 3.7.1
  200 
  201 This is a bug fix release (mostly) made for users of the netcdf client
  202 library who need a fix for a problem dealing with attributes from the HDF4
  203 server. 
  204 
  205 NOTES for version 3.7.0
  206 
  207 This version includes new features and an implementation change.
  208 
  209 This version of libdap now returns the DAP protocol version number, 3.1, in
  210 an HTTP response header. Use this to determine which protocol version the
  211 library implements. The inclusion of a protocol version number is the sole
  212 official new feature of DAP 3.1. Use Connect::get_protocol() to get the
  213 version number. Clients can use this to determine the features supported by a
  214 server. The Connect::get_version() method can still be used to get our
  215 server's implementation version. The distinction is that as more groups
  216 provide their own implementations of the DAP, the protocol version will
  217 provide a way for clients to determine capabilities independently of
  218 implementation.
  219 
  220 The libdap library now contains an implementation of the DDX object/response,
  221 although this is an alpha implementation and it's actually been part of the
  222 library for some time now. The implementation contained in this version of
  223 the library is close enough to the version we intend for DAP4 that developers
  224 can start to use it. Most of the server handlers will return DDXs when asked.
  225 
  226 The DDX combines the information previously held by the DDS and DAS objects,
  227 making it much easier to associate attributes to variables. As the name
  228 suggests, the DDX uses XML rather than curly-braces. You can drop the DDX
  229 into your favorite XML parser and get a DOM tree; no need to use our parsers.
  230 However, libdap contains a nice SAX parser that will build the libdap objects
  231 directly from the XML DDX object/response. Also included in libdap are
  232 methods to build a DDX using a DDS and DAS, so there's an easy migration path
  233 for both servers and clients.
  234 
  235 Finally, the library contains two structural changes. First, the library
  236 named 'libdap' now holds the DAP implementation while two new libraries,
  237 'libdapclient' and 'libdapserver', now hold the client and server helper
  238 classes which are not strictly part of the DAP. Secondly, the DDS/DDX object
  239 now takes the constraint evaluator as a parameter. The class
  240 ConstraintEvaluator holds our default evaluator, but it's now possible to use
  241 your own evaluator .
  242 
  243 NOTES for version 3.6.1
  244 
  245 Version 3.6.1 is bug fix release.
  246 
  247 NOTES for version 3.6.0
  248 
  249 This version of the library may not work older source code. Many of the 
  250 deprecated methods have been removed. 
  251 
  252 Added are headers which send information about the version of the DAP protocol
  253 that the library implements (in contrast to the implementation of the library
  254 itself). A new header named XOPeNDAP-Server is used to send information about
  255 the implementation of servers.
  256 
  257 The libtool interface version has been incremented from 3 to 4 (these versions
  258 do no track the software's release version since several releases might 
  259 present compatible binary interfaces). 
  260 
  261 NOTES for version 3.5.3
  262 
  263 This version of libdap++ cannot be used to build the 3.4.x and previous
  264 clients and/or servers. However, client and servers built using this code
  265 _will_ work with the older clients and servers.
  266 
  267 WHAT'S IN THIS DIRECTORY?
  268 
  269 This directory contains the OPeNDAP C++ implementation of the Data
  270 Access Protocol version 2 (DAP2) with some extensions that will be
  271 part of DAP3.  Documentation for this software can be found on the
  272 OPeNDAP home page at http://www.opendap.org/. The NASA/ESE RFC which
  273 describes DAP2, implemented by the library, can be found at
  274 http://spg.gsfc.nasa.gov/rfc/004/.
  275 
  276 The DAP2 is used to provide a uniform way of accessing a variety of
  277 different types of data across the Internet. It was originally part of
  278 the DODS and then NVODS projects. The focus of those projects was
  279 access to Earth-Science data, so much of the software developed using
  280 the DAP2 to date has centered on that discipline. However, the DAP2
  281 data model is very general (and similar to a modern structured
  282 programming language) so it can be applied to a wide variety of
  283 fields.
  284 
  285 The DAP2 is implemented as a set of C++ classes that can be used to
  286 build data servers and clients. The classes may be specialized to
  287 mimic the behavior of other data access APIs, such as netCDF. In this
  288 way, programs originally meant to work with local data in those
  289 formats can be re-linked and equipped to work with data stored
  290 remotely in many different formats.  The classes can also by
  291 specialized to build standalone client programs.
  292 
  293 The DAP2 is contained in a single library: libdap++.a. Also included
  294 in the library are classes and utility functions which simplify
  295 building clients and servers.
  296 
  297 WHAT ELSE IS THERE?
  298 
  299 The file README.dodsrc describes the client-side behavior which can be
  300 controlled using the .dodsrc file. This includes client-side caching,
  301 proxy servers, et c., and is described in a separate file so it's easy
  302 to include in your clients.
  303 
  304 The file README.AIS describes the prototype Ancillary Information
  305 Service (AIS) included in this version of the library. The AIS is
  306 (currently) a client-side capability which provides a way to augment
  307 DAP attributes. This is a very useful feature because it can be used
  308 to add missing metadata to a data source. The AIS is accessed by using
  309 the AISConnect class in place of Connect in your client.
  310 
  311 This directory also contains test programs for the DAP2, a sample
  312 specialization of the classes, getdap (a useful command-line web
  313 client created with DAP2) and dap-config (a utility script to simplify
  314 linking with libdap.a). Also included as of version 3.5.2 is
  315 libdap.m4, an autoconf macro which developers can use along with
  316 autoconf to test for libdap. This macro will be installed in
  317 ${prefix}/share/aclocal and can be by any package which uses autoconf
  318 for its builds. See the file for more information.
  319 
  320 We also have Java and C versions of the DAP2 library which
  321 inter-operate with software which uses this library. In other words,
  322 client programs built with the Java DAP2 implementation can
  323 communicate with servers built with this (C++) implementation of the
  324 DAP2. The C DAP2 library, called the Ocapi, only implements the
  325 client-side part of the protocol. Clients written using the Ocapi are
  326 interoperable with both the Java and C++ DAP2 libraries. Note that the
  327 Ocapi is in early beta and available only from CVS at this time (5 May
  328 2005).
  329   
  330 THREAD SAFETY
  331 
  332 We don't need to do this since the STL is also not thread safe. Users
  333 of libdap have to be sure that multiple threads never make
  334 simultaneous and/or overlapping calls to a single copy of libdap. If
  335 several threads are part of a program and each will make calls to
  336 libdap, either those threads must synchronize their calls or arrange
  337 to each use their own copy of libdap.  Some aspects of the library
  338 ''are'' thread-safe: the singleton classes are all protected as is the
  339 HTTP cache (which uses the local file system).
  340 
  341 INSTALLATION INSTRUCTIONS
  342 
  343 See the file INSTALL in this directory for information on building the
  344 library and the geturl client.
  345 
  346 COPYRIGHT INFORMATION
  347 
  348 The OPeNDAP DAP library is copyrighted using the GNU Lesser GPL. See
  349 the file COPYING or contact the Free Software Foundation, Inc., at 59
  350 Temple Place, Suite 330, Boston, MA 02111-1307 USA. Older versions of
  351 the DAP were copyrighted by the University of Rhode Island and
  352 Massachusetts Institute of Technology; see the file COPYRIGHT_URI. The
  353 file deflate.c is also covered by COPYRIGHT_W3C.