opendap / loaddap Goto Github PK

Updated for loaddap 3.7.3

The configure script seems to be fixed for the recent versions of Matlab (2010 and onward).
However, it no longer checks the matlab version. This code will not compile unless Matlab
2009 or newer is present. Also note that it relies on what Mathworks now (mid-2015) terms
'legacy' mex functionality.

Tests updated - they should all now pass.

When an incompatible binary mex file is present the error message is now much more clear.

Updated for loaddap 3.7.0

I corrected the URLs usind in the examples and added a note regarding whodap 
because that command only works on the PC.

Updated for 3.6.1

Fixes for the URLs in the online documentation.

Updated for version 3.6.0

** Linux RPM USERS

You will need to add the RPMs using the --nodeps switch (rpm -Uvh --nodeps 
*.rpm) because the Matlab libraries that are dependencies are not in the
RPM database.

If you're reading this after installing using theLinux RPM, loaddap installs
into /usr/bin from the RPM and that's the only directory you need to add to
your matlabpath (because the help files go there as well; we install them in
a bin directory because automake wants to put the scripts there and because
it makes for a simpler configuration in Matlab).

** End Linux RPM Users

Be sure to add loaddap's directory to your matlabpath! For example, you could
add

     addpath /usr/local/bin

to startup.m. The order of the paths' in the matlabpath variable is
important! However you add the paths, /usr/local/bin should appear
before /usr/local/share/loaddap. If the order is reversed you will get
a error in matlab about mismatched parentheses. Here's what matlabpath
looks like when it's set correctly:

<code>
     >> matlabpath

                MATLABPATH

        /usr/local/bin
        /Applications/MATLAB71/toolbox/matlab/general
	.
	.
	.
</code>

Note: For some of the binary builds you may see a message like:

<code>
  Unable to load mex file:
  /home/xcst/codes_programms/cmex/yprime.mexglx.
  /usr/local/matlab7/bin/glnx86/../../sys/os/glnx86/libgcc_s.so.1:
  version `GCC_3.3' not found (required by /usr/lib/libstdc++.so.6)
  ??? Invalid MEX-file '/home/xcst/codes_programms/cmex/yprime.mexglx': 
</code>

This happens because some linux distributions ship with newer versions of
the GNU gcc compiler than the version Mathworks uses to build Matlab. A fix 
for this (documented on the Mathworks web site) is to rename 
<matlab root>/sys/os/glnx86/libgcc_s.so.1 to something else such as 
libgcc_s.so.1.orig. With that change Matlab will now use the libgcc library
bundled with your operating system. It's better to rename the library and not
delete it just in case the version bundled with you OS doesn't work with
your copy of Maltab (in which case you can just undothe rename; you can't
use loaddap, but at least Matlab will still work).

You may also get this error if you compile loaddap yourself. In that case
you have two choices. Either use the above fix or get and install the same
version of GNU's gcc compiler as was used to build your copy of Matlab and 
use that to build libdap and loaddap.

-------------------------------------------------------------------------------

For compilation and installation information, see the file INSTALL.

CONTENTS OF THIS DIRECTORY

The two main programs in this directory are loaddap and whodap (PC
only). These are Matlab command line clients from OPeNDAP which
provide a way to read data from DAP-enabled servers directly into
Matlab. The loaddap function reads data from an OPeNDAP server and
interns it in the Matlab workspace. The whodap function, which is
limited to the Windows versions of loaddap, provides a listing of the
variables in a dataset. Both commands accept DAP URLs as arguments. 

loaddap(<dataset URL>?<variables>)

Example:

<code>
    >> loaddap('http://test.opendap.org/dap/data/nc/fnoc1.nc?u,v')
    Creating matrix u (16 x 17 x 21) with 5712 elements.
    Creating matrix v (16 x 17 x 21) with 5712 elements.
</code>

Note that you need the quotes around the argument to loaddap because
Matlab recognizes commas as special characters.

whodap <dataset URL>

Example

<code>
    >> whodap http://test.opendap.org/dap/data/nc/fnoc1.nc
    Dataset {
	Int16 u[time_a = 16][lat = 17][lon = 21];
	Int16 v[time_a = 16][lat = 17][lon = 21];
	Float32 lat[lat = 17];
	Float32 lon[lon = 21];
	Float32 time[time = 16];
    } fnoc1;
</code>

Both whodap (PC only) and loaddap have online help (type `help
loaddap' at the Matlab prompt). Loaddap has many options, all
described in the on-line help. It can accept multiple URLs, rename
variables, be used to read dataset attribute information and be used
in assignment statements. Here's an example of loaddap called with an
option and returning values using an assignment statement. The -e
option tells loaddap to use the new error reporting scheme (see help
for details). The values of u and v are stored in a and b.

