XML MQSeries connection

With the XML MQSeries connection, you can retrieve data from an XML file through MQSeries. As different servers expect different types of messages, the XML MQSeries connection is set up in a flexible way. You can control the overall layout of the MQSeries request to a large extent with a template. This allows for the construction of any type of MQSeries request message, including messages without XML data.

When an entry is executed in the Master Template, the XML MQSeries connection either extracts data from an earlier collected XML structure, or sends an MQSeries request.

You can configure the XML MQSeries connection in the connection configuration in KCM Core Administrator. Also, you can specify an error tag in the connection configuration to include error information.

By default, XML files use UTF-8 encoding.

Usage

To use this connection type, follow these steps:

Open the required DID document and locate a DID module that contains an XML Web Services connection entry.
Set the CONNECTION attribute to MQXML.
Set the CALLING_CONVENTION attribute to one of the following values:
- MQREQUEST. These entries collect data through an actual MQSeries request.
- SUBELEMENT. These entries collect data through XML structures obtained from the Master Template.
The DATA_RETRIEVAL attribute is dependent on the value set in the CALLING_CONVENTION attribute:
- If CALLING_CONVENTION is set to MQREQUEST, the DATA_RETRIEVAL holds the function that is being called. The returned records are specified at the DEFINE_FIELDS section of the entry. You can refer to the DATA_RETRIEVAL key from within the content template with the expression @(ENTRY:RETRIEVAL).
- If CALLING_CONVENTION is set to SUBELEMENT. The DATA_RETRIEVAL key specifies the XML tag that identifies the entry in the XML file. The returned records are specified at the DEFINE_FIELDS section of the entry. XML tags are case-sensitive.
KEY_RETRIEVAL is only possible for entries that collect their data through MQSeries. It holds the function that is being called. The returned records are specified in a key at the DEFINE_PARAMETERS section of the entry that describes the parameters of the function.

You can refer to the KEY_RETRIEVAL key from within the content template with the expression @(ENTRY:RETRIEVAL).
Set the MODEL_DOC_STATEMENT to WITH for a single entry to retrieve only one record or FORALL for an entry where zero, one, or more records need to be retrieved.
Set the DEFINE section to keys to refer to in the content template. These keys describe the parameters for the key and data retrieval. This gives you the ability to pass any value from the DID to the template.

The result of the HTTP request is returned in an XML structure. The RESULT_PATH specifies where the KEY_RETRIEVAL and DATA_RETRIEVAL are located in this XML structure. Each item in the path specifies the tag of an XML element. The first one holds the root element and the last one specifies the tag of the returned records.

 RESULT_PATH "biztalk_1//body//@(ENTRY:RETRIEVAL).Response//EMPLOYEE//item"

You include references to the function name with the @(ENTRY:RETRIEVAL) statements. Slashes must be escaped. You can use backslashes instead, as shown in this example.

 RESULT_PATH "biztalk_1\body\@(ENTRY:RETRIEVAL).Response\Employee\item"

Also, you can include @(PAR:…) and general @(ENTRY:…) statements when the actual function name is passed as a parameter (and part of the result path).

The result path is not parsed for namespace prefixes. Any prefixes must be included in the path.

Retrieving attributes

An attribute of an XML element becomes a field of an entry with the same name as the element tag.

 <Root>
      <Var1 Attribute="x"> 
            Content of var1.
      </Var1>
 </Root>

This XML is specified in the entry in the following way:

DEFINE_ENTRY
    NAME                     Root                           (* Root *)
    MODEL_DOCUMENT_STATEMENT WITH
      DEFINE_FIELDS
        Var1                C_CHAR LENGTH ( 255  )  DATABASE_FIELD "Var1"
      END_DEFINE_FIELDS
      DEFINE_SUBENTRIES
        Var1                   (* Var1 *)
      END_DEFINE_SUBENTRIES
  END_DEFINE_ENTRY
  DEFINE_ENTRY
    NAME                     Var1                           (* Var1 *)
    MODEL_DOCUMENT_STATEMENT WITH
      DEFINE_FIELDS
        Attribute           C_CHAR LENGTH ( 255  )  DATABASE_FIELD "@Attribute"
      END_DEFINE_FIELDS
  END_DEFINE_ENTRY

The DATABASE_FIELD for such attribute needs to be set to @<name of the attribute> to retrieve the content of the attribute.

You can retrieve the content of a current node with a single period.

Only the following data types are supported for Fields in the XML MQSeries connection: C_CHAR, W_CHAR, and DOUBLE.