OpenVMS Notes: AXIS2, SOAP, gSOAP

Table of Contents

(OpenVMS) Product Name Confusion

Product Description/Notes
ANT Another Neat Tool (an Apache script interpreter)
Apache HTTPd Hyper Text Transport Protocol daemon is a standalone product which operates on TCP/IP port 80 (http) and 443 (https) by default. When OpenVMS was owned by Compaq, this product was called CSWS (Compaq Secure Web Sever) pronounced "C-Swiss". Since HP bought (err, merged with) Compaq, I have heard HP engineers refer to this product as "Swiss" but the downloadable modules still have a "CSWS" prefix.
CSWS_JAVA HPE's name for Apache Tomcat (requires Java which is not included)
CSWS_PERL HPE's name for a module which enables Apache HTTPd to access Perl (requires Perl)
CSWS_PHP HPE's name of a module which provides Apache HTTPd with a PHP Interpreter
Apache Tomcat A standalone Java-based web server product which operates on TCP/IP port 8080 by default
(configure the connector kit to facilitate server back channels between HTTPd and Tomcat)
Confusingly, the Compaq/HP Tomcat product for OpenVMS is named CSWS_JAVA
Jakarta Apache's umbrella name for Java projects
Catalina Name of Tomcat's Servlet Container Technology
Coyote Tomcat's Java-based HTTPd server
Jasper Tomcat's JSP technology
GNV GNU Not VMS (Unix command interpreter for OpenVMS which includes BASH)
Java Standalone product is required by Tomcat. You need the development kit (has a JIT compiler), not the run-time kit.
1.5 and higher 1.4 and lower
JDK java development kit SDK standard development kit
JRE java runtime edition RTE run time edition
JAVA 5 comes up as version 1.5
JAVA 6 comes up as version 1.6
JAVA 8 comes up as version 1.8
OpenSSL Open Secure Sockets Layer "standalone product" (not used by Apache HTTPd which has its own built-in OpenSSL routines) Question: So why would you ever use it? Answer: to support encryption in client apps or standalone server apps Required by OpenVMS 8.x (used to validate HP patch kits)
Perl Standalone product (required by CSWS_PERL)
SOAP Toolkit 1.1 SOAP 1.0 - based upon Apache SOAP 2.31 - Apache's proof of concept SOAP offering (now obsolete)
SOAP Toolkit 2.0 SOAP 1.1 - based upon Apache AXIS/Java - Apache's first production SOAP engine (now obsolete)
AXIS2 SOAP 1.2 - based upon Apache AXIS2/Java - Apache's second production SOAP engine (served up by Tomcat)
WSIT Web Services Integration Toolkit (technology for accessing high level language routines from Java-based web services)
UDDI Universal Description Discovery and Integration is another Web Services component (this technology has not lived up to original expectations)
gSOAP generated SOAP. Third-party SOAP engine supporting SOAP code based upon C/C++
(this looks like a very promising alternative to AXIS2/c which is not available on OpenVMS unless you are willing to do your own build from Apache sources)

Installing "Apache SOAP" on OpenVMS Alpha (2010)

SOAP (Simple Object Access Protocol) is an XML extension for sending messages to other systems on the internet. It is platform neutral as well a language neutral.
AXIS (Apache eXtensible Interaction System)
SOAP
Technology		 Original
Product
Name		 Official
VMS
Name		 Requires
Tomcat?		 Document Links Language
SOAP 1.0 Apache SOAP SOAP Toolkit 1.x Y http://www.w3.org/TR/soap/ Java
SOAP 1.1 Apache AXIS SOAP Toolkit 2.x Y https://en.wikipedia.org/wiki/Apache_Axis Java
SOAP 1.1 and 1.2 Apache AXIS2 Axis2 Y https://en.wikipedia.org/wiki/Apache_Axis2 Java
SOAP 1.1 and 1.2 gSOAP   N http://www.cs.fsu.edu/~engelen/soap.html C or C++

Notes:

Installing AXIS2 on Tomcat for OpenVMS Alpha (2010)

Installing AXIS on Tomcat for OpenVMS Alpha (2010)

AXIS/AXIS2 Tutorials etc.

Miscellaneous notes

"Army Instructions" for creating an AXIS2 Service on OpenVMS

