SE CreateStore

SEDRIS Reference Manual APPENDIX A - Transmittal Access Level 0 API Functions SE CreateStore

extern SE_Return_Code
SE_CreateStore
(
SE_Encoding		encoding,	¹
SE_Store	*	store_out_ptr	²
);

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_RETCOD_SUCCESS	and the SE_Store is created.
SE_RETCOD_FAILURE	and the status code is set appropriately if the call failed.

Status Codes

SE_Status_Code(s) when SE_RETCOD_SUCCESS is returned:

SE_STATCODE_SUCCESS

set if valid parameters were passed in and memory allocation for the store's management structure succeeded.

SE_Status_Code(s) when SE_RETCOD_FAILURE is returned:

SE_STATCODE_C_STORE_INVALID	and no changes are made if store_out_ptr is not a handle to a valid SE_Store.
SE_STATCODE_INACTIONABLE_FAILURE	set if the call failed for any other reason.

Parameters Notes

¹ identifies the API implementation encoding 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 encoding is NULL, then the API implementation encoding to be used must be statically bound at compile time. See also SE_GetEncoding().

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