DEFFUN

DEFFUN

Top  Previous  Next

 

The DEFFUN statement defines a function.

 

 

Format

 

DEFFUN name {(arg1 {, arg2 ...})} {CALLING "subr"} {VAR.ARGS} {KEY key}

DEFFUN name {(arg1 {, arg2 ...})} LOCAL

DEFFUN name {(arg1 {, arg2 ...})} EXTERNAL {CALLING "libname"}

DEFFUN name {(arg1 {, arg2 ...})} EXTERNAL {CALLING "libname:funcname"}

 

where

 

nameis the name of the function.

 

arg1, arg2...are the function arguments. Up to 254 arguments can be supplied except for external functions where this limit is 31.

 

subris the catalogue name of the subroutine if different from name.

 

keyis a key value to be passed into the subroutine as described below.

 

libnameis the name of the program providing the function. This is case sensitive on Linux systems. The .exe suffix is provided automatically on Windows. If no CALLING clause is present, the default name "qmextcall" is used.

 

funcnameis the case sensitive name of the function to be called from libname.  name of the program providing the function.

 

 

The DEFFUN statement defines a function that may be called from within the program. The DEFFUN statement must appear before the first reference to the function. If the function name matches the name of a built in function, any references to name before the DEFFUN will call the intrinsic function and references after the DEFFUN will call the declared function.

 

If the LOCAL and EXTERNAL keywords are not present, the function must correspond to a catalogued item. A call to this function call is effectively translated to a call to a subroutine with an additional hidden first argument through which the result is returned. The optional CALLING component of the DEFFUN statement allows the catalogue name of the function to be different from the name of the function itself.

 

Use of the LOCAL keyword indicates that this function is internal to the program module and will be defined later in the source by use of the LOCAL FUNCTION statement.

 

Use of the EXTERNAL keyword defines reference to a subroutine that is written in some other language such as C and is accessed via the External Call Interface. See External Functions for more details. When used without the CALLING clause, use of the QMBasic function will be passed to the qmextcall handler with the uppercase form of name used as the function to be called. If the CALLING clause is present, the qualifying information may be either just an alternative handler name or it may be a handler name and case sensitive function name separated by a colon. In all cases, the name used within the QMBasic program is case insensitive unless QMBasic case sensitivity has been enabled (see the CASE.SENSITIVE setting of the $MODE compiler directive).

 

The argument names used in the DEFFUN statement are for documentation purposes only and have no significance within the program except that the compiler counts them to verify correct use of the function. The variables used in the actual call to the function are determined by the use of the function. Except when defining an external function, an argument may be defined to be a whole matrix in which case it should be prefixed by the keyword MAT in the DEFFUN argument list.

 

The function is used in the same way as the intrinsic functions described in this manual. Although it is not recommended, a function can update its argument variables.

 

The VAR.ARGS option indicates that compiler should not check the number of arguments in calls to the function. It is of use with functions that take variable length argument lists. This option cannot be used with a local or external function.

 

The KEY option passes the key value as an additional argument before the first one named in calls to the function. This enables construction of multiple functions that call a single catalogued item with a mode key as the first argument. The !PCL() function provided in the BP file of the QMSYS account uses this feature to implement the various PCL functions defined in the SYSCOM PCL.H include record.

 

 

Example

 

DEFFUN MATMAX(MAT A)

DIM VALUES(100)

...

MAX = MATMAX(MAT VALUES)

 

The program fragment above uses a user supplied MATMAX() function to find the maximum value of all the elements of matrix VALUES.

 

 
See also:

FUNCTION, LOCAL