Subroutines

While you can use the GOSUB command in pair with RETURN to call parts of code as subroutines, the more sophisticated way of implementing subroutines is using the SUB … END SUB block.

Subroutines are named routines that accept zero or more arguments. The simplest syntax to define a subroutine is the following:

SUB <rountine_name> ([arg1 AS <type>, arg2 AS <type>, ...])
  <statements>
END SUB

It is worth noting that the argument list is optional. If you omit the arguments, you still must add the empty parentheses after the routine name, like so:

SUB <routine_name> ()
  <statements>
END SUB

You can use the CALL keyword to call a subroutine. It behaves similarly to GOSUB with an important difference: CALL can pass arguments to the subroutine. Consider the following example:

SUB greet (name$ AS STRING * 10)
  PRINT "Hello, "; name$
END SUB

CALL greet("Emily") ' will display: Hello, Emily
CALL greet("Mark") ' will display: Hello, Mark

The CALL command will evaluate the argument list in the parentheses, pass all arguments to the subroutine and then instruct the computer to continue the program at the top of the subroutine.

The subroutine will be exited at the END SUB statement. If you want to exit a subroutine earlier, use the EXIT SUB command:

SUB test (a AS INT)
  IF a < 0 THEN PRINT "positive number please" : EXIT SUB
  PRINT SQR(a)
END SUB
CALL test(-1)

Variables defined inside a subroutine are local variables, i. e. they are only accessible within that subroutine. Global variables (the ones defined outside subroutines) are visible from within all subroutines.

globalvar = 1
SUB test ()
  PRINT globalvar : REM this is okay as globalvar is visible form here
  localvar = 5
END SUB
CALL test()
PRINT localvar : REM ERROR: localvar is not defined in the global scope

A local variable may have the same name as a global variable. In such cases the local variable will be used inside the subroutine. This is know as a “shadow variable.” Consider the following example:

a = 42
SUB test ()
  a = 5
  PRINT a
END SUB
CALL test() : REM will output 5
PRINT a : REM will output 42

It is important to understand how arguments may be passed to a subroutine. XC=BASIC offers two methods:

• Dynamic arguments: the arguments are created dynamically in memory. Before the subroutine is called, a new area in memory - a stack frame - is allocated, and this area holds the passed arguments. The advantage of dynamic memory allocation is that it allows recursive subroutine calls, i. e. the subroutine can call itself without harming its data. However, there is a penalty: dynamic arguments operate much slower than static arguments.
• Static arguments: the arguments are stored in a pre-allocated memory area. When the subroutine is called, the arguments are simply copied to this area. This is much faster than dynamic frame allocation but it doesn't support recursion.

The default method of passing arguments is dynamic. If you'd like to pass arguments statically, append the STATIC keyword to the subroutine definition:

SUB <subroutine_name> (arg AS <type>) STATIC

You can mix static and dynamic behaviour using the STATIC keyword instead of DIM to mark local variables static when a subroutine is otherwise dynamic.

SUB test (arg AS INT)
  DIM a AS INT : REM a is dynamic
  STATIC b AS INT : REM b is static
END SUB

If a subroutine is defined as STATIC, all its local variables will be static, regardless of whether you use the DIM or STATIC keyword to define them:

SUB test (arg AS INT) STATIC
  DIM a AS INT : REM a is static
  STATIC b AS INT : REM b is also static
END SUB

Subroutine overloading, commonly known as method overloading in object-oriented programming languages, refers to the ability to create multiple subroutines with the same name but different parameters. This feature allows a programmer to define different ways to call a subroutine based on the types and number of arguments passed.

Overloaded subroutines have the same name but differ in the type, number, or both type and number of parameters.

The appropriate subroutine to call is determined at compile-time based on the arguments provided in the call.

Consider the following example:

SUB PrintMessage(msg AS STRING * 16)
    PRINT msg
END SUB

SUB PrintMessage(msg AS STRING * 16, num AS INT) OVERLOAD
    PRINT msg; " "; num
END SUB

CALL PrintMessage("Hello, XC=BASIC!")
CALL PrintMessage("The number is", 42)

A subroutine can not be called before it was defined. This often makes it hard to organize your code in a clean and readable way. You may want to put subroutines at the end of your code and that's a perfectly valid requirement.

This is where forward declaration comes in handy. Forward declaration means that you declare a subroutine's all important properties (or the header of the subroutine) beforehand, and leave the actual code implementation for later. Consider the following example:

REM -- the top of the program
DECLARE SUB somesub (arg AS FLOAT) STATIC
REM -- the subroutine will be implemented later but it is already callable
CALL somesub(3.1415)
REM -- the bottom of the program
SUB somesub (arg AS FLOAT) STATIC
  PRINT "two times the argument is: "; arg * 2.0
END SUB

Subroutines, as well as variables, may be defined with different visibility levels. XC=BASIC offers two options:

• Global visibility: the subroutine is callable from within the entire code module it was defined (but not outside the code module).
• Shared visibility: the subroutine is callable from within all code modules.

To define a subroutine as shared, append the SHARED keyword to its definition:

SUB <subroutine_name> (arg AS <type>) SHARED

END SUB

This will ensure the subroutine is callable from within other code modules. Read more about Code Modules here.