Z-Script SOAP

The library uses gSoap and its httpget and httpform plugins for handling HTTP request. That means that you can serve web pages and process CGI request by Z-Script. A Z-Script module used as CGI will get two variables: HTTP_SOAP and HTTP_PARS. The former is a user object and can be used to call functions in the following table; and the later is an array that contains all GET or POST parameters.

The library also implements interfaces for passing data of integer, real, string, and binary between applications using SOAP.

Refer to METEX web site for application examples.

Function	Parameter Type	Remark
soap([io, access, alive])	integers	Returns a SOAP object. Use the optional parameters of io to specify send/receive timeout in second (default =60), access to specify access timeout (default=600), and alive to specify keep-alive (default=100).
.mime(ext)	string	Sets MIME content type of response according file extension. If ext is not in the internal extension list, the function sets content type to ext. Here are the extensions and their corresponding contend types in the list: *→application/octet-stream, htm→text/html, html→text/html, pdf→application/pdf, jpeg→image/jpeg, png→image/png, mpg→video/mpeg, mpeg→video/mpeg, asf→video/x-ms-asf, avi→video/x-msvideo, bmp→image/bmp, jpg→image/jpeg, gif→image/gif, ico→image/x-icon, txt→text/plain, css→text/css, zip→application/x-zip-compressed, tgz→application/x-tar-gz, tar.gz→application/x-tar-gz, tar→application/x-tar, gz→application/x-gunzip, arj→application/x-arj-compressed, rar→application/x-arj-compressed, wav→audio/x-wav, mp3→audio/x-mp3, mid→audio/mid, m3u→audio/x-mpegurl, ram→audio/x-pn-realaudio, ra→audio/x-pn-realaudio, svg→image/svg+xml, doc→application/msword, exe→application/octet-stream, xls→application/excel, ppt→application/vnd.ms-powerpoint, rtf→application/rtf, mathml→application/mathml+xml, xml→application/xml, xsl→application/xml, dtd→application/xml-dtd, xslt→application/xslt+xml, xhtml→application/xhtml+xml, xht→application/xhtml+xml, mid→audio/midi, midi→audio/midi.
.log(fname)	string	Set log file name for logging access information.
.proxy(name, port)	string, integer	Uses the proxy to access server.
.request(http, service, p1[, p2, ...])	string, string, string|integer|real|array	Sends server (http) with the service name and variable number of parameters. If an array parameter is used, it is expected to have two items with the first being the pointer to binary data and the second being the number of bytes. The service name is the function name on the server side.
.send(str)	string	Sends to client HTML content in text.
.send(ptr, n)	user, integer	Sends to client n-bytes of raw data. Note that the content type should be set properly.
.serve(fname, [port])	string, integer	Starts SOAP server. The server create a number of threads which have their own modules loaded from the script file. The optional parameter may be used to specify the port number (default=80). The server may response to clients with a string, an integer, a real, or an array of two items with the first being the pointer to binary data and the second being the number of bytes.
.user(usr, psw)	string, string	Sets client user name and password.

Example 1: Data Exchange

/********************** server.zs **********************************/

load("soap.dll");

sp = soap();

sp.serve("service.zs");


/********************** service.zs *******************************/

function p1_func(p)
{
	csv(p);
	return "Response: " + p;
}

function p3_func(p1, p2, p3)
{
	csv(p1, p2, p3);
	return "Response: p1=" + p1 + " p2=" + p2 + " p3=" + p3;
}

function b_func(p)
{
	csv(p);
	if (!isarray(p)) {
		csv("Client parameter is not an array.");
		return;
	}
	// return whatever binary from the client
	return p;
}


/********************** client.zs ***********************************/

load("soap.dll", "matrix.dll");

sp = soap();

url = "localhost";

a = sp.request(url, "p1_func", "Hi!");
csv(a);

a = sp.request(url, "p1_func", 100);
csv(a);

a = sp.request(url, "p1_func", 100.5);
csv(a);

a = sp.request(url, "p3_func", "Hi!", 100, 100.5);
csv(a);


D = matrix("double", 10);
D.fill(10, 1);
[ptr, m, e] = D.ptr();

[ptr, n] = sp.request(url, "b_func", [ptr, m*e]);
M = matrix("double", 10);
M.import(ptr);
M.print();

Example-2: Web Server

/********************** server.zs **********************************/

load("soap.dll");

sp = soap();

sp.serve("service.zs");

/********************** service.zs **********************************/

// The service script may have nothing. Requests will be handled
// by the script file specified in URL


/********************** get.zs **********************************/

// This script replies to a GET request.
// Assmuning the server is up and you are browsing
// http://localhost/get.zs?a=1&b=2
// you will get the result of a+b

a = HTTP_PARS["a"];
b = HTTP_PARS["b"];
c = integer(a) + integer(b);

HTTP_SOAP.send("<p>" + c + "</p>");


/********************** graph.zs **********************************/

// This script replies to a GET request.
// Assmuning the server is up and you are browsing
// http://localhost/graph.zs,
// you will see a map
// You can use such a script to generate inline image.

gshhs = "./data/gshhs1.3_c.b";          // file containing coastlines
lon1 = 100;                             // start longitude
lon2 = 180;                             // end longitude
dlon = 10;                              // longitude grid increment
lat1 = 10;                              // start latitude
lat2 = 60;                              // end latitude
dlat = 10;                              // latitude grid increment

// import map_class.zs

import map_class;

// create map object

G = new Map;

// set map parameters

G.map(gshhs, lon1, lon2 ,dlon, lat1, lat2, dlat);

// render image to binary stream
[ptr, n] = G.render.tofile("stream.png");

// reply with the image
HTTP_SOAP.mime("png");
HTTP_SOAP.send(ptr, n);