Function Name: Set SRF Parameters

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_SUCCESS - if new_SRF_parameters held legal values. In this case, the current retrieval SRF is set to the SRF specified within new_SRF_parameters, and the SRF parameters specified within new_SRF_parameters, if any, are used for the new retrieval SRF. See the SRM for details.

SE_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_FAILURE - and the retrieval SRF is not changed, if

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

Prototype


extern SE_STATUS_CODE_ENUM
SE_SetSRFParameters
(
SE_SRF_PARAMETERS new_SRF_parameters (notes)
);

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 SEDRIS SRM and the definition of SE_SRF_PARAMETERS for more
    details.
Prev: Set Root Object. Next: Set Second Error Message. Up:Index.