Copies the selected cell elements from the selected area of interest of the given Data Table into a space in memory to which the user has direct access. All memory for the data is allocated within the store provided by the caller. See the comments for the function SE_CreateStore() for details on the function and behavior of stores.
A Data Table is an N-dimensional collection of cells. Each Data Table defines a signature, which applies to the entire Data Table, defining how many elements (values) will be contained in each cell, what the type of each element will be (e.g. SE_INT16, SE_FLOAT64, or ...) and an EDCS Attribute Code (the meaning) for each element.
The extent elements are ordered and the data is scanned into the buffer according to the ordering and fields of the Axis components of the Data Table. For example, if the Data Table has
Axis 0 = Regular_Axis( axis_type = EDCS_AC_SPATIAL_GEODETIC_LONGITUDE,
axis_unit = SE_UNITS_DEGREE_ARC,
axis_value_count = 20,
interpolation_type = SE_LINEAR_INTERPOLATION,
first_value = 0.0,
spacing = 1.0,
values_are_ints = SE_FALSE,
type_of_spacing = SE_LINEAR_SPACING,
axis_alignment = SE_ALIGN_LOWER
)
Axis 1 = Regular_Axis( axis_type = EDCS_AC_SPATIAL_GEODETIC_LATITUDE,
axis_unit = SE_UNITS_DEGREE_ARC,
axis_value_count = 30,
interpolation_type = SE_LINEAR_INTERPOLATION,
first_value = 52.0,
spacing = -0.5,
values_are_ints = SE_FALSE,
type_of_spacing = SE_LINEAR_SPACING,
axis_alignment = SE_ALIGN_LOWER
)
Then extents_ptr->
start_array[0] and
extents_ptr->stop_array[0] refer to
geodetic longitude, and the corresponding [1] elements refer to geodetic
latitude. The API function places data into the caller-provided buffer
with geodetic latitude increasing fastest, corresponding to a 'C' array
indexed buffer[long_idx][lat_idx]. In the example, because the spacing on
the geodetic latitude axis is negative, increasing lat_idx actually
corresponds to scanning southward through the grid locations.
There are two differences between this SE_GetElementOfDataTable() function and the SE_GetDataTable() function.
1st difference - only one type of element from each cell is returned. The user defines a single desired element for this function, instead of an array of elements as defined for the SE_GetDataTable() function. Because only one type element is returned, only one type of value is being returned (only one type of value is being copied into the memory provided by the user). This leads to the second difference,
2nd difference - no space is wasted. See the
SE_GetPackedDataTable() function
comments for a description of how
SE_GetDataTable() wastes
space. The reason this function,
SE_GetElementOfDataTable(),
doesn't
waste space is because the data being returned by this function is
homogeneous. Since only one element is being returned, only one type
value is being returned. Since the type of value is known (based on
the type of value for that element), the type of value is not repeated
throughout the returned data. The user is expected to know the type
of value based on the value type for that element (which was defined
in the signature of the Data Table). This
function also avoids
wasting space because it does not use an
SE_PROPERTY_DATA_VALUE struct
for its return values. Since the type of return values is known,
an array of that type is provided. For example, if
SE_UINT16s are the
type of value requested, then the user allocates an array of
SE_UINT16s,
passes in a pointer to that array, and this function fills in the
array with the appropriate SE_UINT16 values.
No space is wasted because
the type of data is constant (in this example, it was always a
SE_UINT16).
SE_NULL_REQUIRED_PARAMETER - if result_out_ptr was NULL. In this case, *result_out_ptr is left unaltered.
SE_INVALID_OR_NULL_OBJECT - if data_table is not a handle to a valid, active (i.e., unfreed) Data Table object. In this case, *data_out_ptr is set to NULL.
SE_UNRESOLVED_OBJECT - if data_table is an unresolved object (see SE_OBJECT's comments for details on how this condition occurs). In this case, *result_out_ptr is set to NULL.
SE_INVALID_OR_NULL_STORE - if store_in is not a handle to a valid SE_STORE created by SE_CreateStore(). In this case, *result_out_ptr is not affected.
SE_OUT_OF_MEMORY - if the API could not allocate the memory for the data or any dynamically allocate memory it should refer to (e.g., SE_STRINGs). In this case, *result_out_ptr is not affected.
SE_FAILURE - *result_out_ptr is unaffected, if
| extern SE_STATUS_CODE_ENUM | ||||
| SE_GetElementOfDataTable | ||||
| ( | ||||
| SE_OBJECT | data_table, | (notes) | ||
| const | SE_DATA_TABLE_EXTENTS | * | extents_ptr, | (notes) |
| EDCS_AC_ID | element, | (notes) | ||
| EDCS_CC_ID | component, | (notes) | ||
| SE_STORE | store_in, | (notes) | ||
| SE_PROPERTY_DATA_VALUE_PTR | * | result_out_ptr | (notes) | |
| ); | ||||
the <Data Table> object whose cells are being retrieved.
indicates the cells that the user wants returned (which
'region' of the <Data Table> to return).
a single EDCS Attribute Code (EAC), indicating which element
should be returned from each cell.
if element == EDCS_AC_INDEX_TO_COMPONENT and/or
EDCS_AC_INDEX_TO_LIBRARY, used to distinguish which component or
library <Data Table> should be used; otherwise, component is ignored.
a handle to a store. The API allocates memory for the requested
data within this store.
a pointer to an SE_PROPERTY_DATA_VALUE_PTR struct, which
contains a 'tag' indicating which pointer from the union of pointers
is active, and a union of pointers. The memory for the returned data
will be allocated within the store associated with store_in and
according to the value of the tag field in this structure. The
appropriate union member is then set to point to this memory.