Function Name: Put Element Of Data Table

Definition

For each cell of the given Data Table, creates exactly one element from the given data_in_ptr. (To do this for a subregion of the Data Table rather than the entire Data Table, see SE_PutElementOfDataTableExtent(). To create multiple elements per cell, see SE_PutDataTable()).

Returns

SE_INVALID_OR_NULL_OBJECT - and data_table is unaffected, if data_table is not a handle to a valid, active (i.e., unfreed), saved Data Table.

SE_UNRESOLVED_OBJECT - and data_table is unaffected, if data_table is an unresolved object.

SE_INVALID_ACCESS_MODE - and data_table is unaffected, if the transmittal containing the Data Table was opened in read-only mode.

SE_FAILURE - and no changes are made, if any of the following conditions are encountered:

1. the given element, component pair doesn't form a valid Data Table signature,
2. data_table doesn't belong to an open transmittal,
3. data_table is a Property Grid with data_present set to SE_FALSE (note that the default value of this field is SE_TRUE, if the user has not yet set the fields of the Property Grid)
4. byte_count is not correct for the given element, component pair
5. 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 created.

element

 a single EDCS Attribute Code (EAC), indicating which element
    should be written into each cell.

component

 if element == EDCS_AC_INDEX_TO_COMPONENT and/or
    EDCS_AC_INDEX_TO_LIBRARY, used to distinguish which component or
    library <Data Table> should be used; otherwise, component is ignored.

byte_count

 the amount of memory occupied by the data values of the cells
    provided.  The type of the selected element determines the number of
    bytes needed per cell. The product of (number of cells) times (bytes
    per cell) must be provided by the user through this byte_count
    parameter. This is done as a safeguard in an attempt to ensure that
    the user allocated the correct amount of memory for the pointer inside
    data_in_ptr.

data_in_ptr

 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, one of which should be pointing to byte_count bytes
    memory, which will be read by this function to provide the appropriate
    values.  This memory space is entirely under the user's control.  The
    only time the API accesses this memory is when the API reads data from
    it during this function call.