+---------------------------------+
|  User-Defined Functions (UDFs)  |
+---------------------------------+
A user-defined function is a program that returns a value to calling
program (program that executes UDF).  UDF can be a stand alone program,
or procedure or function in a program. UDFs should not be given the same
name as a built-in function (or its abbreviation), because the built-in
function takes precedence.

Returning a Value
        A value can be returned with RETURN <expr>.  RETURN sends a value back
to calling program and is last command executed in UDF.

Parameter Passing
        Data can be passed in form of parameters to UDF.  PARAMETERS statement
in UDF identifies data passed to UDF and assigns local names to data.
Contents of entire arrays can be passed to UDF.  By default, parameters
are passed to a UDF by value, but this default can be changed with the
SET UDFPARMS TO REFERENCE command.

Calling a UDF
        UDFs are referenced by their name followed by a set of parentheses.
Parentheses can optionally contain parameters that are passed to UDF.

UDFs in Logical Expressions
        If one or more UDFs are used in logical expression, they are evaluated
from left to right.

UDFs in Commands
        Many FoxPro commands allow UDFs in their clauses.  UDFs let you execute
routines that can validate data, display a message, enable or disable
controls and so on.

Where UDFs can be used
        UDFs may not be used in certain places.  For a complete listing of
where UDFs may be used, see the User-Defined Functions section in the
FoxPro Commands & Functions manual.

+---------------------------------+
|         Program Example         |
+---------------------------------+
CUSTOMER database is opened, and BROWSE is issued to open a Browse
window for database.  VALID clause calls RIGHTTAX() UDF which tests if
proper tax rate is entered into TAXRATE field.  Proper range for taxes
is 1.0 to 10.0.

If tax rate entered does not fall in this range, a message is displayed
with proper tax rate range.  You cannot move off the record until proper
tax rate is entered.

CLOSE ALL
USE customer

BROWSE FIELDS taxrate, company, contact VALID:F righttax()

FUNCTION righttax  && Called by BROWSE VALID

IF NOT BETWEEN(taxrate, 1.0, 10.0)  && Bad tax rate entered
        WAIT WINDOW 'Enter tax rate from 1.0 to 10.0' NOWAIT
        RETURN 0
ELSE         && Good tax rate entered
        RETURN .T.  && Okay to move to another field or record
ENDIF

This example references a UDF called VALIDATE() in an @ ... GET to
validate input for STATE field.  If a valid abbreviation is not entered,
UDF displays a popup of valid state abbreviations to choose from.

CLOSE ALL
SELECT 0
USE states TAG state
DEFINE POPUP popstate FROM 0,60 TO 15,65 PROMPT FIELD state
ON SELECTION POPUP popstate DO deactpop
SELECT 0
USE customer
CLEAR
@ 1,3  SAY 'Customer: ' GET company
@ 3,3  SAY 'Address: '  GET address1
@ 5,3  SAY 'City: '     GET city
@ 7,3  SAY 'State: '    GET state PICTURE '!!' VALID validate(state)
@ 7,18 SAY 'Zip: '      GET zip
READ
USE
RETURN

*** A UDF that validates state abbreviations ***

FUNCTION validate
PARAMETER stateid
SELECT states
SEEK stateid

IF FOUND()
        SELECT customer
        RETURN .T.
ENDIF

DO WHILE NOT FOUND()
        ACTIVATE POPUP popstate
        SEEK mprompt
ENDDO

SELECT customer
REPLACE state WITH states.state
SHOW GET state
RETURN .T.

PROCEDURE deactpop
STORE PROMPT() TO mprompt
DEACTIVATE POPUP
RETURN

-----------------------------------

See Also:  FUNCTION, PROCEDURE, RETURN, PARAMETERS, PARAMETERS(), SET
UDFPARMS

-----------------------------------