FDO RFC 8 - 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 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.

Note: This RFC does not address geometric functions like Area and Length. This will be addressed in a separate RFC. The reason for this is that there are some issues with respect to coordinate systems/projections to be considered. It is expected that this will result in some discussion within the group. FDO includes coordinate system specification via spatial context, but FDO itself does not expose any projection capabilities nor does it specify use of coordinate system packages. Most providers do not have coordinate system packages available internally. MapGuide for instance does all of its projection work separately, outside of FDO. So we should discuss what happens if the data is lat/long (for example).

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. The returned value is -1 if the expression evaluates to a value les than 0, 0 if the expression evaluates to 0 and 1 if the expression evaluates to a value bigger than 0.

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.