Progress
Language Reference


FUNCTION Statement

Interfaces
OS
SpeedScript
All
All
Yes

Defines or forward declares a user-defined function.

SYNTAX

FUNCTION function-name [ RETURNS ] data-type [ PRIVATE ]
  [ ( param1 [ , param2  ] ... ) ]
  {     FORWARD 
     |  [ MAP [ TO ] actual-name ] IN proc-handle
     |  IN SUPER
  } 

function-name

The name of the function. You must avoid Progress reserved keywords. For a list of Progress keywords, see the "Keyword Index" in this manual.

data-type

The data type of the item the function returns. Progress provides these data types: CHARACTER, COM-HANDLE, DATE, DECIMAL, HANDLE, INTEGER, LOGICAL, MEMPTR, RAW, RECID, ROWID, and WIDGET-HANDLE.

PRIVATE

Indicates the following about the user-defined function:

( param1 [ , param2 ] ... )

One or more parameters of the function. Use the following syntax to define each parameter, which can be scalar, temporary table, or buffer.

SYNTAX
{  { [ INPUT ] | OUTPUT | INPUT-OUTPUT } param-name
          AS data-type
  |   [ INPUT ] TABLE FOR temp-table-name
  |   { OUTPUT | INPUT-OUTPUT } TABLE FOR temp-table-name
          [ APPEND ]
  |  BUFFER buffer-name FOR database-table-name
} 

[ INPUT ] | OUTPUT | INPUT-OUTPUT

The mode of a scalar parameter. An input parameter travels from the caller, which sets its value, to the function, which can use the value. An output parameter travels from the function, which sets its value, back to the caller, which can use the value. An input-output parameter travels from the caller, which sets its value, to the function, which can use and reset the value, then back to the caller, which can use the value.

param-name

The name of a scalar parameter.

AS data-type

The data type of a scalar parameter. Progress provides these data types: CHARACTER, COM-HANDLE, DATE, DECIMAL, HANDLE, INTEGER, LOGICAL, MEMPTR, RAW, RECID, ROWID, and WIDGET-HANDLE.

[ INPUT ] TABLE FOR
{ OUTPUT | INPUT-OUTPUT } TABLE FOR

The mode of a temp-table parameter

temp-table-name

The name of a temp-table parameter.

APPEND

Causes an OUTPUT or INPUT-OUTPUT temp-table parameter to append its data to any existing temp-table data. If you omit the APPEND option, an OUTPUT or INPUT-OUTPUT temp-table parameter overwrites any existing temp-table data.

For more information on temp-table parameters, see the chapter on temporary tables and work tables in the Progress Programming Handbook .

buffer-name

The name of a database buffer parameter.

NOTE: A user-defined function that has one or more buffer parameters cannot be invoked remotely. For more information on remote user-defined functions, see Building Distributed Applications Using the Progress AppServer .

database-table-name

The name of a database table.

FORWARD

Lets a procedure reference a user-defined function whose definition has not yet appeared. You must use this option when the definition of the function appears later in the procedure.

The FUNCTION statement with the FORWARD option must include the following information on the function: the data type it returns, and the data type and mode (INPUT, OUTPUT, or INPUT-OUTPUT) of each parameter.

This entry uses the term forward declaration to refer to statements such as the FUNCTION statement with the FORWARD option. This entry also mentions forward declaring user-defined functions.

If you forward declare a user-defined function, reference it, and do not define it before the end of the procedure, the compiler reports an error.

IN proc-handle

Indicates that the function’s definition resides in another procedure. The proc-handle parameter represents an expression that evaluates to a handle to the procedure that defines the function. This procedure can be an active procedure in the local context or a remote persistent procedure. For more information on remote user-defined functions, see Building Distributed Applications Using the Progress AppServer .

The FUNCTION statement with the IN option must include the following information on the function: the data type it returns, and the data type and mode (INPUT, OUTPUT, or INPUT-OUTPUT) of each parameter.

[ MAP [ TO ] actual-name ] IN proc-handle

Indicates three things: that function-name (the second element in the FUNCTION statement) is an alias (alternative name) of the function, that actual-name is the name that appears in the definition of the function, and that the definition of the function resides in another procedure. actual-name represents the actual name of the function. proc-handle represents an expression that evaluates to a handle to the procedure that defines the function.

