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:

1. A store must be created before it is used
2. 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().
3. 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:

1. Reusing an existing store should always be more efficient (both in speed and memory requirements) than freeing a store and creating a new one.
2. 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_RET_CODE_SUCCESS	and the SE_Store is created.
SE_RET_CODE_FAILURE	and the status code is set appropriately if the call failed.

Status Codes

SE_Status_Code(s) when SE_RET_CODE_SUCCESS is returned:

SE_STAT_CODE_SUCCESS

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

SE_Status_Code(s) when SE_RET_CODE_FAILURE is returned:

SE_STAT_CODE_INACTIONABLE_FAILURE

set if the call failed for any reason.

Parameters Notes

encoding

 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().

store_out_ptr

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

Prev: SE_CreateSpatialSearchBoundary. Next: SE_DetermineSpatialInclusion. Up:Index.

Last updated: July 16, 2004 Copyright © 2004 SEDRIS™