QMCallx

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

Format

C	int QMCallx(char * SubrName, short int ArgCount, ArgList...)

where

SubrName

is the name of the subroutine to be called.

ArgCount

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

ArgList

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

The QMCallx function, available only in the C API, 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. The return value from QMCallx is zero if successful or non-zero in the case of an error. The actual return value is one of the SV_xxx codes as defined in the qmclilib.h include record.

Unlike QMCall, the updated values of any arguments modified by the subroutine do not overwrite the original argument variables. Instead, they can be retrieved using the QMGetArg() function, removing the need to know the size of the returned data prior to the call. The memory allocated by this function must subsequently be released using QMFree().

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.

Example

C	char * ErrMsg QMCallx("SET.CREDIT.LIMIT", 3, Client, NewLimit, ""); ErrMsg = QMGetArg(3); If (ErrMsg != NULL) printf("Failed - %s\n", 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 third argument is passed into QMCallx() as a null string 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.