SUBROUTINE

Top  Previous  Next

 

The SUBROUTINE statement introduces a subroutine. The abbreviation SUB may be used.

 

 

Format

 

SUBROUTINE name{(arg1 {, arg2...}) {VAR.ARGS}}

 

where

 

nameis the name of the subroutine.

 

arg1, etcare the names of the arguments to the subroutine.

 

 

QMBasic programs should commence with a PROGRAM, SUBROUTINE, FUNCTION or CLASS statement. If none of these is present, the compiler behaves as though a PROGRAM statement had been used with name as the name of the source record.

 

The SUBROUTINE statement must appear before any executable statements. A SUBROUTINE with no arguments is equivalent to a PROGRAM. The brackets are optional if there are no arguments. The SUBROUTINE statement may be split over multiple lines by breaking after a comma.

 

The name used in a SUBROUTINE statement need not be related to the name of the source record though this eases program maintenance. The name must comply with the QMBasic name format rules

 

A subroutine module is entered by referencing it a CALL statement. A subroutine that has no arguments can also be entered by use of the RUN command or by executing a command name that corresponds to the name of the program in the system catalogue.

 

The number of arguments in calls to the subroutine must be the same as in the SUBROUTINE statement unless the subroutine is declared with the VAR.ARGS option. When VAR.ARGS is used, any arguments not passed by the caller will be unassigned. The ARG.COUNT() function can be used to determine the actual number of arguments passed. If the values of argument variables are changed by the subroutine, these changes are reflected in the variables used in the CALL statement that entered the subroutine.

 

Subroutine arguments are normally passed by reference such that changes made to the argument variable inside a subroutine will be visible in the caller's variable referenced by that argument. The CALL statement allows arguments to be passed by value by enclosing them in brackets. The SUBROUTINE statement also supports this dereferencing syntax. For example

 

SUBROUTINE INVOICE(P, (Q))

 

 

An argument may refer to a whole matrix. In this case the argument variable name must be preceded by the keyword MAT and there must be a DIM statement following the subroutine declaration to indicate whether this is a one or two dimensional matrix. Alternatively, the dimensions may be given after the variable name in the SUBROUTINE statement. In either case, the actual dimension values are counted by the compiler but otherwise ignored. Use of a dimension value of one emphasises to readers of the program that the value is meaningless. A matrix passed as an argument cannot be redimensioned in the subroutine.

 

For example

 

SUBROUTINE MATMAX(MAX, MAT A)

  DIM A(1)

  MAX = A(1)

  N = INMAT(A)

  FOR I = 2 TO N

     IF A(I) > MAX THEN MAX = A(I)

  NEXT I

END

 

 

This subroutine scans a one dimensional matrix and passes back the value of the largest element via the MAX argument. The first two lines could alternatively be written as

 

SUBROUTINE MATMAX(MAX, A(1))