========================================================================================
title	   : axis2_service_demo_axp.txt
author	   : Neil Rieck
created	   : 2010.07.21
purpose    : A "Simple Service" demo for Apache Axis2 on OpenVMS-8.3
reference 1: Book "Quickstart Apache Axis2" by Deepal Jayasinghe
reference 2: http://people.apache.org/~ruchithf/hw-axis2/
notes      :
1. case is important for files as well as directories (folders)
2. AXIS2 will not deploy a service unless the extension is ".aar" (axis archive)
3. SET PROC/CASE=SENS/PARSE=EXTENDED		! change VMS session to case-sensitive
   SET PROC/CASE=BLIND/PARSE=TRADITIONAL	! restore VMS sessions to default 
4. here, the "ss" prefix means "simple service"
========================================================================================
$ SET PROC/CASE=SENS/PARSE=EXTENDED		! change your DCL session case-sensitive
$ create SimpleService.java			! create a new file with this name
/*
 * The service implementation class
 */
public class SimpleService {
	/*
	 * method: ssAdd 
	 */
	public int ssAdd(int ssValue1, ssValue2) {
		return ssValue1 + ssValue2;
	}
	/*
	 * method: ssSubtract
	 */
	public int ssSubtract(int ssValue1, ssValue2) {
		return ssValue1 - ssValue2;
	}
	/*
	 * method: ssEcho
	 */
	public String ssEcho(String ssValue3) {
		return "You sent: "+ ssValue3;
	}
}
<<<---- hit CTRL-Z here to close the "create" command
$ cre/dir [.TEMP]
$ cre/dir [.TEMP.META-INF]
$ create  [.TEMP.META-INF]services.xml
<service name="SimpleService">
    <description>
	Simple Service Hack
    </description>
    <parameter name="ServiceClass" locked="false">SimpleService</parameter>
    <operation name="ssAdd">
	<messageReceiver
		mep="http://www.w3.org/2004/08/wsdl/in-out"
		class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/>
    </operation>
    <operation name="ssSubtract">
	<messageReceiver
		mep="http://www.w3.org/2004/08/wsdl/in-out"
		class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/>
    </operation>
    <operation name="ssEcho">
	<messageReceiver
		mep="http://www.w3.org/2004/08/wsdl/in-out"
		class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/>
    </operation>
</service>
<<<---- hit CTRL-Z here to close the "create" command
$ javac "SimpleService.java" -d TEMP/
$ jar cvf SimpleService.aar  -C TEMP/ META-INF/services.xml
$ jar uvf SimpleService.aar  -C TEMP/ SimpleService.class
$ unzip -l SimpleService.aar	! test the archive like so

	Archive:  AXIS2$ROOT:[000000.NEIL.SS]SimpleService.aar;21
	  Length     Date   Time    Name
	 --------    ----   ----    ----
	        0  08-10-10 13:41   META-INF/
	       70  08-10-10 13:41   META-INF/MANIFEST.MF
	      572  08-10-10 13:40   META-INF/services.xml
	      585  08-10-10 13:41   SimpleService.class
	 --------                   -------
	     1227                   4 files
$ copy SimpleService.aar	-
	APACHE$COMMON:[JAKARTA.TOMCAT.webapps.axis2.WEB-INF.services]
$! step 7 -------------------------------------------------------------------------

Probe the service with IE8:

    http://yada.net:8080/axis2/services/listServices view the available services
    http://yada.net:8080/axis2/services/SimpleService?xsd view the associated xsd
    http://yada.net:8080/axis2/services/SimpleService?wsdl view the associated wsdl
    http://yada.net:8080/axis2/services/SimpleService?wsdl2 view the associated wsdl2

Test the service methods with IE8:

    http://yada.net:8080/axis2/services/SimpleService/ssEcho?param0=This is a test
    http://yada.net:8080/axis2/services/SimpleService/ssAdd?param0=34&param1=12
    http://yada.net:8080/axis2/services/SimpleService/ssSubtract?param0=34&param1=12

Caveat: this kind of testing only works if you have include support for the HTTP GET
method (usually there with AXIS2; optional with gSOAP; not supported on OpenVMS where
the Apache module 'mod_gsoap.exe' blocks all HTTP GET operations except for '?wsdl')

(using AXIS/AXIS2 to) Generate a WSDL Document

gSOAP (very, very fast)

gSOAP (all platforms)

gSOAP Toolkit for OpenVMS

gSOAP on OpenVMS

Home page of Brett Cameron & John Apps

VMS Pkg gSOAP Links  
12 2.8.3 https://drive.google.com/file/d/0B8fhl85GHPz2bFpheEJzUXFTSFE
https://drive.google.com/file/d/0B8fhl85GHPz2RWtlM0E4eEFxODg
https://drive.google.com/file/d/0B8fhl85GHPz2UC0zSVNNS3JTV1E		 I64
AXP
Notes

Tips for using gSOAP on OpenVMS

