Changes between Initial Version and Version 1 of FDORfc8

Timestamp:

Aug 3, 2007, 12:11:41 PM (17 years ago)

Author:

thomasknoell

Comment:

--

FDORfc8

@@ +1 @@
+
+
+= FDO RFC 5 -  Modify Fdo API !FdoFunctionDefinition =
+
+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||Aug 03, 2007||
+||Last Modified||Thomas Knoell [[Timestamp]]||
+||Author||Thomas Knoell||
+||RFC Status||Draft||
+||Implementation Status ||Under Development||
+||Proposed Milestone||3.3.0.0||
+||Assigned PSC guide(s)||Greg Boone||
+||'''Voting History'''||  ||
+||+1||||
+||+0||||
+||-0||||
+||-1||||
+ 
+== Overview ==
+
+Providers currently can support any number of functions used in the expressions passed to them. Capability methods are available to advertise which functions are supported and their parameters. This RFC adds a set of functions to a number of the current FDO providers using a standard set of names, parameters, parameter types and return types. These functions are commonly used functions in a number of domains and include standard string and numeric type functions. This will allow application developers to start using standard function names knowing that a large number of providers will be supporting those functions. It is hoped that other provider developers will consider adding support for these functions to other FDO providers.
+
+The list of supported functions and their signatures will be defined with the Expression Engine. The Expression Engine will also have a default implementation of those functions. Any provider can retrieve the list of supported functions and their signatures by executing the FDO interface GetWellKnownFunctions. Once the list is retrieved a provider can either enhance the list to add provider-specific functions or remove functions and/or signatures if the provider does not support them.
+
+The following sections list all newly added functions only. Functions already supported (like Max, Min, Sum) are not listed.
+
+
+=== Aggregate Function ===
+
+'''Median''': 
+Represents an inverse distribution function that assumes a continuous distribution model. It takes a numeric value and returns the middle value or an interpolated value that would be the middle value once the values are sorted.
+
+'''Stddev''':
+Returns the sample standard deviation of a provided expression
+
+
+=== Conversion Functions ===
+
+'''!NullValue''': Evaluates two expressions and returns the first one if it does not evaluate to NULL, the second otherwise.
+
+'''!ToDate''': Converts a string with date information into a date.
+
+'''!ToDouble''': Converts a numeric or string expression to a double.
+
+'''!ToFloat''':Converts a numeric or string expression to a float.
+
+'''!ToInt32''': Converts a numeric or string expression to an int32.
+
+'''!ToInt64''': Converts a numeric or string expression to an int64.
+
+'''!ToString''': Converts a numeric or date expression to a string.
+
+
+=== Date Functions ===
+
+'''!AddMonths''': Adds a specified number of months to a given date. 
+
+'''!CurrentDate''':Returns the current date.
+
+'''Extract''': Extracts a specified part of a date.
+
+'''!MonthsBetween''': Calculates the number of months between two given dates.
+
+
+=== Mathematical Functions ===
+
+'''Abs''': Returns the absolute value of a numeric expression.
+
+'''Acos''': Returns the arc cosine of a numeric expression.
+
+'''Asin''': Returns the arc sine of a numeric expression.
+
+'''Atan''': Returns the arc tangent of a numeric expression.
+
+'''Atan2''': Returns the arc tangent based on two numeric expressions.
+
+'''Cos''': Returns the cosine of a numeric expression.
+
+'''Exp''': Returns e raised to the power of a numeric expression.
+
+'''Ln''':  Returns the natural logarithm of a numeric expression.
+
+'''Log''': Returns the logarithm of a numeric expression using the provided base.
+
+'''Mod''': Returns the remainder of the division of two numeric expressions.
+
+'''Power''': Returns the result of one numeric expression raised to the power of a second numeric expression.
+
+'''Remainder''': Returns the remainder of the division of two numeric expressions. In contrast to the function Mod, this routine uses a different calculation algorithm.
+
+'''Sin''': Returns the sine of a numeric expression.
+
+'''Sqrt''': Returns the square root of a numeric expression.
+
+'''Tan''': Returns the tangent of a numeric expression.
+
+
+=== Numeric Functions ===
+
+'''Round''': Returns the rounded value of a numeric expression.
+
+'''Sign''': Returns the sign of a numeric expression.
+
+'''Trunc''': Truncates a numeric or date expression.
+
+
+=== String Functions ===
+
+'''Instr''': Returns the position of a substring in a given string.
+
+'''Length''': Returns the length of a string.
+
+'''Lpad''': Pads a string to the left to a defined string length using the provided pading string.
+
+'''Ltrim''': Removes leading blanks from a string.
+
+'''Rpad''': Pads a string to the right to a defined string length using the provided pading string.
+
+'''Rtrim''': Removes trailing blanks from a string.
+
+'''Soundex''': Returns the phonetic representation of a string.
+
+'''Substr''': Extracts a substring from a given string.
+
+'''Translate''': Replaces a subset of characters in a string with the corresponding value in a set of replacement characters.
+
+'''Trim''':  Removes leading and/or trailing blanks from a string.
+
+
+== Affected Providers ==
+
+This enhancement will affect the following providers: ArcSDE, MySQL, ODBC, SDF, SHP and SQL Server. For the supported signatures and function return values please refer to the attached document.
+
+
+== Required FDO Enhancements ==
+
+Some of the functions take parameters for which values have to come from a pre-defined set of values. For example, the function TRIM takes a string to be processed and a parameter to identify whether the leading, trailing or leading and trailing blanks should be removed. The FDO argument definition class does not allow the specification of such an argument value list. Therefore, to properly implement the function signatures this RFC proposes to enhance the class FdoArgumentDefinition to allow for the specification of argument value list data. This enhancement will introduce a new property and two functions to the named class. None of the existing functions - constructors included - will be changed. The enhancement will take advantage of already existing FDO classes to define value lists. By default, the argument value list will be set to NULL hence providing backward compatibility. No changes in any provider are required unless the provider wants to use this feature. 
+
+Under no circumstances should this enhancement be seen as an implementation of general argument constraints capabilities.
+
+
+=== Proposed Solution ===
+
+This section outlines the necessary code changes in the managed and unmanaged part of FDO.
+
+==== Unmanaged Code ====
+
+The following outlines the necessary changes in the unmanaged code:
+
+{{{
+class FdoArgumentDefinition : public FdoIDisposable
+{
+  …
+  public:
+      /// \brief
+      /// Returns the argument value list for the current argument
+      /// 
+      /// \return
+      /// Returns the argument value list for the current argument
+      FDO_API FdoPropertyValueConstraintList *GetArgumentValueList ();
+
+      /// \brief
+      /// Sets the argument value list for the current argument
+      FDO_API void SetArgumentValueList (FdoPropertyValueConstraintList *argumentValueList);
+  …
+  protected:
+  …
+      FdoPropertyValueConstraintList *m_argumentValueList;
+  …
+}
+}}}
+
+
+==== Managed Code ====
+
+The following outlines the necessary changes in the managed code:
+
+{{{
+public __gc class ArgumentDefinition : public NAMESPACE_OSGEO_RUNTIME::Disposable
+{
+  public:
+      /// \brief
+      /// Returns the argument value list for the current argument
+      /// 
+      /// \return
+      /// Returns the argument value list for the current argument
+      __property NAMESPACE_OSGEO_FDO_SCHEMA::PropertyValueConstraintList Get_ArgumentValueList ();
+
+      /// \brief
+      /// Sets the argument value list for the current argument
+      __property System::Void set_ArgumentValueList (NAMESPACE_OSGEO_FDO_SCHEMA::PropertyValueConstraintList *argumentValueList);
+  …
+  protected:
+  …
+      FdoPropertyValueConstraintList *m_argumentValueList;
+  …
+}
+}}}
+
+
+=== Example ===
+
+The following code example shows how the argument value list enhancement will be used. In this case, it demonstrates the creation of the function definition for the Expression Engine function TRIM. As previously mentioned, one of the arguments identifies what needs to be done. The value of the argument can be either BOTH (in which case leading and trailing blanks are removed from a given string), LEADING (only leading blanks are removed) or TRAILING (only trailing blanks are removed). Please note that the example does not externalize public names and descriptions.
+
+{{{
+    FdoPtr<FdoPropertyValueConstraintList> argumentValueList = FdoPropertyValueConstraintList::Create();
+    FdoPtr<FdoDataValueCollection> values = argumentValueList->GetConstraintList();
+    values->Add( FdoStringValue::Create(L"BOTH") );
+    values->Add( FdoStringValue::Create(L"LEADING") );
+    values->Add( FdoStringValue::Create(L"TRAILING") );
+
+    FdoPtr<FdoArgumentDefinition> arg1 =
+                 FdoArgumentDefinition::Create(L"parameter_1", L”String to be trimmed”, FdoDataType_String);
+    FdoPtr<FdoArgumentDefinition> arg2 =
+                  FdoArgumentDefinition::Create(L"trim_operation", L”Trim operation to be executed”, FdoDataType_String);
+    arg2->SetArgumentValueList(argumentValueList);
+
+    FdoPtr<FdoArgumentDefinitionCollection>trimParameters1 = FdoArgumentDefinitionCollection::Create();
+    FdoPtr<FdoArgumentDefinitionCollection>trimParameters2 = FdoArgumentDefinitionCollection::Create();
+
+    trimParameters1->Add(arg1);
+    trimParameters2->Add(arg1);
+    trimParameters2->Add(arg2);
+
+    FdoPtr<FdoSignatureDefinition> trimSignature;
+    FdoPtr<FdoSignatureDefinitionCollection> trimSignatures = FdoSignatureDefinitionCollection::Create();
+
+    trimSignature = FdoSignatureDefinition::Create(FdoDataType_String, trimParameters1);
+    trimSignatures->Add(trimSignature);
+    trimSignature = FdoSignatureDefinition::Create(FdoDataType_String, trimParameters2);
+    trimSignatures->Add(ltrimSignature);
+
+    FdoPtr<FdoFunctionDefinition> func =
+                  FdoFunctionDefinition::Create(L”TRIM”, L”Trims leading and/or trailing blanks”, false, trimSignatures);
+}}}
+
+
+== Implications ==
+
+This change will not cause any side-effects, nor any compatibility problems. No existing provider needs to change unless the provider wants to use the new feature.
+
+== Test Plan ==
+
+Existing unit tests will be enhanced to test those changes.
+
+== Funding/Resources ==
+
+Autodesk to provide resource / funding to update FDO core and the ArcSDE, MySQL, ODBC, SDF, SHP and SQL Server Providers.
+