VSI-I64VMS-GSOAP-V15-RNOTES.PDF

This document provides an overview of the gSOAP Toolkit for OpenVMS Integrity, released in March 2017 and based on gSOAP distribution 2.8.32. gSOAP is a cross-platform, open-source C/C++ toolkit for SOAP Web Services and XML-based applications, generating RPC code, XML data bindings, and schema-specific parsers.

Primary Purposes:

1. To enable OpenVMS legacy applications (e.g., COBOL, ACMS) to act as Web service clients by calling remote Web services through C libraries.
2. To facilitate the implementation of Web services on the OpenVMS platform, offering an alternative to Java-based solutions like Apache AXIS2/Tomcat.

Key Updates in this Release:

• It is based on gSOAP 2.8.32, a significant upgrade from the previous 2.8.22 version, bringing numerous enhancements.

System Requirements:

• Operating System: OpenVMS 8.4-2L1 or higher.
• Networking: HP TCP/IP Services V5.7 or higher (MultiNet also supported).
• Compilers: HP C V7.3-018 or higher. Optional: HP C++ V7.3 or higher (for C++ development).
• Utilities: UnZip 5.42 or similar for unpacking the kit.
• Optional for specific features: VSI SSL1 V1.0-2KA or higher (for SSL), VSI CSWS V2.4-3E or higher (for Apache mod_gsoap integration).
• Users are expected to have a good knowledge of OpenVMS and software development.

Installation: The kit is distributed as a ZIP file. After copying and unpacking it (preferably on an ODS-5 disk), a [.gsoap] directory will be created. The final step is to define the gsoap$root logical name (process or system-wide) to point to this directory. Users upgrading from a previous release and using mod_gsoap must replace the existing mod_gsoap.exe.

Key Features and Usage Notes:

• Language Integration: gSOAP can be used with various OpenVMS 3GLs (COBOL, BASIC, Pascal, FORTRAN), though C-code wrappers are often necessary for language compatibility. OpenVMS-specific GSOAP$ functions are provided.
• Debugging: A debug library (gsoapdbg.olb), compiled with the SOAP_DEBUG macro, is included to generate detailed log files for application diagnostics.
• SSL Support: The gsoapssl.olb library enables secure communication using OpenSSL. It requires VSI SSL1 V1.0-2KA+ to be installed and all gSOAP-generated code to be compiled with WITH_OPENSSL.
• FastCGI Support: Libraries gsoapfcgi.olb (C) and gsoapxxfcgi.olb (C++) support FastCGI applications, requiring FastCGI for OpenVMS and compilation with WITH_FASTCGI.
• Apache Integration (mod_gsoap): For production environments, gSOAP services can run under Apache using the mod_gsoap module. This involves copying the mod_gsoap.exe module, modifying httpd.conf to load the module and define the service location, defining a system-wide logical name for the service, and restarting Apache.
• OpenVMS-Specific Considerations: Due to gSOAP's UNIX origins, users must be mindful of OpenVMS's handling of mixed-case and long function names, potentially requiring linker directives (case sensitive=yes|no) or #pragma directives. Running gSOAP applications also requires certain privileges (e.g., SYSPRV, BYPASS, OPER) for socket operations and a reasonably high BYTLM quota.

Known Issues:

• On ODS-2 file systems, the soapcpp2 utility may fail if generating sample XML files for Web Service methods with names longer than 35 characters. The -x command-line option can suppress sample XML file generation as a workaround; ODS-5 is recommended.
• CGI programs running with Apache or WASD may experience truncated output. A freopen() call before soap_serve() is provided as a workaround.

Sample Applications: The kit includes various sample applications in gsoap$root:[samples] that illustrate different gSOAP features, language integrations (e.g., COBOL, FORTRAN), and specific configurations (e.g., FastCGI, WSSE). Each sample includes a build.com procedure.

Documentation and Feedback: Users should refer to the comprehensive gSOAP User Guide for detailed information. The developers encourage users to report any issues or suggest additional components for future releases.