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.
The only difference between this SE_GetPackedDataTable() function and the SE_GetDataTable() function is that the SE_GetDataTable() function returns an N-dimensional array of SE_PROPERTY_DATA_VALUEs. An SE_PROPERTY_DATA_VALUE is a struct, containing a 'tag' to indicate what type of a value it contains, and a union of all of the possible types of values for a Data Table value. That representation is inefficient in terms of storage space, since the user should already know the 'type' of each value based on the signature of the Data Table, and because a union of all possible data types always takes up as much space as the largest data type. For systems that use 64-bit pointers, the largest Data Table type would currently be SE_STRING, which is composed of a pointer and a SE_UINT16. So, for each value, using an SE_PROPERTY_DATA_VALUE as the SE_GetDataTable() function wastes space. Some space is wasted to indicate the type of the value, and some space to 'pad' the union in which the value is stored (unless the value happens to be an SE_STRING).
This function, SE_GetPackedDataTable(), doesn't waste any space when it returns the cell values. That's because this function returns the cell values as a 1-dimensional array of bytes. The user must then 'take apart' this array, based on the user's knowledge of how many values are present per cell (selected by the user through parameters to this function), the size and type of each value, the order of the values within the returned cells (defined by the user through parameters to this function), and the knowledge of how many cells are present in the returned data array (also defined by the user through parameters to this function). In this 'packed' representation, only the actual values are returned. No 'typing' information is provided (the 'tag' to indicate the type of each value is not present in the data returned by this function).
WARNING:
'Nice' word boundaries for values (such as floats) are
not preserved by
this function. No padding is added to the returned data. So, let the
user beware. If the user defined order for the returned cell values
causes some values to fall on 'bad' boundaries for those type of values,
then the user will have to copy the bytes for those values to an area
that is 'properly' aligned for those types of values before trying
to access those values in their 'natural' form. This task is similar
to extracting data from a stream of bytes coming from a network.
SE_NULL_REQUIRED_PARAMETER - (*data_out_ptr is unaffected) if
SE_INVALID_OR_NULL_OBJECT - and *data_out_ptr is set to NULL, if data_table is not a handle to a valid, active (i.e., unfreed) Data Table object.
SE_UNRESOLVED_OBJECT - and *data_out_ptr is set to NULL, if data_table is an unresolved object (see SE_OBJECT's comments for details on how this condition occurs).
SE_INVALID_OR_NULL_STORE - and *data_out_ptr is set to NULL, if store_in is not a handle to a valid SE_STORE created by SE_CreateStore().
SE_OUT_OF_MEMORY - and *data_out_ptr is set to NULL, if the API could not allocate the memory for the data or any dynamically allocated memory it should refer to (e.g., SE_STRINGs).
SE_FAILURE - and *data_out_ptr is set to NULL, if
| extern SE_STATUS_CODE_ENUM | |||||
| SE_GetPackedDataTable | |||||
| ( | |||||
| SE_OBJECT | data_table, | (notes) | |||
| const | SE_DATA_TABLE_EXTENTS | * | extents_ptr, | (notes) | |
| SE_PINT32 | element_count, | (notes) | |||
| const | EDCS_AC_ID | selected_elements[], | (notes) | ||
| const | EDCS_CC_ID | selected_components[], | (notes) | ||
| SE_STORE | store_in, | (notes) | |||
| unsigned char | * | * | data_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).
the number of elements per cell to return, and the
size of the following selected_elements array.
an array of EDCS Attribute Codes (EACs), indicating
which elements should be returned for each cell, *and* defining how
those elements should be ordered when they are returned.
an array of EDCS Classification Codes
(ECCs); selected_components[i] is ignored unless selected_elements[i]
== EDCS_AC_INDEX_TO_COMPONENT or EDCS_AC_INDEX_TO_LIBRARY, in which
case selected_components[i] is used to distinguish multiple
EDCS_AC_INDEX_TO_COMPONENT or EDCS_AC_INDEX_TO_LIBRARY entries.
In other words, selected_components is a required parameter if
selected_elements has any EDCS_AC_INDEX_TO_COMPONENT and/or
EDCS_AC_INDEX_TO_LIBRARY entries; otherwise, it is an optional
parameter.
a handle to a store. The API allocates memory for the requested
data within this store.
a pointer to a block of memory containing the returned
data. The API allocates memory for the requested data and sets this
parameter to point to it.