SOAPam Client Documentation
This documentation is for SOAPam Client version 3.1. Not using this version? See Other Documentation Versions.
Welcome to the documentation center for SOAPam Server by NuWave Technologies. You may navigate through the documentation using any of these methods:
The table of contents The navigation links in the sidebar to the left The quick links shown below The search bar in the page header
If you have comments, corrections, or questions about the product that are not answered here, please email [email protected] or submit a support ticket.
Getting Started
What is SOAPam Client
Installing SOAPam Client For Developers
The Developer's Guide
Creating and Editing the Client Definition File
Accessing Secure Web Services
For Administrators
The Administrator's Guide
Installing SOAPam Client
Managing SOAPam Client
Command Line Reference
Release Notes
Table of Contents
Table of Contents
What is SOAPam Client
Administrator's Guide Installing SOAPam Client Managing SOAPam Client Running the Client Process Collecting Process Statistics Using Configuration Files Configuration File Format Log Configuration Message Dump Configuration Statistics Configuration Common Configuration Options Event Message Reference
Developers Guide Creating and Editing the Client Definition File Configuring the Client Process Generating IPM Definitions Generating DDL from a CDF Element Name Considerations Generating IPM Definitions from DDL Calling a Web Service Method Web Service Requests Web Service Replies Using the Stream Protocol Accessing Secure Web Services Using HTTP Authentication Using Client Certificates Using Credential Files Using the MAKECF Utility Using Secure Connections Using W-S Security and WS-Addressing Client Definition File Reference Schema Reference
Command Line Reference CDF2DDL MAKECF SOAPAMCP STATSCON WSDL2CDF Glossary
Release Notes Upgrade Considerations Upgrade Guide Product Licensing Cumulative Change Log Third Party Software Licenses Standards Compliance
How to Obtain Support
Other Documentation Versions
View as PDF What is SOAPam Client
The SOAPam Client allows NonStop applications to access, or "consume", Web services on any platform anywhere in the world. SOAPam hides the complexity of TCP/IP, HTTP, SSL and SOAP required to participate in Web services.Your NonStop application simply sends a formatted interprocess message (IPM) to the SOAPam Client Process (SOAPAMCP) which handles all of the details of mapping the IPM elements to a SOAP envelope, exchanging the SOAP envelope with the Web service provider, and parsing the SOAP response into the reply IPM.
What is a Web Service?
A Web service is a collection of software "methods" that can be invoked (called) through a network by a client application using the SOAP protocol. Methods typically accept one or more parameters, perform some action and return one or more parameters.An example of a Web service might be a "BankingService" that provides methods such as "getAccountBalance", "debitAccount" and "creditAccount". For example, the "getAccountBalance" method might require an "accountNumber" parameter as input and return a "balance" parameter as output.
SOAPam Client Components
The diagram below depicts the SOAPam Client components as they are used at design time (during client application development) and at run time.
The components of the SOAPam Client product are described below:
Client Process (SOAPAMCP)
The Client Process relays messages sent from client applications through NonStop’s native inter-process message system to Web services anywhere in the world. SOAPAMCP hides the complexity of the TCP/IP, HTTP, SSL and SOAP protocols required to participate in Web services. When you start the SOAPAMCP process, you specify the name of a Client Definition File (CDF) that contains a description of the Web service you want to access. The CDF is an XML-formatted text file that you create using the WSDL2CDF utility.
The SOAPAMCP process can be run as a standalone named process or configured as a Pathway serverclass for scalable access to the target Web service.
WSDL2CDF Utility
The WSDL2CDF utility creates a Client Definition File (CDF) by reading the Web Service Description Language (WSDL) file that describes the target Web service and augmenting it with mapping information. The Client Definition File (CDF) contains all of the information needed by the SOAPAMCP process to map a request IPM to a Web service request and map the Web service response back to an reply IPM.
CDF2DDL Utility
Your NonStop application interfaces with the SOAPAMCP process through the native interprocess message system. The format of the request and response interprocess messages (IPMs) used must correspond precisely to the definitions in the CDF file. The CDF2DDL utility facilitates this by producing NonStop DDL source for the IPMs. You then use the NonStop DDL utility to produce the host language-specific definitions that you compile into your application. Administrator's Guide Installing SOAPam Client
This section contains all the information you need to install SOAPam Client.
Installation Prerequisites Obtaining the Software Selecting an Installation Volume Extracting the Release Files Obtaining and Installing a License Testing the Installation
Installation Prerequisites
Please refer to the Release Notes for the latest information. The Release Notes can be viewed at the NuWave Technologies Support Center.
SOAPam Client requires the following HP NonStop Server software:
HP NonStop™ Kernel D48/G06.15/H06.09 or later HP NonStop TCP/IP HP NonStop TM/MP
Although not required, SOAPam integrates with these products, if installed:
HP Data Definition Language HP TCP/IP Parallel Library, or TCP/IPv6
Obtaining the Software
SOAPam Client is distributed as single PAK file which you can download over the Internet. To download the software, use your Web browser to visit the NuWave Technologies Download Center. Click the hyperlink to download the PAK file to your desktop system, then use FTP to upload the file to your NonStop Server (be sure to use binary transfer mode).
Note that the PAK file name is in the format CRmnppa where:
mnpp indicates the version number in the form major.minor.patch, e.g., 3001 indicates release 3.0.1
a indicates the target architecture, where R indicates TNS/R (S-Series) and E indicates TNS/E (H and J series).
Selecting an Installation Volume
The SOAPam program files require approximately 30 megabytes of disk space and may be installed on any volume with sufficient space.
Extracting the Release Files
After copying the WCSPAK PAK file to your NonStop Server, perform the following steps at a TACL prompt. Note that you should substitute the correct PAK file name for your system architecture (WSCPAKR for TNS/R or WSCPAKE for TNS/E).:
1. If you are upgrading an existing installation of SOAPam Client, stop any SOAPAMCP processes running from the current subvolume. This may require shutting down any Pathway systems that are running the SOAPAMCP process as a server.
tacl> STATUS *, PROG SOAPAMCP
2. Extract the release files from the archive by running WSCPAK:
tacl> UNPAK PAKFILE, (*.*.*), VOL $volume.subvolume, MYID, LISTALL
where $volume.subvolume specifies the location to store the extracted files. Because the UNPAK program uses the Guardian RESTORE utility, you must have "execute" permission for that program. If you are extracting the the TNS/E version, specify WSCPAKE instead of WSCPAKR.
3. You may delete the PAK file at this time if you wish: tacl> PURGE PAKFILE
Obtaining and Installing a License
SOAPam Client requires the installation of a license. The license is installed in an edit file on the NonStop Server which is read by the SOAPAMCP program to validate the installation. If you have purchased the product your license will be delivered via email. If you are using a trial copy of the product, trial licenses may be requested at the NuWave Technologies License Center. You must know your system number in order to request a trial license. The system number can be determined using the NonStop SYSINFO program which can be run from the TACL prompt:
tacl>SYSINFO SYSINFO - T9268H01 - (01 OCT 2004) SYSTEM \NSKNODE Date 07 Jan 2015, 12:00:00 Copyright 2003 Hewlett-Packard Development Company, L.P. System name \NSKNODE EXPAND node number 001 Current SYSnn SYS00 System number 012345 Software release ID H06.nn
Note that when requesting a license from the License Center you must enter all digits of the license including the leading '0's. Once your trial license is delivered via email install the license using the procedure outlined in the section Product Licensing.
Testing the Installation
The SOAPam Client software includes a TACL routine that tests the installation by connecting to the EchoString sample web service on NuWave's SOAPam demonstration server. You can test your installation by entering the following command at the TACL prompt: Note that. in order to run this test, your NonStop system must have access to the Internet.
tacl> run ECHOTEST
SOAPam(tm) Client - Echo String Test This TACL routine uses the SOAPam Client Process to access the EchoString service at http://soapam.nuwavetech.com.
Starting the SOAPam Client Process ... Sending a request to the EchoString service ... Checking the reply ...
The EchoString service was called successfully. The SOAPam Web Client software is functioning correctly.
If an error occurs the echotest routine will display the source of the error and the description. The routine also creates a log file named ECHOLOG in the current subvolume which contains information that may be helpful if you need to troubleshoot your installation. Managing SOAPam Client
This section contains the information you need to manage SOAPam Client. Running the Client Process
The SOAPam Client Process receives interprocess messages from your application process and relays them to Web services that you have defined in a Client Definition File (CDF). When the Web service completes, its response is returned as a reply to the original interprocess message request. Refer to Creating and Editing the Client Definition File for more information about the CDF.
The SOAPam Client Process is started by running the SOAPAMCP program as a standalone Guardian process or by configuring the program as a Pathway server.
Running the Client Process as a Guardian Process
The general syntax for starting the client process from TACL as a standalone Guardian process is:
tacl> run SOAPAMCP / run-options / command-line-parameters
Example
The following example starts the Client Process nowaited, with a process name of $WSCP and a home terminal of $VHS, using the configuration options listed in a file named OPTIONS.
tacl> run SOAPAMCP / name $wscp, nowait, term $vhs / @options
Refer to the SOAPAMCP Command-Line Reference page for complete information about options for configuring the Client Process
Running the Client Process as a Pathway Server
The SOAPam Client Process may also be configured as a Pathway server. Potential advantages of running the Client Process as a Pathway server include process management and load balancing.
The configuration options are the same as those for standalone process configuration, however in the Pathway environment individual options are supplied as server PARAMs. The following is a sample pathway server configuration:
reset server set server cpus 0:1 set server createdelay 0 secs set server deletedelay 60 secs set server highpin on set server linkdepth 1 set server maxservers 6 set server maxlinks 20 set server numstatic 0 set server program soapamcp set server tmf on set server debug off set server param cdf "echocdf" set server param log "$0 event info" set server param tcpip "$zsam0" add server echo-service
You may also provide the options in a command file by setting the SERVER STARTUP value to @
Refer to the SOAPAMCP Command-Line Reference page for complete information about options for configuring the Client Process Collecting Process Statistics
The SOAPAMCP process can be configured to collect statistics for web services calls. The statistics are collected in the process and periodically written to an entry sequenced file. The statistics file can then be processed by system monitoring software. SOAPam Client includes definition files necessary for direct integration with the Prognosis performance monitor. DDL source for the statistics file is also included for those customers who wish to implement custom analysis of the statistics.
Activating Statistics Collection
Statistics are activated by supplying the -statscfg option on the process startup command line and supplying the name of a valid statistics configuration file. Refer to Stats Configuration for more information on statistics configuration files. Note that multiple processes can concurrently write to a single statistics collection file.
Integrating with Prognosis
The SOAPam Client release contains two files necessary to integrate statistics collection with Prognosis. These files are:
PRGNCEXT Prognosis extractor script for client statistics file
PRGNCREC Prognosis UDEFSREC record definition for the client statistics file.
These file are for use with the Prognosis File Extractor product. The extractor must be configured as a LOG mode extractor using the extractor script and statistics file as parameters, for example:
tacl> EXTRACT LOG (FSCOL, $DATA1.SOAPAM.PRGNCEXT, $DATA1.SOAPAM.ZZCSTATS, 0, 100)
Refer to your Prognosis documentation for complete instructions on installing these files into Prognosis and configuring the Extractor.
Statistics DDL
The statistics file DDL source is contained in the file STATDDL included with the release. The DDL file contains documentation for each field in the statistics record.
How Statistics are Collected
Statistics data is collected internally in the SOAPAMCP process and periodically flushed to the statistics output file. Only the latest record in the statistics file for each web service request call contains the most recent data. The latest record can be determined using the TimeUpdt field. This collection mechanism allows monitoring processes such as Prognosis to monitor the statistics file for updates and read the latest entries for updated statistics information. The STATSCON utility can be used to consolidate a collection of statistics files into a single statistics record or CSV file containing only the latest information.
Statistics Data Column Descriptions
Detailed descriptions for the statistics data is shown below:
Column Description
Rec Type The record type for this record. Web service client records have the form RECTYPE-2.nn, where nn is the record version number.
NodeName The node name of the SOAPAMCP process.
PathProc The process name of the PATHMON that created the SOAPAMCP process. If the SOAPAMCP process was not launched by PATHMON, the column will contain "N/A". Refer to Determination of the Pathmon Process Name for more information.
ProcName The process name of the SOAPAMCP process.
Tcp Name The name of the TCP/IP process being used by the SOAPAMCP process.
Svc Host The host name of the service endpoint. The host name is extracted from the URL of the web service endpoint, either from the location attribute in the CDF or the -location command line option.
Svc Addr The IP address of the service endpoint. The IP address is resolved using the TCP/IP library gethostbyname() function with the supplied Svc Host name.
Svc Port The TCP protocol port of the service endpoint. The port is extracted from the host portion of the URL of the service endpoint. Svc URL The URI portion of the endpoint URL.
Svc Meth The method name of that was invoked in the web service request.
Svc Cnt The number of time the method was invoked during the sample period.
Svc Warn The number of times the SOAPAMCP process returned a warning reply to the SOAPAMCP client.
Svc Err The number of times the SOAPAMCP process returned an error reply to the SOAPAMCP client.
Svc Flts The number of times the web service returned a SOAP fault to the SOAPAMCP process. The reception of a SOAP fault is returned to the SOAPAMCP client as an error and would be included in the Svc Err count.
Svc TO The number of times the SOAPAMCP process returned a timeout error to the SOAPAMCP client. A timeout error occurs when the web service does not respond within the time period specified by the -httprequesttimeout command line option or the request_timeout field in the SOAPAMCP request header. The timeout error is returned to the SOAPAMCP client as an error and would be included in the Svc Err count.
Svc Canc The number of times a request I/O from the SOAPAMCP client was cancelled. A cancel can occur when the SERVERCLASS_SEND_ or WRITEREAD(X) to the SOAPAMCP process times out or is explicitly cancelled by the client. The cancel may also occur if the SOAPAMCP process is a Pathway server, the server has a TIMEOUT period configured, and the TIMEOUT period expires.
Req times The time taken to receive the request from the SOAPAMCP client. The request may consist of a single IPM or multiple IPMs if † the request is streaming.
Ser times† The time taken to serialize the request IPM(s) into the SOAP request payload.
Send The time taken to transmit the web service request to the service endpoint over the TCP/IP network. This includes the times† transmission of the HTTP request line, HTTP headers, and SOAP payload.
Svc times The time taken by the web service endpoint to process the request. †
Recv The time taken to receive the web service response from the service endpoint over the TCP/IP network. This includes the times† reception of the HTTP status line, HTTP headers, and SOAP payload.
Dser times The time taken to deserialize the SOAP response payload into the reply IPM(s). †
Rep times The time taken to send the response to the SOAPAMCP client. The reply may consist of a single IPM or multiple IPMs if the † response is streaming.
Totl times The total time taken for the web service request. This is the sum of the Req, Ser, Send, Svc, Recv, Dser, and Rep times. †
TimeRset The collection time of the first data point for this data sample.
TimeUpdt The collection time of the latest data point for this data sample.
TimeElap The elapsed time of this data sample.
†Columns with "times" designation represent three columns with the average, maximum, and minimum elapsed times for that data element. The elapsed times are in seconds. Using Configuration Files
Some SOAPAMCP process configuration options support dynamic configuration through the use of configuration files. Instead of providing the configuration options on the process startup command line, the configuration file name is supplied and the configuration options are read from the file. The configuration file is then monitored for changes and when they occur, the options are reloaded from the file. Configuration files are Enscribe EDIT files and use the defacto standard INI file format. The following commands may use configuration files:
Command Description
-logcfg Logging configuration
-statscfg Statistics collection configuration
-messagedumpcfg Diagnostic dumping configuration
The configuration file is continuously monitored for changes. When a change occurs, the file is reloaded and the new options take effect. If the configuration change contains an error or the file is inaccessible then the change is ignored and a notification message is output the the log file.
The following sections describe the configuration options for these commands: Configuration File Format
Configuration files are Enscribe EDIT files and use the defacto standard INI file format described below.
Parameters
Parameters consist of name, value pairs delimited by an equals sign (=). The value may be enclosed in quotes to preserve whitespace when necessary.
Sections
Parameters are grouped into named sections. A section header consists of the a section name enclosed in square brackets ( [ ] ). All parameters found after a section header and before the next section header or end of file are associated with that section header. Section headers may include a process name to indicate that the section applies to a specific process. In this case the section name consists of the process name and section name delimited by a colon (:).
Comments
A semicolon indicates the start of a comment, which continues to the end of the line. All text between the semicolon and end of line is ignored.
Blank Lines
Blank lines are ignored.
Example
; This section configures generic logging options [log] file=zzlog format=text level=info timestamp=lct ; use local civil time.
; Configure trace level logging for process $XYZ. [$XYZ:log] file=zzlog format=text level=trace ; trace level logging for this process. timestamp=lct Log Configuration
Dynamic logging configuration is activated using the -logcfg startup option. Note that when the -logcfg option is used, the -log and -logtime options are ignored.
Configuration Reference
[log] Section
Option Description
file The name of the log file. If not fully qualified then the value of the _DEFAULTS define is used to complete the file name.
format The format value may be "text" indicating that the log events should be output as text strings or "event" indicating that the log events should be output in EMS event format.. If not specified the default value is "text".
level The level value may be "error", "warning", "info", or "trace" and controls the type of information that is output to the log destination. The "error" level produces the least output while the "trace" level produces the most output. The default value is "info".
time Specifies the time format for the process log. Available formats are:
GMT Greenwich mean time (the default)
LST Local standard time (local time without DST adjustment)
LCT Local civil time (local time with DST adjustment)
Additionally, the Common Configuration Options may be included to specify file allocation and rollover options.
Examples
; Log to a file [log] file=$data1.logs.zzlog format=text level=info time=lct rollover-file=$data1.archive.log rollover-count=10
; Log to $0 [log] file=$0 format=event level=info Message Dump Configuration
Dynamic message dump configuration is activated using the -messagedumpcfg startup option. Note that when the -messagedumpcfg option is used, the -messagedump, -messagedumpsubvol, -messagedumpfile, and -messagedumpfilter options are ignored.
Configuration Reference
[messagedump] Section
Option Description
enabled The value may be "0" to disable message dumping or "1" to enable it. The default is "0".
file The name of the message dump file. If not fully qualified then the value of the _DEFAULTS define is used to complete the file name. If omitted, a new dump file is created for each request and has the name format DUnnnnnn where nnnnnn is a sequence number.
subvol When the file parameter is not specified, this parameter specifies the subvol in which the individual message dump files will be created. If not specified the messagedump files are written to the current subvol (as defined by the _DEFAULTS define) of the SOAPAMCP process.
level When specified the web service request and reply messages are dumped to a file. The options SOAP, RAW, and IPM options produce the following output:
SOAP The request/response SOAP envelopes formatted for display
RAW The request/response SOAP envelopes in hex dump format
IPM The request/response IPMs in hex dump format
HTTP HTTP protocol information.
BASIC Basic information including only the dump header.
The SOAP and RAW options also produce network connection and HTTP header information.
filter When specified the messagedump information will only be dumped when the IPM response reply code is in the specified range. The range is specified as a comma-separated list of values or value ranges. Value ranges are specified with a min value and max value separated by a colon (:). For example, to dump only messages that have a reply code of 1 or 2 the reply code range may be specified as "1,2" or "1:2". If not specified, all messages are dumped.
filetype The value may be "E" to indicate dumping to an edit file (code 101) or "U" to dump to an unstructured entry sequenced file. The default is "E".
Additionally, the Common Configuration Options may be included to specify file allocation and rollover options.
Examples
; Dump all soap faults. [messagedump] enabled=1 file=$data1.msgdump.faults level=soap raw ipm filter=500
; Dump all SOAP payloads to individual files. [messagedump] enabled=1 subvol=$data1.msgdump level=soap Statistics Configuration
Dynamic statistics configuration is activated using the -statscfg startup option.
Configuration Reference
[stats] Section
enabled The value may be "0" to disable statistics collection or "1" to enable it. The default is "0".
file The name of the statistics file. If not fully qualified then the value of the _DEFAULTS define is used to complete the file name.
time Specifies the time format for the statistics file entries. Available formats are:
GMT Greenwich mean time (the default)
LST Local standard time (local time without DST adjustment)
LCT Local civil time (local time with DST adjustment)
flush-interval Specifies how often statistics are written to the statistics file, specified in seconds. The default value is 15 seconds. Valid values are 15 - 86400.
reset-interval Specifies how often the process statistics counters are reset, specified in minutes. The default value is 0, which indicates that the statistics are not automatically reset and continue to accumulate for the life of the process. Valid values are 0 - 10080.
on-reset The action to take on the statistics file when a reset occurs. The available options are:
rollover The current file is renamed according to the 'rollover-file' specification and a new file is opened.
purgedata The current file data is purged with a call to CONTROL 20 and the current file remains open.
keep No action is taken. Statistics continue to be written to the current file (the default).
Additionally, the Common Configuration Options may be included to specify file allocation and rollover options.
Example
; Enable statistics collection. [stats] enabled=1 file=$data1.stats.zzstats maxentents=200 time=lct Common Configuration Options
Several common file management configuration options may be used when configuring log, statistics, and message dump options.
Configuration Reference
ext The primary and secondary extent size for the file in the form: < pri-extent-size>, [
maxextents The maximum extents for the file. The default value is 100.
on-file-full The action to take when the output file is full. The available options are:
rollover The current file is renamed according to the 'rollover-file' specification and a new file is opened. This is the default action
purgedata The current file data is purged with a call to CONTROL 20 and the current file remains open.
rollover-file The file name prefix for rollover files, which may be partially or fully qualified. The file name portion of the specified file will be truncated to a maximum of 5 characters and a 3 digit sequence number will be appended. The default rollover-file name is the current output file name. Specifying a remote system file for the rollover file name is not supported.
rollover-count The maximum number of rollover files to retain. Note that when a rollover occurs, the oldest rollover files are deleted until
Examples
; Log to a file, specifying the extents. Note that if rollover occurs on the file, the
; rollover file names will be zzlog000, zzlog001, etc. [log] file=$data1.logs.zzlog format=text level=info time=lct ext=16,32 maxextents=512 ; Log to a file, specifying an alterate subvol for the "rolled over" files and limitin g ; to a maximum of 10 rollover files. [log] file=$data1.logs.zzlog format=text level=info time=lct rollover-file=$data1.archive.log rollover-count=10
; Log statistics to a file that is read by Prognosis, purging the statistics data when the file is full. [stats] file=$data1.stats.zzstats enabled=1 on-file-full=purgedata Event Message Reference
This appendix describes the SOAPAMCP process messages. Message numbers are grouped into the following ranges:
Errors 1000 - 1999
Warnings 2000 - 2999
Information 3000 - 3999
Messages
SOAPAMCP 1922 Unable to open CDF file file-name : reason-for-failure.
Cause: The CDF file could not be opened. The reason-for-failure describes the failure.
Effect: The SOAPAMCP process stops.
Recovery: Resolve the cause of the failure and restart the SOAPAMCP process.
SOAPAMCP 1923 Unable to load CDF file file-name : reason-for-failure.
Cause: The CDF file was opened but could not be loaded. The reason-for-failure describes the failure.
Effect: The SOAPAMCP process stops.
Recovery: Resolve the cause of the failure and restart the SOAPAMCP process.
Cause: The option-name option was specified but no credentials were supplied. The option requires a credentials string or file name.
SOAPAMCP 1924 The option-name option requires a valid credentials string.
Effect: The SOAPAMCP process stops.
Recovery: If you wish to use a HTTP authentication correct the option specification and restart the SOAPAMCP process.
SOAPAMCP 1925 Unable to load credentials: reason-for-failure .
Cause: The credentials specified in the -sslclientcert or -httpauth option could not be loaded. The reason-for-failure describes the failure.
Effect: The SOAPAMCP process stops.
Recovery: Resolve the cause of the failure and restart the SOAPAMCP process.
SOAPAMCP 1926 The specified trusted root file file-name does not exist.
Cause: The file specified with the -sslcarootfile option does not exist. Effect: The SOAPAMCP process stops.
Recovery: Correct the file specification and restart SOAPAMCP.
SOAPAMCP 1927 The specified local CA file file-name does not exist.
Cause: The file specified with the -sslcalocalfile option does not exist.
Effect: The SOAPAMCP process stops.
Recovery: Correct the file specification and restart SOAPAMCP.
SOAPAMCP 1928 SSL Initialization error: reason-for-failure.
Cause: An error occurred while initialization the SSL subsystem or loading the client certificate.
Effect: The SOAPAMCP process stops.
Recovery: Correct the issue described in reason-for-failure and restart SOAPAMCP.
SOAPAMCP 1929 Invalid syntax for the -messagedump option. Valid message dump values are 'soap', 'ipm', and 'raw'.
Cause: The -messagedump option was incorrectly specified.
Effect: The SOAPAMCP process stops.
Recovery: Correct the -messagedump option and restart the process.
Cause: The -sslclientcert option was specified but no file name or credentials were supplied.
SOAPAMCP 1931 Unable to load the product license from license-source : reason-for-failure.
Cause: There is a problem with the license file. The reason-for-failure describes the failure.
Effect: The SOAPAMCP process starts but will not process web service requests until a valid license is installed.
Recovery: Install a valid license.
SOAPAMCP 1938 The -sslclientcert option requires a valid certificate file name and associated credentials.
Effect: The SOAPAMCP process continues to run but no client certificate will be loaded.
Recovery: If you wish to use a client certificate correct the option specification and restart the SOAPAMCP process.
SOAPAMCP 1940 The service location URL is not valid.
Cause: The URL specified for the service endpoint is not valid. This URL may be specified in the CDF or with the -location startup option.
Effect: The SOAPAMCP process stops.
Recovery: Correct the URL specification and restart SOAPAMCP.
SOAPAMCP 1941 Host name host-name could not be resolved to an IP address.
Cause: The host name specified in the service location URL could not be resolved to an IP address. This URL may be specified in the CDF or with the -location startup option.
Effect: The SOAPAMCP process stops.
Recovery: Correct the URL specification and restart SOAPAMCP. If the URL is correct then resolve the name resolution problem and restart SOAPAMCP.
SOAPAMCP 1944 The required -cdf option was not supplied.
Cause: The -cdf option is a required startup parameter and it was not supplied.
Effect: The SOAPAMCP process stops.
Recovery: Restart the SOAPAMCP process and supply a valid -cdf option.
SOAPAMCP 1945 Unable to open policy file file-name : reason-for-failure.
Cause: The web service policy file could not be opened. The reason-for-failure describes the failure.
Effect: The SOAPAMCP process stops.
Recovery: Resolve the cause of the failure and restart the SOAPAMCP process.
SOAPAMCP 1946 Unable to load policy file file-name : reason-for-failure.
Cause: The policy file was opened but could not be loaded. The reason-for-failure describes the failure.
Effect: The SOAPAMCP process stops.
Recovery: Resolve the cause of the failure and restart the SOAPAMCP process.
SOAPAMCP 1947 Invalid syntax for the -messagedumpfilter option.
Cause: The -messagedumpfilter option was incorrectly specified. Effect: The SOAPAMCP process stops.
Recovery: Correct the -messagedumpfilter option and restart the process.
SOAPAMCP 1948 Unable to open certificate file file-name : reason-for-failure.
Cause: The certfiicate file could not be opened. The reason-for-failure describes the failure.
Effect: The SOAPAMCP process stops.
Recovery: Resolve the cause of the failure and restart the SOAPAMCP process.
SOAPAMCP 2800 Warning: The installed license expires on date.
Cause: The installed license will expire on the specified date. This message is generated once per day when the license will expire in less than 30 days.
Effect: When the license expires the server will no longer process web service requests.
Recovery: Renew the license.
SOAPAMCP 3100 NuWave Technologies SOAP/AM Client version.
Cause: This message is generated at SOAPAMCP process startup and displays the product version.
Effect: This message in informational.
Recovery: None
SOAPAMCP 3102 Starting in CPU cpu-number with options: startup-options-list.
Cause: This message is generated at SOAPAMCP process startup and displays the startup CPU and options.
Effect: This message in informational.
Recovery: None
SOAPAMCP 3106 Stopping.
Cause: This message is displayed when the SOAPAMCP process begins the shutdown process.
Effect: This message in informational.
Recovery: None
SOAPAMCP 3107 Stopped.
Cause: This message is displayed when the SOAPAMCP process stops.
Effect: This message in informational.
Recovery: None
SOAPAMCP 3112 Using TCPIP process process-name , specified by < options | DEFINE | default >.
Cause: This message is generated at SOAPAMCP process startup and displays the TCP/IP process name being used and how the process name was determined.
Effect: This message in informational.
Recovery: None
Developers Guide
The Developer's Guide is comprised of two main sections: "Accessing a Web Service" and the "Client Definition File Reference".
Accessing a Web Service
Accessing a Web service using the SOAPam Client requires four implementation steps:
Creating and Editing the Client Definition File Configuring the Client Process Generating IPM Definitions Calling a Web Service Method
Additonally, a Web service may dictate a security protocol that must be used to access the service:
Accessing Secure Web Services
Client Definition File Reference Creating and Editing the Client Definition File
The Client Definition File (CDF) contains all of the information needed by the SOAPAMCP process to map an IPM to a Web service request and map the Web service response back to an IPM. You use the WSDL2CDF utility to generate a CDF file from the Web Services Description Language (WSDL) file that describes the Web service you want to access.
It is common for Web services to use arbitrary-length strings and unbounded arrays in their type definitions. Since your application will use interprocess messages (which have a finite size) to access Web services, you must set specific limits on the sizes of these items. This may require some minor editing of the CDF that was generated by WSDL2CDF.
This section explains the Client Definition File creation and editing process.
Creating the Client Definition File using WSDL2CDF
The WSDL2CDF utility creates a Client Definition File (CDF) by reading the Web Service Description Language (WSDL) file that describes the target Web service and augmenting it with mapping information. The CDF contains all of the information needed by the SOAPAMCP process to map a request IPM to a Web service request and map the Web service response back to an reply IPM. Some minor manual tuning of the generated CDF may be required, however. See Editing the Client Definition File, below, for more information.
tacl> run WSDL2CDF -wsdl http://soapam.nuwave-tech.com/services/bankdemo/bankdemo.wsdl -cdf bankcdf
Refer to the WSDL2CDF Command Line Reference for complete details.
Editing the Client Definition File
You use the WSDL2CDF utility to create your Client Definition File (CDF). However, there a few circumstances in which it may be necessary or desirable to edit the CDF that WSDL2CDF produced:
to change the maximum length of a string-type element to change the upper boundary of an array-type element to specify an alternate name for an element to specify an alternate data type for an element
The Client Definition File (CDF) is an XML-format text file. You can edit it with any text editor. Be sure to observe the rules for XML; that all attribute values be quoted, for example. Refer to the Client Definition File Reference for complete details on structure of the Client Definition File.
Changing the maximum length of a string or upper bound of an array
It is common for Web services to use arbitrary-length strings and unbounded arrays in their type definitions. Since your application will use interprocess messages (which have a finite size) to access Web services, you must set specific limits on the sizes of these items.
The WSDL2CDF utility does this for you automatically when creating the Client Definition File (CDF). By default, it sets all string elements to a maximum length of 32 characters and all arrays to a maximum of two occurrences. You can override these settings by using the -stringsize and -maxoccurs command line parameters. However, WSDL2CDF applies the same sizes to all of the string elements and all of the array elements in the CDF, which may not be appropriate for your application. In such cases, you must manually adjust the sizes by editing the CDF.
Here's an example of a string element whose size was set to '32' by WSDL2CDF:
To change the maximum length of the string element 'mystring' to 256, change the entry to:
Here's an example of an array element whose upper bound (maxOccurs) was set to '2' by WSDL2CDF because the WSDL did not specify an upper bound:
To change the upper bound of the myarray to 8, change the entry to:
Bear in mind that changing the sizes of elements will change the size of the interprocess message your application must send to access the Web service, and that the maximum size of an interprocess message is 32,767 bytes. Specifying an alternate name for an element
The CDF is used by the CDF2DDL utility to generate DDL descriptions of the IPMs your application will use to access the Web service. CDF2DDL will adjust the names of the elements it generates to conform to DDL naming rules (maximum length, reserved word conflicts, etc.). This may result in somewhat cryptic element names in the generated DDL. Although you can manually change the names in the DDL, the changes will be lost if you ever need to run CDF2DDL again. Instead, add the "ddlName" attribute to the element to specify the name that CDF2DDL should use in the DDL it generates. For example:
02 ThirdPartyProductDetails01 PIC 9(4). which, when output as COBOL, will look like this:
02 THIRDPARYPRODUCTDETAILS01 PIC 9(4). whereas
02 THIRD-PARTY-PROD-DET-COUNT PIC 9(4). which, when output as COBOL, will look like this:
02 THIRD-PARTY-PROD-DET-COUNT PIC 9(4).
Refer to Element Name Considerations for more information.
Specifying an alternate data type
The WSDL2CDF utility generates alternate data types for the types contained in the WSDL depending on the language bias you specify with the -language command line parameter. For example, if the WSDL contains an element whose type is 'float' and you specify 'COBOL', WSDL2CDF sets the CDF element type="numeric", with size="19" and scale="6", since COBOL does not support floating-point data.
However, this default alternate type may not be appropriate for your application. You may wish to change the precision (size) or scale, or you may wish to specify a different type altogether, such as 'string':
The SOAPam Client Process receives interprocess messages from your application process and relays them to Web services that you have defined in a Client Definition File (CDF). When the Web service completes, its response is returned as a reply to the original interprocess message request. Refer to Creating and Editing the Client Definition File for more information about the CDF.
The SOAPam Client Process is started by running the SOAPAMCP program as a standalone Guardian process or by configuring the program as a Pathway server.
Running the Client Process as a Guardian Process
The general syntax for starting the client process from TACL as a standalone Guardian process is:
tacl> run SOAPAMCP / run-options / command-line-parameters
Example
The following example starts the Client Process nowaited, with a process name of $WSCP and a home terminal of $VHS, using the configuration options listed in a file named OPTIONS.
tacl> run SOAPAMCP / name $wscp, nowait, term $vhs / @options
Refer to the SOAPAMCP Command-Line Reference page for complete information about options for configuring the Client Process
Running the Client Process as a Pathway Server
The SOAPam Client Process may also be configured as a Pathway server. Potential advantages of running the Client Process as a Pathway server include process management and load balancing.
The configuration options are the same as those for standalone process configuration, however in the Pathway environment individual options are supplied as server PARAMs. The following is a sample pathway server configuration:
reset server set server cpus 0:1 set server createdelay 0 secs set server deletedelay 60 secs set server highpin on set server linkdepth 1 set server maxservers 6 set server maxlinks 20 set server numstatic 0 set server program soapamcp set server tmf on set server debug off set server param cdf "echocdf" set server param log "$0 event info" set server param tcpip "$zsam0" add server echo-service
You may also provide the options in a command file by setting the SERVER STARTUP value to @
Refer to the SOAPAMCP Command-Line Reference page for complete information about options for configuring the Client Process Generating IPM Definitions
Once you have created a Client Definition File, you can use it to create the interprocess message (IPM) definitions that your application will use to communicate with SOAPAMCP, and ultimately, the desired web service. Generating the IPM definitions is a two-step process: Generating DDL from a CDF
To generate DDL (Data Definition Language) from a CDF (Client Definition File), use the CDF2DDL uitlity. CDF2DDL is a command line application that you run from TACL:
tacl> run CDF2DDL -cdf bankcdf -ddl bankddl
Refer to the CDF2DDL Command Line Reference for complete details. Element Name Considerations
The CDF2DDL utility will change the name of the elements it outputs under certain conditions. The names will be changed in the following cases:
Web Service element names that are too long DDL object names are limited to 30 characters. If while converting a Web service element name to a DDL name, the resulting name is longer than 26 characters, the name will be truncated and a numeric sequence will be appended to the name. Web service element name is a host language reserved word If while converting a Web service element name to a DDL object name, the resulting name is the same as a host language reserved word, a 'Z' character is appended to the name. A child element has the same name as the parent element If a child element of a web service type has the same name as the type itself, the child element name is altered by appending a 'Z' character to the name
If any changes are made by the CDF2DDL utility, the changes are documented in the DDL source header. Sample documentation is shown below:
! ! The following object names were altered to conform to DDL name ! length restrictions. ! ! ThirdPartyProductDetailsItemCount -> ThirdPartyProductDetails01 ! ! ! The following object names were altered because they are reserved words ! in one or more host languages. ! ! page -> pagez ! mode -> modez ! type -> typez ! sort -> sortz ! Status -> Statusz ! return -> returnz ! author -> authorz ! ! ! The following child object names were altered because they were the ! same as their parent definition name. ! ! KeyPhrase -> KeyPhraseZ !
To provide a DDL-compatible name that won't require changing by CDF2DDL, specify the 'ddlName' attribute on the
produces this DDL:
02 ThirdPartyProductDetails01 PIC 9(4).
which, when output as COBOL, will look like this:
02 THIRDPARYPRODUCTDETAILS01 PIC 9(4). whereas
produces this DDL:
02 THIRD-PARTY-PROD-DET-COUNT PIC 9(4).
which, when output as COBOL, will look like this:
02 THIRD-PARTY-PROD-DET-COUNT PIC 9(4). Generating IPM Definitions from DDL
The NonStop Data Definition Language (DDL) Compiler is a utility that is included with your NonStop system. It compiles DDL definitions into a binary format which can be subsequently output in the syntax of various programming languages such as C, COBOL, TAL or TACL.
The CDF2DDL utility produces DDL definitions from your Client Definition File (CDF). The DDL definitions describe the interprocess messages (IPMs) that your application sends to SOAPAMCP in order to call a Web service method. You use the DDL compiler to translate the DDL definitions into source code that you'll compile into your application.
> DDL DDL Compiler T9100ABS - (30JUN00) SYSTEM \NODE COPYRIGHT TANDEM COMPUTERS INCORPORATED 1978, 1979, 1981, 1982, 1986-2000 !?DICT $MYVOL.MYSUBVOL Dictionary opened on subvol $MYVOL.MYSUBVOL for update access. !?COBOL mycopybk ! !?C myheader ! !?SOURCE ddldefs !exit
This example opens a COBOL source file, "mycopybk", and a C source file, "myheader", for output. The "?SOURCE" command simultaneously loads and compiles the definitions from the "ddldefs" file (the output from CDF2DDL), translates the definitions to COBOL and C and stores the output in the appropriate files.
Notes for SCOBOL Users
Note that if you are generating a source file for use in SCOBOL programs, you should set the COBOL74 option before generating the output. An example of the use of this option is shown below:
> DDL DDL Compiler T9100ABS - (30JUN00) SYSTEM \NODE COPYRIGHT TANDEM COMPUTERS INCORPORATED 1978, 1979, 1981, 1982, 1986-2000 !?DICT $MYVOL.MYSUBVOL Dictionary opened on subvol $MYVOL.MYSUBVOL for update access. !?SETCOBOL74 !?COBOL mycopybk ! !?SOURCE ddldefs !exit
Refer to the HP Data Definition Language (DDL) Reference Guide for more information about the DDL Compiler. Calling a Web Service Method
Once the SOAPAMCP process is configured and running, any NonStop application can access the associated Web service by sending the process a predefined IPM request and waiting for the response. Each IPM request contains a SOAPAMCP header which contains a 2 byte method code. The method code indicates which Web service method should be invoked by this IPM request. The remainder of the IPM consists of fields that correspond to the parameters of the selected Web service method.
Once the SOAPAMCP process invokes the Web service method it returns the response in an IPM. This response IPM also contains a standard SOAPAMCP header which contains a 2 byte response code. If the response code is zero, the remainder of the IPM consists of fields that correspond to the output parameters of the Web service method. If the response code is non-zero then the IPM is a standard SOAPAMCP error reply structure. Web Service Requests
In order to invoke a Web service method, the IPM must be formatted appropriately and sent to the SOAPam Client Process (SOAPAMCP) using whatever interprocess communications mechanism is appropriate (e.g. the "SEND" verb or WRITEREAD or SERVERCLASS_SEND_ Guardian System Procedures) for your application.
The format of Web service requests have a similar structure regardless of what service or method is being accessed. Every request IPM has the following header:
DEF soapam-rq-hdr. 02 message-code TYPE BINARY 16. 02 reserved TYPE CHARACTER 30. END.
The message-code element must be initialized with the message code value associated with the method you want to invoke. The reserved fiel d should be initialized to 0.
Arrays
When the WSDL2CDF utility creates a type definitions in the Client Definition File (CDF), it inserts a 'depends on' element for every array. Your application must set the 'depends on' element to the number of valid entries in the array.
Example
A COBOL example of an echo string service request is shown below. The echoString service is a SOAPam sample service that is available on the SOAPam demo server. WORKING-STORAGE.
01 MESSAGE-CODE-VALUES. 02 MC-ECHOSTRING NATIVE-2 VALUE 101.
01 RQ-ECHOSTRING. 02 SOAPAM-RQ-HDR. 03 MESSAGE-CODE NATIVE-2. 03 RESERVED PIC X(30). 02 ECHOSTRING. 03 INPUTSTRING PIC X(32).
01 RP-ECHOSTRING. 02 SOAPAM-RP-HDR. 03 REPLY-CODE NATIVE-2. 03 INFO-CODE NATIVE-2. 03 INFO-DETAIL NATIVE-2. 03 RESERVED PIC X(26). 02 ECHOSTRINGRESPONSE. 03 RETURNZ PIC X(32).
. . .
PROCEDURE-DIVISION.
MOVE LOW-VALUES TO SOAPAM-RQ-HDR OF RQ-ECHOSTRING. MOVE MC-ECHOSTRING TO MESSAGE-CODE OF RQ-ECHOSTRING. MOVE "Hello world!" TO INPUTSTRING OF RQ-ECHOSTRING.
SEND RQ-ECHOSTRING TO "ECHO-SERVICE" REPLY CODE 0,1 YIELDS RP-ECHOSTRING CODE OTHER YIELDS SOAPAM-REPLY.
IF REPLY-CODE OF SOAPAM-RP-HDR OF RP-ECHOSTRING = 0 DISPLAY RETURNZ OF RP-ECHOSTRING. Web Service Replies
The reply from the Client Process varies depending on whether or not the call to the Web service method was successful or not. If successful a method specific reply is returned. Success is indicated by value of 0 or 1 in the first 2 bytes of the header. Successful replies have a similar structure regardless of what service or method is being accessed. Every reply IPM has the following header structure:
DEF soapam-rp-hdr. 02 reply-code TYPE BINARY 16. 02 info-code TYPE BINARY 16. 02 info-detail TYPE BINARY 16. 02 reserved TYPE CHARACTER 26. END.
If the reply-code value contains 0 the request was successful and the web service reply data follows the header. If the reply-code contains the value 1, then the request was successful but info- fields contain information about issues that occurred during deserialization of the web service reply. The info-code may indicate that a string field was truncated because it was too long to fit in the reply structure or array elements were truncated because there were to many to fit in the reply structure. Should this occur, it is up to the application to determine how to proceed. If the reply-code contains the value 2, then an error occurred. In this case, the format of the reply as described by the soapam-reply structur e shown below:
DEF soapam-reply. 02 soapam-rp-hdr TYPE soapam-rp-hdr. 02 error-source TYPE soapam-error-source. 02 filler TYPE CHARACTER 2. 02 error-detail TYPE CHARACTER 4092. 02 soapam-error-detail REDEFINES error-detail. 03 error-code TYPE soapam-error-code. 03 error-description TYPE CHARACTER 512. 03 filler TYPE CHARACTER 3578. 02 tcpip-error-detail REDEFINES error-detail. 03 host-address TYPE CHARACTER 128. 03 error-number TYPE BINARY 16. 03 error-description TYPE CHARACTER 512. 03 filler TYPE CHARACTER 3450. 02 http-error-detail REDEFINES error-detail. 03 url TYPE CHARACTER 512. 03 status-code TYPE BINARY 16. 03 reason-phrase TYPE CHARACTER 512. 03 filler TYPE CHARACTER 3066. 02 ssl-error-detail REDEFINES error-detail. 03 url TYPE CHARACTER 512. 03 error-description TYPE CHARACTER 512. 03 error-number TYPE CHARACTER 16. 03 filler TYPE CHARACTER 3052. 02 soap-fault-detail REDEFINES error-detail. 03 faultcode TYPE CHARACTER 32. 03 faultsubcode TYPE CHARACTER 32. 03 faultreason TYPE CHARACTER 1024. 03 faultdetail TYPE CHARACTER 2048. 03 filler TYPE CHARACTER 956. END.
A COBOL example of an echo string reply processing is shown below. The echoString service is a SOAPam sample service that is available on the SOAPam demo server. WORKING-STORAGE.
01 MESSAGE-CODE-VALUES. 02 MC-ECHOSTRING NATIVE-2 VALUE 101.
01 RQ-ECHOSTRING. 02 SOAPAM-RQ-HDR. 03 MESSAGE-CODE NATIVE-2. 03 RESERVED PIC X(30). 02 ECHOSTRING. 03 INPUTSTRING PIC X(32).
01 RP-ECHOSTRING. 02 SOAPAM-RP-HDR. 03 REPLY-CODE NATIVE-2. 03 INFO-CODE NATIVE-2. 03 INFO-DETAIL NATIVE-2. 03 RESERVED PIC X(26). 02 ECHOSTRINGRESPONSE. 03 RETURNZ PIC X(32).
. . .
PROCEDURE-DIVISION.
MOVE LOW-VALUES TO SOAPAM-RQ-HDR OF RQ-ECHOSTRING. MOVE MC-ECHOSTRING TO MESSAGE-CODE OF RQ-ECHOSTRING. MOVE "Hello world!" TO INPUTSTRING OF RQ-ECHOSTRING.
SEND RQ-ECHOSTRING TO "ECHO-SERVICE" REPLY CODE 0,1 YIELDS RP-ECHOSTRING CODE OTHER YIELDS SOAPAM-REPLY.
IF REPLY-CODE OF SOAPAM-RP-HDR OF RP-ECHOSTRING = 0 DISPLAY RETURNZ OF RP-ECHOSTRING. WORKING-STORAGE.
01 MESSAGE-CODE-VALUES. 02 MC-ECHOSTRING NATIVE-2 VALUE 101.
01 RQ-ECHOSTRING. 02 SOAPAM-RQ-HDR. 03 MESSAGE-CODE NATIVE-2. 03 RESERVED PIC X(30). 02 ECHOSTRING. 03 INPUTSTRING PIC X(32).
01 RP-ECHOSTRING. 02 SOAPAM-RP-HDR. 03 REPLY-CODE NATIVE-2. 03 INFO-CODE NATIVE-2. 03 INFO-DETAIL NATIVE-2. 03 RESERVED PIC X(26). 02 ECHOSTRINGRESPONSE. 03 RETURNZ PIC X(32).
. . .
PROCEDURE-DIVISION.
MOVE LOW-VALUES TO SOAPAM-RQ-HDR OF RQ-ECHOSTRING. MOVE MC-ECHOSTRING TO MESSAGE-CODE OF RQ-ECHOSTRING. MOVE "Hello world!" TO INPUTSTRING OF RQ-ECHOSTRING.
SEND RQ-ECHOSTRING TO "ECHO-SERVICE" REPLY CODE 0,1 YIELDS RP-ECHOSTRING CODE OTHER YIELDS SOAPAM-REPLY.
IF REPLY-CODE OF SOAPAM-RP-HDR OF RP-ECHOSTRING = 0 DISPLAY RETURNZ OF RP-ECHOSTRING. Using the Stream Protocol
The request/response stream protocol may be used in those instances when the Web service you are accessing requires request and/or response IPMs that are larger then the IPM message size limit imposed by the Guardian file system. When streaming a request to the SOAPAMCP process, you indicate the length of the stream in the soapam_rq_hdr and then write the request to the process in sequential blocks of arbitrary size. The SOAPAMCP process can also stream the Web service response back to your application in the same fashion. Note that the DDL method of IPM generation cannot create IPM structures larger than 32,767 bytes, however, the CDF2C utility can be used to convert CDF definitions to C language IPM structures that exceed this limit.
IPMs generated with CDF2C have the following request and response header structures:
typedef struct __soapam_rq_hdr { short message_code; short request_timeout; unsigned long stream_length; short variable_reply; short reserved[11]; } soapam_rq_hdr_def;
typedef struct __soapam_rp_hdr { short reply_code; short info_code; short info_detail; unsigned long stream_length; short reserved[11]; } soapam_rp_hdr_def;
By setting the request header stream_length variable to a non-zero value you indicate your desire to use the streaming protocol for the Web service request and response. Set this value to the actual size of your request and write the message to the SOAPAMCP process in sequential blocks of arbitrary size. SOAPAMCP will not begin processing the Web service request until the number of bytes indicated by stream_length is received. When the response is returned, the SOAPAMCP process will return the length of the response stream in the response header stream_ length variable. Your application should issue a sufficient number of read operations to the SOAPAMCP process in order to read the entire response.
The variable_reply header field may be used to optimize the response from SOAPAMCP. Setting this field to a non-zero value causes SOAPAMCP to truncate the reply to the length of the actual response data. For example, a service reply IPM of 50K will require two response IPMs when using the stream protocol. However, if the service only returns 10K of data, processing the entire 50K response is inefficient. By setting the variable_reply request header field to non-zero will cause SOAPAMCP to truncate the response to 10K and return one response IPM. The truncated reply size will be reflected in the reply stream_length header field.
Note that if you are using Pathsend to communicate with the SOAPAMCP process you must initiate a Pathsend dialog with the SOAPAMCP server class to ensure that your requests and responses are routed to and from the same SOAPAMCP process instance. Refer to the TS/MP Pathsend and Server Programming Manual for more information on Pathsend dialog programming.
The SOAPam Client Sample Pack includes a sample C program, lmstest.c, which illustrates how to use the stream protocol with both Pathway and standalone instances of the SOAPAMCP process. The program communicates with a Web services that requires request and response IPMs which exceed 10K bytes. The Sample Pack can be found at the NuWave Software Download Center. Accessing Secure Web Services
SOAPam provides several different mechanisms to allow you to access Web services securely. Which mechanism you must use, if any, is dictated by Web service.
HTTP Authentication
The Client Process automatically negotiates HTTP Basic or Digest authentication with the Web service host using credentials you provide. Refer to Using HTTP Authentication for details.
Client Certificates
During secure connection negotiation, the Client Process can transmit a provided PKCS12 client certificate in order to identify itself to the Web service host. Refer to Using Client Certificates for details.
Secure Credentials Files
SOAPam can securely store user id and password information in encrypted credentials files that can only be decrypted by the Client Process. This eliminates the need to store credentials in clear text in the Client Process configuration. Refer to Using Credential Files for details.
Secure Connections
By specifying "https" as the protocol scheme for a Web service endpoint, the Client Process will negotiate a secure SSLv3 or TLS v1 connection with the Web service host and verify the host's server certificate against a local list of trusted Certificate Authorities. Refer to Using Secure Connections for details. Using HTTP Authentication
The SOAPam Client Process automatically negotiates HTTP Basic or Digest authentication when sending requests to the Web service host. You specify your authentication credentials using the -httpauth command line option when starting the Client Process. The credentials may be specified as userid:password in clear text or in an encrypted credentials file.
To specify the credentials as a clear text string use the following format for the -httpauth option:
tacl> run SOAPAMCP / name $wscp / -httpauth #userid:password
In order to provide the credentials in a SOAPam credentials file, first create the credentials file using the MAKECF utility:
tacl> run MAKECF mylogin userid:password
Then provide the credentials file name in the -httpauth option:
tacl> run SOAPAMCP / name $wscp / -cdf mycdf -httpauth mylogin
Refer to Using Credential Files for information about creating credentials files. Refer to Configuring the Client Process for more information about SOAPAMCP command line parameters. Using Client Certificates
During secure https connection (SSL/TLS) negotiation, the SOAPam Client Process can send a PKCS12 client certificate to the Web service host in order to authenticate itself. First, you must obtain a certificate file from the Web service provider and transfer it to your NonStop server as a binary file. To use the certificate, you specify the name of the certificate file using the -sslclientcert command line option when starting the Client Process.
It is common practice for the Web service provider to associate a pass phrase with the certificate. You must know the pass phrase in order to use the certificate. The pass phrase also can be specified using the -sslclientcert command line option. The pass phrase can be specified in clear text or in an encrypted credentials file.
To specify the pass phrase as a clear text string use the following format for the -sslclientcert option:
tacl> run SOAPAMCP / name $wscp / -cdf mycdf -sslclientcert mypkcs #my^pass^phrase
where 'mypkcs' is the certificate file name and 'my^pass^phrase' is the pass phrase. In order to provide the pass phrase in a SOAPam credentials file, first create the credentials file using the MAKECF utility:
tacl> run MAKECF mycreds my^pass^phrase
Then provide the credentials file name in the -sslclientcert option:
tacl> run SOAPAMCP / name $wscp / -cdf mycdf -sslclientcert mypkcs mycreds
Refer to Using Credential Files for information about creating credentials files. Refer to Configuring the Client Process for more information about SOAPAMCP command line parameters. Using Credential Files
Some Web services may require clients to authenticate themselves before allowing access to the service. The authentication process uses credentials. There are two types of credentials supported by SOAPam:
a userid and password used for HTTP authentication a pass phrase associated with a PKCS12 certificate used for SSL client authentication
The type of authentication required, if any, is dependent on the Web service. If authentication is required, you must supply your credentials to the SOAPam Client Process to use on your behalf .
SOAPam provides a mechanism for storing your credentials in an encrypted format. Rather then specifying your credentials in clear text as a command line parameter whenever starting SOAPAMCP, you can specify the name of an encrypted credentials file. The encrypted credential information can then be used by the SOAP/CM Client Process for authentication to servers when necessary.
SOAPam credentials files are created using the MAKECF utility. Refer to Using the MAKECF Utility for more information. You can create as many SOAPam credentials files as necessary, since different Web services may require different credentials.
This example stores the userid 'myuserid' and password 'mypassword' in the encrypted credentials file "mylogin", then supplies the credentials filename with the -httpauth command line parameter when starting SOAPAMCP.
tacl> run MAKECF mylogin myuserid:mypassword tacl> run SOAPAMCP / name $WSCP / -httpauth mylogin @otheropts
The second example stores the pass phrase in the encrypted credentials file "certpass". (Since the pass phrase was not supplied on the command line, MAKECF prompts for the information, but does not echo it.)
tacl> run MAKECF certpass tacl> run SOAPAMCP / name $WSCP / -sslclientcert mypkcs certpass @otheropts
Note that the credentials file is location dependent, i.e., if the file is moved or renamed, the credentials cannot be decrypted. This feature is designed to disable the credentials in case the file is stolen or otherwise used inappropriately. Even though credentials become invalid when moved, system administrators should still use Guardian security to prevent unauthorized access to the contents of the file.
This example verifies the contents of the credentials file and that it is located in the correct subvolume
tacl> run MAKECF certpass -verify
Refer to Using HTTP Authentication for more information about HTTP authentication. Refer to Using Client Certificates for more information about SSL client authentication. Using the MAKECF Utility
The MAKECF utility creates SOAPam credentials files. Refer to Using Credential Files for more information about credentials files.
tacl> run MAKECF
or
tacl> run MAKECF
Refer to MAKECF for complete details on the MAKECF utility.
Using Secure Connections
The SOAPam Client Process can establish a secure SSL or TLS connection with a Web service host. In order to request a secure connection you must specify the https protocol scheme when specifying the service location attribute in the binding element of the CDF file. For example:
The Client Process will negotiate an SSL v3 or TLS v1 connection using the strongest cipher suite common to both the client and server platforms. Note that because of known vulnerabilities inherent in the SSL v2 protocol, the Client Process will not attempt to negotiate an SSL v2 connection by default. If your Web service host requires an SSL v2 connection you must specify the -sslallowv2 command line option when starting the Client Process.
During the connection negotiation process, the Client Process will verify the server certificate against a list of trusted Certificate Authorities. By default, this list is contained in the CAROOT file which is included with the product. The file contains a list of PEM-encoded certificates of trusted root Certificate Authorities. You can override the default file name using the -sslcarootfile command line parameter when starting the Client Process.
You may also create a list of local certificate authorities by creating an edit file named CALOCAL that contains a list of PEM-encoded certificates of local certificate authorities and storing the file in the Client Process installation subvolume. You can override the default file name using the -sslcalocalfile command line parameter when starting the Client Process.
Occasionally you may not want the Client Process to verify the server certificate. This is often the case when you are testing against a development Web service host that has a certificate that was not issued by a trusted certificate authority. If this case you may use the -sslnoverify command line parameter when starting the Client Process to indicate that you do not want the server certificate verified.
Refer to Configuring the Client Process for more information about starting the Client Process and using command line parameters. Using W-S Security and WS-Addressing
SOAPam Client provides limited support for the WS-Addressing and WS-Security standards. This support includes:
WS-Security
Automatic generation of the Security header which can include the following elements:
UsernameToken BinarySecurityToken (X509 only) Signature
WS-Addressing
Automatic generation of the following WS-Addressing elements:
To Action
Automatic generation of the WS-Security and WS-Addressing fields is controlled by the definition of a "policy" file which allows the generation to be controlled without altering the contents of the Client Definition File (CDF). The policy file is an XML file which consists of definitions of each Web service method that requires the addition of WS-Security and/or WS-Addressing headers and how those headers should be applied. The policy file location is passed to the SOAPAMCP process using the -wssepolicy option. A sample policy file for the SOAPam EchoString service is shown below:
This policy file consists of
All methods should contain the following headers on request messages:
A WS-Addressing To header with the value "http://soapam.nuwave-tech.com/services/echostring/echostring" A WS-Security header with a UsernameToken element. The userid and password are obtained from the -wsseauth startup option. A WS-Security header with a BinarySecurityToken element. The certificate is obtained from the -sslclientcert startup option. A WS-Security header with a Signature element.
All methods should contain the following headers on response messages:
A WS-Security hedaer with a Signature element. The Signature will be validated against the reply message.
The echoString method should contain the following header on request messages:
A WS-Addressing Action header with the value "echoString". Client Definition File Reference
A SOAPam Client Definition File (CDF) is an instance of an XML document that describes a Web service, its methods and their parameters, and the types on which the parameters are based. A CDF is a standard "edit" file (type 101). Typically, it is initially created using the WSDL2CDF utility. Usually, it then must be edited manually to specify fixed lengths for any string-type elements or unbounded arrays copied from the WSDL. Schema Reference
This section describes the content of the CDF.The XML schema for the CDF is located at http://www.nuwave-tech.com/schemas/soapam/cdf/cdf. xsd . If you have an XML-aware editor such as XMLSpy, the schema may be helpful in creating and/or validating your CDFs.
Below is an outline of a Client Definition File. Click the element name for detailed information.
The bracketed notation indicates the minimum and maximum number of occurrences [minOccurs:maxOccurs] for the element. [1] indicates the element must occur exactly once. indicates that maxOccurs is unbounded.
This element describes the endpoint and protocol details for the target web service.
parents service
children none
Attributes
Attribute Data Type Usage Default Description Value
location xsd:anyURI required The URL of the target Web service endpoint.
protocol xsd:NCName optional httpSoap11 The protocol to use when sending messages to the Web service provider. Currently the only supported protocol is HTTP POST using the SOAP 1.1 protocol.
elementThis element describes the attributes of the SOAP envelope body and is a container for one or more part elements.
parents soapMessage
children part[1:]
Attributes
Attribute Data Type Usage Default Description Value
wrapper xsd:NCName optional Indicates the name of the element that encapsulates the part elements, if any.
use xsd:token optional literal Indicates the default format for the part elements. If literal is specified, the part elements are formatted exactly as specified by the associated type. If encoded is specified, the part elements are formatted using SOAP Section 5 encoding rules.
This is the root element of the CDF document. Children must appear in the order shown.
parents none; this is the root element
children types[1] service[1]
Attributes
None
This element represents an element of a
parents type
children none
Attributes
Attribute Data Type Usage Default Description Value
name xsd:NCName required The name of the element. It must be unique within the parent
type xsd:NCName required The data type of the element. Must be one of the built-in types or the name of another
cdataWrapper xsd:NCName optional If non-zero, the element content is wrapped in a CDATA section on serialization and upon deserialization, any CDATA sections are removed.
ddlName xsd:NCName optional Alternate identifier to be used for the name of this element by the CDF2DDL utility when generating DDL. By default, CDF2DDL uses the value of the 'name' attribute as the corresponding DDL element name, but truncates or suffixes the name if it would violate DDL naming rules. Use this attribute to provide a DDL-compatible name.
dependsOn xsd:NCName optional If maxOccurs is greater than 1, the name of an element (contained within the same
ignore xsd:positiveInteger optional 0 Indicates whether or not the element is serialize/deserialized. Typically used on elements serving as the 'dependsOn' for an array. If the value of this attribute is 0, the element is assumed to be included in the SOAP envelope. If non-zero, the element will not be included in the SOAP envelope.
minOccurs xsd:positiveInteger optional 1 If the element represents an array, the minimum number of occurrences.
maxOccurs xsd:positiveInteger optional 1 If the element represents an array, the maximum number of occurrences.
offset xsd:nonNegativeInteger optional The position of this element relative to the start of the containing
size xsd:positiveInteger optional The storage size for the element. If omitted, the default size for the type is assumed.
stringPadding xsd:token optional inherited Specifies how SOAPam should treat string values it receives from, and returns to, client from parent applications when serializing and deserializing SOAP messages. Valid values are "zeros"
whitespace xsd:NCName optional preserve Causes an xml:space="default|preserve" attribute to be added to the element. Valid values are "default" and "preserve".
xsdType xsd:NCName optional Indicates an alternate, standard XML schema type that should be used when serializing/deserializing this element to/from the SOAP envelope. If omitted, the SOAP envelope type is determined by the standard NSK/XSD type translation. A list of standard type translations can be found in built-in types.
encoding xsd:NCName optional ISO-8859-1 Indicates an character encoding that should be used when serializing/deserializing this element to/from the SOAP envelope. If omitted, the default encoding is ISO-8859-1. A list of available encoding names can be found in Character Encoding Names.
Remarks
To override the default name generation behavior of CDF2DDL, use the ddlName attribute.
To override the default data type translation behavior, modify the type attribute to the desired type name and set the xsdType to the type name that the Web service expects (what WSDL2CDF originally generated for the type attribute).
The stringPadding attribute specifies how SOAPam should treat string values it receives from, and returns to, client applications when serializing and deserializing SOAP messages. When stringPadding="spaces", SOAPam will remove trailing spaces from the value before sending to the target web service. Likewise, it will space pad a string value returned the web service before replying to the client application. The "spaces" setting is typically used for client applications written in COBOL. When stringPadding="zeros", SOAPam will treat the value as a null-terminated string. The "zeros" setting is typically used for client applications written in C. Set stringPadding on the parent
This element defines a SOAP header that is included in the SOAP envelope. The header's content is mapped to an element of the server request or response type.
parents soapMessage
children none
Attributes
Attribute Data Type Usage Default Description Value
name xsd:NCName required The name of the element.
element xsd:NCName required A reference to an element in the
namespace xsd:anyURI optional The namespace of the element. If omitted, the namespace of the element referenced by the element attribute is used.
use xsd:token optional literal Indicates the default format for the part elements. If literal is specified, the part elements are formatted exactly as specified by the associated type. If encoded is specified, the part elements are formatted using SOAP Section 5 encoding rules.
This element is a container for the request and response elements. This element and its children represent a SOAP request/response pair.
parents messages
children request[1] response[1]
Attributes
attribute data usage default description name type value
messageCode xsd:integer required The message code used to invoke this SOAP request/response. It must be unique within the parent
This element is a container for one or more message elements.
parents service
children message[1:]
Attributes
None
This element defines a message part included in the SOAP body. The part's content is mapped to an element of the server request or response type.
parents body
children none
Attributes
Attribute Data Type Usage Default Description Value
element xsd:NCName required A reference to an element in the
namespace xsd:anyURI optional The namespace of the element. If omitted, the namespace of the element referenced by the element attribute is used.
use xsd:token optional literal Indicates the default format for the part elements. If literal is specified, the part elements are formatted exactly as specified by the associated type. If encoded is specified, the part elements are formatted using SOAP Section 5 encoding rules.
This element identifies the server request interprocess message and its type. Children must appear in the order shown.
parents message
children soapMessage[0:1]
Attributes
Attribute Data Type Usage Default Value Description
type xsd:NCName required The name of a
This element identifies the server request interprocess message and its type.Children must appear in the order shown.
parents message
children soapMessage[0:1]
Attributes
Attribute Data Type Usage Default Value Description
type xsd:NCName required The name of a
This element defines a Web service.Children must appear in the order shown.
parents definitions
children binding[1] messages[1]
Attributes
Attribute Data Type Usage Default Value Description
name xsd:NCName required The name of the service.
namespace xsd:anyURI required The namespace of the target service.
This element defines a SOAP message.Children must appear in the order shown.
parents request response
children header[0:] body[1]
Attributes
Attribute Data Usage Default Description Type Value
soapAction xsd:anyURI optional empty The value of the SOAPAction header for this SOAP message. This element is ignored unless the string soapMessage is a child of the
style xsd:token optional document The style of this soap message, which may be either "document" or "rpc". If omitted, "document" is used.
This element describes a "type". It is a container for one or more
parents types
children element[1:]
Attributes
Attribute Data Type Usage Default Value Description
name xsd:NCName required The type name. Must be unique within
size xsd:positiveInteger optional The number of bytes that the type represents. If omitted, the size will be calculated based on the aggregate size of the child elements.
stringPadding xsd:token optional inherited from parent The default string padding specification for all child
This element is a container for one or more type elements.
parents definitions
children type[1:]
Attributes
Attribute Data Usage Default Description Type Value
stringPadding xsd:token optional zeros The default string padding specification for all child
namespace xsd:anyURI optional The default namespace for child
Simple Types
SOAPam supports the following CDF / XSD type translations.
CDF Type Default SDF Length XSD Type
int 4 int
short 2 short
long 4 int
longlong 8 long
byte 1 byte
unsignedInt 4 unsignedInt
unsignedShort 2 unsignedShort
unsignedLong 4 unsignedInt
unsignedByte 1 unsignedByte
float 4 float
double 8 double
string no default string
numeric 18 decimal
unsignedNumeric 18 decimal
decimal 18 decimal
juliantimestamp1 8 dateTime
dateTime1 8 dateTime
date1 8 date
timestamp2 6 dateTime
base64Binary no default base64Binary
hexBinary no default hexBinary
boolean3 4 boolean
1Contains 64 bit JULIANTIMESTAMP value.
2Contains 48 bit TIMESTAMP value.
3Will be serialized as "0" for false or "1" for true. Deserializer accepts "0", "1", "true", or "false". Character Encodings
SOAPam uses IBM International Components for Unicode (ICU) to provide string translation services when deserializing and serializing Web service requests and responses. ICU allows the character encoding name to be specified using one of the various standard encoding names in addition to a number of aliases. An abridged list of available character encoding names appears below. To see a complete list of available encoding names visit the ICU Web site or the ICU Converter Explorer.
Encoding Names
ISO-8859-1 ISO-8859-2 ISO-8859-3 ISO-8859-4 ISO-8859-5 ISO-8859-6 ISO-8859-7 ISO-8859-8 ISO-8859-9 ISO-8859-13 ISO-8859-14 ISO-8859-15 Command Line Reference
The Command Line Reference describes all startup options for the programs supplied with the SOAPam Client release.
Refer to the following sections for more information: CDF2DDL
CDF2DDL generates a Data Definition Language (DDL) file from a Client Definition File (CDF). The DDL file contains interprocess message definitions that correspond to each of the Web service methods defined in the CDF. In turn, you will use the NonStop DDL Compiler to generate language-specific "copybooks" or "include" files that you can incorporate into the application that will call the Web service method.
You run CDF2DDL from TACL. The general syntax to run the CDF2DDL utility is:
tacl> run CDF2DDL / run-options / [ command-line-parameters ]
run-options
The standard TACL run options. command-line-parameters
@
Reads command line parameters from
-cdf
The Guardian file name of an existing Client Definition File. This parameter is required.
-ddl
The name of a new or existing DDL source file to be created or replaced. If the file already exists, specify the '!' option to indicate that the existing file should be overwritten. This parameter is required.
-help
Displays documentation for the program command line options.
Remarks
If multiple occurrences of the same command line parameter are encountered, the last occurrence is used.
CDF2DDL may change the names of some elements as it generates output in order to comply with DDL naming rules. Refer to Element Name Considerations for more information.
It is possible that CDF2DDL may produce a DDL definition that represents a structure larger than 32,767 bytes (the maximum size of an interprocess message). In this case, the DDL compiler won't be able to process the definition. To avoid this situation, edit your CDF and reduce the bounds of arrays or strings that comprise the offending definition and rerun CDF2DDL. Refer to Editing the Client Definition File for more information.
Examples
tacl> run CDF2DDL –cdf echocdf -ddl echoddl MAKECF
The MAKECF utilitycreates SOAPam credentials files. Refer to Using Credential Files for more information about credentials files.
This section describes how to use the MAKECF utility.
tacl> run MAKECF
tacl> run MAKECF
The name of the credentials file to be created. Use the "!" character to specify that the file should be overwritten if it already exists.
By default, MAKECF creates credentials files that are only valid in the location specified by
The credentials string to be encrypted and stored; either a userid:password or pass phrase.
The name of an input file containing the credentials string to be encrypted and stored; either a userid:password or pass phrase.
If both
Remarks
If you do not pass the credentials string on the command line, MAKECF will prompt for the information. The advantage to this usage is that your credentials are not echoed to the screen as you type, preventing any onlookers from reading your private security information.
The credentials file is location dependent, i.e., if the file is moved or renamed, the credentials cannot be decrypted. This feature is designed to disable the credentials in case the file is stolen or otherwise used inappropriately. Even though credentials become invalid when moved, system administrators should still use Guardian security to prevent unauthorized access to the contents of the file.
If you want to verify that a credentials file is a valid credentials file and also that the credentials file is in the subvolume that the credentials file expects to be in, use the -verify option.
Examples
> run MAKECF ! mylogin userid:password
> run MAKECF ! mylogin +clrtext
> run MAKECF certpass Enter the credentials string: Re-enter the credentials string:
This command creates a credentials file "cfile" that won't be valid until it has been moved to \sys2.$data.mysubvol.cfile2 tacl> run MAKECF cfile myuser:mypass -targetfilename \sys2.$data.mysubvol.cfile2
This command inspects the credentials file "cfile" to check the integrity of the credentials and also that "cfile" is located in the correct subvolume
tacl> run MAKECF cfile -verify SOAPAMCP
SOAPAMCP is the SOAPam Client Process, which is responsible for relaying messages between a client application and a web service based on the contents of a Client Definition File (CDF).The SOAPam Client Process is started by running the SOAPAMCP program from TACL or by configuring the program as a Pathway server. This section describes how to start the program from TACL. See Running the Client Process for information about Pathway configuration.
tacl > run SOAPAMCP / run-options / command-line-parameters
The "-cdf" command-line parameter is required. All others are optional.
You should be logged-on as a user with sufficient privileges to access the system resources that the process requires. run-options
The standard TACL run options. Note that process does not open the IN or OUT file; diagnostic output is sent to the location specified by the 'log' parameter described below. command-line-parameters
@
Reads command line parameters from
-authheader
Specifies an application specific authentication header. When this option is specified, each request will include the specified HTTP header name and and associated credentials. Note that this is an application specific header and is not related to standard HTTP authentication.
-cdf
The name of an existing Client Definition File to be processed by this instance of process. This parameter is required.
-doc
Display a sample request and response for the specified method. Note that the SOAPAMCP process will exit after displaying the samples.
-enabletcpkeepalive
Indicates that the TCP/IP socket keep alive option should be enabled when a socket connection is established. By default the keep alive option is disabled. Specifying this option will enable keep alives using the timeout settings configured for the TCP/IP process. For a detailed explanation of TCP/IP keep alive processing, see RFC 1122.
-disablehttpkeepalive
Indicates that HTTP 1.1 persistent connections should be disabled. By default, socket connections are kept open between requests to the SOAP server. Specifying this option will disable persistent connections and cause the socket connection to close after each request to the SOAP server. For a detailed explanation of HTTP persistent connections, see RFC 2616.
-help
Displays documentation for the program command line options.
-httpauth { #
The credentials required for the HTTP connection to the Web service host when HTTP Basic or Digest authentication is required. Specify either your userid and password (in plain text) or the name of an existing SOAPam credentials file containing the encrypted userid and password.
-httpkeepalivetimeout
The number of seconds to keep an HTTP 1.1 persistent connection open when idle. The omitted, the default value of 60 seconds is used.
-httppreauth
Indicates that pre-authentication should be used for HTTP authentication. This causes Basic authentication credentials to be sent with every request, without waiting for a HTTP 401 response. Use of this option can improve performance on connections that use HTTP Basic authentication but has serious security implications for connections that are not meant to use HTTP Basic authentication. This option should not be used unless the security implications are fully understood.
-httpproxy
The address and port of an HTTP proxy that should be used for HTTP connections. If omitted, no proxy is used. If the port value is omitted, port 80 is used.
-httpproxyauth { #
The credentials required for authentication with the HTTP proxy. Specify either your userid and password (in plain text) or the name of an existing SOAPam credentials file containing the encrypted userid and password.
-httprequesttimeout
The number of seconds to wait for a SOAP request/response exchange to complete. If omitted, the default value of 180 seconds is used. If '!' is specified, this value will override any value set by the client application in the request_timeout field of the SOAPam request header. Note that if '!' is not specified, and the client application specifies a timeout value in the request_timeout field of the SOAPam request header, the value in the request_timeout field is used..
-ignoreclose
Specifying this option causes the process to ignore close messages. In order to function properly in the Pathway environment, the SOAPAMCP process, by default, matches open and close messages and terminates when all clients have close the process. This option can be used to prevent the process from terminating when it is run as a standalone process.
-licensefile
The name of an existing edit file containing the SOAPam product license. If this option is omitted, the file named LICENSE in the client process program subvolume is used.
-licensekey
The SOAPam product license key. If this option is omitted the value of the -licensefile option is used.
-location
The URL of the target web service. If this option is specified, it will override the value of the location attribute in the
-log {
Specifies the process log location, the log event format, and the log level. The destination value may be a process name, a file name, or the asterisk (*) character. If the asterisk is used then the log output is directed to the home term of the process. The format value may be "text" indicating that the log events should be output as text strings or "event" indicating that the log events should be output in EMS event format. The level value may be "error", "warning", "info", or "trace" and controls the type of information that is output to the log destination. The "error" level produces the least output while the "trace" level produces the most output. If omitted, the default is "-log $0 event warning".
-logcfg
Specifies the log configuration file name. If this option is omitted then no log configuration file is used. Refer to Log Configuration for details.
-messagedump < [soap] [raw] [ipm] >
When specified the web service request and reply messages are dumped to a file. The options SOAP, RAW, and IPM options produce the following output:
SOAP The request/response SOAP envelopes formatted for display.
RAW The request/response SOAP envelopes in hex dump format.
IPM The request/response IPMs in hex dump format.
HTTP HTTP protocol information
BASIC Basic information including only the dump header.
The SOAP and RAW options also produce network connection and HTTP header information. A new dump file is created for each request and has the name format DUnnnnnn where nnnnnn is a sequence number. This option is for diagnostic purposes and seriously degrades performance. This option should never be used in a production environment.
-messagedumpcfg
Specifies the messagedump configuration file name. If this option is omitted then no messagedump configuration file is used. Refer to Me ssage Dump Configuration for details. -messagedumpfile < filename >
When specified the messagedump information will be dumped to the specified file instead of individual sequenced files.
-messagedumpfiletype < E | U >
Specifies the messagedump file type. This option must be either E or U to indicate an Edit or Unstructured file.
-messagedumpfilter < reply code range >
When specified the messagedump information will only be dumped when the IPM response reply code is in the specified range. The range is specified as a comma-separated list of values or value ranges. Value ranges are specified with a min value and max value separated by a colon (:). For example, to dump only messages that have a reply code of 1 or 2 the reply code range may be specified as "1,2" or "1:2".
-messagedumpsubvol < subvol >
When specified the messagedump files will be created in the specified subvol. If not specified the messagedump files are written to the current subvol of the SOAPAMCP process.
-pathmonpattern
The file name pattern to be used for determining the Pathmon process name for statistics collection. Note that the file name pattern must be fully qualified, including the node name, vol, subvol, and file. If this option is omitted, the pattern "\*.$*.*.*pathmon*" is used. Refer to D etermination of the Pathmon Process Name for more information.
-resolveonconnect
Causes SOAPAMCP to resolve the DNS name of the target server on each connection attempt. Use this option in the case where the web service is behind a load balancer which is using a round robin balancing scheme.
Note that this option should be used with caution. Because NonStop TCP/IP does not provide non-blocking name resolution services, SOAPAMCP will stop processing requests while resolving the host name. If the DNS is slow, this processing delay may be unacceptable.
-sslallowv2
This option indicates that the Client Process should enable SSL v2 connections. Note that because of known flaws inherent in the v2 specification, you should not enable this option unless it is required by your Web service host.
-sslclientcert
The client certificate to use for the SSL connection. Specify the name of the file and, if required, the associated pass phrase required to access the certificate. Specify the pass phrase, in plain text, or the name of an existing SOAPam credentials file containing the encrypted pass phrase.
-sslcarootfile
The name of the file containing the certificates of all trusted root certificate authorities. If omitted, this value defaults the CAROOT file that is provided with the SOAPam software.
-sslcalocalfile
The name of a file containing the certificates of local trusted certificate authorities. If omitted, no local CA certificates are loaded.
-sslnoverify
This option indicates that the Client Process should not validate the server certificate for common name, expiration date, or issuer when an SSL connection is established. Note that this option should only be used in a development/test environment where the server may not necessarily pass all of the verification criteria. It should not be used in a production environment.
-statscfg
Specifies the stats configuration file name. If this option is omitted then no stats configuration file is used and statistics are not collected. Refer to Statistics Configuration for details.
-switchontimeout
If this option is specified, and the -tcpipalt option is also specified, the process will switch to the alternate TCPIP process when
-tcpip
Specifies the name of the TCPIP process that the process should use. It can represent a standard TCPIP process or a Parallel Library Socket Access Method (TCPSAM) process. If omitted, the value of the =TCPIP^PROCESS^NAME MAP define is used.
-tcpipalt
Specifies the name of an alternate TCPIP process to use in the event that the process specified by the -tcpip option fails or loses network connectivity. If omitted, no backup process is used.
-wsseauth { #
The credentials required for the WS-Security UsernameToken header. Specify either your userid and password (in plain text) or the name of an existing SOAPam credentials file containing the encrypted userid and password.
-wssecert
The certificate to use for the WS-Security BinarySecurityToken header. Specify the name of the file and, if required, the associated pass phrase required to access the certificate. Specify the pass phrase, in plain text, or the name of an existing SOAPam credentials file containing the encrypted pass phrase.
Note: Prior to release 3.0, this value was specified using the -sslclientcert option. The -sslclientcert option may still be used for this purpose, however, the -wssecert option allows different certificates to be used for the SSL connection and BinarySecurityToken.
-wssepolicy
The name of the file containing the Web services extensions policy definition.
Determination of the Pathmon Process Name
SOAPAMCP determines if is running as a Pathway serverclass by examining the program file name of its ancestor process. The Guardian FILENAME_MATCH_ procedure is used to match the ancestor program file name with the default pattern "\*$*.*.*pathmon*". If the pattern matches, then SOAPAMCP assumes it is running as a serverclass and its ancestor is a Pathmon process. In some cases, such as when a copy of the PATHMON program file is used to run the Pathmon process, the default pattern won't match and SOAPAMCP will assume it is running as a standalone process. In these cases, the -pathmonpattern option can be used to override the default pattern. Refer to the documentation for the FILENAME_MATCH_ procedure in the Guardian Procedure Calls Reference Manual for information on the pattern syntax.
Remarks
All command-line parameter names and values are case-insensitive except where noted. If multiple occurrences of the same command line parameter are encountered, the setting of the last occurrence is used.
Each SOAPAMCP process supports exactly one CDF. Each CDF supports exactly one Web service (though having many methods, perhaps). Therefore, a separate SOAPAMCP process (or serverclass) must be configured for each Web service that applications on your system want to access.
When the -log option format is set to event, EMS events will be sent to the output device with the following EMS Subsys ID:
Z-OWNER "NUWAVE"
Z-NUMBER 2
Z-VERSION 3
Examples
tacl> run SOAPAMCP / name $wscp, nowait, term $vhs, cpu 0 / -cdf echocdf -log $0 event info
tacl> run SOAPAMCP / name $wscp, nowait, term $vhs / @options
tacl> run SOAPAMCP / name $wscp, nowait, term $vhs / -cdf echocdf -httpproxy myproxy STATSCON
The STATSCON utilityconsolidates one or more statistics files into a single file with only the most recent statistics records for each request.The output file can be created in the standard client or server statistics record format or as a CSV file.
The general syntax to start the STATSCON program from TACL is
tacl> run STATSCON / run-options / [ command-line-parameters ]
run-options
The standard TACL run options. command-line-parameters
-infile
An input file specification that selects the input statistics file or files. The specification can contain wildcard characters to allow the selection of multiple files. This parameter is required.
-outfile
The consolidated output file name. If the file already exists, specify the '!' option to indicate that the existing file should be overwritten. This parameter is required.
-outformat < record | CSV >
The desired output format. This parameter is optional and if not specified, "record" is the default.
-help
Displays documentation for the program command line options.
Remarks
If the input specification selects both client and server statistics files an error will be returned.
Examples
tacl> run STATSCON –infile zzsstats -outfile statsout !
tacl> run STATSCON -infile zzsst* -outfile sstats ! -outformat csv WSDL2CDF
The WSDL2CDF utilitycreates a Client Definition File (CDF) by reading the Web Service Description Language (WSDL) file that describes the target Web service and augmenting it with mapping information.The Client Definition File (CDF) contains all of the information needed by the SOAPAMCP process to map a request IPM to a Web service request and map the Web service response back to an reply IPM. Some minor manual tuning of the generated CDF may be required, however. See Editing the Client Definition File for more information.
This section describes how to start the WSDL2CDF program from TACL.
tacl> run WSDL2CDF / run-options / command-line-parameters
The "-wsdl" and "-cdf" command-line parameters are required. All others are optional. run-options
The standard TACL run options. command-line-parameters
@
Reads command line parameters from
-wsdl
The URL or file name of a WSDL file. This parameter is required. If the name begins with "http:" or "https:", it is assumed to be a URL. Otherwise, it is assumed to be a Guardian filename. For URLs, case is preserved. Note that some http servers treat URLs as case sensitive. This parameter is required.
-cdf
The Guardian filename of the Client Definition File to be created. If the file already exists, specify the '!' option to indicate that the file should be overwritten, or specify the '+' option to indicate that you want to merge the result of this session into the existing CDF. This parameter is required.
-help
Displays documentation for the program command line options.
-httpauth { #
The credentials required for the HTTP connection to the Web service host when HTTP Basic or Digest authentication is required. Specify either your userid and password (in plain text) or the name of an existing SOAPam credentials file containing the encrypted userid and password. Refer to Using Credentials Files for additional information.
-httpproxy
The URL or IP address and port of an HTTP proxy that should be used for HTTP connections. If omitted, no proxy is used. If the port value is omitted, port 80 is used.
-httpproxyauth { #
The credentials required for authentication with the HTTP proxy. Specify either your userid and password (in plain text) or the name of an existing SOAPam credentials file containing the encrypted userid and password.
-importtypes
If this parameter is specified, and the WSDL is located on an instance of SOAPam™ Server, the utility will attempt to import types and their attributes from the associated Service Definition File. See Remarks, below.
-language { COBOL | COBOL74 | C | TAL | TACL }
The language bias that should be used when generating the CDF. If omitted, "C" is assumed. For Screen COBOL clients, use the "COBOL74" option.
-maxoccurs
The default 'occurs' count to be used for unbounded arrays. If omitted, 2 is used.
-methods
-sslallowv2
This option indicates that the Client Process should enable SSL v2 connections. Note that because of known flaws with the v2 implementation, you should not enable this option unless it is required by your Web service host.
-sslnoverify
This option indicates that the Client Process should not validate the server certificate for common name, expiration date, or issuer when an SSL connection is established. Note that this option should only be used in a development/test environment where the server may not necessarily pass all of the verification criteria. It should not be used in a production environment.
-stringsize
The size to be used for strings that have do not have a specified length in the WSDL. If omitted, 32 is used.
-tcpip
Specifies the name of the TCPIP process that the process should use if the WSDL file is specified as a URL. It can represent a standard TCPIP process or a Parallel Library Socket Access Method (TCPSAM) process. If omitted, the value of the =TCPIP^PROCESS^NAME define is used.
Remarks
All command-line parameter names and values are case-insensitive except where noted. If multiple occurrences of the same command line parameter are encountered, the setting of the last occurrence is used.
By default, the WSDL2CDF utility sets all the sizes of all string elements that it copies from the WSDL to a default value. However, if the Web service is implemented with SOAPam Server, WSDL2CDF can read the Service Definition File (SDF) associated with the WSDL to determine the actual string sizes. Use the "-importtypes" command-line parameter to invoke this feature.
Examples
tacl> run WSDL2CDF –wsdl http://soapam.nuwave-tech.com/services/bankdemo/bankdemo2.wsdl -cdf bankcdf
tacl> run WSDL2CDF –wsdl http://soapam.nuwave-tech.com/services/bankdemo/bankdemo2.wsdl -cdf bankcdf ! -language cobol Glossary
| A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z |
A authentication
The process through which an http server verifies the identity of its client.
C
CDF
see Client Definition File
CDF2DDL
The CDF-to-DDL utility, a component of SOAPam Client. It creates DDL source that describes the interprocess messages that a client application uses to call a Web service via the SOAPam Client Process.
Client Definition File
CDF; an XML-based document used to describe a Web service. It contains information that tells the SOAPam Client Process how to map an interprocess message received from a client application to a Web service method call. A CDF is created by the WSDL2CDF utility and is read by the CDF2DDL utility to produce a DDL definition that describes the interprocess message.
Control Panel
A component of SOAPam Server; the browser-based application that lets you manage the SOAPam Server environment.
D
Data Definition Language
NonStop Server product that defines a language for describing structured data. It includes a compiler for the language and repositories ("dictionaries") in which to store the compiled descriptions.
DDL
see Data Definition Language deserialization
The process through which SOAPam converts an XML-formatted SOAP request into a server request interprocess message. See also serialization.
G
Guardian
One of the two operating environments ("personalities") supported by the NonStop Kernel (NSK) operating system on HP NonStop Servers. Also see NSK.
H
HTTP
see HyperText Transfer Protocol HTTPS
Hypertext Transfer Protocol over Secure Socket Layer
HyperText Transfer Protocol
HTTP; the set of rules for exchanging files (text, graphic images, sound, video, and other multimedia files) on the World Wide Web.
I interprocess message
A message exchanged between two processes, typically a 'client' and a 'server', in predefined, structured format.
IPM
see interprocess message
M method
A member function of a Web service, it performs some action and typically accepts and returns information as one or more parameters.
N
NSK
NonStop Kernel; the core layer of the operating system on HP (formerly Compaq, Tandem) NonStop Servers. Although "NSK" originally was intended to describe the part of the operating system shared by both the Open System Services (OSS) and Guardian "personalities", it is commonly used as a synonym for the Guardian personality itself.
P
Pathway
HP NonStop Server server management environment. Performs load-balancing and process management for customer-written application servers. SOAPam interfaces to Pathway to send interprocess messages on behalf of Web service client applications.
S
SDF
see Service Definition File
Secure Sockets Layer
SSL; a commonly-used protocol for managing the security of a message transmission on the Internet. SSL uses a program layer located between the Internet's Hypertext Transfer Protocol (HTTP) and Transport Control Protocol (TCP) layers. SSL uses the public-and-private key encryption system from RSA, which also includes the use of a digital certificate. See also Transport Layer Security (TLS). serialization
The process through which SOAPam converts an application server reply interprocess message (IPM) to an XML-formatted SOAP response. See also deserialization. service
see Web service Service Definition File
SDF; an XML-based document used to describe a service. It contains information that tells SOAPam Server how to map Web service methods calls to specific servers or server classes on a NonStop Server. It also contains information that SOAPam Server uses to map SOAP method parameters to and from server interprocess messages (IPM). Service Definition File names always have the ".sdf" extension. SOAPam dynamically generates a standard WSDL file from your .sdf file.
Service Definition Wizard
A component of SOAPam Server; provides browser-based user interface for creating and maintaining Service Definition Files (SDF). It is accessed via the SOAPam Server Control Panel.
SOAP
Simple Object Access Protocol; a lightweight protocol for exchange of information in a decentralized, distributed environment. It is an XML-based protocol that consists of three parts: an envelope that defines a framework for describing what is in a message and how to process it, a set of encoding rules for expressing instances of application-defined data types, and a convention for representing remote procedure calls and responses.
SOAPam Server (process)
The NSK-based server process (a running SOAPAM object) responsible for receiving SOAP requests over HTTP from remote client applications, reformatting them as interprocess messages and forwarding them to the appropriate server application. It also implements the SOAPam Server Control Panel, the WebDAV interface to the VFS and the Service Definition Wizard.
SOAPam Server (product)
The SOAPam product that allows standard Web service client applications on any platform to access an existing Pathway or $RECEIVE-based server application as a Web service.
SOAPam Client
The SOAPam product that allows NSK-based client applications to consume Web services on any platform via native interprocess messages.
SOAPam Client Process
The NSK-based server process (a running SOAPAMCP object) responsible for receiving interprocess messages from NSK-based client applications, reformatting them as SOAP requests and forwarding them to the appropriate WSDL endpoint.
SSL
see Secure Sockets Layer
T
TLS
see Transport Layer Security
Transport Layer Security
TLS; a protocol that ensures privacy between communicating applications and their users on the Internet. When a server and client communicate, TLS ensures that no third party may eavesdrop or tamper with any message. TLS is the successor to the Secure Sockets Layer (SSL).
TMF
see Transaction Monitoring Facility
Transaction Monitoring Facility
NonStop Server product responsible for maintaining.... Now known as NonStop TM/MP.
V VFS
see Virtual File System
Virtual File System
VFS; a component of SOAPam Server. A WebDAV-compliant file system, it provides a network-accessible repository for Service Definition Files (SDF) and Web Service Description Language (WSDL) files.
W
Web service
A Web service is a collection of "methods" that can be invoked (called) through a network by a client application using the SOAP protocol. Methods perform some defined action and typically accept and return one or more parameters.
Web Services Description Language
WSDL; an XML-based language used to describe the services a business offers and to provide a way clients to access those services electronically.
WebDAV
Web Distributed Authoring and Versioning; a set of extensions to the Hypertext Transfer Protocol (HTTP) that facilitates collaborative editing and file management between users located remotely from each other on the Internet.
WSDL
see Web Services Description Language
WSDL2CDF
The WSDL-to-CDF utility, a component of SOAPam Client. It reads a WSDL file describing a Web service and creates a CDF that incorporates additional information about the service based on parameters you supply.
X
XML
eXtensible Markup Language: a standard for creating structured textual documents. SOAP, WSDL and SDF are XML documents. See http://w ww.w3.org/xml. Release Notes
This Release Notes contains important information about the 3.1 release of the product. Review all sections before installing or upgrading the product.
If you are upgrading from a prior release please review the Upgrade Considerations.
Upgrade Considerations Upgrade Guide Product Licensing Cumulative Change Log Third Party Software Licenses Standards Compliance Upgrade Considerations
This section contains information about upgrading from previous releases of SOAPam Client to release 3.1. Read this section carefully before attempting to upgrade your current installation of SOAPam Client.
Licensing Changes
Note that SOAPam Client release 3.1 requires a multi-line license that contains the supportExpiration property. If you currently have a 19 character license key or a multi-line license that does not contain the supportExpiration property, please Submit a Support ticket and request an updated license.
Changes to Namespace Handling
All SOAPam Client versions prior to 3.0 used default namespaces when creating XML requests. This produced XML which did not use namespace prefixes on elements in the SOAP Body payload. SOAPam Client 3.0 was changed to eliminate the use of default namespaces, which produced XML that contained namespace prefixes on all elements in the SOAP Body. Although this caused no impact for applications that processed the namespaces, applications that took advantage of the lack of namespace prefixes to forego namespace processing no longer worked. In order to resolve this incompatibility, default namespace usage has been restored in this release. This change should not impact applications that process namespaces, but will allow those that don't to continue to work.
CDF2C Utility Retired
The CDF2C utility allowed C language header files with structure sizes greater than 32K to be generated from a CDF. The utility could be used instead of the CDF2DDL / DDL to source procedure when DDL was limited to 32K structures. With the introduction of DDL2, CDF2C is no longer necessary and the utility is no longer supported. In the unlikely event that you are using CDF2C, please let us know by submitting a ticket. Upgrade Guide NuWave Technologies is currently supporting a number of SOAPam release lines. When an issue is corrected or a periodic update is made in a release line, a patch is released with a patch version number, for example, 2.1.1, 2.2.1. Prior to minor version 2.1, an alphanumeric "SPx" patch designation (2.0.SP1, 2.0.SP2) was used. NuWave typically issues quarterly updates to the latest minor release line, which may contain problem corrections and new features. When a high impact issue is discovered in any release line we will immediately issue a patch to that line and other lines if applicable.
The table below can be used to help determine the appropriate upgrade path. If your current release contains fixes that you must have (which is usually the case), you must upgrade to a version with the same or greater minor release number and is chronologically newer than your current release. For example, if your current release is 2.2.5, you can safely upgrade to version 2.3.4 or greater, or version 2.4.0 or greater. You could not upgrade to version 2.3.0 - 2.3.3 because they were released prior to release 2.2.5.
Using the table first locate your current release. The release you are upgrading to must appear in the table in a cell that is lower than, and to the right of your current release.
The release you choose to upgrade to will contain all fixes and enhancements that have been made since the current release version, up to and including the release you are upgrading to. For example, if you upgrade from 2.2.5 to 2.4.2, you will receive all fixes and enhancements made from version 2.2.5 to 2.4.2. You can view a cumulative list of all updates and considerations in section Cumulative Change Log
Date 2.0 2.1 2.2 2.3 2.4 3.0 3.1
24 Aug 2005 2.0 (2.0.5236)
12 Dec 2005 2.0.SP1 (2.0.5350)
25 Apr 2006 2.0.SP2 (2.0.6114)
29 Nov 2006 2.0.SP3 (2.0.6334)
28 Nov 2007 2.0.SP4 (2.0.7330)
14 Jan 2008 2.0.SP4a (2.0.8014)
15 Feb 2008 2.0.SP4b (2.0.8046)
06 Jun 2008 2.0.SP5 (2.0.8113)
27 Jun 2008 2.0.SP5a (2.0.8278)
03 Nov 2008 2.1.0
14 Apr 2009 2.2.0
24 Jun 2009 2.0.SP4c (2.0.9175)
21 Jul 2009 2.2.1
19 Jul 2009 2.2.2
14 Dec 2009 2.3.0
29 Dec 2009 2.3.2
06 Jan 2010 2.3.3
13 Jan 2010 2.2.5
27 Jan 2010 2.3.4
19 Mar 2010 2.3.5
19 Apr 2010 2.3.7
26 May 2010 2.3.8
26 Aug 2010 2.0.SP4d (2.0.44)
13 Oct 2010 2.3.9
13 Oct 2010 2.4.0
20 Dec 2010 2.4.1
12 Apr 2011 2.4.2
01 Jun 2011 2.4.4
29 Jun 2011 2.3.12
22 Aug 2011 2.4.5
06 Sep 2011 2.4.6
23 May 2012 2.4.9
24 Oct 2012 2.4.11
18 Apr 2013 2.4.12
31 May 2013 3.0.0 10 Apr 2014 3.0.3
27 Oct 2014 3.0.4
20 Aug 2015 3.0.5
06 Apr 2015 3.1.0
20 Aug 2015 3.1.1
26 Oct 2016 3.1.2
11 Aug 2017 3.1.3
Product Licensing
All SOAPam products require the installation of a license. The license is stored in an edit file on the NonStop Server that is read by the SOAPam product in order to validate the installation. A SOAPam license is a multi-line text block similar to that shown below:
-----BEGIN LICENSE----- product=soapam_client systemnumber=012345 restrictedlicense=no expiration=12/31/2020 supportExpiration=12/31/2017 signature=172 j7EWNBiTMY4Yw+0Hd9CtCGMZARqEhVHt7NsslMSJwfYND/SqnC wjsS2YzudXnqh7ZTlrq9SWsrAAXjUjbeRXc62d5DWW6BLutUza 3FqjTxH3X57uVTjtBaJAhhESS0faLw3wVeJ5W960r6F9ghVWVI L+rfWomyUksa236jDk9cs= -----END LICENSE-----
Note that SOAPam release 3.1 and above require a multi-line license that contains the supportExpiration property. If you currently have a 19 character license key or a multi-line license that does not contain the supportExpiration property, please Submit a Support ticket an d request a new license.
When the license is received from NuWave Technologies it must be copied to an edit file on the NonStop System exactly as provided. The product searches for the license file in the following locations and in the following order:
The file specified by the command line option -licensefile The file LICENSE in the SOAPAMCP program subvolume. The file LCLIENT in the SOAPAMCP program subvolume. The file $SYSTEM.NUWAVE.LCLIENT
License Expiration
The license contains two expiration date fields to be aware of: expiration
This field contains the date that the license will expire, or "none" if the license never expires. For licenses that expire, once the expiration date has passed the software will no longer function. For licenses that don't expire, the software will run indefinitely. supportExpiration
This field contains the date that your current software support agreement expires. Once this expiration date has passed the software will continue to run with full functionality (subject to the expiration date) on your current release but you may not upgrade the software to a version that was released after the supportExpiration date. Software with a release date after the supportExpiration date will shutdown immediately with a license error. The release date for a particular software version can be found in the Upgrade Guide or the product VPROC.
When you renew your support agreement we will email you a new license. You do not need to install the new license until the next software upgrade.
Cumulative Change Log
The cumulative change log for version 3.x releases is shown below. To view the change log for 2.x releases refer to the latest version 2.x Release Notes.
Version 3.1.3 - 11AUG2017
Problems Corrected
[SOAP-895] - WSDL2CDF reports "CDF file was not created" when certain conversion errors occur. [SOAP-884] - SOAPAMCP doesn't report log open errors when configured as a serverclass with no OUT file. [SOAP-927] - ICU data file not found if not located in the current subvol (L-series only)
New Features
[SOAP-935] - Upgrade to OpenSSL 1.0.2k
Version 3.1.2 - 26OCT2016
Problems Corrected
[SOAP-900] - SOAPAMCP does not validate server certificates with wildcard host names. [SOAP-903] - WSDL2CDF imports nonNegativeInteger types as string. [SOAP-885] - SOAPAMCP drops query string parameters from the request URI. [SOAP-910] - File system browser shows mobile view in IE 11 on Windows 10 [SOAP-885] - SOAPAMCP drops query string parameters from the request URI. [SOAP-881] - Add support to SOAPAMCP for multipart responses.
New Features
[SOAP-909] - Update to OpenSSL 1.0.2j
Version 3.1.1 - 20AUG2015
Problems Corrected
None
New Features
[SOAP-855] - Add support for NonStop X [SOAP-865] - Update to OpenSSL 1.0.1p [SOAP-876] - Update CAROOT file.
Version 3.1.0 - 06APR2015
Problems Corrected
[SOAP-718] - MAKECF may loop when CTRL-Y is entered while prompting for credentials. [SOAP-841] - Client messagedump options are not fully documented. [SOAP-847] - Stats configuration loader interprets missing [stats] section as invalid configuration file.
New Features
[SOAP-853] - Upgrade to OpenSSL 1.0.1m.
Version 3.0.5 - 20AUG2015
Problems Corrected
None
New Features
[SOAP-865] - Update to OpenSSL 1.0.1p [SOAP-876] - Update CAROOT file. Version 3.0.4 - 27OCT2014
Problems Corrected
None
New Features
[SOAP-807] - Update to OpenSSL 1.0.1j [SOAP-809] - Update CAROOT file.
Version 3.0.3 - 10APR2014
Problems Corrected
[SOAP-719] - Deserialization/serialization errors are not reported properly in SOAP faults. [SOAP-743] - WSDL2CDF uses an incorrect default value for schema attribute elementFormDefault [SOAP-747] - WSDL2CDF does not process schema list types. [SOAP-744] - WSDL2CDF does not report errors in some cases when CDF cannot be created. [SOAP-758] - SOAPAMCP records internal server error responses (HTTP 500) as a timeout in the statistics log.
New Features
[SOAP-753] - Update TNS/E version to OpenSSL 1.0.1g. [SOAP-754] - Update CAROOT file [SOAP-759] - Update TNS/R version to OpenSSL 0.9.8y.
Version 3.0.0 - 31MAY2013
Problems Corrected
None
New Features
[SOAP-385] - Add support for Pathway large messages. [SOAP-420] - Update CAROOT file. [SOAP-451] - Allow element default values to be set from type element "value" attribute. [SOAP-484] - Include SOAP/AM Web Service client documentation on server documentation page. [SOAP-560] - Add certificate chain to SOAPAMCP message dump. [SOAP-609] - Move documentation from VFS to web based content delivery system. [SOAP-662] - Add ssl client certificate capability to WSDL2CDF
Third Party Software Licenses
The SOAPam Client incorporates code from several third party software packages. The licenses for these packages are included below:
Apache Portable Runtime Apache Portable Runtime Utility Library Apache HTTP Server dlmalloc Memory allocator International Components for Unicode cURL libxml2 XML Toolkit OpenSSL Toolkit Perl Compatible Regular Expressions
Apache Portable Runtime
Copyright (c) 2011 The Apache Software Foundation.
This product includes software developed by The Apache Software Foundation (http://www.apache.org/).
Portions of this software were developed at the National Center for Supercomputing Applications (NCSA) at the University of Illinois at Urbana-Champaign.
This software contains code derived from the RSA Data Security Inc. MD5 Message-Digest Algorithm.
This software contains code derived from UNIX V7, Copyright(C) Caldera International Inc. http://apr.apache.org http://www.apache.org/licenses/LICENSE-2.0
Apache Portable Runtime Utility Library
Copyright (c) 2011 The Apache Software Foundation.
This product includes software developed by The Apache Software Foundation (http://www.apache.org/).
Portions of this software were developed at the National Center for Supercomputing Applications (NCSA) at the University of Illinois at Urbana-Champaign.
This software contains code derived from the RSA Data Security Inc.
MD5 Message-Digest Algorithm, including various modifications by Spyglass Inc., Carnegie Mellon University, and Bell Communications Research, Inc (Bellcore). http://apr.apache.org http://www.apache.org/licenses/LICENSE-2.0
Apache HTTP Server
Copyright 2013 The Apache Software Foundation.
This product includes software developed at The Apache Software Foundation (http://www.apache.org/).
Portions of this software were developed at the National Center for Supercomputing Applications (NCSA) at the University of Illinois at Urbana-Champaign.
This software contains code derived from the RSA Data Security Inc. MD5 Message-Digest Algorithm, including various modifications by Spyglass Inc., Carnegie Mellon University, and Bell Communications Research, Inc (Bellcore). http://httpd.apache.org http://www.apache.org/licenses/LICENSE-2.0
dlmalloc Memory allocator
Written by Doug Lea and released to the public domain. ftp://g.oswego.edu/pub/misc/malloc.c http://creativecommons.org/publicdomain/zero/1.0/
International Components for Unicode
Copyright (c) 1995-2014 International Business Machines Corporation and others. http://site.icu-project.org/ http://source.icu-project.org/repos/icu/icu/trunk/license.html
cURL
Copyright (c) 1996 - 2014, Daniel Stenberg,
libxml2 XML Toolkit
Copyright (C) 1998-2012 Daniel Veillard. All Rights Reserved. http://www.xmlsoft.org/ http://opensource.org/licenses/mit-license.html
OpenSSL Toolkit
Copyright (c) 1998-2011 The OpenSSL Project. All rights reserved.
Copyright (C) 1995-1998 Eric Young ([email protected]) http://www.openssl.org http://www.openssl.org/source/license.html
Perl Compatible Regular Expressions
Copyright (c) 1997-2013 University of Cambridge
Copyright (c) 2009-2013 Zoltan Herczeg
Copyright (c) 2007-2012 Google Inc. http://www.pcre.org/ http://www.pcre.org/licence.txt
Standards Compliance
SOAPam complies with the following standards:
SOAP 1.1 WSDL 1.1 XML 1.0 HTTP 1.1 TLS 1.2 SSL 3.0 (only if enabled, not by default) How to Obtain Support
We welcome your feedback and encourage you to contact us with any questions or comments. You can view the current SOAPam support options by visiting the NuWave Technologies Support Center.