Function Name: Put Element Of Data Table Extent

Definition

Copies the selected element from a buffer into the selected area of interest of the given Data Table.

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

Returns

SE_SUCCESS - and the cells are created as specified, if valid parameters were passed in and all operations succeeded.

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 data_table is unaffected, 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


extern SE_STATUS_CODE_ENUM
SE_PutElementOfDataTableExtent
(
SE_OBJECT data_table, (notes)
constSE_DATA_TABLE_EXTENTS *extents_ptr, (notes)
EDCS_AC_ID element, (notes)
EDCS_CC_ID component, (notes)
SE_UINT32 byte_count, (notes)
SE_PROPERTY_DATA_VALUE_PTR data_in_ptr (notes)
);

Parameters Notes

data_table

 the <Data Table> object to which cells are being added.

extents_ptr

 specifies the cells provided by the user (which 'region'
    of the <Data Table> is to be written).

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, needed 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.
    (The number of cells is determined from the extents 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.
Prev: Put Element Of Data Table. Next: Put Fields. Up:Index.