GetData Bindings

home | download | API documentation | dirfile standards | mailing list | sourceforge | github

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:

Additionally, the GetData namespace includes the DataType enumeration, containing:

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:

IDL> DEFSYSV, "!GD", GETDATA_CONSTANTS()

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
>> help getdata
will provide an overview of the bindings.

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 using php-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:

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.

Table 1: Python and GetData data types
Python TypeGetData Types
int UINT8, INT8, UINT16, INT16, INT32
long UINT32, UINT64, INT64
float FLOAT32, FLOAT64
complex COMPLEX64, COMPLEX128
: Python2 only. In Python3 these types also use int.

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.

© 2009, 2010, 2012, 2014, 2018 D. V. Wiebe
Valid HTML 4.01 StrictValid CSS