Changes between Initial Version and Version 1 of FDORfc29


Ignore:
Timestamp:
11/11/08 15:17:28 (16 years ago)
Author:
thomasknoell
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • FDORfc29

    v1 v1  
     1
     2
     3= FDO RFC 29 -  Redefining Expression Function EXTRACT =
     4
     5This page contains a request for comments document (RFC) for the FDO Open Source project. 
     6More FDO RFCs can be found on the [wiki:FDORfcs RFCs] page.
     7
     8== Status ==
     9 
     10||RFC Template Version||(1.0)||
     11||Submission Date||Nov 11, 2007||
     12||Last Modified||Thomas Knoell [[Timestamp]]||
     13||Author||Thomas Knoell||
     14||RFC Status||Draft||
     15||Implementation Status ||Pending||
     16||Proposed Milestone||3.4.0.0||
     17||Assigned PSC guide(s)||Greg Boone||
     18||'''Voting History'''||  ||
     19||+1||||
     20||+0||||
     21||-0||||
     22||-1||||
     23 
     24== Overview ==
     25
     26It has been noted that the use of the expression function '''EXTRACT''' in its current specification may cause some usability issues. This is related to the result the function returns, a '''!FdoDateTime''' object in which all properties are set to the default value except the property for which the function was executed. For example, if the user requested the year of a date property, the year property of the returned '''!FdoDateTime''' object is set to the corresponding value whereas all other properties in the object - month, day, hour, minute and seconds - are set to their default value which is either -1 for month, day, hour and minute or 0 for seconds. It is up to the function caller to select the correct property from the retuned object. In some cases, users were not aware of this and hence experienced unexpected results.
     27
     28The purpose of this RFC is to make the function easier to use. Instead of returning a '''!FdoDateTime''' object, the proposed modification will return a numeric value to represent the requested value directly. This will eliminate any misunderstanding related to this expression function. It will also allow the function to be used in a nested function statement like ''!TOSTRING (EXTRACT ( ...))''.
     29
     30The proposed redefinition of the expression function ''EXTRACT'' will also address backward compatibility to avoid cases where any user/application has used this function in the expected manner.
     31
     32 
     33== Proposal ==
     34
     35It is proposed to add the following new expression functions to the list of supported expression functions:
     36
     37    * '''!ExtractToInt''': Extracts the requested part of a date/time property and returns the value as an integer.
     38
     39    * '''!ExtractToDouble''': Extracts the requested part of a date/time property and returns the value as a double.
     40
     41Both functions will have the same signature and differenciate themselves in the return value only:
     42
     43    * ''!FdoInt16 !ExtractToInt ({YEAR | MONTH | DAY | HOUR | MINUTE | SECOND}, <date_time_prop>); ''
     44
     45    * ''!FdoDouble !ExtractToDouble ({YEAR | MONTH | DAY | HOUR | MINUTE | SECOND}, <date_time_prop>); ''
     46
     47The two functions are required because by default, seconds are defined as a double whereas all other date/time properties are defined as integers. The following describes the expected behavior of the functions when invoked with different options:
     48
     49||FUNCTION||REQUEST||RETURN
     50||  ||  ||
     51||!ExtractToInt||YEAR||The year portion of the specified date. If the date does not contain year information, the function returns -1||
     52||!ExtractToInt||MONTH||The month portion of the specified date. If the date does not contain month information, the function returns -1||
     53||!ExtractToInt||DAY||The day portion of the specified date. If the date does not contain day information, the function returns -1||
     54||!ExtractToInt||HOUR||The hour portion of the specified date. If the date does not contain hour information, the function returns -1||
     55||!ExtractToInt||MINUTE||The minute portion of the specified date. If the date does not contain minute information, the function returns -1||
     56||!ExtractToInt||SECONDS||The seconds portion of the specified date as an INTEGER. In this case the actual value is rounded to the closest integer value. If the date does not contain seconds information, the function returns -1||
     57|| || ||
     58||!ExtractToDouble||YEAR||The year portion of the specified date as a DOUBLE. If the date does not contain year information, the function returns -1||
     59||!ExtractToDouble||MONTH||The month portion of the specified date as a DOUBLE. If the date does not contain month information, the function returns -1||
     60||!ExtractToDouble||DAY||The day portion of the specified date as a DOUBLE. If the date does not contain day information, the function returns -1||
     61||!ExtractToDouble||HOUR||The hour portion of the specified date as a DOUBLE. If the date does not contain hour information, the function returns -1
     62||!ExtractToDouble||MINUTE||The minute portion of the specified date as a DOUBLE. If the date does not contain minute information, the function returns -1||
     63||!ExtractToDouble||SECONDS||The seconds portion of the specified date. If the date does not contain seconds information, the function returns -1||
     64
     65For backward-compatibility reasons, the original expression function ''!Extract'' will still be supported. However, it will be marked as deprecated and users are expected to switch over to the new functions as the original function will eventually be removed from the list of supported expression functions.
     66
     67
     68== Affected Providers/Components ==
     69
     70This enhancement will affect the following providers: ArcSDE, MySQL, ODBC and SQL Server 2008. It will also affect the Common Expression Engine.
     71
     72
     73== Implications ==
     74
     75The new functions will be part of the default expression function list provided by the Expression Engine and hence will have a default implementation there. Any provider that relies on the default implementation therefore does not need to be modified. Only providers that map the expression function ''EXTRACT'' to a native supported routine (for example some RDBMS providers) should be changed to map the new functions to the corresponding native routine.
     76
     77
     78== Test Plan ==
     79
     80Existing unit tests will be enhanced to test those changes.
     81
     82
     83== Funding/Resources ==
     84
     85Autodesk to provide resource / funding to implement the changes related to this RFC.
     86