SE CreateStore

SEDRIS Reference Manual APPENDIX A - LEVEL 0 READ and WRITE API Functions SE CreateStore

extern SE_Status_Code
SE_CreateStore
(
const	char		implementation_identifier[],	(notes)
	SE_Store	*	store_out_ptr	(notes)
);

Definition

Creates a store to be used by the API in returning data to the application.

A store is an opaque data type, created by this API call, that is used to provide the memory context within which the API returns data. The behavior of stores, and the data returned within them, exhibits the following:

A store must be created before it is used
Data returned in a store is valid until the next time the store is used as a parameter to a function, or until the application frees the store by calling SE_FreeStore().
Memory managed by a store is not guaranteed to be released (freed) until the store is freed by SE_FreeStore().

The implementation of the API is at liberty to decide the exact allocation scheme. However, applications should safely expect the following performance characteristics:

Reusing an existing store should always be more efficient (both in speed and memory requirements) than freeing a store and creating a new one.
Reusing a store to return similarly sized data (e.g. object fields, or portions of a <Data Table>), will result in the most efficient use of memory space.

Returns

SE_STAT_CODE_SUCCESS and a handle to the new store is copied into *store_out_ptr, if valid parameters were passed in and memory allocation for the store's management structure succeeded.

SE_STAT_CODE_NULL_REQUIRED_PARAMETER and *store_out_ptr is left unaltered, if store_out_ptr was NULL, or if implementation_identifier was NULL and the API implementation to be used could not otherwise be determined.

SE_STAT_CODE_OUT_OF_MEMORY and *store_out_ptr is set to NULL, if the API could not allocate the memory for the management structure of the store.

SE_STAT_CODE_FAILURE *store_out_ptr is set to NULL, if dynamic binding is specified at compile time but

the shared library for the specified API implementation cannot be found, or

the API implementation specified does not provide this function in its shared library.

Parameters Notes

implementation_identifier

 identifies the API implementation
    to use when creating this store.  If the specified API can't create the
    store, then the API will return a status code indicating why it could
    not be created.  If implementation_identifier is NULL, then the API
    implementation to be used must be statically bound at compile time.

    See also SE_GetImplementationIdentifier().

store_out_ptr

 a pointer to SE_Store from the user.  The store will be
    created and associated with this handle.

SE_STAT_CODE_SUCCESS	and a handle to the new store is copied into *store_out_ptr, if valid parameters were passed in and memory allocation for the store's management structure succeeded.
SE_STAT_CODE_NULL_REQUIRED_PARAMETER	and *store_out_ptr is left unaltered, if store_out_ptr was NULL, or if implementation_identifier was NULL and the API implementation to be used could not otherwise be determined.
SE_STAT_CODE_OUT_OF_MEMORY	and *store_out_ptr is set to NULL, if the API could not allocate the memory for the management structure of the store.
SE_STAT_CODE_FAILURE	*store_out_ptr is set to NULL, if dynamic binding is specified at compile time but the shared library for the specified API implementation cannot be found, or the API implementation specified does not provide this function in its shared library.