/*
 * ENUM: SE_STATUS_CODE_ENUM
 *
 *   Return codes for all SEDRIS Level 0 API functions that can fail.
 *   To determine the exact meaning of a status code with respect to a
 *   particular function, read the comments for that function.
 *
 *   SE_NULL_REQUIRED_PARAMETER has priority over the other failure values.
 *   If a function call would fail due to multiple reasons, and if
 *   SE_NULL_REQUIRED_PARAMETER is one of those reasons, then
 *   SE_NULL_REQUIRED_PARAMETER is the reason that will be returned.
 */

Enumerator Notes

SE_SUCCESS

 To be returned when all parameters are valid and all operations
 succeeded, as a general statement. SE_SUCCESS always indicates
 that the function succeeded.

 However, see individual functions for details, since some of the
 other status codes do not necessarily indicate error conditions
 (e.g., SE_NO_OBJECT, SE_MULTIPLE_OBJECTS, SE_DIFFERENT_TRANSMITTAL,
 etc.)

 In other words, a function may return something other than
 SE_SUCCESS, without encountering an error condition. (See
 SE_GetNextObject(), for example.)

SE_INVALID_OR_NULL_OBJECT

 To be returned by a function when an argument of type SE_OBJECT
 is NULL or invalid.

 Note that this does *not* apply to an argument of type
 SE_OBJECT *, which is a pointer to an SE_OBJECT handle;
 this error condition arises when an SE_OBJECT handle is
 itself NULL or invalid, e.g. calling a <Data Table>
 function with an object that is not a <Data Table>.

 See also SE_NULL_REQUIRED_PARAMETER.

SE_NULL_REQUIRED_PARAMETER

 To be returned by a function when a required pointer argument
 is NULL, or when a required numerical argument is zero.

 Notes:
 (1) This does not apply to optional arguments.

 (2) While this does not apply to arguments that are handles,
     e.g. SE_SEARCH_FILTER, SE_OBJECT, SE_TRANSMITTAL, it
     *does* apply to required arguments that are pointers to
     handles, e.g. SE_OBJECT *.

 See the individual functions that can return this status
 for further details.

SE_NO_OBJECT

 To be returned by SE_GetNextObject(), the 1-shot functions,
 etc. when there are no objects left to return that meet the
 specified criteria.

SE_INVALID_OR_NULL_STORE

 To be returned by a function when an argument of type SE_STORE
 is NULL or invalid.

 Note that this does *not* apply to an argument of type
 SE_STORE *, which is a pointer to an SE_STORE handle;
 this error condition arises when an SE_STORE handle is
 itself NULL or invalid, e.g. calling an SE_GetFields()
 function with an SE_STORE whose management structure
 has not been allocated and initialized by SE_CreateStore().

 See also SE_NULL_REQUIRED_PARAMETER.

SE_MULTIPLE_OBJECTS

 To be returned by the 1-shot functions (e.g. SE_GetAggregate(),
 SE_GetComponent(), SE_GetAssociate()) when more than 1 object
 satisfies the conditions; the function will work, it just
 indicates that the user really should have used an iterator
 instead.)

SE_OUT_OF_MEMORY

 To be returned when the API is out of memory.

SE_COORD_OP_FAILURE

 To be returned when:
 (A) the user has set the Spatial Reference Frame (via the
     SE_SetSRFParameters() function) to a SRF other than the
     SRF of the transmittal object being extracted.
 AND
 (B) the <Location> object about to be returned could
     not be converted into the user selected SRF.

 For example, consider a transmittal built entirely in terms
 of the Geodetic (GD) SRF.  Then, consider a user consuming
 that transmittal by calling SE_SetSRFParameters() to set the
 retrieval SRF to Polar Stereographic (PS).  The Read API,
 when retrieving <Location> objects, is supposed to
 automatically convert the objects into either <PS Location 2D>
 or <PS Location 3D> objects.  That's fine for the GD <Locations>
 that are not invalid in the Polar Stereographic SRF, but what is
 the API supposed to do when the GD <Location> in the transmittal
 can't be converted to Polar Stereographic because the <Location>
 falls outside the valid boundaries for Polar Stereographic?  The
 answer is, return this new code - SE_COORD_OP_FAILURE.  This
 value would be returned from the functions SE_GetComponent(),
 SE_GetNextObject(), SE_GetNthComponentOfGivenType(), and their
 related macros when the object that is being returned is a
 <Location> object that cannot be translated into the
 user-specified retrieval SRF.

