SE SetSRFParameters

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

extern SE_Status_Code
SE_SetSRFParameters
(
SRM_SRF_Parameters	new_SRF_parameters	(notes)
);

Definition

Sets the spatial reference frame (SRF) that will be used to represent all <Location> objects returned after this function is called. This function has no effect on <Location> objects that have already been returned to the user before this function was called. See the Spatial Reference Model (SRM) for details on the various SRFs supported by SEDRIS.

The SRF used for returning <Location> objects can be changed as often as the user desires. After changing to any particular SRF, if the user wants to return to the 'default' state where coordinates are returned in the SRF in which they were originally stored in the SEDRIS transmittal, then call the SE_UseDefaultSRFParameters() function.

SPECIAL EXCEPTION:

If coordinates are defined as Local Space Rectangular (LSR) or 2D Local Space Rectangular (LSR2) coordinates, then they will always be returned as LSR/LSR2 coordinates, regardless of the values passed to SE_SetSRFParameters(). LSR/LSR2 coordinates are only converted into another spatial reference frame if they are instanced into the scope of another SRF via a model instance with a <World Transformation>. If a <Model> has been so instanced, and if that instance was traversed to reach the 'current' <Location> object, and if this API was instructed to transform coordinates when going through transformations, then and only then will LSR/LSR2 coordinates be transformed into the current scoping SRF. See the various initialize iterator functions for details on how to instruct this API on whether to transform coordinates when going through transformations.

Returns

SE_STAT_CODE_SUCCESS and the current retrieval SRF is set to the SRF specified by new_SRF_parameters, if a valid parameter was passed in.

SE_STAT_CODE_OUT_OF_MEMORY and the retrieval SRF is not changed, if the API implementation cannot allocate memory to hold a copy of the new_SRF_parameters.

SE_STAT_CODE_FAILURE and the retrieval SRF is not changed, if

new_SRF_parameters failed to specify a legal SRF within SEDRIS, or

the parameters for the specified SRF were not legal for that SRF.

Parameters Notes

new_SRF_parameters

 specifies the new SRF and the necessary SRF
    parameters for the selected SRF, if any.  Some SRFs don't need
    parameters, and have a 'place-holder' field, "ignore_na".  See
    the SRM and the definition of SRM_SRF_Parameters for more
    details.

SE_STAT_CODE_SUCCESS	and the current retrieval SRF is set to the SRF specified by new_SRF_parameters, if a valid parameter was passed in.
SE_STAT_CODE_OUT_OF_MEMORY	and the retrieval SRF is not changed, if the API implementation cannot allocate memory to hold a copy of the new_SRF_parameters.
SE_STAT_CODE_FAILURE	and the retrieval SRF is not changed, if new_SRF_parameters failed to specify a legal SRF within SEDRIS, or the parameters for the specified SRF were not legal for that SRF.