Sub...End Sub statement - MapBasic - 2023

Purpose

Defines a procedure, which can then be called through the Call statement.

Syntax

Sub proc_name [ ( [ ByVal ] parameter As var_type [ , ... ] ) ] 
	 statement_list 
End Sub

proc_name is the name of the procedure.

parameter is the name of a procedure parameter.

var_type is a standard MapBasic variable type (for example, integer) or a custom variable Type.

statement_list is a list of zero or more statements comprising the body of the procedure.

Restrictions

You cannot issue a Sub...End Sub statement through the MapBasic window.

Description

The Sub...End Sub statement defines a sub procedure (often, simply called a procedure). Once a procedure is defined, other parts of the program can call the procedure through the Call statement.

Every Sub...End Sub definition must be preceded by a Declare Sub statement.

A procedure may have zero or more parameters. parameter is the name of the parameter; each of a procedure's parameters must be unique. If a sub procedure has two or more parameters, they must be separated by commas.

By default, each sub procedure parameter is defined "by reference." When a sub procedure has a by-reference parameter, the caller must specify the name of a variable as the parameter. Subsequently, if the sub procedure alters the contents of the by-reference parameter, the caller's variable will reflect the change. This allows the caller to examine the results returned by the sub procedure. Alternately, any or all sub procedure parameters may be passed "by value" if the keyword ByVal appears before the parameter name in the Sub statement. When a parameter is passed by value, the sub procedure receives a copy of the value of the caller's parameter expression; thus, the caller can pass any expression, rather than having to pass the name of a variable. A sub procedure can alter the contents of a ByVal parameter without having any impact on the status of the caller's variables.

A procedure can take an array as a parameter. To declare a procedure parameter as an array, place parentheses after the parameter name in the Sub...End Sub statement (as well as in the Declare Sub statement). The following example defines a procedure which takes an array of Integers as a parameter.

Sub ListProcessor(items() As Integer)

When a sub procedure expects an array as a parameter, the procedure's caller must specify the name of an array variable, without the parentheses.

If a sub procedure's local variable has the same name as an existing global variable, all of the sub procedure's references to that variable name will access the local variable.

A sub procedure terminates if it encounters an Exit Sub statement.

You cannot pass arrays, custom Type variables, or Alias variables as ByVal (by-value) parameters to sub procedures. However, you can pass any of those data types as by-reference parameters.

Example

In the following example, the sub procedure Cube cubes a number (raises the number to the power of three), and returns the result. The sub procedure takes two parameters; the first parameter contains the number to be cubed, and the second parameter passes the results back to the caller.

Declare Sub Main 
Declare Sub Cube(ByVal original As Float, cubed As Float)

Sub Main 
	Dim x, result As Float
	Call Cube(2, result) 
	' result now contains the value: 8 (2 x 2 x 2)
	x = 1
	Call Cube(x + 2, result) 
	' result now contains the value: 27 (3 x 3 x 3) 
End Sub 

Sub Cube (ByVal original As Float, cubed As Float) 
	' Cube the "original" parameter value, and store 
	' the result in the "cubed" parameter. 
	cubed = original ^ 3
End Sub

See Also:

Call statement, Declare Sub statement, Dim statement, Exit Sub statement, Function...End Function statement, Global statement