Here is a summary of the PowerBASIC functions used to create and manage procedures. These are discussed in more detail further down this page.

Procedure Declaration	Sub, Function, Macro, Method, Property
Execute/Terminate	Call, RaiseEvent
Information	FuncName$
Early Termination	Exit

Declarations

And here are the allowed locations of procedure declaration statements within PowerBASIC programs. Note that the PowerBASIC compiler allows the CLASS/Sub/Function code blocks to be placed before or after the PBMain() function.

    #COMPILE EXE

    Function PBMain() As Long              'PBMain() Function
    End Function

    CLASS myClass                          
        INTERFACE myInterface
            METHOD myMethod                'Method
            END METHOD
            PROPERTY myProperty            'Property
            END PROPERTY
        END INTERFACE
    END CLASS

    SUB mySub()                            'Sub
    END SUB

    FUNCTION myFunction()                  'Function
    END FUNCTION

See the declarations tutorial for syntax and examples on using the declare statements. Usage is very straight-forward but be sure to note that when using the GLOBAL declaration on arrays, the array variables must be declared with no subscripts.

Sub and Function Examples
To aid in the discussion of these two types of procedure (Sub and Function), here is a very simple example of each.

    Function MyFunc(nVar As Long) As LONG  'nVar is argument passed to MyFunct
        nVar = nVar + 1                    'increments nVar by 1
        MyFunc = 1                         'Function return value set to 1
    End Function
    
    Sub MySub(nVar As Long)                'nVar is argument passed to MySub
        MSGBox nVar                        'nVar is shown in a MSGBox
    End Sub

Both procedure types can be given one or more values when called. In these examples, a single variable called nVar (long integer) is made available to each procedure. When the Sub/Function procedures are called, the calling source code provides nVar.

The two procedures differ in that a function can act like a variable - returning a value when the last line of the function code is executed. A subroutine (Sub) cannot return values. It simply executes the lines of code within it and returns execution to the point in source code which called the subroutine.

Calling Sub/Function Procedures
To execute a Sub simply put its name on a line of code by itself, including any needed arguments. However, a Function returns a value and is inserted into a PowerBASIC expression like any other variable. Here are some statements which show how to call the Sub/Function examples given above.

    Dim nVar As Long          'variable nVar is defined as long integer
    nVar = 5                  'nVar value set to 5
    MySub(nVar)               'executes MySub.  MSGBox displays "5"

    Dim nVar, Result As Long  'two variables defined - nVar and Result
    nVar = 5                  'nVar value set to 5
    Result = MyFunc(nVar)     'Result = 1, nVar = 6. Treats MyFunc like a variable
                              'whose value is assigned to Result

In both examples, code is shown that creates variables outside the Sub or Function. The variable nVar is passed as an argument to both procedures. In the Sub, the value of nVar is displayed. In the Function, the value of nVar is changed - both inside and outside the function.

Sub/Function Location
In a PowerBASIC source code file, Sub/Function procedures may be placed in any order. The compiler reads the entire source code before attempting to execute the PBMAIN() function, so the order in which procedures are placed in the source code file is not important.

It is common, however, for the PBMAIN() function to be placed at the top of a source code file so that a programmer can easily see the code which will be executed first.

Procedure Declaration
A Sub/Function procedure is created by simply writing the code and enclosing it with the Sub/End Sub or Function/End Function statements. The syntax for the Sub/Function statements is shown next.

[STATIC] SUB ProcName [BDECL | CDECL | SDECL] 
         [ALIAS "AliasName"] [([arguments])] 
         [EXPORT | PRIVATE] [STATIC]
    .... statements
END SUB

   Sub MySub()                 # no arguments
   Sub MySub (iVar as Long)    # one passed variable
   STATIC Sub MySub()          # variable values kept between calls
   Sub MySub ALIAS "M" ()      # simple alias name reduces typing
   Sub MySub () Export         # allows external access

[CALLBACK | THREAD] FUNCTION FuncName [BDECL | CDECL | SDECL] 
         [ALIAS "AliasName"] [([arguments])] 
         [EXPORT | PRIVATE] [AS type]
    .... statements
END FUNCTION

   Function MyFunc () AS Long      # no arguments, returns Long
   Function MyFunc (r as Integer)  # single argument, default type
   Function MyFunc () Export       # allows external access

These two procedures use mostly common arguments, although some difference exist. The arguments are discussed here.

• STATIC - saves variable values between calls
• CALLBACK - defined as target for Windows messages
• THREAD - defines Function as starting point for a new thread
• BDECL/CDECL/SDECL - calling convention (BASIC/Pascal, C, STDCALL)
• ALIAS - case-sensitive alternative name for the procedure
• arguments - list of values to pass to procedure
• EXPORT/PRIVATE - defines access by external modules

Arguments
Not just one, but a list of values may be passed to procedures. Constants (numeric or string literals) may be passed, but it is more common to put variables in the argument list of a procedure so that the current value of the variables are received by the Sub/Function procedures. The list of arguments (values/variables) passed to a procedure consists of one or more arguments using the following syntax. The first two examples show the syntax for a single passed value. The third line of example code shows how three arguments would be passed, as a comma-separated list.

    Sub MySub (ByVal arg1 As Long)
    Sub MySub (ByRef arg1 As Single)

    Sub MySub (arg1 as Long, arg2 as Single, arg3 as String)

Each argument can carry two descriptors - the way in which the value is passed (ByVal or ByRef) and the data type (Long, Single, ...).

When the calling source code uses a variable as an argument, the programmer can determine if the procedure is allowed to change the value of the variable. Placing the ByVal keyword in front of an argument, prevents the procedure from changing the value of the argument.

Global Variables - No Argument Needed
While Sub/Function procedures can have variables/values passed to them, global variables are available to all Sub/Function procedures without having to include them in the argument list. Further, any change made to a global variable is permanent. The changed value will be seen by all source code anywhere in the PowerBASIC program.

It is common practice to avoid using Global variables. Using only local variables, those defined within a Sub/Function procedure, helps to prevent procedure code from having unintended impact on code elsewhere in the program.

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