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

@<command-file>

Reads command line parameters from <command-file>. Options specified on the command line override any duplicates specified in the file. At most, one '@' parameter may used. The file itself cannot contain an '@' parameter (i.e., no nesting).

-authheader <header name> { #<credentials> | <credentials-file> }

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 <file name>

The name of an existing Client Definition File to be processed by this instance of process. This parameter is required.

-doc <method name>

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 { #<userid>:<password> | <credentials-file> }

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 <seconds>

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 <address[:port]>

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 { #<userid>:<password> | <credentials-file> }

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 <seconds> [ ! ]

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 <file name>

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 <key>

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 <binding/> element in the CDF.

-log { <destination> | * }   [ format  [ level ] ]

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". Note that this option is ignored if -logcfg is specified.

-logcfg <filename>

Specifies the log configuration file name. If this option is omitted then no log configuration file is used. Refer to Log Configuration for details. Note that if this option is specified, the -log and logtime options are ignored.

-logtime <format>

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).

 Note that this option is ignored if -logcfg is specified.

-messagedump < [soap] [raw] [ipm] >

-messagedumpcfg <filename>

Specifies the messagedump configuration file name. If this option is omitted then no messagedump configuration file is used. Refer to Message 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 <file name pattern>

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 Determination 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.

-ssl-disable-tlsv1.0

This option disables the TLS v1.0 protocol for HTTPS connections

-ssl-disable-tlsv1.1

This option disables the TLS v1.1 protocol for HTTPS connections

-ssl-disable-tlsv1.2

This option disables the TLS v1.2 protocol for HTTPS connections

-ssl-disable-tlsv1.3

This option disables the TLS v1.3 protocol for HTTPS connections

-sslclientcert <certificate-file> [ { #<pass phrase> | <credentials-file> } ]

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 <file name>

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 <file name>

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 <filename>

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 <count>

If this option is specified, and the -tcpipalt option is also specified, the process will switch to the alternate TCPIP process when <count> sequential HTTP request timeout errors have occurred. The HTTP request timeout is value is specified with the -httprequesttimeout option and/or the request_timout field in the application request message.

-tcpip <process name>

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 <process name>

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 { #<userid>:<password> | <credentials-file> }

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 <certificate-file> [ { #<pass phrase> | <credentials-file> } ]

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 <file name>

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:

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