Q(uick)BASIC Statement: SUB

Quick View

SUB...END SUB

A procedure statement that marks the beginning and end of a subprogram

Worth knowing

Useful and cross-version information about the programming environments of QBasic and QuickBasic.

Syntax
  • SUB name[(parameterlist)] [STATIC] [statementblock] END SUB
Description/Parameter(s)
name The name of the SUB procedure, up to 40 characters long, with no data type suffix.
parameterlist One or more variables that specify parameters to be passed to the SUB procedure when it is called:
variable[( )] [AS type] [, variable[( )] [AS type]]…
variableA Basic variable name.
typeThe data type of the variable (INTEGER, LONG, SINGLE, DOUBLE, STRING, or a user-defined data type).
STATIC Specifies that the values of the SUB procedure's local variables are saved between function calls.
When you call the SUB procedure, you can specify that an argument's value will not be changed by the procedure by enclosing the argument in parentheses.
Example

The program REMLINE.BAS illustrates calling SUB procedures. To view or run this program, load REMLINE.BAS using the Open command from the File menu.

See also:

Syntax
  • SUB globalname[parameterlist][STATIC] [statements] [EXIT SUB] [statements] END SUB
Description/Parameter(s)
Argument Description
globalname A variable name up to 40 characters long. This name cannot appear in any other FUNCTION or SUB statement in the same program or the user library.
parameterlist Contains the names of simple variables and arrays passed to the subprogram when the SUB is invoked. Each name is separated from the preceding name by a comma. Note that these variables and arrays are passed by reference, so any change to an argument's value in the subprogram also changes its value in the calling program. See below for a complete description of the syntax.

A SUB parameterlist has the following syntax:

  • variable[()] [AS type][, variable[( )] [AS type]]…
  • A variable is a BASIC variable name. Previous versions of BASIC required the number of dimensions in parentheses after an array name. In QuickBASIC, the number of dimensions is not required.
  • The argument type is the type of the variable. The type argument can be INTEGER, LONG, SINGLE, DOUBLE, STRING or a user-defined type. You may not use a fixed-length string, or an array of fixed-length strings, as a parameter. However, you may use a simple fixed-length string as an argument in a CALL statement-QuickBASIC converts a simple fixed-length string argument to a variable-length string argument before passing the string to a SUB.

A subprogram is a separate procedure, like a FUNCTION. However, unlike a FUNCTION, a SUB cannot be used in an expression.

SUB and END SUB mark the beginning and end of a subprogram. You may also use the optional EXIT SUB statement to exit a subprogram.

Subprograms are called by a CALL statement or by using the subprogram name followed by the argument list. See the entry for the CALL statement.

The STATIC attribute indicates that all variables local to the SUB are STATIC - their values are saved between calls. Using the STATIC keyword slightly increases execution speed. STATIC is not usually used with recursive subprograms.

Any subprogram variables or arrays are considered local to that sub- program, unless they are explicitly declared as shared variables in a SHARED statement.

You cannot define SUB procedures, DEF FN functions, or FUNCTION procedures inside a SUB procedure.

Note: You cannot use GOSUB, GOTO, or RETURN to enter or exit a subprogram.
Example

SUB_EX.BAS is a program file in the subdirectory ADVR_EX that illustrates the SUB...END SUB statement. To look at the program in the View window and, optionally, to run it, load the program using the File menu's Open Program command.
The main program calls a subprogram which searches for a given string in each line of input from a file. When the subprogram finds the string in a line, it prints the line, along with the number of the line. Notice that the value of a line number counter is saved between calls because the STATIC keyword is used on the SUB statement.
Below is sample output from the program:

Sample Output:

Pattern to search for? SUB Line # 9 : SUB Linesearch(Test$,P$) STATIC Line # 13 : END SUB

See also:

Syntax
  • SUB globalname[(parameterlist)] [STATIC] [statementblock] [EXIT SUB] [statementblock] END SUB
Description/Parameter(s)
globalname A variable name up to 40 characters long. This name cannot appear in any other SUB or FUNCTION statement in the same program or the user library. The name cannot include a type-declaration character.
parameterlist The list of variables, representing parameters, that will be passed to the SUB when it is called. called. See details below for the syntax of parameterlist.
STATIC Indicates the function's local variables are to be saved between calls.
EXIT SUB Causes an immediate exit of a SUB procedure. Program execution continues with the statement after the CALL statement.
  • Names in the parameterlist are separated by commas. The syntax of parameterlist is:
    [BYVAL] variable[( )] [AS type] [, [BYVAL] variable[( )] [AS type]]…
    BYVALDefines the variable as being passed by value rather than by reference (the default). BYVAL can be used only with simple numeric types (INTEGER, LONG, SINGLE, DOUBLE, or CURRENCY).
    variableA BASIC variable name. Previous versions of BASIC required the number of dimensions in parentheses after an array name. In the current version of BASIC, only empty parentheses are required.
    AS typeThe type of the variable: INTEGER, LONG, SINGLE, DOUBLE, STRING, CURRENCY, or a user-defined type. You cannot use a fixed-length string as a parameter unless it is contained in an array. You can use a simple fixed-length string as an argument in a CALL statement; BASIC converts a simple fixed-length string argument to a variable-length string argument before passing the string to a SUB procedure.
  • STATIC indicates that the SUB's local variables are to be saved between calls. Without STATIC, the local variables are allocated each time the SUB is invoked, and the variables' values are lost when the SUB returns to the calling program. The STATIC attribute does not affect variables that are used in a SUB but declared outside the SUB in DIM or COMMON statements using the SHARED statement.
  • EXIT SUB immediately exits a SUB procedure. Program execution continues with the statement after the CALL statement. EXIT SUB can be used only in a SUB procedure.

Usage Notes

  • A SUB procedure is a separate procedure, like a FUNCTION procedure. However, unlike a FUNCTION procedure, a SUB procedure cannot be used in an expression.
  • SUB and END SUB mark the beginning and end of a SUB procedure. You also can use the optional EXIT SUB statement to exit a SUB procedure.
  • SUB procedures are called by a CALL statement or by using the SUB procedure name followed by the argument list. See the ⮜ CALL Statement (BASIC Procedures) ⮞.
  • BASIC SUB procedures can be recursive--they can call themselves to perform a given task.
  • The STATIC attribute indicates that all variables local to the procedure are static--their values are saved between calls. STATIC is not usually used with recursive SUB procedures.
  • Any SUB procedure variables or arrays are considered local to that SUB procedure, unless they are explicitly declared as shared variables in a SHARED statement.
  • You cannot define SUB procedures, DEF FNfunctions, or FUNCTION procedures inside a SUB procedure.
  • Earlier versions of BASIC did not allow you to pass arrays containing fixed-length strings as parameters. BASIC now supports this.
  • If a parameter is passed by reference, any change to the parameter's value inside the procedure changes its value in the calling program.
  • If a parameter is passed by value, any changes to the parameter's value inside the procedure is local to that procedure and does not affect its value in the calling program.

Important

  • You cannot use GOSUB, GOTO, or RETURN to enter or exit a SUB procedure.
Example

This example uses the CALL statement to call a SUB procedure that prints a message on the 25th line of the display.

CLS message$ = "The quick brown fox jumped over the lazy yellow dog." CALL PrintMessage(message$) END SUB PrintMessage (message$) LOCATE 24, 1 PRINT message$; END SUB

See also: