NAME

call - call a subprogram

SYNOPSIS

call Name[(Arg[, Arg]. . .)]

DESCRIPTION

Call is used to call a subprogram (see sub).  The subprogram need not lie in the same module as the call.  In fact, the subprogram need not be coded in BASIC. 

Name is the name that identifies the subprogram.  Arg is an argument to the subprogram.  An argument may be any expression and can be read by the subprogram.  Passing an argument to the subprogram is performed by reference, i.e., by an address where the actual value is stored.  If the argument is a simple or array element variable, the address of the variable is passed.  This allows the subprogram to modify the variable.  If the argument is a variable enclosed in parentheses, however, the variable’s value is copied to another address which is passed thus preventing the subprogram from modifying the variable.  An argument may also be an entire array signified by the array name followed by an empty pair of parentheses.  An array passed to a subprogram may be modified by the subprogram. 

The names and number of arguments in a call statement need not match those defined in the subprogram.  It is the position and type that is important.  Especially important is the type of a constant argument since it is easy to overlook.  For example, "-1" is an integer but "-1.0" is a single-precision value. 

A subprogram may also return a value; see usr for details. 

EXAMPLE

Suppose we have a BASIC source file "call.b" that changes an employee’s name:
	for i = 1 to 3
		read name$(i)
	next i
	data "Larry Leinweber", "Roger Bielefeld", "Gary Goins"
	input "Old name"; old$
	call find(name$(), 3, (old$), n)
	if n < 0 then stop
	input "New name"; new$
	name$(n) = new$
	print old$ " changed to " new$
And another BASIC source file "find.b" that contains the search routine:
	defint a-z
	sub find(n$(1), n%, x$, i)
		for i = 1 to n%
			if n$(i) = x$ then exit sub
		next i
		i = -1
	end sub
Of course, the code from both these files may have been coded in a single file, but in this case the two files may be compiled together with the command:
	$ basic call.b find.b
Notice the arguments passed to "find": name$ denotes an entire array because the identifier is followed by an empty pair of parentheses.  Old$ is enclosed in parentheses to guarantee that it is not modified by the subprogram.  On the other hand, n is not enclosed; this permits the subprogram to set its value.  Also note that the names of the arguments do not match those defined in the subprogram but the positions and types are matched. 

The search routine could have as easily been coded in a C source file "find.c":

	#include <basic/string.h>
	#include <basic/array.h>

	find(nstr, n, xstr, i)
	struct array *nstr;
	struct string *xstr;
	short *n; float *i;
	{
		for (*i = 0.0; *i <= (float) *n; *i += 1.0)
			if (!cmpstr(nstr->arr_ptr.arr_str + (int) *i, xstr))
				return;
		*i = -1.0;
	}
The cmpstr function is described in the Run-Time Support Library section of this manual.  This C routine and the BASIC source file "call.b" may be compiled together with the commands:
	$ cc -c find.c
	$ basic call.b find.o
Notice that the arguments to the C function are pointers.  Also note that each BASIC data type maps into a different C data type— some of which are complex structures.  The correspondence between BASIC and C data types is defined below. 

In principle, the search routine could be defined in most any language but it is difficult to give examples.  Under UNIX, it is customary to describe language interfaces in terms of C although these interfaces sometimes vary from machine to machine.  It is always possible to interface Basmark QuickBASIC and C without any portability problems.  To interface BASIC with another language, it is suggested that you obtain a description of the interface between that language and C.  Armed with that information you might be able to interface the other language with BASIC directly.  If not, you can always interface the two by means of a "glue" routine written in C that handles the incompatibilities. 

SEE ALSO

sub, usr

USAGE NOTES

In Basmark QuickBASIC, absolute addresses are avoided in favor of symbolic names; thus, call absolute is not implemented.  Call and usr are implemented in Basmark QuickBASIC in a form similar to Microsoft BASIC but are intended for use with high-level language subroutines which are referenced symbolically and linked to the main program by the native link editor.  Assembly language routines may be interfaced similarly.  The possibility of conflict between the names of user-defined subroutines and run-time library routines exists. 

Variable types between Basmark QuickBASIC and C language functions correspond as follows:

Basmark QuickBASIC	C

integer			short
single precision	float
double precision	double
string			struct string {
				short str_len, str_flag;
				char *str_text;
			}

array			struct array {
				union {
					short		*arr_int;
					float		*arr_flt;
					double		*arr_dbl;
					struct string	*arr_str;
					char		*arr_chr;
				} arr_ptr;
				short arr_dim;
			}
For further information on interfacing with C, consult the Run-Time Support Library section of this manual. 

from The Basmark QuickBASIC Programmer’s Manual by Lawrence Leinweber