The following known issues exist:
One transfer at a time with any given connection. The SWIG interface permits reusing an NDS connection for multiple requests. However, while one request is in progress over a given connection, the server will refuse most other requests. As a consequence, some care must be taken when using the online data retrieval functions iterate()
and next()
. For example, consider the following MATLAB transcript in which iterate()
is called twice on the same connection
object:
>>conn = nds2.connection('nds.ligo-la.caltech.edu');
>>conn.iterate(1037022904, 1037023024, {'L1:PSL-ISS_PDA_OUT_DQ'});
>>conn.iterate(1037022904, 1037023024, {'L1:PSL-ISS_PDA_OUT_DQ'});
Error using nds2.connection/iterate Java exception occurred: java.lang.RuntimeException: Another transfer is already in progress. Complete the transfer or retry on a new connection object. at nds2.nds2JNI.connection_iterate__SWIG_0(Native Method) at nds2.connection.iterate(connection.java:87)
The above example could be fixed by (a) creating a second connection
object for the second call to iterate()
or (b) completing the first request by consuming all of the data with next()
.
Note that the find_channels()
and fetch()
methods always complete their transfers before returning, so it is safe to issue them repeatedly in any combination.
Windows installer by default does not add NDS libraries to the system PATH. The Windows installer by default has the option "Do not add nds2-client to the system PATH" checked. Be sure to choose one of the other two options, "Add nds2-client to the system PATH for all users" or "Add nds2-client to the system PATH for current user", so the proper dll files can be loaded at runtime.
Windows installer includes only the MATLAB/Java language interface. The Windows installer does not include the Python and Octave language interfaces.
Requesting unfiltered channel lists from servers that advertise millions of channels is slow and memory intensive.
Some NDS servers (notably nds.ligo.caltech.edu
) advertise millions of channels. Attempting to retrieve the full channel list from such a server may involve transferring as much as a hundred megabytes of channel metadata over the network. Moreover, preparing the representation of millions of channels as objects in Python, Octave, or MATLAB is memory-intensive, consuming a few hundred bytes per object. As a result, requesting the full, un-filtered list of all channels with find_channels()
can consume hundreds of megabytes of RAM when working with such NDS servers. (Note that the legacy MATLAB interface also has this issue.) A remedy would be to have the find_channels()
method return an iterator rather than a list.
Capitalization of method names in Java.
According to prevailing code conventions, in C, Python, and Octave, function names are all lowercase with underscores (_
) separating words, as in find_channels
. The MATLAB interface, on the other hand, follows the "camel case" convention of Java, as in findChannels
.
Indexing of arrays.
In C and Python, arrays are indexed starting with 0
, whereas in Octave and MATLAB arrays are indexed starting with 1
. (On the other hand, if you use the MATLAB/Java bindings directly from Java, 0
-based indexing applies.) Also, the syntax for accessing elements of sequences returned by find_channels()
, fetch()
, and next()
are slightly different in the target languages: use square brackets []
in C, Python, and Java; curly braces {}
in Octave; and parentheses ()
in MATLAB.
Java strings and MATLAB.
MATLAB does not automatically convert Java strings to MATLAB char arrays in all circumstances, so some methods in the Java interface have return types of char [][]
instead of String
. This subtlety does not affect MATLAB users; it is only a concern for those who wish to use the NDS interface in Java source code.
Cyrus SASL 2.1.25 and MacPorts.
NDS2 authentication currently does not work the MacPorts package cyrus-sasl2
version 2.1.25. If you are compiling nds2-client
from source, build against either Apple's own distribution of cyrus-sasl2 (which comes preinstalled on every Mac) or build against the MIT Kerberos GSSAPI.