SE SetSRFInfo

SEDRIS Reference Manual APPENDIX A - Transmittal Access Level 0 API Functions SE SetSRFInfo

extern SE_Return_Code
SE_SetSRFInfo
(
SE_SRF_Info	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_UseDefaultSRFInfo() 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_SetSRFInfo(). 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_RET_CODE_SUCCESS and the SRF parameters are set.

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 and the current retrieval SRF is set to the SRF specified by new_SRF_parameters, if a valid parameter was passed in.

SE_Status_Code(s) when SE_RET_CODE_FAILURE is returned:

SE_STAT_CODE_INACTIONABLE_FAILURE set 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_RET_CODE_SUCCESS	and the SRF parameters are set.
SE_RET_CODE_FAILURE	and the status code is set appropriately if the call failed.