A remote procedure call, or RPC, is a mechanism by which a client application communicates with an Open Server application. Typically, the client issues the RPC to obtain information from the Open Server application. An RPC consists of a name and often, but not always, parameters. For example, a department store application could return a customer’s name and address in response to an RPC called get_cust. This RPC could take one parameter, a customer ID number.
When a client sends an RPC, Open Server checks to see whether the RPC is registered. A registered procedure is a special kind of RPC that Open Server recognizes and executes directly without calling an application’s SRV_RPC event handler. For more information on registered procedures, see “Registered procedures”.
If the RPC is not registered, Open Server triggers a SRV_RPC event. From within the SRV_RPC event handler, the application can retrieve the RPC’s name, and parameters if any, and respond appropriately. The event handler is coded to verify the names of all possible RPCs the client could send and the number of parameters each uses. The handler includes code for responding to each RPC and returns the error information to the client if it does not recognize the RPC.
From within its SRV_RPC event handler, the application should perform the following steps:
Call srv_rpcname to retrieve the RPC name. (An application can also choose to retrieve the RPC number, owner, and associated database, using srv_rpcnumber, srv_rpcowner, and srv_rpcdb, respectively.) If no RPC by that name exists, or the number, owner, or database information are invalid, the application returns error information through srv_sendinfo.
Verify that the appropriate number of parameters were sent by calling srv_numparams. If any of the parameter information is invalid, return error information through srv_sendinfo.
Process the parameters by calling srv_descfmt, srv_bind, and srv_xferdata. For details, see “Processing parameter and row data”.
Return any data the client expects by calling srv_descfmt, srv_bind, and srv_xferdata. For details, see “Processing parameter and row data”.
RPC parameters are passed either by name or by position. If the RPC is invoked with some parameters passed by name and some parameters passed positionally, an error will result.
An application could register all its procedures and use the SRV_RPC event handler to trap errors. Open Server would only call the SRV_RPC event handler if the client sent an unregistered and therefore invalid RPC. The SRV_RPC event handler, then, would use srv_sendinfo to inform the client that it had issued an invalid RPC.
