Introduction
In addition to the C API described in the Using GetData document, various bindings to this library have been written which permit use of GetData in other programming languages. As of 0.9, bindings for the following languages are included in the GetData package:
Further documentation for these bindings is provided in the GetData
package in the /doc/ subdirectory. Additionally, all
bindings include a test suite (not installed) which shows rudimentary
usage of the bindings.
Both the Python and IDL bindings require a C99-compatible C compiler. If one cannot be found, these bindings will not be built.
C++ Bindings
The C++ bindings are implemented in a library (libgetdata++), and a
collection of header files installed in
${PREFIX}/include/getdata. The bindings declare a
GetData namespace containing three
classes:
- Dirfile, which encapsulates the C API's DIRFILE pointer, and is used to access Dirfile data and global metadata.
- Entry, which encapsulates the C API's gd_entry_t object, and is used to access and modify field metadata.
- Fragment, which is used to access and modify dirfile metadata with fragment scope (ie., byte sex, encoding scheme, frame offset and protection levels).
Null, Unknown, UInt8, Int8, UInt16, Int16, UInt32, Int32, UInt64, Int64, Float32, Float64, Complex64, Complex128,
which are aliases for the gd_type_t values (GD_NULL, GD_NULL, &c.); and the EntryType enumeration, containing:
NoEntryType RawEntryType, LincomEntryType, LinterpEntryType, BitEntryType, MultiplyEntryType, PhaseEntryType, PolynomEntryType, SBitEntryType, DivideEntryType, RecipEntryType, ConstEntryType, StringEntryType, IndexEntryType,
which are, similarly, aliases for the gd_entype_t values (GD_NO_ENTRY, GD_RAW_ENTRY, &c.). C-style parser callback functions can be used by these bindings. Vector data fetched by Dirfile.getdata() or provided to Dirfile.putdata() are specified via pointer, as in the C API. Complex valued metadata are returned as std::complex<double> objects, and should be specified in the same way.
Fortran Bindings
Two sets of Fortran bindings are provided. The basic bindings are
implemented in a compatibility library (libfgetdata.so) and defined in a
Fortran-77 source file, getdata.f, which will be installed
along with the GetData header files. This file defines several
convenient parameters including the DIRFILE flags, the data type
specifiers, and error codes, and declares all external subroutines defined
by the bindings. Any Fortran-77 compiler which implements the MIL STD
1753 (DoD Extension) INCLUDE statement (which any remotely modern compiler
should) can include this file to define these parameters for convenience.
These basic bindings define a Fortran-77 compliant interface with an API similar to the C API. However, instead of a DIRFILE pointer, the Fortran bindings use a numerical Dirfile unit number to refer to an open dirfile. Space is available in the compatibility library for only 1023 dirfile units. If an application attempts to open more than 1023 dirfiles simultaneously, the compatibility library will emit an error message on standard error and raise SIGABRT. Passing an invalid dirfile unit number to a subroutines which requires one as input will result in the call failing with error code GD_EBD (= GD_E_BAD_DIRFILE). The exceptions to this are GDCLOS and GDDSCD (corresponding to the C API's gd_close() and gd_discard()) which ignore invalid dirfile units.
Integers passed to the bindings are expected to have the same size as the C API's int type. As a result, largefile support may not present in the Fortran bindings, if this is not a 64-bit type. All character string arguments require also an integer indicating the size of the character buffer provided. In cases where the bindings return a string value, the value will not be returned if the string length supplied is too short. In these cases, the character string will be left untouched, but the integer indicating the string length will be updated to indicate the required string length. The exception to this is GDESTR (the Fortran-77 equivalent to gd_error_string()), which simply truncates the string it outputs, as the C API does.
Because of shortcomings in the Fortran-77 specification (for instance,
the six character limitation on identifier length), a second set of
Fortran bindings is implemented on top of the Fortran-77 bindings. These
second bindings conform to the Fortran-95 standard and declare a GetData
module, described by a getdata.mod file installed alongside
the GetData headers. The Fortran-95 bindings provide longer identifier
names, stronger type-safety, and abstract data types as compared to the
basic Fortran-77 bindings, and should be preferred when possible.
Furthermore, while character string arguments in the Fortran-77 bindings
require also an integer indicating the size of the character buffer, the
Fortran-95 bindings do not.
The Fortran-95 bindings are a simple, light-weight wrapper around the Fortran-77 bindings, and calls to the two sets of bindings may be mixed, if desired, without ill effect. Both sets of bindings provide the C API constants used by the library.
IDL Bindings
Bindings are provided for the Interactive Data Language (IDL) developed by Research Systems, Incorporated (now Exelis, Inc.). The bindings are implemented in a dynamically loaded module (DLM)idl_getdata.so which is
described by idl_getdata.dlm both of which will be installed
in IDL's DLM search path. The bindings should work with any version of
IDL from version 5.5 onwards, but are not compatible with earlier
versions.
Because the GetData library relies on a large number of symbolic constants, a convenience function, GETDATA_CONSTANTS() is provided. This function will create a structure of constants, with member names identical to the GetData C API's symbolic constants, but without the initial GD_ (eg. E_OK, INT8, &c.). This is a structure of type GD_CONSTANTS, which is defined by the bindings. The typical use of this function is to define a new system variable, called !GD which can then be used to reference these constants, when necessary. This is done using the following command:
Instead of using a DIRFILE pointer, an integer dirfile unit number is used to refer to an open dirfile object. Space is available in the bindings for only 1023 dirfile units. If an application attempts to open more than 1023 dirfiles simultaneously, the bindings will emit an error message and immediately return to the interpreter. Passing an invalid dirfile unit number to a procedure which requires one as input (other than DIRFILE_CLOSE, which will simply ignore it) will result in the call failing with error code !GD.E_BAD_DIRFILE. IDL supports all GetData data types with the exception of INT8. Attempting to return data as INT8 will result in an error.
Because of licensing restrictions, most pre-built versions of GetData lack IDL bindings. A stand-alone source package is provided for these situations which permits building just the IDL bindings against an already installed GetData. See the download section.
MATLAB Bindings
Bindings are provided for MATLAB developed by The MathWorkds, Incorporated. The bindings are implemented as a combination of native MATLAB and MEX files, plus a compatibility library (libgetdata_matlab.so). By default, the MATLAB bindings are
installed in ${libdir}/getdata/matlab/getdata, which should
be added to the MATLAB search path. After installation, full
documentation for the bindings are provided from within the MATLAB help
system. After installing the bindings, running
Because of licensing restrictions, most pre-built versions of GetData lack MATLAB bindings. A stand-alone source package is provided for these situations which permits building just the MATLAB bindings against an already installed GetData. See the download section.
Perl Bindings
Bindings to Perl5 are provided in a Perl module (GetData.pm) backed by an XS interface library
(GetData.so). The bindings should work with any version of
Perl5 from 5.6.0 onwards. The core module Math::Complex is
used to represent complex data in the bindings, which otherwise require
no other modules to run. (ExtUtils::MakeMaker is needed to
build the bindings, and Test::Harness to test them, both also
core modules).
The bindings are low-level and operate on a simplistic
GetData::Dirfile object, which may either be used similarly
to the C API's DIRFILE pointer, or
else in a more object-oriented way. The C API's gd_entry_t structure is represented using a hash.
Data may be returned as either a packed string (which is fast), or else
unpacked into an array (which is not). The format requirements of data
passed to the library is similarly flexible. Perl is not well suited to
numerical analysis, and the bindings may be inefficient.
PHP Bindings
Bindings to PHP5 and PHP7 are provided in a PHP extension (called "getdata") which also defines all the GetData constants (GD_RDONLY, GD_E_OK, &c.). The bindings are configured usingphp-config, which should provide all
necessary configuration.
In PHP, GetData's DIRFILE object is
represented by a Dirfile resource, allocated
by gd_open().
The DIRFILE associated with a
Dirfile resource is automatically discarded and de-allocated when the
resource goes out of scope and is reclaimed by GC. Typically this means
that a Dirfile opened with these bindings stays open only while the
calling script runs. However, Dirfile resources can also be made
persistent by calling gd_popen() instead. (See
Persistent Database Connections in the PHP manual for details on
persistent resources.) A persistent Dirfile resource is not collected by
GC when it goes out of scope. Call gd_discard
or gd_close to explicitly delete it. See the
discussion of gd_popen() in the README.php file in the
GetData documentation details on retrieving previously-created persistent
Dirfile resources.
Python Bindings
Bindings to Python are provided using a Python Extension Module (pygetdata.so), which defines a pygetdata module. These bindings should work with any Unicode-enabled 2.x series Python interpreter from version 2.4 onwards and any 3.x series Python interpreter from version 3.2 onwards. NumPy is required by the bindings.The pygetdata module defines three classes:
- dirfile, which encapsulates the C API's DIRFILE pointer, and is used to access Dirfile data and global metadata.
- entry, which encapsulates the C API's gd_entry_t object, and is used to access field metadata.
- fragment, which is used to access and modify dirfile metadata with fragment scope (ie., byte sex, encoding scheme, frame offset and protection levels).
The pygetdata module also contains all the GetData API constants: pygetdata.UINT8, pygetdata.E_OK, pygetdata.RAW_ENTRY, &c.
GetData library errors are converted into Python exceptions by the module. In general, functions which accept numerical data, such as dirfile.putdata(), automatically choose an appropriate C type for transferring the data to the dirfile, and specifying an explicit type is not needed. By default, calls to dirfile.getdata() will return a NumPy array with a dtype corresponding to the return type specified. A Python list can be returned as well, with data coerced to the native python numeric types as listed in Table 1.
| Python Type | GetData Types |
|---|---|
| int | UINT8, INT8, UINT16, INT16, INT32 |
| long† | UINT32, UINT64, INT64 |
| float | FLOAT32, FLOAT64 |
| complex | COMPLEX64, COMPLEX128 |
Because the Dirfile Standards specify no character encoding for metadata, by default the strings returned by the GetData library are encoded. They can be decoded to Unicode by specifying a character encoding in the bindings, either globally, or else on a per-object basis.
All pygetdata functions may be given positional or keyword parameters.
