Function

See Also: Methods, Variable Parameter Lists, End_Function, Function_Return, Get, Procedure

Purpose

To define a function.

Syntax

Function {function-name} [Global] [{type} [ByRef] {param} … ] Returns {return-type}

    …

End_Function

Or

Function {function-name} [{type} {param} … ] Returns {return-type}

    …

End_Function

Argument Explanation

{function-name} The name of the function being created. {function-name} may be between 1 and 4096 characters in length, must start with a letter, and may not contain spaces. Recommended characters are 0-9, a-z, A-Z and _ (underscore).

{type} The data type of each parameter param in the parameter list.

{param} The name of the parameter passed to the function.

{return-type} The data type of the value returned by the function.

What It Does

A class's behavior is defined by the methods that it implements. In DataFlex, there are two types of methods: functions and procedures. A function is used whenever you require a return value whereas procedures are useful for implementations of events.

The Function command defines an implementation of a function in the object or class where it is defined. Within the scope of the function are the variables on the parameter list and any variables declared within the body of the function.

You may call a function with the various forms of the Get command (e.g; Delegate Get and Forward Get, Broadcast Get) or by using it in an expression:

Object oTest Is A Button

    // Define a function that changes the order of the name 

    // and places a comma separator.

    Function SwitchName String sFirstName String sLastName Returns String

        Function_Return (sLastName +  "," + sFirstName) 

    End_Function

    Procedure OnClick

        String sSwitchedName

        Move (SwitchName(Self, "John", "Smith")) to sSwitchedName

        Showln "Formatted Name is " sSwitchedName

        Get SwitchName "John" "Smith" to sSwitchedName

        Showln "Formatted Name is " sSwitchedName

    End_Procedure

End_Object

The name of the function, fnName, must be unique in the current object or class.

The End_Function command defines the end of the function-definition block. You may use the Function_Return command within the body of the function to exit the function, returning a value. If no Function_Return executes before the End_Function command, the function returns zero.

Global Functions

The keyword Global allows you to define a global function. A global function may be used throughout your program. The following is the same example as before, but the function is now defined as global.

Function SwitchName Global String sFirstName String sLastName Returns String

    Function_Return( sLastName +  "," + sFirstName) 

End_Function

Object oTest Is A Button

    // Define a function that changes the order of the name 

    // and places a comma separator.

    Procedure OnClick

        String sSwitchedName

        Move (SwitchName("John", "Smith")) to sSwitchedName

        Showln "Formatted Name is " sSwitchedName

        Get SwitchName "John" "Smith" to sSwitchedName

        Showln "Formatted Name is " sSwitchedName

    End_Procedure

End_Object

Note that like DataFlex expression functions, when a global function is invoked, you do not put an object reference such as "Self". Global functions are not sent to objects. They are defined for the whole system.

By Reference Parameters

The special ByRef keyword can be used to specify a parameter that is passed by reference instead of by value. When a parameter is passed by reference the code that calls the function must pass the address of a variable of the correct type as the parameter. By reference parameters allow the function to directly modify the value of the variable passed to it. For example…

Function LeftMostChar Global String ByRef sValue Returns String

    // Returns the leftmost character of the passed string. Removes

    // this character from the passed string.

    String sReturns

    Move (Left(sValue, 1)) to sReturns

    Move (Remove(sValue, 1, 1)) to sValue

    Function_Return sReturns

End_Function

String sName sChar

Integer iLength

Move "Frank Lloyd Wright" to sName

While (Length(sName) > 0)

    Move (LeftMostChar(&sName)) to sChar

    Show sChar " "

Loop

For more information refer to Parameter Passing.

Notes

• If you call a function and pass an parameter that does not match the type in your function declaration, DataFlex will perform type conversion.

• The total number of parameters passed to a function is contained in the predefined variable Num_Arguments. This feature allows you to create different implementations for the same function, depending on the number of parameters provided.

• User defined and predefined functions may be included in user defined functions, down to a maximum depth of 18 levels, but a user-defined function may not be defined within a global function.

• Often a Procedure Set and Function pair will be created using the same name allowing the developer to access the methods as a "get/set" pair.
  
  A Function and/or Procedure Set method declared in the same class and with the same name as an actual property will not execute.
  
  You may create Function and Procedure Set methods of the same name as a property in a subclass of the class where the property is declared, but not in the same class.