betty.rpc.client

Syntax	betty.rpc.client (rpcServer, rpcPort, procedureName, adrParamList, flDebug, ticksToTimeOut, flShowMessages, rpcPath, flAsynch, adrCallback, extraInfo, adrErrorCallback)
Params	rpcServer is a string, a domain name or dotted ID of a server supporting XML-RPC, it defaults to "localhost". rpcPort is a number, the port number of the XML-RPC server, it defaults to the port that HTTP is configured to run on, on the client machine. procedureName is the name of an XML-RPC procedure that you want to run on the server, it defaults to the empty string (probably an error). adrParamList is the address of a list, these are the parameters that will be sent with the procedure call, it defaults to an empty list (no params). flDebug, a boolean, indicates whether you want a copy of the request stored in scratchpad.httpCommand and a copy of the result in scratchpad.httpResult. Default value is false. ticksToTimeOut is the number of sixtieths of a second before the request times out with a scriptError, default value is 30 seconds. The default is stored in ticks at user.betty.prefs.rpcClientDefaultTimeout. It can be changed. flShowMessages is a boolean, if true, Frontier's About window displays real-time messages at the HTTP level, default value is true. rpcPath is the path through which the server handles XML-RPC requests. The default path is /RPC2. This default is stored at user.betty.prefs.rpcClientDefaultPath and can be changed. flAsynch, a boolean, if true then this is an asynchronous XML-RPC call. It's optional, it defaults to false. adrCallback, defaults to nil, is the address of a script to run on the client when an asynchronous call is completed. It takes a single parameter, the address of a table describing the RPC request, including the value returned by the server. The routine pointed to by this address must not be local to the script calling betty.rpc.client because it won't be around when the actual RPC call is made. It must be in Frontier.root or in a guest database. extraInfo, defaults to nil, it's any kind of object, it's available to the callback to help it interpret the response. adrErrorCallback, defaults to nil, is the address of a script to run when an asynchronous RPC message fails. It takes a single parameter, the address of a table describing the RPC request. If the callback adds a boolean to the table named flDeleted, with the value true, the message will be deleted from the queue.
Action	Sends a remote procedure call to the indicated server with the indicated parameters, and passes the response back to the caller.
Returns	The value returned by the RPC handler on the server machine.
Examples	local (params = {18, 31, 2, 44}); betty.rpc.client (procedureName:"examples.getStateNames", adrparamlist:@params) //runs on localhost //"Louisiana\rNew Mexico\rAlaska\rUtah" local (params = {18, 31, 2, 44}); betty.rpc.client (rpcServer:"www.scripting.com", rpcPort:81, procedureName:"examples.getStateNames", adrparamlist:@params) //"Louisiana\rNew Mexico\rAlaska\rUtah" try {betty.rpc.client (procedureName:"wild.Beatnik.Pie")} else {tryError} //"The server, localhost, returned error code 7: Can't evaluate the expression because the name "wild" hasn't been defined."
Errors	If the server doesn't respond within ticksToTimeOut sixtieths of a second, betty.rpc.client will give up by throwing a scriptError. If the server doesn't speak XML-RPC, you may get a cryptic XML-level error message, complaining about poorly formed text. (Many servers respond with HTML, which in some ways looks like XML.)
Notes	It's implemented as a script, it encodes the parameter list and procedure name in XML and sends it to the server. The response is also XML-encoded, it's converted to a Frontier data structure and returned to the caller. This is one of two core routines in Frontier's XML-RPC functionality. The other side, the server, is implemented in "betty.rpc.server". The rpcPath, flAsynch, adrCallback, and extraInfo parameters were new in Frontier 6. adrErrorCallback is new in 6.1.
See Also	"betty.rpc.server" tcp.httpClient