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.

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 data_out_ptr), if valid parameters were passed in.
SE_STAT_CODE_NULL_REQUIRED_PARAMETER	and *data_out_ptr is unaffected, if extents_ptr was NULL, element_count is zero, table_prop_descript_number was NULL, or data_out_ptr was NULL.
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, active (i.e., unfreed) SE_Store created by SE_CreateStore().
SE_STAT_CODE_OUT_OF_MEMORY	and *data_out_ptr is set to NULL, if the API could not allocate memory for the data or any dynamically allocated memory it should refer to (e.g., strings).
SE_STAT_CODE_FAILURE	and *data_out_ptr is set to NULL, if any of the following are true: the extents pointed to by extents_ptr are invalid for the , any of the table_prop_descript_number entries are invalid for data_table, or are not unique within the array, 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 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> object whose cells are being retrieved.

extents_ptr

 indicates the cells that the user wants returned (which
    'region' of the <Data Table> to return).

element_count

 the number of elements per cell to return, and the
    size of the following table_prop_descript_number array.

table_prop_descript_number

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

store_in

 a handle to a store; the API allocates memory for the requested
    data within this store.

data_out_ptr

 a pointer to an SE_Property_Data_Value pointer.  The API
    allocates memory for the requested data and sets this
    parameter to point to it.

Prev: SE_GetContextTransformation. Next: SE_GetElementOfDataTable. Up:Index.

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