Requests

Each MQSeries request consists of a single message containing a character string. This string encodes all request parameters and may use any code page for which MQSeries for NT supports conversion to Unicode (ITP/Server uses Unicode internally). This usually means that the local code page of the sending application can be used. The only requirements are:

• The CodedCharSetId attribute in the MQSeries message descriptor must be set to the used code page. If the local code page is used the default MQSeries descriptor settings will automatically indicate the correct code page.
• The Format attribute in the MQSeries message descriptor must be set to MQFMT_STRING, in order to enable automatic conversion of the request string by MQSeries.

Request parameters

For MQSeries each request contains the following parameters. Unlike the TCP/IP protocols, there is no need to include the user id as a parameter, as MQSeries already includes this information in each message.

Job Identifier

Every job that you submit must have a non-empty identifier. You are free to choose this identifier. It is used for progress messages and by the ITP/Server monitor, but not internally for identification of request messages. This means that job identifiers do not necessarily have to be unique.

Service

The second parameter is also required and contains the name of the service that you want to run.

Optional Parameters

Every job that you submit can have zero or more additional parameters. In the ITP/Server administration program you define how these parameters are mapped to script parameters. When the mapping contains more parameters than those specified in a job then these parameters are assumed to be undefined.

Request Format

The MQSeries interface for ITP/Server supports 2 different formats for job submission; a coded string or an XML message.

Coded string

Each request is specified as a single string of characters that has the following format:

<s><Job Identifier><s><Service><s>[<parameter 1><s>...]

Here, <s> is a single character that does not occur in the parameter data. Both the job identifier and the service name may not be empty and the request must end with the separator. The parameters are optional. The separator can be any character except a NUL character ('\0'), because the MQSeries code page translation treats a NUL character as the end of the string.

Example

#ITP Job#runmdl#order#

In the example above the '#' character has been used as the separator.

XML Message

Each request is put in an XML message. The content of the message is mostly free, however, the interface will look for an <itp:job> element containing the job submission information. This element has the following format:

<?xml version="1.0" ?>

<itp:job version="1" id="jobid">

    <itp:service>service name</itp:service>

    <itp:parameters>

        <itp:parameter>parameter 1 data</itp:parameter>

        <itp:parameter>parameter 2 data</itp:parameter>

        …

    </itp:parameters>

</itp:job>

Replace:

• jobid with the identification of the job.
• service name with the name of the service to call.
• parameter n data with the value of the nth parameter.

Note

The XML message should start with <?xml. <?xml have to be the first five characters in the request string, otherwise the request will fail.

Invalid Requests

If a request uses a code page that MQSeries cannot convert to Unicode, or if it does not conform to the request format, ITP/Server will reject the request. It logs the error and does one of the following:

• By default, ITP/Server will move the request to the dead-letter queue of the queue manager that manages the request queue. If no dead-letter queue has been specified, the request will be removed from the request queue (refer to the MQSeries manuals how to define a dead-letter queue for a queue manager for more information).
• If the MQRO_DISCARD_MSG option is used in the Report field of the request message descriptor the message will be removed from the request queue.

In both cases, a negative action notification will be sent to the client if it had requested this (refer to below for more information). This notification will contain the reason that the message was rejected.