Configuring the Client Process |
  
|
Configuring the Client Process |
|
The SOAP/AM 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.
> 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).
-cdf <file name>
The name of an existing Client Definition File to be processed by this instance of process. This parameter is required. Refer to Creating and Editing the Client Definition File for additional information.
-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.
-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 SOAP/AM credentials file containing the encrypted userid and password. Refer to Using Credentials Files for additional information.
-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.
-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.
-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 SOAP/AM product license key. If this option is omitted, the file named LICENSE in the client process program subvolume is used.
-licensekey <key>
The SOAP/AM 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 * text error".
-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.
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
-messagedumpfile < filename >
When specified the messagedump information will be dumped to the specified file instead of individual sequenced files.
-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".
-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. Refer to Using Secure Connections for additional information.
-sslclientcert <certificate-file> [ { #<pass phrase> | <credentials-file> } ]
The name of a PKCS12 client certificate file and, if required, the associated pass phrase required to access the certificate. Specify either the pass phrase (in plain text) or the name of an existing SOAP/AM credentials file containing the encrypted pass phrase. Refer to Using Credentials Files for additional information.
-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 SOAP/AM software. Refer to Using Secure Connections for additional information.
-sslcalocalfile <file name>
The name of a file containing the certificates of local trusted certificate authorities. If omitted, no local CA certificates are loaded. Refer to Using Secure Connections for additional information.
-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. Refer to Using Secure Connections for additional information.
-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.
-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 SOAP/AM credentials file containing the encrypted userid and password. Refer to Using Credentials Files for additional information.
-wssepolicy <file name>
The name of the file containing the Web services extensions policy definition.
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.
Examples
> run soapamcp / name $wscp, nowait, term $vhs, cpu 0 / &
-cdf echocdf -log $0 event info
> run soapamcp / name $wscp, nowait, term $vhs / @options
> run soapamcp / name $wscp, nowait, term $vhs / &
-cdf echocdf -httpproxy myproxy