SE GetSRFParameters

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

extern SE_Status_Code
SE_GetSRFParameters
(
SE_Object		object_in,	(notes)
SRM_SRF_Parameters	*	SRF_params_out_ptr	(notes)
);

Definition

Gives the user the spatial reference frame (SRF) parameters currently being used when returning <Location> objects in the same SRF scope as the specified object.

See the SE_SetSRFParameters() function for more details.

The answer depends on the last call made to SE_SetSRFParameters() and/or SE_UseDefaultSRFParameters() and the manner in which the transmittal was produced.

case 1 - SE_SetSRFParameters() was called more recently than SE_UseDefaultSRFParameters()

The SRF defined by SE_SetSRFParameters() is still the current retrieval SRF, and that SRF's parameters will be returned in *SRF_params_out_ptr by this function. It doesn't matter what SRF was used to originally produce the given transmittal, since the SE_SetSRFParameters() function was used to over-ride any 'default' SRF choices and force all <Location> objects to be of the type specified by the current retrieval SRF.

case 2 - SE_UseDefaultSRFParameters() was called more recently than SE_SetSRFParameters(), or SE_SetSRFParameters() was never called.

In this case, the retrieval SRF that will be used to define <Location> objects from the given transmittal depends entirely on the transmittal. The retrieval SRF used to return data will be the retrieval SRF that was used when producing the transmittal. This is the default case. If the supplied object does not fall within the scope of *any* SRF, then the SRF parameters are undefined and SE_GetSRFParameters() will return SE_STAT_CODE_FAILURE.

Returns

SE_STAT_CODE_SUCCESS and the scoping retrieval SRF parameters are copied into *SRF_params_out_ptr, if valid parameters were passed in.

SE_STAT_CODE_NULL_REQUIRED_PARAMETER and *SRF_params_out_ptr is left unaltered, if SRF_params_out_ptr was NULL.

SE_STAT_CODE_INVALID_OR_NULL_OBJECT and *SRF_params_out_ptr is left unaltered, if object_in is not a handle to a valid, active (i.e., unfreed) SEDRIS object with a scoping SRF.

SE_STAT_CODE_FAILURE and *SRF_params_out_ptr is left unaltered, if

the specified object has no scoping SRF, and either SE_UseDefaultSRFParameters() was called more recently than SE_SetSRFarameters() or SE_SetSRFParameters() was never called,

API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

Parameters Notes

object_in

  the object in the transmittal of which the user is asking the
    question "What are the parameters for/what is the SRF whose scope
    includes this object?"

SRF_params_out_ptr

 a pointer to the variable in the user's memory
    space where the answer will be stored.

SE_STAT_CODE_SUCCESS	and the scoping retrieval SRF parameters are copied into *SRF_params_out_ptr, if valid parameters were passed in.
SE_STAT_CODE_NULL_REQUIRED_PARAMETER	and *SRF_params_out_ptr is left unaltered, if SRF_params_out_ptr was NULL.
SE_STAT_CODE_INVALID_OR_NULL_OBJECT	and *SRF_params_out_ptr is left unaltered, if object_in is not a handle to a valid, active (i.e., unfreed) SEDRIS object with a scoping SRF.
SE_STAT_CODE_FAILURE	and *SRF_params_out_ptr is left unaltered, if the specified object has no scoping SRF, and either SE_UseDefaultSRFParameters() was called more recently than SE_SetSRFarameters() or SE_SetSRFParameters() was never called, API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.