Values that a function can manipulate

The values that a function can manipulate are:

  • Values contained in module-level variables that the function can access directly
  • Values contained in member variables of a class that a function can access directly if it has been defined as a member of that class
  • Values that the application passes to the function at run time either directly or by reference as arguments (sometimes called actual parameters) in the statement that calls the function
  • Values contained in variables (known as local variables) that the function defines for its own use
  • Values returned by another function that the function calls

The following sections describe the way a function handles module-level variables, the values that the application passes it as arguments when calling the function, and variables that a function defines for its own use.

Module-level variables

As long as a function doesn't define a local variable with the same name, it can access a variable defined at module level.

For example:

Dim anInt As Integer
Function ThreeTimes1 As Double
   ' Multiply the module-level variable anInt% by 3
   ' and assign the result as the function's return value.
   ThreeTimes1# = anInt% * 3
End Function
anInt% = 5
Print ThreeTimes1#
' Output: 15

Using procedures to directly manipulate module-level variables is not recommended because you can introduce errors into your application, especially if you don't always declare your variables explicitly.

Parameters

When you define a function, you can declare a list of variables (sometimes called formal parameters or, simply, parameters) as part of its signature. These variables are placeholders for values that the application passes to the function at run time and that the function then uses when it executes. The run-time values that the application passes the function are known as actual parameters or arguments.

Local variables

A procedure can define variables for its own use. By default, a local variable exists only as long as the procedure in which it is defined is executing. If you include the Static keyword in the declaration of a local variable, that variable retains its address in memory, and its value persists between calls to the procedure. In either case, local variables are not visible outside of the procedure in which you define them though you can pass them as arguments to other procedures that the procedure calls.

When you define a local variable with the same name as a module-level variable, the procedure uses the local variable and ignores the module-level variable. This is known as shadowing.

For example, defining counter% as a local variable makes this example work properly. The calling While loop executes three times, because BadCount no longer has any effect on the counter variable in the calling loop:

Dim counter As Integer          ' Module-level variable
Function BadCount As Integer
   Dim counter As Integer       ' Local variable
   counter% = 1
   While counter% < 4
     ' Do something. 
     counter% = counter% +1
   Wend
   BadCount% = counter%
End Function
counter% = 1
While counter% < 4
  Print "BadCount% = " & BadCount%
  counter% = counter% +1
Wend  

This example shows static and nonstatic local variables and how to pass a local variable as an argument in a call to another procedure. The example consists of two functions, GetID and FindMatch. GetId prompts the user for a password (the first name) and then calls FindMatch, passing it the password. FindMatch determines if the name is in the module-level array theNames. If it is, FindMatch returns a value of True (-1) and GetId displays a confirmation message. If the name is not in the array, FindMatch increments the static variable callCounter% by 1 and returns a value of False (0), at which point GetId displays a message asking the user to try again or quit. If the user tries again, GetId again calls FindMatch to check the name. If the user enters three invalid names in a row (in three successive calls to FindMatch), FindMatch terminates the program.

%Include "LSCONST.LSS"
' Declare an array of Strings and initialize it with some 
' names.
Dim theNames(1 to 6) As String
  theNames(1) = "Alex" 
  theNames(2) = "Leah"
  theNames(3) = "Monica"
  theNames(4) = "Martin"
  theNames(5) = "Elizabeth"
  theNames(6) = "Don"

Function FindMatch(yourName As String) As Boolean
  Static callCounter As Integer ' To count the number of
                                ' calls to FindMatch.
Dim counter As Integer    ' Loop counter.
FindMatch = FALSE
For counter% = 1 to 6
If yourName$ = theNames(counter%) Then
  FindMatch = TRUE
Exit For                  ' Exit from the For loop now.
End If
Next

' If the user enters an invalid name, 
' increment callCounter%.
If FindMatch = False Then callCounter% = callCounter% + 1
' After three consecutive invalid names, terminate the script.
If callCounter% = 3 Then 
Print "Go away, friend."
End                         ' Terminate execution.
   End If
End Function

Function GetId As String
    Dim match As Boolean
    Dim goAgain As Boolean
    Dim pswd As String
    Dim msg As String
    Dim msgSet As Integer
    Dim ans As Integer
    match = FALSE
    goAgain = TRUE
  msg$ = "That's not a valid name." & _
         "Would you like to try again?"
    msgSet% = MB_YESNO + MB_ICONQUESTION 

     ' Go through this While loop at least once.
     While match = FALSE and goAgain = TRUE
        pswd$ = InputBox$("Please enter your name.")
        ' Call FindMatch, passing it the name the user
        ' just entered (pswd$).
        match = FindMatch(pswd$)
        ' If the name the user entered isn't in theNames,
        ' see if the user would like to try again or quit.
        If match = False Then
           ans% = MessageBox(msg$, msgSet%)
           ' If No, end the While loop.
             If ans% = IDNO Then
                goAgain = FALSE
                GetID$ = "Have a nice day, " & pswd$ & "."
             End If
         Else
            GetID$ = "Your ID is valid, " & pswd$ & "."
         End If
     Wend
End Function

Print GetID$
' Output: (1) The application prompts "Please enter your name."
' The user enters the name "Martin"
' The application answers  "Your ID is valid, Martin."
' Output: (2)The application prompts "Please enter your name."
' The user enters the name "Fred" 
' The application answers "That's not a valid name. Would you 
' like to try again?"
' The user selects No
' The application answers "Have a nice day, Fred."
' Output: (3)he application prompts "Please enter your name."
' The user enters the name "Fred" 
' The application answers "That's not a valid name. Would you 
' like to try again?"
' The user selects Yes, then enters "Frank," 
' The application answers "That's not a valid name. Would you 
' like to try again?"
' The user selects Yes, then enters "Joe":
' The application answers "Go away, friend."