Copyright © 2010-2013 Mark G. Daniel
This program, comes with ABSOLUTELY NO WARRANTY.
This is free software, and you are welcome to redistribute it under the
conditions of the GNU GENERAL PUBLIC LICENSE, version 3, or any later version.
http://www.gnu.org/licenses/gpl.txt
SOAP, "originally defined as Simple Object Access Protocol, is a protocol specification for exchanging structured information in the implementation of Web Services in computer networks. It relies on eXtensible Markup Language (XML) as its message format, and usually relies on other Application Layer protocols (most notably Remote Procedure Call (RPC) and HTTP) for message negotiation and transmission. SOAP can form the foundation layer of a web services protocol stack, providing a basic messaging framework upon which web services can be built. This XML based protocol consists of three parts: an envelope - which defines what is in the message and how to process it - a set of encoding rules for expressing instances of application-defined datatypes, and a convention for representing procedure calls and responses."
http://en.wikipedia.org/wiki/SOAP
gSOAP, "is an open source C and C++ software development toolkit for SOAP/XML Web services and non-SOAP C/C++ XML data bindings. The toolkit analyzes WSDLs and XML schemas (separately or as a combined set) to map the XML schema types and the SOAP messaging protocols to easy-to-use and efficient C and C++ code. It also supports exposing (legacy) C and C++ applications as SOAP/XML Web services by auto-generating XML serialization code and WSDL specifications to advertize your Web service."
http://gsoap2.sourceforge.net/
gSOAP on OpenVMS is a VMS port of the gSOAP toolkit developed and maintained by John Apps and Brett Cameron and available for later versions of Alpha and Itanium VMS.
http://gsoaponopenvms.blogspot.com/
https://sites.google.com/a/johndapps.com/www/download
gSOAPrte and CGIplus_gSOAP are two WASD environments for providing persistent, (g)SOAP applications natively under the WASD VMS Web Services environment. The third uses the FastCGI interface provided with the gSOAP toolkit. Application persistence provides lower latency, greater throughtput and less system overhead. A fourth, non-persistent approach is vanilla CGI. Under WASD persistence can translate into one tenth (yes, that's 10%) of the same application latency under CGI, or 10x the throughput.
The WASD gSOAP RTE and CGIplus module have been developed and tested on VMS
V8.3 using the WASD v10.2.0 and gSOAP on OpenVMS version 12 AXP kit.
Obviously VMS gSOAP needs to be installed on a system to build VMS (g)SOAP
applications. If you are using a later kit it is not impossible that this
release of the RTE will break. Updating the RTE may be as simple as
copying the
GSOAP$ROOT:[INCLUDE]STDSOAP2.H and
GSOAP$ROOT:[INCLUDE]APACHE_GSOAP.H files to
WASD_ROOT:[SRC.GSOAP]
and rebuilding the RTE ($ @BUILD_GSOAPRTE.COM REFRESH will do this). Of
course the changes may just have been too great for this to be
successful.
gSOAPrte
This is a WASD Run-Time Environment for executing (g)SOAP applications built as shareable images.
For convenience, gSOAPrte uses the Apache apache_gsoap.h header file and the VMS gSOAP build procedures to create a shareable image for the SOAP application which can then be deployed directly under the WASD RTE as it would under VMS Apache. The same image can be used under either. Just place the executable into the application's web-space.
gSOAPrte can load, cache and execute multiple SOAP applications.
See VMS gSOAP samples and WASD gSOAPrte kit examples for Apache mod_gsoap
(and hence WASD shareable) build examples.
CGIplus_gSOAP
The code module CGIplus_gSOAP.c provides a wrapper with FastCGI-equivalent function calls for deploying a persistent SOAP application as WASD CGIplus using the same paradigm as FastCGI. Just substitute the FastCGI initialisation and request acceptance calls with CGIplus functional equivalents, build, deploy, voila! (There's testing in there somewhere :-)
For example ...
#include "fcgi_stdio.h"
int main (int argc, char **argv)
{
struct soap soap;
FCGI_InitVMS (argc, argv);
soap_init1 (&soap, SOAP_IO_BUFFER);
while (FCGIplus_Accept() >= 0)
{
soap_serve (&soap);
soap_end (&soap);
}
exit (0);
}
becomes ...
#include "CGIplus_gsoap.h"
int main (int argc, char **argv)
{
struct soap soap;
CGIplus_InitVMS (argc, argv);
soap_init1 (&soap, SOAP_IO_BUFFER);
while (CGIplus_Accept() >= 0)
{
soap_serve (&soap);
soap_end (&soap);
}
exit (0);
}
Pretty straight-forward!
It also removes the additional encumbrance of needing to employ the FastCGI development environment
http://fastcgiforopenvms.blogspot.com/to build, and WASD FastCGI interface to deploy, under WASD. Just make the application native CGIplus avoiding both of the former. (And of course with #ifdef both could be built from exactly the same source.)
http://www.johndapps.com-a.googlepages.com/fastcgionopenvms
To build just compile
$ CC /NAME=AS_IS /PREFIX=ALL CGIPLUS_GSOAP.Cand then link the object module into the desired SOAP application.
There is no significant difference in performance between gSOAPrte and CGIplus_gSOAP (see below).
The RTE approach allows a single scripting process to support multiple applications. The usual CGI variable environment is unavailable with a shared image. This is commonly not an issue with SOAP applications. A million test-bench transactions have been processed by a single scripting process so it appears to be reliable.
The CGIplus approach makes a single application dedicated to a single scripting process. The usual CGI variable environment is complete using CGIplus. CGIplus is a simple conversion from FastCGI. A CGIplus_gSOAP built application can also be used as vanilla CGI. CGIplus_gSOAP does seem to leak a little memory (see code description).
It is imagined the RTE should be suitable for the majority of applications.
Performance
The author's test-bench was HP TCP/IP Services for OpenVMS Alpha Version V5.6 - ECO 2 on a Digital Personal WorkStation (PWS500) running OpenVMS V8.3, HP C V7.3-009, WASD 10.0.1 and (VMS Apache) CPQ AXPVMS CSWS V2.1-1 .
The test SOAP application was ECHO.C and ECHOCLIENT.C wrapped by HAMMER.COM in the examples [.ECHO] subdirectory.
Apache (port 8888) configuration:
LoadModule gsoap_module modules/mod_gsoap.exe
<Location /soap-bin/soap_echo_share>
SetHandler gsoap-handler
SOAPLibrary wasd_root:[axp-bin]soap_echo_share.exe
</Location>
The ECHOCLIENT.C contains code to interate a number of requests against the configured URL. The first (hex) number output is the PID of the process handling the SOAP processing, the second the number of times the (persistent) application has been (re)used, followed by the case-complemented string. The HAMMER.COM procedure measures the time these requests take.
$! VMS Apache mod_gsoap $ ECHO_URL = "http://192.168.1.3:8888/soap-bin/soap_echo_share" $ echoclient "aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789_!@#$%^&*()_+=-" http://192.168.1.3:8888/soap-bin/soap_echo_share 0000661A 1 "AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_!@#$%^&*()_+=-" $ @hammer /out=nl: 1000 http://192.168.1.3:8888/soap-bin/soap_echo_share 00:00:22.87 $! $! WASD gSOAPrte $ ECHO_URL = "http://192.168.1.3/soap-bin/soap_echo_share" $ echoclient "aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789_!@#$%^&*()_+=-" http://192.168.1.3/soap-bin/soap_echo_share 0000661B 1 "AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_!@#$%^&*()_+=-" $ @hammer /out=nl: 1000 http://192.168.1.3/soap-bin/soap_echo_share 00:00:05.12 $! $! WASD CGIplus $ ECHO_URL = "http://192.168.1.3/cgiplus-bin/soap_echo_cgiplus" $ echoclient "aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789_!@#$%^&*()_+=-" http://192.168.1.3/cgiplus-bin/soap_echo_cgiplus 0000661D 1 "AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_!@#$%^&*()_+=-" $ @hammer /out=nl: 1000 http://192.168.1.3/cgiplus-bin/soap_echo_cgiplus 00:00:05.78 $! $! WASD (vanilla) CGI $ ECHO_URL = "http://192.168.1.3/cgi-bin/soap_echo_cgiplus" $ echoclient "aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789_!@#$%^&*()_+=-" http://192.168.1.3/cgi-bin/soap_echo_cgiplus 0000661F 1 "AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_!@#$%^&*()_+=-" $ @hammer /out=nl: 1000 http://192.168.1.3/cgi-bin/soap_echo_cgiplus 00:00:46.72
As can be seen from the table of results, WASD RTE and CGIplus are more than competitive.
| Seconds | Average mS | Requests/S | |
|---|---|---|---|
| Apache mod_gsoap | 22.87 | 22.8 | 44 |
| WASD gSOAPrte | 5.12 | 5.1 | 195 |
| WASD CGIplus | 5.78 | 5.8 | 173 |
| WASD CGI | 46.72 | 46.7 | 21 |
Of course, in the field who knows? - but on the test-bench one million
requests (500k of CALC.C and 500k of ECHO.C) have been made against a single
gSOAPrte process without failure or virtual memory / working set increase.
Installation
https://sites.google.com/a/johndapps.com/www/downloadand install according to the instructions available.
$ RENAME WASD_ROOT:[SRC]GSOAP.DIR WASD_ROOT:[SRC]GSOAP_nnn.DIR
http://wasd.vsm.com.au/wasd/
$ SET DEFAULT WASD_ROOT:[000000] $ UNZIP "-V" location:GSOAPRTEnnn.ZIP
$ SET DEFAULT WASD_ROOT:[SRC.GSOAP] $ @BUILD_GSOAPRTE LINK
$ COPY WASD_EXE:GSOAPRTE.EXE CGI_EXE:
(g)SOAP shareable executables by default have a .EXE file type. WASD will automatically execute .EXEs so some portion of the the request path will need to be used to indicate it needs to run under the gSOAPrte.
The most obvious is an EXEC path:
# WASD_CONFIG_MAP exec+ /soap-bin/* ($cgi_exe:gsoaprte)/cgi-bin/* map=once
or if retaining SOAP applications with gSOAP (for example, or elsewhere):
# WASD_CONFIG_MAP exec+ /soap-bin/* ($cgi_exe:gsoaprte)/gsoap$root/bin/* map=once
Alternatively, to automatically map script names beginning with "soap_" use something like:
# WASD_CONFIG_MAP redirect /soap_* /soap-bin/soap_* exec+ /soap-bin/* ($cgi_exe:gsoaprte)/cgi-bin/* map=once
Remember to
$ HTTPD /DO=MAPafter changing mapping rules.
A CGIplus (g)SOAP application may be configured and accessed in the same way as any other CGIplus script.
# WASD_CONFIG_MAP exec+ /cgiplus-bin/* /cgi-bin/* map=once
Remember to manually
$ HTTPD /DO=DCL=PURGEafter rebuilding a CGIplus or shareable (g)SOAP application otherwise any previous version executing will continue until the scripting process is purged automatically at some stage.
Two example applications are provided (DECC is required to build these):
The calc application is essentially lifted directly from the VMS gSOAP [.SAMPLES] directory. Minor modifications to enhance usability have been made.
The echo application is a home-grown demonstrator, and with the request iteration functionality used to measure relative performances (as with the statistics above).
Both contain BUILD.COM procedures to build shareable and CGIplus(/CGI) versions of the application using procedures essentially lifted directly from the VMS gSOAP package. Just copy the SOAP_*.EXE executable to CGI_EXE: and configure. After configuration (as described immediately above) these applications may be used to confirm the environment is functioning. The client can be used in situ. Each takes a DCL symbol assigned to contain the (g)SOAP application URL. The following will be available after configuration.
The author of the gSOAPrte interface is not in any position to answer
queries about SOAP "programming" or usage.
Releases
Many thanks to John Apps and Brett Cameron for their port and ongoing
maintenance of gSOAP for VMS.