Two Flavors (client and server)

One tiny little problem with the plugin

Case Sensitivity

gSOAP sample apps were originally written for use in a case-sensitive environment (UNIX/Linux). So now you've got several options:

  1. Keep your DCL session in case insensitive mode but double-quote every parameter (to preserve case) like so:
    $ soapcpp2 "-c" "-S" -1 yada.h		! only generate "c" code
$					! only generate Server code
$					! only support soap1.1
  2. Switch to case-sensitive mode, execute your case-sensitive command, then switch back to case-insensitive mode:
    $ SET PROC/CASE=SENS/PARSE=EXTENDED	! switch your DCL session to case-sensitive
    $ soapcpp2 -c -S -1 yada.h		! only generate "c" code
$					! only generate Server code
$					! only support soap1.1
    $ SET PROC/CASE=BLIND/PARSE=TRADITION	! revert your DCL session back to case-insensitive
  3. Permanently switch your process to case sensitive and leave it there
    caveat: if you previously used mixed-case symbols and/or logical names in your scripts, then you might have trouble doing anything including "logging out" 

Overview of gSOAP code development in C

Sample Apache configuration for plugin mod_gsoap

file: [.conf]httpd.conf 
#=======================================================================
# experimental stuff for gSOAP (root)
# required so I can use a browser to look at docs specific to this stack
#=======================================================================
# DCL: $define/sys/trans=conc "gsoap$root" "DISK$USER1:[gsoap.]"
Alias /gsoap/ "/gsoap$root/000000/"
Alias /GSOAP/ "/gsoap$root/000000/"
<Directory "/gsoap$root/000000/">
	Options Indexes MultiViews
	IndexOptions NameWidth=*
	AllowOverride None
	Order allow,deny
	Allow from all
</Directory>
#
# this plugin module is required for gSOAP to work
#
LoadModule gsoap_module modules/mod_gsoap.exe
#
# enabled gSOAP services
# 1. only enable the stuff we need because more stuff seems to take a toll)
# 2. SOAPLibrary must point to a valid gSOAP executable (or Apache won't start)
#===============================
#	service: calc demo
#	logical: $def/sys gsoap_calc_server CSMIS$ROOT3:[DVLP._GSOAP_SAMPLES.CALC-NSR]calcserver.EXE 
#
<Location /gsoap_calc_server>		# lowercase name (also enable in SSL.CONF if HTTPS support is desired)
	SetHandler gsoap-handler
	SOAPLibrary GSOAP_CALC_SERVER	# this system-level logical name points to the executable
</Location>
#===============================
#	service: current-time demo
#	logical: $def/sys gsoap_current_time CSMIS$ROOT3:[DVLP._GSOAP_CURRENT_TIME]GSOAP_CURRENT_TIME.EXE 
#
<Location /gsoap_current_time>		# lowercase name (also enable in SSL.CONF if HTTPS support is desired)
	SetHandler gsoap-handler
	SOAPLibrary GSOAP_CURRENT_TIME	# this system-level logical name points to the executable
</Location>
#===============================
file: [.conf]ssl.conf 
<VirtualHost 142.180.39.16:443>
#===============================
#	service: calc service demo
#	logical: $def/sys gsoap_calc_server CSMIS$ROOT3:[DVLP._GSOAP_SAMPLES.CALC-NSR]calcserver.EXE 
#
<Location /gsoap_calc_server>		# lowercase name (also enable in HTTPD.CONF if HTTP support is desired)
	SetHandler gsoap-handler
	SOAPLibrary GSOAP_CALC_SERVER	# this system-level logical name points to the executable
</Location>
#===============================
#
#	service: current-time demo (not used here)
#	logical: $def/sys gsoap_current_time CSMIS$ROOT3:[DVLP._GSOAP_CURRENT_TIME]GSOAP_CURRENT_TIME.EXE
#
#<Location /gsoap_current_time>		# lowercase name (also enable in HTTPD.CONF if HTTP support is desired)
#	SetHandler gsoap-handler
#	SOAPLibrary GSOAP_CURRENT_TIME	# this system-level logical name points to the executable
#</Location>
#===============================
</VirtualHost>

My gSOAP Application for OpenVMS

Overview (Implements the PUSH-PUSH model)

Note: Due to a corporate security directive, all transmissions are encrypted via OpenSSL.

Flow #1 (Company 1 to 2 with response back)

	    Company #1			    Company #2
	    SOAP Client			    SOAP Server
