The SEDRIS API and its use is documented in the following volumes of Part 4 of the Documentation Set:

• Volume 13: How to Extract Data from SEDRIS Transmittals

• Volume 14: How to Produce SEDRIS Transmittals

• Volume 17: API Reference Manual

In this section, the reader is assumed to be familiar with the SEDRIS API. This section provides supplemental information on SEDRIS API functions that are related to the extraction of data from <Data Table> instances.

The SEDRIS API provides three functions to retrieve data from <Data Table> instances. The first two ( SE_GetDataTable() and SE_GetPackedDataTable()) are used to retrieve data for the complete <Data Table> signature, or for a subset of the signature. The SE_GetElementOfDataTable() function is used to retrieve data for one signature item at a time, an element of table cells. Each of these functions allows data to be retrieved for a subset of the cells of the given <Data Table>. This is important if the table is large and the data consumer is interested only in part of the table, or if the data consumer has memory constraints and can only handle the table piecemeal. <Data Table> cell subsets are specified using a SEDRIS API data type, SE_Data_Table_Sub_Extent (see).

SE_Data_Table_Sub_Extent contains 2 fields: axes_count and axes_bounds, where axes_count specifies the size of the axes_bounds array. When a handle to a SE_Data_Table_Sub_Extent, call it extents_ptr, is provided to a data table retrieval function, the value of extents_ptr->axes_count is required to match the number of <Axis> components of the <Data Table> instance. Each entry in axes_bounds specifies the desired range of axis index values for the corresponding <Axis>. The indexing is zero-based, so that for the kth <Axis> component of the table for which cells are being retrieved, where axis_value_count is the number of tick marks on the kth <Axis>,

The number of cells, cell_count, specified by an SE_Data_Table_Sub_Extent is the product of the lengths of the index ranges for each axis.

The SEDRIS API provides several functions to perform the cell count calculation and define SE_Data_Table_Sub_Extent elements. These functions are discussed in section 5.5.

The prototype for SE_GetElementOfDataTable() is given below.

SE_Status_Code SE_GetElementOfDataTable
(
          SE_Object                   data_table,
    const SE_Data_Table_Sub_Extent   *extents_ptr,
          SE_Integer_Positive         table_prop_descript_number,
          SE_Store                    store_in,
          SE_Property_Data_Value_Ptr *result_out_ptr
);

The data_table argument is an SE_Object representing a handle to the <Data Table> instance for which cell data is being retrieved. The extents_ptr argument uses the SE_Data_Table_Sub_Extent data type to specify the index bounds for the cells for which signature element data is desired.

The table_prop_descript_number argument specifies the signature item to be retrieved. Since the signature item corresponds to a specific <Table Property Description> component of the <Data Table>, and since the <Table Property Description> components of a <Data Table> are ordered, the table_prop_descript_number argument specifies the signature item by specifying the 1-based index of the <Table Property Description> among the <Table Property Description> components of data_table.

