advr.hlp (Topic list)
Important Notice
The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.
FUNCTION Statement Details
  Summary  Details  Example                Contents  Index  Back
──────────────────────────────────────────────────────────────────────────────
 [STATIC] FUNCTION globalname [(parameterlist)] [AS type]
      [statementblock]
      globalname = expression]
      [EXIT FUNCTION]
      [statementblock]
      globalname = expression]
 END FUNCTION
 
 Usage Notes
   ■ FUNCTION and END FUNCTION mark the beginning and end of a FUNCTION
     procedure. You can use the optional EXIT FUNCTION statement to exit
     a FUNCTION from any point within the procedure.
 
   ■ STATIC indicates that the value of a FUNCTION's local variables are
     saved between calls. Without STATIC, the local variables are allocated
     each time the FUNCTION is invoked, and the variable values are lost
     when the FUNCTION returns to the calling program.
 
   ■ Using the STATIC attribute increases execution speed slightly.
 
   ■ The STATIC attribute does not affect variables that are used in a
     FUNCTION but declared outside the FUNCTION in DIM or COMMON statements
     using the SHARED statement.
     See: COMMON Statement  DIM Statement  SHARED Statement
 
   ■ The FUNCTION name cannot appear in any other SUB or FUNCTION statement
     in the same application unless the FUNCTION is in form code. Note: Code
     within a form module is known only to the procedures in that module.
 
   ■ The name of the FUNCTION determines the data type the FUNCTION returns.
     For example, to create a FUNCTION procedure that returns a string, you
     include a dollar sign ($) in the name, or give it a name defined as a
     string name with a DEFSTR statement. Alternatively, you can use an AS
     clause following parameterlist to identify the data type.
     See: DEFtype Statements
 
   ■ BYVAL can be used only with simple numeric types (INTEGER, LONG, SINGLE,
     DOUBLE, or CURRENCY). The additional types, FORM and CONTROL, can only
     be used when a form or control is passed as an argument to a SUB or
     FUNCTION procedure.
 
   ■ Unless identified with the BYVAL keyword, individual arguments are
     passed by reference, so any change to an argument value inside the
     FUNCTION procedure changes its value in the calling procedure. If an
     argument passed to a function is an expression, it is treated the same
     as if it used the BYVAL keyword - that is, no part of the expression is
     altered by the function.
 
   ■ If a parameter is passed by reference, any change to the parameter
     value inside the procedure changes its value in the calling program.
 
   ■ If no value is assigned to the FUNCTION name, the procedure returns a
     default value: A numeric function returns zero; a string function
     returns the null string ("").
 
   ■ A FUNCTION can be recursive - that is, it can call itself to perform a
     given task. The STATIC keyword is usually not used with recursive
     FUNCTION procedures.
 
   ■ Any FUNCTION procedure variables or arrays are considered local to that
     FUNCTION procedure, unless they are explicitly declared as shared
     variables in a SHARED statement. See: SHARED Statement
 
   ■ Avoid using I/O statements in a FUNCTION procedure called from an
     I/O statement; they can cause unpredictable results.
 
   ■ Because Visual Basic may rearrange arithmetic expressions to attain
     greater efficiency, avoid using FUNCTION procedures that change program
     variables in arithmetic expressions.
 
   ■ A FUNCTION procedure is a separate procedure, like a SUB procedure. It
     can accept arguments, perform a series of statements, and change the
     values of its arguments. However, unlike a SUB procedure, a FUNCTION
     procedure is used in an expression in the same manner as any Visual
     Basic intrinsic function (such as SQR, COS, or CHR$).
     See: SUB Statement
 
   ■ You cannot use an array of fixed-length strings as an argument when
     calling a FUNCTION procedure, because Visual Basic converts a simple
     fixed-length string argument to a variable-length string argument before
     passing the string to a FUNCTION procedure.