Function Name: Create Reference Symbol From String

Definition

Creates a reference symbol from a character string.

This reference symbol can be used in SE_AddSymbolicComponent() and/or SE_AddSymbolicAssociate() either before or after being assigned to an object with SE_AssignReferenceSymbolToObject(). This allows a user to create an object's relationships without keeping the object in memory for a prolonged period of time.

NOTES:

1. Once the user has created the reference symbol, the memory pointed to by symbol_string_in is the user's responsibility. (The reference symbol creates a copy of the string, and uses the copy instead.)

2. While this reference symbol is active (i.e., between the time it is created by this function and the time it is freed by SE_FreeReferenceSymbol()), no other reference symbols may be created using the same string (where "same" is determined using the ANSI C rules for strcmp()).

Returns

SE_NULL_REQUIRED_PARAMETER - and no changes are made, if symbol_string_in is NULL or ref_symbol_out_ptr is NULL.

SE_DUPLICATE_REFERENCE_SYMBOL - and *ref_symbol_out_ptr is set to NULL, if the reference symbol has been created previously.

SE_OUT_OF_MEMORY - and *ref_symbol_out_ptr is set to NULL, if the reference symbol could not be allocated.

SE_FAILURE - and *ref_symbol_out_ptr is set to NULL, if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

Prototype

Parameters Notes

implementation_identifier

 identifies the API implementation
    to use when creating this reference symbol.  If the specified API can't
    create the reference symbol, 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().

symbol_string_in

  a character string, terminated by '\0' (the null
    character), to be used to create the reference symbol. This string
    must be properly null-terminated, because the API will allocate
    space within the reference symbol in order to copy the string into
    the reference symbol. The string will be used as a unique identifier
    for the reference symbol being created.

ref_symbol_out_ptr

 pointer to a variable, passed in by the user,
    in which a handle to the reference symbol being created will be placed.