SE_TRANSMITTAL_UNACCESSIBLE

 To be returned by the open-transmittal functions (e.g.
 SE_OpenTransmittalByFile()) if the resolved file location
 was not accessible by the API.

 This could occur if the file was opened for read-only or update
 and the file did not exist.  It could also occur if the file
 location specified a non-local file and the API had no transport
 mechanism for accessing the remote file.

SE_UNRESOLVED_TRANSMITTAL

 To be returned when a reference to a transmittal is encountered
 that cannot be resolved.

SE_INVALID_ACCESS_MODE

 To be returned by a function (e.g. SE_OpenTransmittalByFile())
 if the resolved file location of a transmittal was found, but
 the security permissions of the underlying system (OS /
 filesystem) prohibited access to the file in the mode specified.

 This could occur if
 (1) the access mode specified was create or update and the
     file was marked read-only, or

 (2) no access was permitted for the account running the
     application, or

 (3) create or update mode was requested but the API
     implementation did not support the write capability
     (e.g. when linked to a read-only s1000-SEDRIS API
     implementation).

 (4) a function requiring create or update mode was invoked
     for an object in a transmittal that was opened in
     read-only mode, e.g. attempting to remove an object
     from a read-only transmittal.

SE_UNSUPPORTED_FORMAT

 To be returned by the open-transmittal functions (e.g.
 SE_OpenTransmittalByFile()) when a transmittal was requested
 in a format that is not supported by the implementation(s)
 of the SEDRIS API linked to the application.

SE_INVALID_TRANSMITTAL_NAME

 To be returned when a parameter representing a transmittal name
 did not specify a name that was valid according to the formal
 SEDRIS namespace. See SE_ResolveTransmittalName()'s description
 for a description of the validation done.

SE_UNPUBLISHED_OBJECT

 To be returned when an object is encountered (while
 attempting to process an intertransmittal reference)
 that is not published by its its transmittal.

 (To be available for intertransmittal referencing,
 an object must be published.)

SE_UNRESOLVED_OBJECT

 To be returned when an SE_OBJECT handle is encountered that
 references an SDRM object that is not available to the
 SEDRIS API, i.e., the SDRM object is contained within a
 transmittal whose content the API cannot access or the
 application programmer has chosen to not to access that
 content.

 Note that this status is not necessarily an error condition.
 See the individual functions that can return this status
 for further details.

SE_UNRESOLVED_START_OBJECT

 To be returned when the caller has provided as a function
 argument an unresolved object, e.g. as the start object
 for an iterator.

 Note that this status *is* an error condition, returned
 when the API must be able to access the content of the
 unresolved object in order to perform the requested
 operation.

SE_INVALID_OBJECT_LABEL

 To be returned when the caller has provided as a function
 argument a label that is not valid in accordance with label
 syntax rules (i.e. the same lexical conventions that apply
 to the name of a variable in ANSI C), or when an attempt
 is made to publish an object with a label that is already
 in use.

SE_DIFFERENT_TRANSMITTAL

 To be returned when the caller passed in valid parameters
 to the given function, and one or more objects were encountered
 that were in a different transmittal than the start object.

 Note that this status is *not* an error condition when
 extracting objects, but *is* an error condition when
 attempting to remove objects from a transmittal.

SE_INVALID_OR_NULL_TRANSMITTAL

 To be returned by a function when an argument of type SE_TRANSMITTAL
 does not correspond to a valid, open transmittal.

SE_DUPLICATE_REFERENCE_SYMBOL

 In the case where a reference symbol has already been created
 (e.g., a reference symbol created with the string "Current Model")
 and the user is trying to create another reference symbol
 with the same unique identifying information.

SE_REFERENCE_SYMBOL_HAS_ASSIGNED_OBJECT

 In the case where an object has been previously assigned to a
 reference symbol, and the caller is trying to assign a different
 object to the same symbol.

SE_INVALID_OR_NULL_REFERENCE_SYMBOL

 In the case where a reference symbol is passed in that
 cannot be resolved, e.g. the reference symbol has been freed
 or was never created.

SE_FAILURE

 In the cases where
 (1) an invalid iterator or search filter is encountered, since
     these types do not have invalid/null status codes of their
     own,
 (2) an API implementation that does not support the given function
     has been linked to (i.e., a shared library has been loaded that
     does not implement the given function, so the call cannot be
     resolved properly),
 (3) some other error condition has arisen that is not covered
     by any of the more specific status codes.

 See individual functions' comments for how SE_FAILURE should be
 interpreted.

SE_NUM_STATUS_CODES

 A placeholder. This entry always appears at the end of this
 enumeration; it is never returned by any API function.