Caché MultiValue Basic Reference
[Back] [Next]
Go to:

Defines an external subroutine.
SUBROUTINE [name][(arglist)]
name Optional — Any valid name to assign to the subroutine.
arglist Optional — List of variables specifying arguments that are passed to the SUBROUTINE when it is called. Multiple arguments are separated by commas. The arglist is enclosed with parentheses.
statements A group of statements to be executed within the body of the SUBROUTINE.
The SUBROUTINE statement defines an external subroutine. A SUBROUTINE is a separate procedure that can take arguments, perform a series of statements, and change the values of its arguments.
The SUBROUTINE statement is very similar to FUNCTION, except that FUNCTION always returns a value. A SUBROUTINE generally does not return a value. (You can use the SUBR function to call an external subroutine that returns a value.)
There cannot be a label on the SUBROUTINE statement line. There can only be one SUBROUTINE statement in an external subroutine (no nested subroutines). The SUBROUTINE statement must be the first line in the external subroutine, with the following exceptions: comment lines, $OPTIONS statements, $COPYRIGHT statements, and DIM statements that do not dimension a static array. For example, DIM Var() and DIM abc are permitted, but DIM Var(2) is not.
The name argument allows you to identify the external subroutine; it is not (strictly speaking) required to define or invoke an external subroutine. If name is omitted, either of the following syntactic forms are permitted: SUBROUTINE (arglist) or SUBROUTINE(arglist).
An external subroutine must be compiled and cataloged before it can be invoked. You can invoke an external subroutine with a CALL statement. The CALL statement invokes a subroutine by its name in the catalog; this is not necessarily the same as name.
When using CALL to invoke a subroutine, you can pass it arguments. The list of arguments passed by CALL must correspond in position and number to the number of arguments defined in SUBROUTINE to receive the passed values. The names of the arguments do not have to correspond.
The argument list can contain any combination of regular variables and array variables. In arglist, an array variable name must be preceded by the MAT keyword. The following is an argument list that specifies a regular variable and two array variables:
SUBROUTINE MySub(myvar,MAT myarray,MAT refarray)
By default, all arguments are passed by reference. If the subroutine changes the value of an argument passed by reference, this value is also changed in the calling program. You can specify in the CALL statement that an argument is to be passed by value. If the subroutine changes the value of an argument passed by value, the value of this argument in the calling program remains unchanged.
You can also use the COMMON statement to make specified variables available to all external subroutines.
You can terminate an external subroutine with a RETURN or with an END statement. Following a RETURN, program execution resumes with the line immediately following the invoking CALL statement.
The SUBR function is used to call an external subroutine that returns a value. The CALL statement is used to call an external subroutine that does not return a value. The GOSUB statement is used to call an internal subroutine.
See Also