Definition

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 extents_ptr->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.

There are two differences between this SE_GetElementOfDataTable() function and the SE_GetDataTable() function.

1. 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,
2. 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_Short_Integer_Unsigned is the type of value requested, then the user allocates an array of SE_Short_Integer_Unsigned, passes in a pointer to that array, and this function fills in the array with the appropriate SE_Short_Integer_Unsigned values. No space is wasted because the type of data is constant (in this example, it was always a SE_Short_Integer_Unsigned).

Returns

SE_STAT_CODE_SUCCESS	and memory for the requested data is allocated within the store associated with store_in, and the requested data is copied into that memory (which is pointed to by the appropriate field of *result_out_ptr), if valid parameters were passed in.
SE_STAT_CODE_NULL_REQUIRED_PARAMETER	and *result_out_ptr is left unaltered, if extents_ptr was NULL, table_prop_descript_number is zero, or result_out_ptr was NULL.
SE_STAT_CODE_INVALID_OR_NULL_OBJECT	and *result_out_ptr is unaffected, if data_table is not a handle to a valid, active (i.e., unfreed) <Data Table> instance.
SE_STAT_CODE_UNRESOLVED_OBJECT	and *result_out_ptr is set as for SE_STAT_CODE_INVALID_OR_NULL_OBJECT, 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 *result_out_ptr is set as for SE_STAT_CODE_INVALID_OR_NULL_OBJECT, if store_in is not a handle to a valid SE_Store created by SE_CreateStore().
SE_STAT_CODE_OUT_OF_MEMORY	and *result_out_ptr is set as for SE_STAT_CODE_INVALID_OR_NULL_OBJECT, if the API could not allocate the memory for the data or any dynamically allocated memory it should refer to (e.g., strings).
SE_STAT_CODE_FAILURE	and *result_out_ptr is set as for SE_STAT_CODE_INVALID_OR_NULL_OBJECT, if the extents pointed to by extents_ptr are invalid for data_table, table_prop_descript_number is not valid for data_table, the type of pointer indicated to be active within the result_out_ptr struct is not the correct type of pointer for the value used to represent the specified table_prop_descript_number, data_table is a <Property Grid> with a data_present field set to SE_FALSE, data_table has been created via the API but has not yet had had cells added to it, or the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

Parameters Notes

data_table

 the <Data Table> instance whose cells are being retrieved.

extents_ptr

 indicates the cells that the user wants returned (which
    'region' of data_table to return).

table_prop_descript_number

 an index into the ordered list of
    <Table Property Descriptions> aggregated by data_table.

store_in

 a handle to a store, within which the API allocates
    memory for the data.

result_out_ptr

 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.

Prev: SE_GetDataTable. Next: SE_GetErrorDescription. Up:Index.

Last updated: May 15, 2003 Copyright © 2003 SEDRIS™