Progress
Language Reference
FUNCTION Statement
Defines or forward declares a user-defined function.
SYNTAX
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:
- That it cannot be invoked from an external procedure-that is, from a procedure file external to the current procedure file
- That the INTERNAL-ENTRIES attribute on the procedure that defines it does not provide its name (unless the procedure that defines it is the current procedure file)
- That the GET-SIGNATURE method on the procedure that defines it does not provide its signature (unless the procedure that defines it is the current procedure file)
( 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.
[ 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 FORThe 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 .
EXAMPLESThe first example,
r-udf1.p
, defines and references the user-defined function doubler(), which accepts an integer and returns the integer multiplied by two.
The second example,
r-udf2.p
, forward declares, references, and defines doubler().
The third example consists of two procedures,
r-udf3.p
andr-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.
The second procedure,
r-udfdef.p
, defines doubler().
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).
NOTES
- Before you reference a user-defined function, you must forward declare it, declare it external (by using FUNCTION statement’s IN option), or define it.
- To declare a function forward or external, you must specify at minimum the function name and return type, and for each parameter, the mode and data type.
- To define a function you have forward declared, you must specify at minimum the function name, the return type, the parameters (if any), and the logic.
- A period must appear after the FUNCTION statement and after each logic statement.
- A user-defined function’s logic must not reference, either directly or indirectly, statements that block I/O-namely, the UPDATE, SET, PROMPT-FOR, INSERT, CHOOSE, READKEY, and WAIT-FOR statements.
- You cannot define shared objects, work tables, or temporary tables within a user-defined function.
- Progress implements scalar parameters of user-defined functions as NO-UNDO variables.
- A reference to a user-defined function must match the forward declaration or definition with respect to the return type, and with respect to the number, type, and mode of the parameters.
- When a Progress 4GL predicate (such as a WHERE clause) contains a user-defined function, Progress evaluates the function once-when it opens the query or enters the FOR EACH block
- When Progress encounters a user-defined function declared external that references a user-defined function declared external that references a user-defined function declared external, etc., Progress tolerates up to 64 levels of indirection. At the 65th level, Progress issues an error message and returns the UNKNOWN value.
- If a user-defined function has one or more buffer parameters and its definition resides in another procedure, the referencing procedure and the defining procedure must reside on the same machine. If a user-defined function does not have buffer parameters, the invoking procedure and the defining procedure can reside on different machines.
- When you invoke a user-defined function (or a built-in function), you need not assign the function’s return value to a variable. You might use this technique with a function that performs some action on a persistent object, such as a shared variable, when you want the action to occur and do not want to check the return value. An example is the following:
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 |