QMCall

 Top  Previous  Next

 

The QMCall function calls a catalogued subroutine on the server. It is analogous to the QMBasic CALL statement.

 

 

Format

 

VBQMCall ByVal SubrName as String, ByVal ArgCount as Integer, Optional ByRef Arg1 as String, ...

 

CQMCall(char * SubrName, short int ArgCount, ArgList...)

 

ObjSession->Call(SubrName, ArgList...)

 

where

 

SubrNameis the name of the subroutine to be called.

 

ArgCountis the number of arguments following (not present in the QMBasic class module API).

 

ArgListis a list of arguments to be passed to the subroutine. In the C API, these arguments are char *.

 

 

The QMCall function calls the named catalogued subroutine on the server system. This subroutine may take up to 20 arguments. QMClient does not provide a method to call subroutines with a greater number of arguments or that are defined to pass a QMBasic dimensioned matrix as an argument.

 

In the Visual Basic and C APIs, there may be at most 20 variables named as arguments and these must be declared as strings.

 

In the C API, the size of any argument variable that may be overwritten by the subroutine must be large enough to receive the updated value. Failure to observe this rule will result in memory corruption. See the QMCallx function for an alternative way to handle returned argument values.

 

If the subroutine modifies the values of any of its arguments, this will be reflected in the variables specified in ArgList. It is a good idea to ensure that arguments that are only used for values returned from the subroutine are set to empty strings before the call to minimise data unnecessarily sent across the network.

 

The called subroutine may make use of any of the standard QMBasic programming statements and functions, however, it may not perform terminal input or output as there is no terminal associated with a server process.

 

 

Examples

 

VB

ErrMsg = ""

QMCall "SET.CREDIT.LIMIT", 3, Client, NewLimit, ErrMsg

If ErrMsg <> "" Then MsgBox ErrMsg, VBExclamation, "Failed"

C

ErrMsg[0] = '\0';

QMCall("SET.CREDIT.LIMIT", 3, Client, NewLimit, ErrMsg);

If (ErrMsg[0] != '\0') printf("Failed - %s\n", ErrMsg);

QMBasic

ErrMsg = ""

session->Call("SET.CREDIT.LIMIT", Client, NewLimit, ErrMsg)

if ErrMsg # "" then display "Failed - " : ErrMsg

 

The above example calls a subroutine on the server that sets the credit limit for a specific client. The subroutine takes three arguments, the third of which is used to return an error message if the action fails. Note how the ErrMsg variable is set to a null string before calling the subroutine so that any old content of this variable is not unnecessarily sent across the network to the server. To optimise network traffic, the server only returns arguments values if they have been modified by the called subroutine.

 

 

See also:

QMCallx, QMTrapCallAbort