NOTE: The MAP option might simplify your code if it references two different user-defined functions that have the same name but that reside in different procedures.

IN SUPER

Indicates that the implementation of the function resides in a super procedure. For more information on super procedures, see the “Procedure Overriding” section of the “Block Properties” chapter of the Progress Programming Handbook .

EXAMPLES

The first example, r-udf1.p, defines and references the user-defined function doubler(), which accepts an integer and returns the integer multiplied by two.

r-udf1.p
/* r-udf1.p */
/* Defines and references a user-defined function */

/* Define doubler() */
FUNCTION doubler RETURNS INTEGER (INPUT parm1 AS INTEGER).
    RETURN (2 * parm1). 
    END FUNCTION.   
    
/* Reference doubler() */
DISPLAY  "doubler(0)=" doubler(0) skip
  "doubler(1)=" doubler(1) skip
  "doubler(2)=" doubler(2) skip. 

The second example, r-udf2.p, forward declares, references, and defines doubler().

r-udf2.p
/* r-udf2.p */
/* Forward-declares, references, and defines a user-defined function */

/* Forward declare doubler() */
FUNCTION doubler RETURNS INTEGER (INPUT parm1 AS INTEGER) FORWARD.    
    
/* Reference doubler() */
DISPLAY "doubler(0)=" doubler(0).
DISPLAY "doubler(1)=" doubler(1).
DISPLAY "doubler(2)=" doubler(2).

/* Define doubler() */
FUNCTION doubler RETURNS INTEGER. 
    RETURN (2 * parm1). 
    END FUNCTION. 

The third example consists of two procedures, r-udf3.p and r-udfdef.p. The example illustrates defining a user-defined function in an external procedure.

The first procedure, r-udf3.p, runs the first procedure persistently, declares doubler(), references it, and deletes the persistent procedure.

r-udf3.p
/* r-udf3.p */
/* references an externally-defined user-defined function */

/* define items */
DEFINE VARIABLE myhand AS HANDLE.
DEFINE VARIABLE mystr  AS CHARACTER FORMAT "x(20)".

/* forward declare doubler() */
FUNCTION doubler RETURNS INTEGER (INPUT parm1 AS INTEGER) IN myhand. 

/* run the procedure that defines doubler() */
RUN src\prodoc\langref\r-udfdef.p PERSISTENT SET myhand. 
    
/* reference doubler() */
DISPLAY  "doubler(0)=" doubler(0) skip
        "doubler(1)=" doubler(1) skip
        "doubler(17)=" doubler(17) skip.

/* delete the procedure that defines doubler */
DELETE PROCEDURE(myhand).  

The second procedure, r-udfdef.p, defines doubler().

r-udfdef.p
/* r-udfdef.p */
/* Defines user-defined function doubler() */

FUNCTION doubler RETURNS INTEGER (INPUT parm1 AS INTEGER).
  RETURN (2 * parm1). 
  END FUNCTION.        

To start the third example, run r-udf3.p in the Procedure Editor.

In the fourth example, r-fctrl2.p, the user-defined function fact() implements the factorial function, common in probability and statistics, and commonly notated “!” (6! = 6 x 5 x 4 x 3 x 2; 100! = 100 x 99 x 98 x ... x 2).

r-fctrl2.p
/* r-fctrl2.p */
/* demonstrates user-defined function fact() */

FUNCTION fact RETURNS INTEGER (val AS INTEGER):
  IF val LT 0 THEN RETURN 0.
  IF val LE 1 THEN RETURN 1.
  RETURN val * (val - 1).
END.

DEFINE VARIABLE inp AS INTEGER LABEL "Input Value".
REPEAT:
  UPDATE inp WITH TITLE "Factorials".
  DISPLAY fact(inp) LABEL "Factorial".
END. 

NOTES

SEE ALSO

COMPILE Statement, DYNAMIC-FUNCTION Function, GET-SIGNATURE( ) Method, INTERNAL-ENTRIES Attribute, PROGRAM-NAME Function, RETURN Statement


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095