|
SEDRIS Reference Manual
APPENDIX A - LEVEL 0 READ and WRITE API Functions SE GetPackedDataTable |
|---|
| extern SE_Status_Code | |||||
| SE_GetPackedDataTable | |||||
| ( | |||||
| SE_Object | data_table, | (notes) | |||
| const | SE_Data_Table_Sub_Extent | * | extents_ptr, | (notes) | |
| SE_Integer_Positive | element_count, | (notes) | |||
| const | SE_Integer_Positive | table_prop_descript_number[], | (notes) | ||
| SE_Store | store_in, | (notes) | |||
| unsigned char | * | * | data_out_ptr | (notes) | |
| ); | |||||
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_Short_Integer, SE_Long_Float, 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
Then extents_ptr-> axes_bounds[0]. first_index and axes_bounds[0]. last_index 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 EDCS_String, which is composed of a pointer and a SE_Short_Integer_Unsigned. 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 EDCS_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_STAT_CODE_SUCCESS | and
|
| SE_STAT_CODE_NULL_REQUIRED_PARAMETER | and no changes are made, if
|
| SE_STAT_CODE_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> instance. |
| SE_STAT_CODE_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_STAT_CODE_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_STAT_CODE_OUT_OF_MEMORY | and *data_out_ptr is set to NULL, if memory allocation failed. |
| SE_STAT_CODE_FAILURE |
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 table_prop_descript_number array.
an array of indices into the ordered list of
<Table Property Descriptions> aggregated by the
<Data Table>.
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.
Prev: SE_GetObjectReferenceCount.
Next: SE_GetPackedHierarchy.
Up:Index.
|