1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
|
% These bindings provide light-weight bindings to the GetData C library for
% use withing MATLAB. In general, there is a one-to-one mapping between C API
% functions and matlab functions. Differences in behaviour, where notable, are
% provided in the corresponing function help.
%
% The Dirifle object:
% Dirfile objects returned from GD_OPEN and similar should be treated as
% opaque objects. They should not be used other than when passing to a
% function in these bindings.
%
% GetData symbolic constants:
% Like the underlying C API, the GetData bindings make use of a large number
% of special numbers. For convenience, a struct containing all these numbers
% is provided by the GETDATA_CONSTANTS function, which is typically used by
% doing something like:
%
% >> GD = GETDATA_CONSTANTS;
%
% This then allows the use of these constants as GD.UINT8, GD.RAW_ENTRY, &c.,
% which is both shorter than using the function directly, i.e.,
% GETDATA_CONSTANTS.UINT8, and also only requires evaluating the
% GETDATA_CONSTANTS function once.
%
% In this documentation, when a reference is made to a GetData symbolic
% constant, it is done so as if the GD variable had been created as above.
% The reader should understand, e.g., GD.UINT8 as referring to the same
% special number as the similarly-named C API's symbolic constant, e.g.,
% GD_UINT8.
%
% Input and Output:
% Functions in these GetData bindings produce either one or zero scalar or
% vector outputs, as explained in the corresponding function documentation.
%
% In general, where the C API would allow a NULL string pointer, these
% bindings accept a numeric zero (0) instead of a string input in place of a
% NULL.
%
% Unlike the C Library, real and complex data may be used interchangeably in
% function calls.
%
% Error reporting:
% GetData C Library errors are represented in MATLAB as standard exceptions
% (see MEXCEPTION). In general, GetData functions should be evaluated in a
% TRY ... CATCH ... END block. GetData-specific exceptions can be identified
% through their MEXCEPTION.identifier. The component part of a GetData
% MEXCPETION.identifier will always start with 'GetData:'.
%
% Exceptions representing a GetData C Library error will have the component
% identifier 'GetData:Lib'. Exceptions generated by the bindings themselves
% (almost all of which are failures in data conversion between MATLAB and C
% API data types) will have the component identifier 'GetData:GDMX'. For C
% Library errors, the mnemonic part of the MEXCEPTION.identifier corresponds
% to the C library error code (e.g. 'GetData:Lib:BadCode'). For C Library
% errors, numeric error codes can be obtained using the GD_ERROR function, as
% in the C Library. The return value of GD_ERROR is unspecified after an
% exception in the MATLAB bindings (i.e. a 'GetData:GDMX' exception).
%
% The Entry structure:
% Functions which deal with generic field metadata (GD_ADD, GD_ALTER_ENTRY,
% GD_ENTRY, &c.) use structures mirroring the C API's gd_entry_t object with
% the following exceptions:
%
% * In entries with multiple input fields, .IN_FIELDS is a cell array of
% strings of the appropriate length. For entries with a single input field,
% .IN_FIELDS may be either a simple string or else a cell array of length
% one.
%
% * A distinction is not made between real and complex data. As a result,
% the entry struct for, say, a POLYNOM, stores co-efficients in the .A
% member, regardless of whether they are complex or purely real.
%
% * LINCOM entries don't provide a .N_FIELDS member, nor do POLYNOM entries
% provide a .POLY_ORD member; these values should be determined by
% determining the length of .IN_FIELDS, .M, or .B for LINCOMs or of .A for
% POLYNOMs.
%
% * The .SCALAR and .SCALAR_IND members are provided for field types which
% allow non-literal parameters. Where the C API would have NULL pointers
% in .SCALAR to indicate a literal, the bindings will have a numeric 0 in
% the corresponding .SCALAR cell array element. As with .IN_FIELDS, a
% length-one .SCALAR cell array may be replaced by a scalar.
%
% See gd_entry(3) in section 3 of the UNIX manual for details on the C API's
% gd_entry_t object.
%
% Function list:
% NOTE: accompanying documentation for the functions below in general only
% point out differences in behaviour between these MATLAB bindings and
% the underlying C API function which the MATLAB function wraps. Users
% should also consult the C API documentation, which can be found in
% section 3 of the UNIX manual, e.g.
%
% $ man 3 gd_open
%
|
