+---------------------------------+
|            FUNCTION             |
+---------------------------------+
FUNCTION <function name>

-----------------------------------
Defines start of a subroutine.
-----------------------------------

In many programs certain routines are frequently repeated.  Defining
these commonly used routines as separate functions reduces program size
and complexity, and eases program maintenance.

FUNCTION <function name> is a statement within a program.  It designates
the beginning of each function in a program and identifies the function
by name.  Function names may be up to 10 characters long.  They must
begin with a letter or underscore and can contain any combination of
letters, numbers and underscores.

The first line containing the FUNCTION <function name> is followed by a
series of commands that make up the function.  You may optionally
include RETURN as the last line of a function although an implicit
RETURN is automatically executed following the last statement of a
function.

The next FUNCTION statement or the end of the file, whichever comes
first, signals the end of the function.

When a function is executed with DO <program>, the function is searched
for in a specific order.

        . First the file containing the DO <function name> command is searched.

        . If the function is not found there, the SET PROCEDURE file is
searched (if one is set).

        . Next, FoxPro searches the programs in the execution chain.  Program
files are searched beginning with the most recently executed program and
continuing through the first executed program.

        . If the function is still not found, FoxPro searches for a stand-alone
program.  If a matching program file is found the program is executed.
Otherwise an error message "File does not exist" is returned.

        . DO IN searches only the named file.

By default, variables are passed to functions by value.  See the help
for SET UDFPARMS for information on passing variables to functions by
reference.

+---------------------------------+
|         Program Example         |
+---------------------------------+
The example below shows LONGDATE and QUARTER UDFs.  LONGDATE function
converts date variable into character string suitable for use in
reports.  QUARTER function returns quarter when given month number.
These two functions are used to print heading for report.

SET CENTURY ON
@ 5,0 SAY longdate({08/19/89})
@ 6,5 SAY quarter(DATE())

FUNCTION longdate
PARAMETER mdate
RETURN CDOW(mdate) + ', ' + MDY(mdate)

FUNCTION quarter
PARAMETER qdate
DO CASE
        CASE MONTH (qdate) > 9
                RETURN 'Fourth Quarter'
        CASE MONTH (qdate) > 6
                RETURN 'Third Quarter'
        CASE MONTH (qdate) > 3
                RETURN 'Second Quarter'
        OTHERWISE
                RETURN 'First Quarter'
ENDCASE

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

See Also:  PARAMETERS, PARAMETERS(), RETURN, PRIVATE, PUBLIC,
USER-DEFINED FUNCTIONS (UDFs), SET UDFPARMS

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