+-------+  +---------------+		   +---------------+  +------+
| Human	+->| create ticket +-- HTTP POST ->| Queue Msg/Job +->| db + |
| Event	|  | update ticket |<- Status:200 -+ HTTP response |  | code |
+-------+  +---------------+		   +---------------+  +--+---+
	    SOAP Server			    SOAP Client		 |
	   +---------------+		   +---------------+	 |
	   | Queue Msg/Job |<- HTTP POST --+ Action: Reply |<----+
	   | HTTP Response +- Status:200 ->| within 60 sec |
	   +---------------+		   +---------------+

Flow #2 (Company 2 to 1 with response back)

	    Company #1			     Company #2
	    SOAP Server			     SOAP Client
 +------+  +---------------+		   +---------------+  +-------+
 | db + |<-+ Queue Msg/Job |<- HTTP POST --+ Update Ticket |<-+ Human |
 | code |  | HTTP response +- Status:200 ->| Close Ticket  |  | Event |
 +--+---+  +---------------+		   +---------------+  +-------+
    |	    SOAP Client			     SOAP Server
    |	   +---------------+		   +---------------+
    +----->| Action: Reply +-- HTTP POST ->| Queue Msg/Job |
	   | within 60 sec |<- Status:200 -+ HTTP Response |
	   +---------------+		   +---------------+

gSOAP Caveats (all platforms)

One of the things I like about gSOAP is that it is constantly being improved then rereleased. However, this caused me to waste an hour (totally my own fault) when I casually attempted to use demo client program calcclient.c from gSOAP-2.8.15 with demo server program calcserver.c from gSOAP-2.8.3 which caused the client to always display a result of '0' with no error messages. This was caused by the fact that file calc.h had changed between releases which affected generated code, wsdl, and data.

ver calc.h calc_add_req.xml
2.8.3
(old)		 
//gsoap ns service name:        calc
//gsoap ns service style:       document
//gsoap ns service encoding:    literal
//gsoap ns service namespace:   http://websrv.cs.fsu.edu/~engelen/calc.wsdl
//gsoap ns service location:    http://websrv.cs.fsu.edu/~engelen/calcserver.cgi

//gsoap ns schema namespace: urn:calc

int ns__add(double a, double b, double *result);
int ns__sub(double a, double b, double *result);
int ns__mul(double a, double b, double *result);
int ns__div(double a, double b, double *result);
int ns__pow(double a, double b, double *result);


<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
 xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:ns="urn:calc">
 <SOAP-ENV:Body>
  <ns:add>
   <ns:a>0.0</ns:a>
   <ns:b>0.0</ns:b>
  </ns:add>
 </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
2.8.15
(new)		 
//gsoap ns service name:        calc Simple calculator service
//gsoap ns service protocol:    SOAP
//gsoap ns service style:       rpc
//gsoap ns service encoding:    encoded
//gsoap ns service namespace:   http://websrv.cs.fsu.edu/~engelen/calc.wsdl
//gsoap ns service location:    http://websrv.cs.fsu.edu/~engelen/calcserver.cgi

//gsoap ns schema namespace:    urn:calc

//gsoap ns service method-documentation: add Sums two values
int ns__add(double a, double b, double *result);

//gsoap ns service method-documentation: sub Subtracts two values
int ns__sub(double a, double b, double *result);

//gsoap ns service method-documentation: mul Multiplies two values
int ns__mul(double a, double b, double *result);

//gsoap ns service method-documentation: div Divides two values
int ns__div(double a, double b, double *result);

//gsoap ns service method-documentation: pow Raises a to b
int ns__pow(double a, double b, double *result);
 
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:ns="urn:calc">
 <SOAP-ENV:Body 
  SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <ns:add>
   <a>0.0</a>
   <b>0.0</b>
  </ns:add>
 </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

To diagnose problems (without resorting to a packet sniffer) you might wish to insert these 3-4 lines into your server or client program. Remember that you must link against "gsoapdbg.olb" rather than "gsoap.olb".

soap_init(&soap);					// initialize (this line will already be present)
soap_set_recv_logfile(&soap, "server-recv.log");	// -+
soap_set_sent_logfile(&soap, "server-sent.log");	// -+- usually written to the Apache logging area
soap_set_test_logfile(&soap, "server-test.log");	// -+
soap_set_mode(&soap, SOAP_XML_STRICT);			// tell gSOAP to reject bad SOAP transactions (will throw an error)
soap_serve(&soap);					// serve as a CGI application (this line will already be present)

Installing "Apache SOAP" on OpenVMS Itanium (2018)

caveat: since this is based upon Tomcat 7.0 this procedure is slightly different from the previous install in 2010

Links:

Back to Home
Neil Rieck
Waterloo, Ontario, Canada.