Fundamentals Overview IDE (Editor) Syntax Variables Data Types Declarations Scope Operators

Standard Functions Arithmetic Trigonometry Strings Arrays Date/Time Flow Control Procedures Printing Files Folders

Additional Capabilities Keyboard Sound Graphics Concepts Screen (text) Screen (drawing) Gaming (sprites) Event Trapping Errors System Calls

Procedures
In QBasic, a programmer can name a block of code which can be executed by simply calling out that name. These named blocks of code are called procedures. There are subroutine procedures and function procedures.

Subroutines simply execute one of more statements. They do not return values.

Functions not only execute one or more statements, but also returns a value of a declared type.

QBasic provides several ways of declaring procedures and of executing procedures, as shown in the following table of keywords.

Declaring Procedures	declare, sub, function, def fn
Using Procedures	call, as, any
Exiting Procedures	exit

Declaring Procedures
Use of the Declare statement to define a procedure is required if you call the procedures without CALL. However, QBasic will automatically add the Declare statement whenever you save your program.

     Declare Sub MySubName (arglist) STATIC
     Declare Function MyFunctionName (arglist) STATIC

            # arglist/static are optional in a Declare statement

     MySubName and MyFunctionName must follow variable naming syntax

     MyFunctionName determines the type of variable to be returned. If
     no variable type suffix is used, then a type single is returned.
     Otherwise, the type returned is defined by the variable type suffix
     used in the function name, i.e.:

     Declare Function MyFunctionX (arglist)    

     where X is one of the following variable type suffixes may be used
           $ suffix defines a string
           % suffix defines an integer
           & suffix defines a long integer
           ! suffix defines a single
           # suffix defines a double

Procedure Arguments
Procedure definitions may include a list of arguments, with optional type definition. When calling a procedure, variables of the same data type must be passed to the procedure. The procedure is allowed to modify the passed variables unless the variables was enclosed in () as part of the calling statement.

The argument list can take on several forms, as shown in the next three examples.

 
     var1 AS type, var2 as type, ...    
     where type = integer, long, single, double, string, any,
                  or user-defined type

     var1, var2, var3, ...         
     where type is not defined and defaults to single

     var%, var$, var#, var&, var!, ...
     where the variable type suffix is part of procedure definition

Note the "any" type, which means that any type of value may be passed to the procedure.

Calling Procedures
A procedure can be called in two ways - using "call" to run the procedure or simply typing in the procedure name alone or as part of an expression (functions only).

   call MySub(arglist)       # call used, so arglist parentheses required
   MySub arglist             # arglist not enclosed by parentheses
   result$ = MyFunction      # return value assigned to result$

Exiting Procedures
Normally, a procedure ends when the "End Sub" or "End Function" line is executed.

     Function MyFunction         Sub MySub
         .. statements              .. statements
     End Function                End Sub

QBasic also provides the Exit statement to end a procedure early.

     Function MyFunction                 Sub MySub
        .. statements executed              .. statements executed
        exit function                       exit sub
        .. statements not executed          .. statements not executed
     End Function                        End Sub

Procedures and Variable Scope
Normally, procedures do not have access to module-level variables. However, if a module-level variable is passed to a procedure as an argument, then the procedure can modify the module-level variable. Also, any module-level variables declared using the keyword SHARED.

Variables created within a procedure exist only for the duration of the procedure call. Once the procedure ends, the variables are deleted and are not accessible at the module leve. An exception is that if the keyword STATIC was used in the declaration of the procedure all variables created within the procedure are stored until the next call of the procedure. The stored variables are not accessible at the module-level.

Procedure Location
A procedure may be placed anywhere in the QBasic program, as long as the Declare statement is placed before the procedures is called. The QBasic editor manages this requirement automatically.

Return Values - Functions Only
When a Function is called it returns a value by assigning a value to the function name as though it were a variable. The value assigned to the function name must be of the same type as the Function declaration

     Declare MyFunction% (i as integer)  # function type is integer
                                         # argument type is long
                                         # function name is MyFunction
     Function MyFunction()
          MyFunction = 2       # MyFunction is assigned an integer value
     End Function

     Examples of calling a function:
     var% = 5
     call result% = MyFunction(var%)  # integer variable passed
     result% = MyFunction var%        # no call, do not use parentheses

If no value is assigned to the function name (such as when an Exit is used to return before a value has been assigned) the function value returns a zero for numeric function types or an empty string for string function types.

If you have suggestions or corrections to this page, please let me know.