= FDO RFC 28 -  Add X,Y,Z and M Expression Functions =

This page contains a request for comments document (RFC) for the FDO Open Source project.  
More FDO RFCs can be found on the [wiki:FDORfcs RFCs] page.

== Status == 
 
||RFC Template Version||(1.0)|| 
||Submission Date||October 20, 2008||
||Last Modified||Robert Fortin[[Timestamp]]||
||Author||Greg Boone||
||RFC Status||Draft||
||Implementation Status ||Pending||
||Proposed Milestone||3.4.0.0||
||Assigned PSC guide(s)||Greg Boone||
||'''Voting History'''||  ||
||+1||Greg Boone, Orest Haslustchak, Jason Birch||
||+0||Frank Warmerdam||
||-0||||
||-1||||
 
== Overview ==

This RFC follows from RFC 8 by adding geometric functions to retrieve the X, Y, Z and M value of a point.

== Signatures ==

This RFC proposes the following signatures for the new functions: 


{{{
double X(<geometry property>);
double Y(<geometry property>);
double Z(<geometry property>);
double M(<geometry property>);

}}}

All of the above functions accept a geometry property of type point only. if the geometry is not a point or if the dimension of the geometry prevent from returning a proper value (e.g. Z() function on a 2D geometry), a null value is returned. The new functions will be categorized as geometry functions (!FdoFunctionCategoryType_Geometry). 



=== Example ===


{{{
FdoPtr<FdoISelect> select = (FdoISelect*)mConnection->CreateCommand (FdoCommandType_Select);
select->SetFeatureClassName (L"POLE");
FdoPtr<FdoIdentifierCollection> idColl = select->GetPropertyNames();

FdoPtr<FdoExpressionCollection> functionArgs = FdoExpressionCollection::Create();
FdoPtr<FdoIdentifier> arg1 = FdoIdentifier::Create(L"GEOMETRY");
functionArgs->Add(arg1);
FdoPtr<FdoFunction> expr = FdoFunction::Create(L"X", functionArgs);
FdoPtr<FdoComputedIdentifier> computedId = FdoComputedIdentifier::Create(L"POLE_X", expr);
idColl->Add(computedId);

FdoPtr<FdoIFeatureReader> reader = select->Execute ();
}}}

== Standard Considerations ==

During the initial proposal of this RFC (which was focusing on returning the StartX/Y/Z and EndX/Y/Z of any geometry),  many altertives were considered.  The concensus was that FDO should try to adopt an existing standard.  The function signatures adopted here are based on the OGC [http://www.opengeospatial.org/standards/sfa Simple Feature Access] standard.

Other functions were considered for the initial RFC proposal but are __outside the scope__ of this RFC:

   !StartPoint(): Point[[BR]]
   !EndPoint(): Point[[BR]]
   !NumPoints(): Int[[BR]]
   PointN(N): Point[[BR]]


Using these additional functions in combination with the X,Y,Z and M functions, it would have been possible to return the start and end coordinate for other type of geometry.

Example:
   To retrieve the X value for the first point of a line -->  X(!StartPoint(<geometry>) or X(PointN(1, <geometry>)[[BR]]
   To retrieve the Y value for the last point of a line -->  Y(!EndPoint(<geometry>) or X(PointN(!NumPoints(<geometry>, <geometry>)[[BR]]



== Affected Providers ==

This enhancement is being targeted to only affect the following providers: SDF. However, if a shared generic implementation can be designed, these functions may also be exposed through the SHP provider.

== Required FDO Enhancements ==

No FDO enhancements are required.

== Implications ==

This change will not cause any side-effects. No existing provider needs to change unless the provider wants to expose the new capability.

== Test Plan ==

Existing unit tests will be enhanced to test those changes.

== Funding/Resources ==

Autodesk to provide resource / funding to implement the feature for the affected providers.