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_info1
);

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
  1. new_srf_context_info failed to specify a legal SRF within SEDRIS, or
  2. the parameters for the specified SRF were not legal for that SRF.

Parameters Notes

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


Prev: SE_SetRootObject. Next: SE_SetSecondErrorMessage. Up:Index.

Last updated: July 26, 2006 Copyright © 2006 SEDRIS