QMCall()

 Top  Previous  Next

 

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

 

The subroutine may take up to 20 arguments that must be passed as strings. QMClient does not provide a method to call subroutines with a greater number of arguments or those that are defined to pass a QMBasic dimensioned matrix as an argument.

 

The called subroutine may make use of any of the standard QMBasic programming statements and functions, however, it may not perform terminal input that is not handled via the data queue as there is no terminal associated with the server process. Any terminal output will be discarded unless redirected to a COMO file.

 

The QMCLIENT configuration parameter can be used to restrict QMCall() to calling only subroutines that have been compiled with the $QMCALL compiler directive. Use of this feature prevents a malicious application that uses the QMClient API calling other subroutines that might not perform adequate security validation to protect the system.

 

Handling values returned via the subroutine arguments differs depending on the variant of the QMClient API in use. Some update the argument variables directly, others require use of the QMGetArg() function. The language specific descriptions below give more details.

 

The example program fragments below call 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.

 

 

hmtoggle_plus1C

void QMCall(char * SubrName, short int ArgCount, ArgList...)

ErrMsg[0] = '\0';

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

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

 

Use of this function in the C API is not recommended as 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.

 

hmtoggle_plus1VB.Net

QMCall(ByVal SubrName as String, ByVal ArgCount as Short, Optional ByRef Arg1 as String, ...)

 

ErrMsg = ""

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

If ErrMsg <> "" Then MsgBox(ErrMsg, MsgBoxStyle.Exclamation, "Failed")

 

If the subroutine modifies the values of any of its arguments, this will be reflected in the variables specified in ArgList on return from the call.

 

 

hmtoggle_plus1QMBasic Class Module

Call(SubrName, ArgList...)

 

ErrMsg = ""

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

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

 

If the subroutine modifies the values of any of its arguments, this will be reflected in the variables specified in ArgList on return from the call.

 

hmtoggle_plus1Java

Call(String SubrName,  String Arg1,  String Arg2...)

ErrMsg = "";

qm.Call("SET.CREDIT.LIMIT", Client, NewLimit, ErrMsg);

ErrMsg = qm.GetArg(3);

if (ErrMsg != "") System.out.printf("Failed - %s%n", ErrMsg);

 

Note use of the GetArg() method to retrieve the value of the modified ErrMsg argument. The ErrMsg variable in the call could have been replaced with a literal null string as it is an output only argument.

 

hmtoggle_plus1Python

Call(SubrName, ArgCt, Arg1, Arg2...)

ErrMsg = ""

qm.Call("SET.CREDIT.LIMIT", 3, Client, NewLimit, ErrMsg)

ErrMsg = qm.GetArg(3);

if ErrMsg == "": print("Failed", ErrMsg)

 

Note use of QMGetArg() to retrieve the value of the modified ErrMsg argument. The ErrMsg variable in the call could have been replaced with a literal null string as it is an output only argument.

 

 

See also:

QMCallx, QMTrapCallAbort