amqwdeployWMQService: deploy web service utility

The deployment utility prepares a service class for use as a web service using IBM MQ as the transport.

Purpose

Use the deployment utility to generate the files that are needed to deploy an Axis 1.4, .NET Framework 1 or .NET Framework 2 service. Use the files to deploy a service invoked by IBM MQ. The files generated by amqwdeployWMQService are shown in Output files from amqwdeployWMQService.

Syntax diagram

Required parameters

-f className

className is the name of the class to be deployed. For Axis services className is the Java source file, and for .NET services, the .asmx file. Figure 1 illustrates the deployment of an Axis service and Figure 2 of a .NET service.

amqwdeployWMQService -f javaDemos/service/StockQuoteAxis.java

amqwdeployWMQService -f StockQuoteDotNet.asmx

For Java, className must be fully qualified by the package name. It can be specified as a path name with directory separators or as a class name with period separators. The generated class is located in ./generated/client/remote/path name. For a .NET service, although the directory can be specified, generated Java proxies are always located in ./generated/client/remote/dotNetService.

If you specify a URI with the -u option and within the URI specify targetService, the deployment utility checks the className. className must match targetService. If the class and service do not match, the deployment utility displays an error message and exits.

-?

Print out help text describing how the command is used.

Optional parameters

-a integrityOption

integrityOption specifies the behavior of IBM MQ SOAP listeners if it is not possible to put a failed request message on the dead-letter queue. integrityOption can take one of the following values:

DefaultMsgIntegrity

For non-persistent messages, the listener displays a warning message and continues to execute with the original message being discarded. For persistent messages, it displays an error message, backs out the request message so it remains on the request queue and exits. DefaultMsgIntegrity applies if the -a option is omitted, or if integrityOption is not specified.

LowMsgIntegrity

For both persistent and non-persistent messages, the listener displays a warning and continues to execute, discarding the message.

HighMsgIntegrity

For both persistent and non-persistent messages, the listener displays an error message, backs out the request message so it remains on the request queue and exits.

The deployment utility checks for the compatibility of the -x and -a flags. If -x none is specified, then -a LowMsgIntegrity must be specified. If the flags are incompatible the deployment utility exits with an error message and with no deployment steps having been undertaken.

-b bothresh

bothresh specifies the backout threshold setting for the request queue. The default is 3.

-c operation

operation specifies which part of the deployment process to execute. operation is one of the following options:

allAxis

Perform all compile and setup steps for an Axis or Java service ¹ .

compileJava

Compile the Java service: .java to .class.

genAxisWsdl

Generate WSDL: .class to .wsdl.

axisDeploy

Deploy the class file: .wsdl to .wsdd, apply .wsdd.

genProxiestoAxis

Generate proxies: .wsdl to .java and .class.

genAxisWMQBits

Set up IBM MQ queues, IBM MQ SOAP listeners and triggers for an Axis service.

allAsmx

Perform all setup steps for a .NET service ² .

genAsmxWsdl

Generate WSDL: .asmx to .wsdl.

genProxiesToDotNet

Generate proxies: .wsdl to .java, .class, .cs and .vb.

genAsmxWMQBits

Set up IBM MQ queues, IBM MQ SOAP listeners and triggers

startWMQMonitor

Start the trigger monitor for IBM MQ SOAP services. Note: runmqtrm runs under the mqm user ID. If security is an issue, you must ensure that the listeners are started under appropriate user IDs.

-i Context

Context specifies whether the listeners pass identity context. Context takes the following values:

passContext

Set the identity context of the original request message into the response message. The SOAP listener checks that it has authority to save the context from the request queue and to pass it to the response queue. It makes the checks at run time when opening the request queue to save context, and the response queue to pass context. If it does not have the required authority, or the MQOPEN call fails, and the response message is not processed. The response message is put on the dead-letter queue with the dead-letter header containing the return code from the failed MQOPEN. The listener then continues to process subsequent incoming messages as normal.

ownContext

The SOAP listener does not pass context. The returned context reflects the user ID under which the listener is running rather than the user ID which created the original request message.

The fields in the origin context are set by the queue manager, and not by the SOAP listener.

-n numThreads

numThreads specifies the number of threads in the generated startup scripts for the IBM MQ SOAP listener. The default is 10. Consider increasing this number if we have high message throughput.

-r

-r specifies that any existing request or trigger monitor queue definitions are replaced. Trigger monitor queues are replaced only if -tmq is also specified. Queues are re-created with standard default attributes and existing messages on the queues are deleted. If the -r option is not used then any existing queue definitions are not altered and existing messages are not deleted. By not specifying -r, you ensure that any customized queue attributes are preserved.

-s

Configure the listener to run as an IBM MQ service. If -s and -tmq are both specified, the deployment utility displays an error message and exits.

-tmp programName

programName specifies the name of a trigger monitor program. Use -tmp programName in a UNIX or Linux environment as an alternative to using runmqtrm. Programs it initiates run under mqm authority.

For example:

amqwdeployWMQService -f javaDemos/service/StockQuoteAxis.java
-tmq trigger.monitor.queue -tmp trigmon

-tmq queueName

queueName specifies a trigger monitor queue name. IBM MQ process definitions are created to configure automatic triggering of IBM MQ SOAP listeners with the associated trigger monitor queue name. If the option is not specified then no triggering configuration is defined by the deployment utility. If -s and -tmq are both specified, the deployment utility displays an error message and exits.

URI platform

See URI syntax and parameters for web service deployment.

-v

-v sets verbose output from external commands. Error messages are always displayed. Use -v to output commands that we can tailor to create customized deployment scripts.

-w

-w controls the style of WSDL to generate. The default is rpcEncloded, for compatibility with previous releases of IBM MQ transport for SOAP. Use rpcLiteral to create WSDL compatible with Axis2 client proxy generation. rpcEncoded is not compatible with WS-I recommendations.

-x transactionality

transactionality specifies the type of transactional control for the listener. transactionality can be set to one of the following values:

onePhase

IBM MQ one-phase support is used. If the system fails during processing, the request message is redelivered to the application. IBM MQ transactions ensure that the response messages are written exactly once.

twoPhase

Two-phase support is used. If the service is written appropriately the message is delivered exactly once, coordinated with other resources, within a single committed execution of the service. This option applies to server bindings connections only.

none

No transactional support. If the system fails during processing, the request message can be lost, even if persistent. The service might or might not have executed, and response, report or dead-letter messages might or might not be written.

The deployment utility checks for the compatibility of the -x and -a flags. See the description of the -a flag for details.

Errors

%windir%/Microsoft.NET/Framework/ version number /aspnet_regiis.exe -ir