SUB

See also: Functions and Subroutines, BYREF

  sub subName zero or more comma separated parameter variable names
   
'code for the sub goes in here
  end sub

Description:

This statement defines a subroutine. Zero or more parameters may be passed into the subroutine. A subroutine cannot contain another subroutine definition, nor a function definition.

The CALL statement is used to access the SUBROUTINE and to pass values into it. The values must be the same type as the SUB statement defines them to be. So the following example:

  sub mySubName string$, number, string2$

is called like this:

  call mySubName "string value", 123, str$("321")

Local Variables

The variable names inside a subroutine are scoped locally, meaning that the value of any variable inside a subroutine is different from the value of a variable of the same name outside the subroutine.

Passing by Reference

Variables passed as arguments into subroutines are passed "by value" which means that a copy of the variable is passed into the subroutine. The value of the variable is not changed in the main program if it is changed in the subroutine. A variable may instead be passed "byref" which means that a reference to the actual variable is passed and a change in the value of this variable in the subroutine affects the value of the variable in the main program.

Global Variables and Devices

Variables declared with the GLOBAL statement are available in the main program and in subroutines and functions.

Arrays, structs and handles of files, DLLs and windows are global to a Liberty BASIC program, and visible inside a subroutine without needing to be passed in.

Special global status is given to certain default variables used for sizing, positioning, and coloring windows and controls. These include variables WindowWidth, WindowHeight, UpperLeftX, UpperLeftY, ForegroundColor$, BackgroundColor$, ListboxColor$, TextboxColor$, ComboboxColor$, TexteditorColor$. The value of these variables, as well as DefaultDir$ and com can be seen and modified in any subroutine/function.

Branch Labels

Branch labels are locally scoped. Code inside a subroutine cannot see branch labels outside the subroutine, and code outside a subroutine cannot see branch labels inside any subroutine.

Ending a Subroutine:

The sub definition must end with the expression: end sub

Exit a Subroutine:

The sub can be exited before the end with an "exit sub" statement.

Executing Subroutines

Be sure that a program doesn't accidentally flow into a subroutine. A subroutine should only execute when it is called by command in the program.

wrong:

  for i = 1 to 10
    'do some stuff
  next i

sub MySub param1, param2
  'do some stuff
end sub

correct:

  for i = 1 to 10
    'do some stuff
  next i
  wait

sub MySub param1, param2
  'do some stuff
end sub

Example:

Usage:

  'copy two files into one
  fileOne$ = "first.txt"
  fileTwo$ = "second.txt"
  combined$ = "together.txt"
  call mergeFiles fileOne$, fileTwo$, combined$
  end

sub mergeFiles firstFile$, secondFile$, merged$
  open merged$ for output as #merged
  open firstFile$ for input as #first
  print #merged, input$(#first, lof(#first));
  close #first
  open secondFile$ for input as #second
  print #merged, input$(#second, lof(#second));
  close #second
  close #merged
end sub

See also: FUNCTION, Recursion, Functions and Subroutines