Subroutines and External Functions

The purpose of DataBasic subroutines and external functions is to specify sets of instructions that are required in more than one place in a program, or in more than one program. Instead of duplicating the instructions, you can create a subroutine or external function and call it from within the program as needed.

Subroutines are of two types: Internal and External. External functions are similar to external subroutines, but return a value in a similar way to the intrinsic functions that form part of DataBasic.

Using subroutines and external functions improves program source code by allowing you to reuse common code, thus enhancing readability, maintainability and testability. In addition, using external subroutines and functions avoids duplication of effort by enabling a number of programs to share the same source code. Refer to the topic Efficient Use of Subroutines for guidelines on the use of subroutines to make a program more efficient.

Internal Subroutine

An internal subroutine is a sequence of statements within a DataBasic program which starts with a statement label and ends with a RETURN statement. Internal subroutines are called, from within the same program only, using the GOSUB or ON GOSUB statements.

Example of Internal Subroutine

GOSUB VERIFYINPUT
CRT NUMBER
STOP
*************************************
* Subroutine VERIFYINPUT
*
* Inputs a number from 1 to 1000.
*
VERIFYINPUT:
   LOOP
      PRINT "Input Number from 1 to 1000":
      INPUT NUMBER
   UNTIL NUMBER >= 1 AND NUMBER <= 1000 DO
      PRINT "Invalid data"
   REPEAT
*
RETURN
**************************************

The GOSUB statement calls the subroutine VERIFYINPUT from within the same program. The statements in the subroutine are then processed until the RETURN statement is reached. Control is then passed back to the program statement following the most recently executed GOSUB statement, in this example, CRT NUMBER.

The VERIFYINPUT subroutine requests a numeric input and checks that it is in the range 1 to 1000. If it is, it returns control to the calling program which outputs the number to the screen. If it is not, it displays the message 'Invalid data' and requests another number.

External Subroutine

An external subroutine is a separate DataBasic program which can be called in various ways:

• By other programs via the CALL statement.

• Automatically by Reality (see Embedded Basic Subroutines).

• From a web browser using RealWeb.

• From an application running on a client host, by using JReal, the Remote Basic ActiveX Control or a Web Service.

The subroutine returns to the calling program when a RETURN statement is encountered; if no RETURN statement is encountered, the subroutine does not return.

An external subroutine must be in a separate program module, starting with a SUBROUTINE statement (only comments can precede the SUBROUTINE statement). The name of the subroutine (declared in the SUBROUTINE statement) must match the module's item-id and obey the rules for identifiers.

External subroutines must be cataloged (see the CATALOG command for details). It is recommended that you also catalog the calling program, because this will make your program more efficient.

There are two methods you can use to pass data between the calling program and the subroutine:

• As arguments to the subroutine call. In this case, the subroutine declaration must include any required parameters. For example:

  SUBROUTINE DISTANCE(X1, Y1, X2, Y2, D)

  This declares parameters called X1, Y1, X2, Y2 and D which must be used to pass data to the DISTANCE subroutine. The subroutine would be called as follows:

  CALL DISTANCE(SX, SY, EX, EY, DIST)

  where SX, SY, EX and EY contain the data to be passed to the subroutine, and DIST is a variable to which the result will be returned.

  An argument passed to a subroutine can be any valid DataBasic expression that returns a value of the required type. Variables used as arguments to an external subroutine are passed by reference; if the subroutine changes the values of these parameters, the changes will be visible to the calling program (in the above example, the D parameter is used to return the result of the subroutine). The results of all other expressions are passed by value.

• Using one or more COMMON variables, accessible to both the calling program and the subroutine. In this case, both the calling program and the subroutine must declare the necessary COMMON variables. For example, in the subroutine:

  SUBROUTINE DISTANCE
     COMMON X1, Y1, X2, Y2, D

  and in the calling program:

  COMMON SX, SY, EX, EY, DIST
  CALL DISTANCE

  Note

  Using COMMON variables is more efficient than passing data as arguments in the subroutine call.

Identifiers used within an external subroutine are local in scope and can be the same as identifiers used in the calling program.

Example of External Subroutine

**************************************
* Subroutine DISTANCE
*
* Computes the distance between two points.
*
SUBROUTINE DISTANCE(X1, Y1, X2, Y2, D)
   DX = X2 - X1
   DY = Y2 - Y1
   D = SQRT(DX * DX + DY * DY)
   RETURN
END
**************************************

This example defines an external subroutine called DISTANCE that accepts five arguments. It computes the distance between two points (defined by the X1/Y1 and X2/Y2 parameters) and returns the result in the D parameter.

External Function

An external function is similar to an external subroutine, but is called in the same way as an intrinsic function and returns a value to the calling program. It must be:

• Defined in a separately compiled and cataloged program module that starts with a FUNCTION statement.

• Return its result by means of the RETURN statement.

• Declared before use with the DEFFUN statement.

As with external subroutines, you can pass data between the calling program and the function by means of arguments to the subroutine call or by using COMMON variable. Variables used as arguments to an external function are normally passed by reference; any changes to the values of these variables are returned to the calling program.

Examples of External Functions

DISTANCE Function

**************************************
* Function DISTANCE
*
* Computes the distance between two points.
*
FUNCTION DISTANCE(X1, Y1, X2, Y2)
   DX = X2 - X1
   DY = Y2 - Y1
   D = SQRT(DX * DX + DY * DY)
   RETURN(D)
END
**************************************

This example shows an alternative way of writing the DISTANCE subroutine above. It defines an external function called DISTANCE that accepts four arguments. It computes the distance between two points (X1, Y1 and X2, Y2) and returns the result.

SQUARE Function

In the item SQ:

**************************************
* Function SQ
*
* Returns the result of squaring a number.
*
**************************************
FUNCTION SQ(V)
   RETURN(V * V)
END

In the item SQPROG:

* Declare the SQ function.
DEFFUN SQ(VAL)
.
.
.
* Call the SQ function.
SQVAR = SQ(4)

The latter program fragment sets the variable SQVAR to the square of 4; that is, 16.