Function Name: Get Data Table

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

Returns

SE_NULL_REQUIRED_PARAMETER - and *data_out_ptr is unaffected, if

1. data_out_ptr was NULL,
2. extents_ptr was NULL,
3. element_count is zero,
4. selected_elements was NULL, or
5. selected_components was NULL but selected_elements contained EDCS_AC_INDEX_TO_COMPONENT and/or EDCS_AC_INDEX_TO_COMPONENT entries.

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 - 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 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 any of the following are true:

1. the extents pointed to by extents_ptr are invalid for the Data Table,
2. any of the selected_elements are not applicable to (are not contained in) the Data Table,
3. for any selected_element[i] == EDCS_AC_INDEX_TO_COMPONENT or EDCS_AC_INDEX_TO_LIBRARY, selected_component[i] is not applicable to (is not contained in) the Data Table,
4. any of the selected_elements, selected_components pairs are duplicate entries,
5. data_table is a Property Grid with a data_present field set to SE_FALSE,
6. data_table has been created via the API but has not yet had cells added to it, or
7. the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

Prototype

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 selected_elements array.

selected_elements

 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.

selected_components

 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.

store_in

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

data_out_ptr

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