The store_in argument, in this and the other <Data Table> retrieval functions, is required in order to allow the API to manage the memory associated with the cells of the given <Data Table> instance, rather than requiring the user to do so. Consequently, the user does not allocate the memory within result_out_ptr, but merely provides a handle to the structure, which is then filled out by the API if valid parameters were passed in and all operations succeeded (e.g., memory allocation didn't fail).

A common error for new users of this function is to visualize the structure of SE_Property_Data_Value_Ptr incorrectly. The data structure is not a pointer, but rather a tagged union of arrays.

typedef struct
{
    SE_Property_Data_Value_Type pointer_type;
    union
    {
        EDCS_Boolean                   *boolean_value_ptr;
        SRM_Byte                       *byte_value_ptr;
        SRM_Byte_Positive              *byte_positive_value_ptr;
        EDCS_Byte_Unsigned             *byte_unsigned_value_ptr;
        EDCS_Short_Integer             *short_integer_value_ptr;
        SRM_Short_Integer_Positive     *short_integer_positive_value_ptr;
        EDCS_Short_Integer_Unsigned    *short_integer_unsigned_value_ptr;
        EDCS_Integer                   *integer_value_ptr;
        EDCS_Integer_Interval          *integer_interval_value_ptr;
        SRM_Integer_Positive           *integer_positive_value_ptr;
        EDCS_Integer_Unsigned          *integer_unsigned_value_ptr;
        EDCS_Integer_Unsigned_Interval *integer_unsigned_interval_value_ptr;
        EDCS_Float                     *float_value_ptr;
        EDCS_Float_Interval            *float_interval_value_ptr;
        EDCS_Long_Float                *long_float_value_ptr;
        EDCS_String                    *string_value_ptr;
        SRM_Integer_Positive           *DT_component_index_ptr;
        SRM_Integer_Positive           *DT_library_index_ptr;
        EDCS_Enumerant_Code            *ee_code_ptr;
        EDCS_Metadata_Code             *em_code_ptr;
    } u;
} SE_Property_Data_Value_Ptr;

As an example of the usage of SE_GetElementOfDataTable(), consider the "Surface Backscatter" table from section 3.1, from which a consumer wishes to extract the value corresponding to the angle of incidence of 30 degrees from the IR band. The table is a 2-dimensional array, in which the first <Axis> represents the EM band (EAC_EM_BAND), wherein the IR band (EEC_EMBAND_INFRARED) is located at index 2 in the (zero-based) axis_value_array. On the second <Axis> (EAC_INCIDENCE_ELEV_ANGLE_LOCAL), the value 30 has index 1. Consequently, to specify a single cell, the index start and stop bounds on the first axis are from 2 to 2, and those on the second axis are from 1 to 1. In the following code example (Figure 5-1, the extents_ptr argument is set, then the value (EAC_SURFACE_BACKSCATTER) is retrieved.

SE_Status_Code             status;
SE_Property_Data_Value_Ptr result;
EDCS_Float                 data_value;
SE_Data_Table_Sub_Extent   extent;
SE_Index_Range             ax_range[] = {{2, 2}, {1, 1}};

/*
 * Set extents for cell (2, 1)
 */
extent.axes_count  = 2;
extent.axes_bounds = ax_range;

/*
 * back_scatter_table has already been retrieved
 * cell_store has already been created by SE_CreateStore
 */
status = SE_GetElementOfDataTable
         (
             back_scatter_table,
            &extent,
             1,
             cell_store,
            &result
         );

/*
 * Extract data value from result
 */
if ((status == SE_STAT_CODE_SUCCESS) &&
    (result.value_type == SE_PDV_FLOAT))
{
    data_value = result.u.float_value;
}

Retrieving the entire table, rather than one value, requires only changes to the values within the extent structure, as shown in Figure 5-2, since store_in handles the memory management aspects of the retrieval for the user.

SE_Index_Range             ax_range[] = {{0, 0}, {4, 5}};

The user is not required to possess a priori knowledge of the exact value count of each <Axis> component of a <Data Table> instance to fill in an SE_Data_Table_Sub_Extent structure, however. As a convenience, the level 1 API provides the SE_GetDataTableSubExtent() function, which allocates the axes_bounds field and sets each range entry with the minimum (0) and maximum (axis_value_count - 1) index values. As an additional feature, the function also computes the cell count of the specified extent. This is illustrated in Figure 5-3, below.

...
SE_Data_Table_Sub_Extent  extent;
SE_Integer_Unsigned       cell_count;

/*
 * Get the complete extents
 */
status = SE_GetDataTableSubExtent
         (back_scatter_table, &extent, &cell_count);

...
/* code that uses extent would be located here */

SE_FreeDataTableSubExtent(&extent);

Note that the user calls SE_FreeDataTableSubExtent() to free the memory allocated within the SE_Data_Table_Sub_Extent structure when it is no longer needed.

If the cell count exceeds 1, then the cell data is arranged within the appropriate union member of the SE_Property_Data_Value_Ptr argument with the first <Axis> varying slowest and the last <Axis> varying fastest. Consequently, the property value corresponding to cell index (1, 2), if it is an EDCS_Float, is in result.float_value_ptr[1+2*6]. In general, for a 2-dimensional array where the (i,j)-th cell satisfies the SE_Data_Table_Sub_Extent specification given by the extents_ptr argument, the cell property value will be found in the kth array element within result, where

k = (i - extents_ptr->axes_bounds[0].first_index) +
(j - extents_ptr->axes_bounds[1].first_index) *
(1 + extents_ptr->axes_bounds[1].last_index -
extents_ptr->axes_bounds[1].first_index);

This holds similarly for <Data Table> instances of higher dimension.

If the signature of a <Data Table> has more than one <Table Property Description> (signature item), the SE_GetDataTable() function allows several or all signature elements to be retrieved in one function call. The prototype for SE_GetDataTable() is:

SE_Status_Code SE_GetDataTable
(
          SE_Object                  data_table,
    const SE_Data_Table_Sub_Extent  *extents_ptr,
          SE_Integer_Positive        element_count,
    const SE_Integer_Positive        table_prop_descript_number[],
          SE_Store                   store_in,
          SE_Property_Data_Value   **data_out_ptr
);

The arguments of SE_GetDataTable() resemble those of SE_GetElementOfDataTable(), except that the single table_prop_descript_number value of SE_GetElementOfDataTable() is replaced by a signature element count, element_count and an array of indices into the <Table Property Description> components of the given <Data Table> instance. The element_count specifies the number of elements to be returned per cell, and is the dimension of the table_prop_descript_number array that follows. The table_prop_descript_number array itself both indicates which elements are requested for each cell and specifies the order in which they shall be retrieved; in other words, the retrieval order is not restricted to the <Table Property Description> order.

SE_GetElementOfDataTable(), since it returns a tagged union that presents the retrieved slice of the given <Data Table> as a homogeneous array of its particular data type, is both simple to consume and memory efficient. Unfortunately, it imposes limitations due to its one-element-at-a-type structure. On the other hand, SE_GetDataTable(), which allows many elements to be retrieved at once, returns cell data in an array of type SE_Property_Data_Value, which is simple to consume in terms of processing, but is not memory efficient, since each instance of the data structure will be as big as its largest legal union member.

To provide a compromise - a function that retrieves multiple elements of a <Data Table> in a memory-efficient manner - the API provides a third function to retrieve <Data Table> data. The prototype for SE_GetPackedDataTable() is

SE_Status_Code
SE_GetPackedDataTable
(
          SE_Object                  data_table,
    const SE_Data_Table_Sub_Extent  *extents_ptr,
          SE_Integer_Positive        element_count,
    const SE_Integer_Positive        table_prop_descript_number[],
          SE_Store                   store_in,
          unsigned char            **data_out_ptr
);

The difference between this function and SE_GetDataTable() is that the returned value, data_out_ptr is a 1-dimensional array of bytes in a 'packed' representation, in which only the actual values are returned. No value typing information is provided (the information provided by the value_type 'tag' in the SE_Property_Data_Value structure). To extract values from this 'packed' representation, the data consumer requires prior knowledge (possibly computed by analyzing the signature of the <Data Table> first) of how many values are present per cell, the size and type of each value, the order of the values within the returned cells, and how many cells are present in the returned data array. In other words, the 'packed' representation trades ease of consumption for efficient memory usage.