SE SetSRFContextInfo

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

extern SE_Return_Code
SE_SetSRFContextInfo
(
SE_SRF_Context_Info	new_srf_context_info	¹
);

Definition

Sets the spatial reference frame (SRF) that will be used to represent all <Location> instances returned after this function is called. This function has no effect on <Location> instances 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> instances 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 transmittal, then call the SE_UseDefaultSRFContextInfo() 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_SetSRFContextInfo(). 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> instance, 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_RETCOD_SUCCESS	and the SRF parameters are set.
SE_RETCOD_FAILURE	and the status code is set appropriately if the call failed.

Status Codes

SE_Status_Code(s) when SE_RETCOD_SUCCESS is returned:

SE_STATCODE_SUCCESS

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

SE_Status_Code(s) when SE_RETCOD_FAILURE is returned:

SE_STATCODE_INACTIONABLE_FAILURE

set if

new_srf_context_info failed to specify a legal SRF within SEDRIS, or
the parameters for the specified SRF were not legal for that SRF.

Parameters Notes

¹ 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.