Sysquake Pro – Table of Contents
Sysquake for LaTeX – Table of Contents
Web Services
This section describes functions which implement the client side of the XML-RPC and SOAP protocols, as well as low-level functions which can also be used to implement the server side. XML-RPC and SOAP permit web services, i.e. calling a function on a remote server over the World Wide Web. XML-RPC is based on two standards: XML (eXtended Mark-up Language), used to encode the request to the server and its response to the client, and HTTP (HyperText Transfer Protocol), the main communication protocol used by the World Wide Web. In XML-RPC, RPC means Remote Procedure Call; it is a mechanism used for decades to communicate between a client and a server on a network. The advantages of XML-RPC are that it is based on the same technologies as the Web and it is very simple. Its drawbacks are that it is less efficient than a binary encoding, and it is sometimes too simple and requires encoding of binary data, which defeats its main advantage. For instance strings are encoded in ASCII, and supported types are much less rich than LME's.
SOAP is also a standard used for exchanging data encoded with XML. It is more complicated than XML-RPC and supports more types. Function parameters are referenced by name while XML-RPC uses an ordered list. SOAP requests can be sent with different communication protocols; the implementation described here uses only the most common one, HTTP.
XML-RPC
In LME, XML-RPC makes calls to remote procedure similar to the use of feval. The two main functions are xmlrpccall and xmlrpccallset. Lower-level functions which encode and decode calls and responses, while not necessary for standard calls, can be used to understand exactly how data are converted, to implement the server, or for special applications.
Procedure calls can contain parameters (arguments) and always return a single response. These data have different types. XML-RPC converts them automatically, as follows.
| XML-RPC | LME |
|---|---|
| i4 | int32 scalar |
| int | int32 scalar |
| boolean | logical scalar |
| string | character 1-by-n array |
| double | real double scalar |
| dateTime.iso8601 | 1-by-6 double array |
| base64 | 1-by-n uint8 array |
| struct | structure |
| array | list |
There is no difference between i4 and int. In strings, only the least-significant byte is transmitted (i.e. only ASCII characters between 0 and 127 are transmitted correctly). Double values do not support an exponent (a sufficient number of zeros are used instead). The XML-RPC standard does not support inf and NaN; XML-RPC functions do, which should not do any harm. In LME, date and time are stored in a row vector which contains the year, month, day, hour, minute, and second (like the result of the function clock), without time zone information.
SOAP
SOAP calls are very similar to XML-RPC. The main difference is that they use a single structure to represent the parameters. The member fields are used as parameter names. The table below shows the mapping between SOAP types and LME types.
| SOAP | LME |
|---|---|
| xsd:int | int32 scalar |
| xsd:boolean | logical scalar |
| xsd:string | character 1-by-n array |
| xsd:double | real double scalar |
| xsd:timeInstant | 1-by-6, 1-by-7, or 1-by-8 double array |
| SOAP-ENC:base64 | 1-by-n uint8 array |
| (structure) | structure |
| SOAP-ENC:array | list |
In LME, time instants are stored as a row vector of 6, 7, or 8 elements which contains the year, month, day, hour, minute, second, time zone hour, and time zone minute; the time zone is optional. Arrays which are declared with a single type xsd:int, xsd:boolean, or xsd:double are mapped to LME row vectors of the corresponding class.
The two main functions for performing a SOAP call are soapcall and soapcallset.
Functions
soapcall
Perform a SOAP remote procedure call.
Syntax
response = soapcall(url, method, ns, action, opt) response = soapcall(url, method, ns, action, opt, param)
Description
soapcall(url,method,ns,action,opt,param) calls a remote procedure using the SOAP protocol. url (a string) is either the complete URL beginning with http://, or only the absolute path; in the second case, the server address and port come from argument opt. method is the SOAP method name as a string; ns is its XML name space; action is the SOAP action. opt is a structure which contains the options; it is typically created with soapcallset, or can be the empty array [] for the default options. param, if present, is a structure which contains the parameters of the SOAP call.
Example
The following call requests a translation from english to french (it assumes that the computer is connected to the Internet and that the service is available).
url = 'http://services.xmethods.net/perl/soaplite.cgi';
method = 'BabelFish';
ns = 'urn:xmethodsBabelFish';
action = 'urn:xmethodsBabelFish#BabelFish';
param = struct;
param.translationmode = 'en_fr';
param.sourcedata = 'Hello, Sysquake!';
fr = soapcall(url, method, ns, action, [], param)
fr =
Bonjour, Sysquake!
Note that since the server address is given in the URL, the default options are sufficient. The variable param is reset to an empty structure to make sure that no other parameter remains from a previous call.
See also
soapcallset
Options for SOAP call.
Syntax
options = soapcallset options = soapcallset(name1, value1, ...) options = soapcallset(options0, name1, value1, ...)
Description
soapcallset(name1,value1,...) creates the option argument used by soapcall, including the server and port. Options are specified with name/value pairs, where the name is a string which must match exactly the names in the table below. Case is significant. Options which are not specified have a default value. The result is a structure whose fields correspond to each option. Without any input argument, soapcallset creates a structure with all the default options. Note that soapcall also interpret the lack of an option argument, or the empty array [], as a request to use the default values.
When its first input argument is a structure, soapcallset adds or changes fields which correspond to the name/value pairs which follow.
Here is the list of permissible options:
| Name | Default | Meaning |
|---|---|---|
| Server | '' | server name or IP address |
| Port | 80 | port number |
| Timeout | 10 | maximum time in seconds |
| Debug | false | true to display data |
If the server is an empty string, it is replaced with 'localhost'. The Debug field is not included in the default options; when set, it causes the display of the request and responses.
Example
Default options:
soapcallset Server: '' Port: 80 Timeout: 10
See also
soapreadcall
Decode a SOAP call request.
Syntax
(method, namespace, pstruct, url) = soapreadcall(fd) (method, namespace, pstruct, url) = soapreadcall(str)
Description
soapreadcall(fd), where fd is a file descriptor, reads a complete SOAP call, decodes it, and returns the result in four output arguments: the method name and namespace as strings, a structure which contains the parameters, and the URL as a string.
soapreadcall(str) decodes its string argument which must be a whole SOAP call.
Example
param = {x=pi,y=true};
str = soapwritecall('','/','','fun','namespace',param);
(method, ns, pstruct, url) = soapreadcall(str)
method =
fun
ns =
namespace
pstruct =
x: 3.1416
y: true
url =
/
See also
soapreadresponse, soapwritecall
soapreadresponse
Decode a SOAP call response.
Syntax
(fault, value) = soapreadresponse(fd) (fault, value) = soapreadresponse(str)
Description
soapreadresponse(fd), where fd is a file descriptor, reads a complete SOAP response and decodes it. In case of success, it returns true in the first output argument and the decoded response value in the second output argument. In case of failure, it returns false and the fault structure, which contains the fields faultcode (error code as a string) and faultstring (error message as a string).
soapreadresponse(str) decodes its string argument which must be a whole SOAP response.
Examples
str = soapwriteresponse('fun', 'namespace', 123);
(fault, value) = soapreadresponse(str)
fault =
false
value =
123
strf = soapwritefault(12int32, 'No power');
(fault, value) = soapreadresponse(strf)
fault =
true
value =
faultcode: '12'
faultstring: 'No power'
See also
soapreadcall, soapwriteresponse, soapwritefault
soapwritecall
Encode a SOAP call request.
Syntax
soapwritecall(fd, server, url, action, method, ns, params) soapwritecall(server, url, action, method, ns, params) str = soapwritecall(server, url, action, method, ns, params)
Description
soapwritecall(fd,server,url,action,method,ns,params) writes to file descriptor fd a complete SOAP call, including the HTTP header. If fd is missing, the call is written to standard output (file descriptor 1); since the output contains carriage return characters, it may not be displayed correctly on all platforms. The server argument is a string which contains the server name, and, optionally, a colon and the server port number. url is a string which contains the absolute path (without the protocol, server, and port part). action is a string which contains the SOAP action, or is empty if no action is required for the service. method contains the method name sent to the server; ns is its XML name space. param, if present, is a structure which contains the parameters of the SOAP call.
With an output argument, soapwritecall returns the call as a string, without any output.
Example
param = {x=pi,y=true};
soapwritecall('server.com','/','action','fun','ns',param)
POST / HTTP/1.1
User-Agent: LME 4.5
Host: server.com
Content-Type: text/xml; charset=utf-8
Content-Length: 495
SOAPAction: action
<?xml version="1.0"?>
<SOAP-ENV:Envelope
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/1999/XMLSchema"
xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance">
<SOAP-ENV:Body>
<m:fun xmlns:m="ns">
<x xsi:type="xsd:double">3.1415926535898</x>
<y xsi:type="xsd:boolean">1</y>
</m:fun>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
See also
soapwriteresponse, soapreadcall, soapreadresponse
soapwritefault
Encode a SOAP call response fault.
Syntax
soapwritefault(fd, faultCode, faultString) soapwritefault(faultCode, faultString) str = soapwritefault(faultCode, faultString)
Description
soapwritefault(fd,faultCode,faultString) writes to file descriptor fd a complete SOAP response fault, including the HTTP header. If fd is missing, the response is written to standard output (file descriptor 1); since the output contains carriage return characters, it may not be displayed correctly on all platforms. The faultCode argument is the fault code as an integer or a string, and the faultString is the fault message.
With an output argument, soapwritefault returns the response as a string, without any output.
See also
soapwriteresponse, soapreadresponse
soapwriteresponse
Encode a SOAP call response.
Syntax
soapwriteresponse(fd, method, ns, value) soapwriteresponse(method, ns, value) str = soapwriteresponse(method, ns, value)
Description
soapwriteresponse(fd,method,ns,value) writes to file descriptor fd a complete SOAP response, including the HTTP header. If fd is missing, the response is written to standard output (file descriptor 1); since the output contains carriage return characters, it may not be displayed correctly on all platforms. The method argument is the method name as a string; ns is the XML name space; and value is the result of the call.
With an output argument, soapwriteresponse returns the response as a string, without any output.
Example
soapwriteresponse('fun', 'namespace', 123)
HTTP/1.1 200 OK
Connection: close
Server: LME 4.5
Content-Length: 484
Content-Type: text/xml
<?xml version="1.0"?>
<SOAP-ENV:Envelope
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/1999/XMLSchema"
xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance">
<SOAP-ENV:Body>
<m:funResponse xmlns:m="namespace">
<Result xsi:type="xsd:double">123.</Result>
</m:funResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
See also
soapwritecall, soapreadresponse, soapreadcall
xmlrpccall
Perform an XML-RPC remote procedure call.
Syntax
response = xmlrpccall(url, method, opt, params...)
Description
xmlrpccall(url,method,opt,params) calls a remote procedure using the XML-RPC protocol. url (a string) is either the complete URL beginning with http://, or only the absolute path; in the second case, the server address and port come from argument opt. method is the XML-RPC method name as a string; opt is a structure which contains the options; it is typically created with xmlrpccallset, or can be the empty array [] for the default options. The remaining input arguments are sent to the server as parameters of the XML-RPC call.
Examples
The following call requests the current time and date with a complete URL (it assumes that the computer is connected to the Internet and that the service is available).
url = 'http://time.xmlrpc.com/RPC2';
dateTime = xmlrpccall(url, 'currentTime.getCurrentTime')
dateTime =
2005 1 20 17 32 47
The server address (and the server port if it was not the default value of 80) can also be specified in the options; then the URL contains only the absolute path.
server = xmlrpccallset('Server', 'time.xmlrpc.com');
dateTime = xmlrpccall('/RPC2', 'currentTime.getCurrentTime', server)
dateTime =
2005 1 20 17 32 47
See also
xmlrpccallset
Options for XML-RPC call.
Syntax
options = xmlrpccallset options = xmlrpccallset(name1, value1, ...) options = xmlrpccallset(options0, name1, value1, ...)
Description
xmlrpccallset(name1,value1,...) creates the option argument used by xmlrpccall, including the server and port. Options are specified with name/value pairs, where the name is a string which must match exactly the names in the table below. Case is significant. Options which are not specified have a default value. The result is a structure whose fields correspond to each option. Without any input argument, xmlrpccallset creates a structure with all the default options. Note that xmlrpccall also interpret the lack of an option argument, or the empty array [], as a request to use the default values.
When its first input argument is a structure, xmlrpccallset adds or changes fields which correspond to the name/value pairs which follow.
Here is the list of permissible options:
| Name | Default | Meaning |
|---|---|---|
| Server | '' | server name or IP address |
| Port | 80 | port number |
| Timeout | 10 | maximum time in seconds |
| Debug | false | true to display data |
If the server is an empty string, it is replaced with 'localhost'. The Debug field is not included in the default options; when set, it causes the display of the request and responses.
Example
Default options:
xmlrpccallset Server: '' Port: 80 Timeout: 10
See also
xmlrpcreadcall
Decode an XML-RPC call request.
Syntax
(method, arglist, url) = xmlrpcreadcall(fd) (method, arglist, url) = xmlrpcreadcall(str)
Description
xmlrpcreadcall(fd), where fd is a file descriptor, reads a complete XML-RPC call, decodes it, and returns the result in three output arguments: the method name as a string, a list of arguments, and the URL as a string.
xmlrpcreadcall(str) decodes its string argument which must be a whole XML-RPC call.
Example
str = xmlrpcwritecall('rpc.remote.com', '/rpc', 'getPressure');
(method, arglist, url) = xmlrpcreadcall(str)
method =
getPressure
arglist =
{}
url =
/rpc
See also
xmlrpcreadresponse, xmlrpcwritecall
xmlrpcreadresponse
Decode an XML-RPC call response.
Syntax
(fault, value) = xmlrpcreadresponse(fd) (fault, value) = xmlrpcreadresponse(str)
Description
xmlrpcreadresponse(fd), where fd is a file descriptor, reads a complete XML-RPC response and decodes it. In case of success, it returns true in the first output argument and the decoded response value in the second output argument. In case of failure, it returns false and the fault structure, which contains the fields faultCode (error code as an int32) and faultString (error message as a string).
xmlrpcreadresponse(str) decodes its string argument which must be a whole XML-RPC response.
Examples
str = xmlrpcwriteresponse(123);
(fault, value) = xmlrpcreadresponse(str)
fault =
false
value =
123
strf = xmlrpcwritefault(12int32, 'No power');
(fault, value) = xmlrpcreadresponse(strf)
fault =
true
value =
faultCode: 12int32
faultString: 'No power'
See also
xmlrpcreadcall, xmlrpcwriteresponse, xmlrpcwritefault
xmlrpcwritecall
Encode an XML-RPC call request.
Syntax
xmlrpcwritecall(fd, server, url, method, params...) xmlrpcwritecall(server, url, method, params...) str = xmlrpcwritecall(server, url, method, params...)
Description
xmlrpcwritecall(fd,server,url,method,params...) writes to file descriptor fd a complete XML-RPC call, including the HTTP header. If fd is missing, the call is written to standard output (file descriptor 1); since the output contains carriage return characters, it may not be displayed correctly on all platforms. The server argument is a string which contains the server name, and, optionally, a colon and the server port number. The url argument is a string which contains the absolute path (without the protocol, server, and port part). The method argument contains the method name sent to the server. Remaining input arguments, if any, are sent as parameters.
With an output argument, xmlrpcwritecall returns the call as a string, without any output.
Example
xmlrpcwritecall('rpc.remote.com', '/rpc', 'getPressure', 1int32)
POST /rpc HTTP/1.0
User-Agent: LME 4.5
Host: rpc.remote.com
Content-Type: text/xml
Content-Length: 111
<?xml version="1.0"?>
<methodCall>
<methodName>getPressure</methodName>
<params>
<param>
<value>
<int>1</int>
</value>
</param>
</params>
</methodCall>
See also
xmlrpcwriteresponse, xmlrpcreadcall, xmlrpcreadresponse
xmlrpcwritedata
Encode an XML-RPC value.
Syntax
xmlrpcwritedata(fd, val) xmlrpcwritedata(val) str = xmlrpcwritedata(val)
Description
xmlrpcwritedata(fd,val) writes to file descriptor fd the value val encoded for XML-RPC. If fd is missing, the value is written to standard output (file descriptor 1); since the output contains carriage return characters, it may not be displayed correctly on all platforms.
With an output argument, xmlrpcwritedata returns the encoded value as a string, without any output.
Example
xmlrpcwritedata(pi) <double>3.141592653589</double>
See also
xmlrpcwritecall, xmlrpcwriteresponse
xmlrpcwritefault
Encode an XML-RPC call response fault.
Syntax
xmlrpcwritefault(fd, faultCode, faultString) xmlrpcwritefault(faultCode, faultString) str = xmlrpcwritefault(faultCode, faultString)
Description
xmlrpcwritefault(fd,faultCode,faultString) writes to file descriptor fd a complete XML-RPC response fault, including the HTTP header. If fd is missing, the response is written to standard output (file descriptor 1); since the output contains carriage return characters, it may not be displayed correctly on all platforms. The faultCode argument is the numeric fault code, and the faultString is the fault message.
With an output argument, xmlrpcwritefault returns the response fault as a string, without any output.
See also
xmlrpcwriteresponse, xmlrpcreadresponse
xmlrpcwriteresponse
Encode an XML-RPC call response.
Syntax
xmlrpcwriteresponse(fd, value) xmlrpcwriteresponse(value) str = xmlrpcwriteresponse(value)
Description
xmlrpcwriteresponse(fd,value) writes to file descriptor fd a complete XML-RPC response, including the HTTP header. If fd is missing, the response is written to standard output (file descriptor 1); since the output contains carriage return characters, it may not be displayed correctly on all platforms. The value argument is the result of the call.
With an output argument, xmlrpcwriteresponse returns the response as a string, without any output.
Example
xmlrpcwriteresponse(123) HTTP/1.1 200 OK Connection: close Server: LME 4.5 Content-Length: 123 Content-Type: text/xml <?xml version="1.0"?> <methodResponse> <params> <param> <double>123.</double> </param> </params> </methodResponse>