<code>
    >> [a, b] = loaddap('-e', 'http://test.opendap.org/dap/data/nc/fnoc1.nc?u,v');   
    >> 
</code>

OTHER CONTENTS OF THIS DIRECTORY

In addition to the two user programs, this directory includes:

writedap - Dereferences a DAP URL and returns a mixed ASCII and binary
stream of data. loaddap calls writedap to perform the actual data
fetch and this program must be in the same directory as loaddap. While
this program was originally intended to be used with loaddap, it can
also be used for other purposes as well. For example a user could save
binary data to a file with writedap. Note that with the `-f' option
writedap translates all simple types to either Float64 or String.

writedap can also be used to read from standard input, write ASCII
output and access the DDS for a given dataset. See writedap's online
help for information about these options.

BACKGROUND TECHNICAL INFORMATION

The following provides background technical information on the design
of loaddap.

There are two programs that comprise the OPeNDAP-Matlab command line
interface; loaddap and whodap. Both of these communicate with a third
program called writedap. writedap is a DAP2 client; programs pass
writedap one or more URLs along with some options, and writedap
returns the results from a DAP-enabled server.

A grammar for writedap

Note: writedap supports all of the DAP2 datatypes even though this
documentation doesn't show it.

Here is a pseudo grammar describing the output of writedap. I used *
as the Kleene closure (zero or more) and + as one or more. The idea is
simple; write the type and name of the variable each on one line and
data for it on the following line. For constructor types (Grid,
Sequence, Structure) it becomes more complex, but not much. For arrays
write Array, newline, the type, the name, the number of dimensions,
newline, a list of dimension sizes, newline and the data. Finish by
writing a newline.

While this means sending out some extra characters it makes the output
of writedap very simple to parse.  Strings are individually terminated
by a newline. A second newline follows the last string.

<code>
  <data request> :: <variable>*

  <variable> :: <simple variable>
             :: <vector variable>
             :: <constructor variable>

  <simple variable> :: Byte '\n' <variable name> '\n' <data> '\n'
                    :: Int32 '\n' <variable name> '\n' <data> '\n'
                    :: Float64 '\n' <variable name> '\n'  <data> '\n'
                    :: String '\n' <variable name> '\n' <string data> '\n'
                    :: Url '\n' <variable name> '\n' <string data> '\n'

  <vector variable> :: Array '\n' <array variable> '\n' <data> [see note 1]
                    :: List '\n' <list variable> '\n' <data>

  <constructor variable> :: Structure '\n' <struct variables> 
                         :: Sequence '\n' <sequence variables>
                         :: Grid '\n' <grid variables>

  <string data> :: <string 0> '\n' <string 1> '\n' ... <string n> '\n'

  <array variable> :: <variable type> ' ' <variable name> ' ' 
                      <number of dims> '\n' <dim size>+ 

  <list variable> :: <variable type> <variable name> <list size>

  <struct variables> :: <variable name> <num of elements> '\n' 
                        (<variable>)+

  <sequence variables> :: <variable name> <num of elements> '\n' 
                          (<variable>)+

  <grid variables> :: <variable name> '\n' 'array '\n' <array variable>
                      'map <num of arrays>\n' (<array variable>)+ 

  <error> :: Error '\n' <message> '\n'
</code>

Note: The vector type's data is sent using the print_val() method of
the vector's contained type. That is, for a vector of int32s, the
contained type is int32 and the print_val() method of the int32 class
is used to send the vector's values. This method writes binary values
and terminates them with a `\n'.  Thus, the vector variable's
print_val() methods do not need to send the `\n'.  Since we know that
all vector and ctor types must ultimately `lead to' simple types, it
is sufficient to have the simple types handle writing the `\n'
separators. Having the ctors (and vectors) do this too just means more
information for the recipient to parse.