ITP DID Language

The following specifics are introduced for the XML MQSeries Connection:

DID Module

You must use MQXML for the Connection attribute in a DID Module that contains XML MQSeries Connections Entries.

The DID module can optionally include a NAMESPACE section which maps namespace prefixes to their URIs in the format "prefix" = "uri". If this section is present all namespace prefixes in tags in the DID module will be replaced with the mapped URIs in this mapping. Lookups in the XML file during model execution are then done based on the URIs instead of the literal prefixes.

If the NAMESPACE section is omitted lookups are done based on the literal prefixes.

Special values:

• Prefix "" is used to map the default namespace for the tags specified in the DID module. This mapping is applied to all tags that do not have a prefix.
• URI "*" can be used as a wildcard. This URI matches any namespace in the XML file during model execution.

Example

DEFINE_DIDMODULE
  NAME "SOAP"
  CONNECTION XMLFILE

  NAMESPACE
    "" = "http:////www.aia-itp.com//itpserver//wsdl"
    "soap" = "http:////schemas.xmlsoap.org//soap//envelope//"

  DEFINE_ENTRY
...

Note that the slash is the escape character in the ITP DID language. All slashes in URIs must therefore be duplicated.

Mappings are applied to all tags (the KEY_RETRIEVAL, DATA_RETRIEVAL and DATABASE_FIELD keywords) of an entry.

If a tag does not have a namespace prefix is it mapped to the default namespace. If the NAMESPACE section does not specify a default namespace (using the prefix "") for backward compatibility the tag will match all tags that use any default namespace in the XML file.

Example:

  NAMESPACE
    "" = "http:////www.aia-itp.com//itpserver//wsdl"
    "soap" = "http:////schemas.xmlsoap.org//soap//envelope//"

  ...
  Plugh ... DATABASE_FIELD "plugh"
  Plover ... DATABASE_FIELD "soap:plover" 

The Plugh field will match the following elements in the XML file:

<plugh xmlns="http://www.aia-itp.com/itpserver/wsdl">...</plugh>
<x:plugh xmlns:x="http://www.aia-itp.com/itpserver/wsdl">...</plugh>

The Plover field will match the following elements in the XML file:

<plover xmlns="http://schemas.xmlsoap.org/soap/envelope/">...<plover>
<soap:plover xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">...<plover>
<x:plover xmlns:x="http://schemas.xmlsoap.org/soap/envelope/">...<plover>

Removing the default namespace from the mapping will change the way tags without a namespace are handled:

Example:

  NAMESPACE
    "soap" = "http:////schemas.xmlsoap.org//soap//envelope//"

  ...
  Plugh ... DATABASE_FIELD "plugh"
  Plover ... DATABASE_FIELD "soap:plover" 

The Plugh field will now match the following elements in the XML file:

<plugh xmlns="http://www.aia-itp.com/itpserver/wsdl">...</plugh>
<plugh xmlns="http://schemas/xmlsoap.org/soap/envelope/">...</plugh>
<plugh xmlns="http://some/random/uri">...</plugh>

But it will not match the following element (because it has an explicit namespace prefix):

<x:plugh xmlns:x="http://www.aia-itp.com/itpserver/wsdl">...</plugh>

Entries

CALLING_CONVENTION

There are two types of entries for the XML MQSeries Connection. The type of an entry is specified in the CALLING_CONVENTION:

1. MQREQUEST. These entries collect their data through an actual MQSeries request.
2. SUBELEMENT. These entries collect data in earlier collected XML structures

DATA_RETRIEVAL

The DATA_RETRIEVAL is dependent on the CALLING_CONVENTION:

1. MQREQUEST.
   The DATA_RETRIEVAL holds the function that is called. The records that are returned 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).
2. SUBELEMENT.
   The DATA_RETRIEVAL key specifies the XML tag that identifies the entry in the XML file. The records that are returned are specified at the DEFINE_FIELDS section of the entry. XML tags are case sensitive and, at the moment, only ASCII tags can be specified.

MODEL_DOC_STATEMENT

• WITH, a singular entry. This entry retrieves at most one record. The DataManager will deliver the first record that has a matching tag, and ignores the others. This behavior is consistent with other ITP Connection types. It is up to the XML producer to generate only one XML element with the corresponding tag at the corresponding level in the XML file.
• FORALL, a plural entry. This entry retrieves zero, one, or more records. The DataManager will deliver all records with a matching tag in the order that they are stored in the XML file. In this way, the XML producer can influence the order that data is passed to ITP. In general, if data must be ordered, it is better to store it in the required order in the XML file, than to let ITP sort things out. This is a) more efficient and, b) keeps a clear correspondence between the XML input and the ITP output.

KEY_RETRIEVAL

KEY_RETRIEVAL is only possible for entries that collect their data through MQSeries. The KEY_RETRIEVAL holds the function that is called. The records that are returned are specified in a key at the DEFINE_PARAMETERS section of the entry that describes the parameters of the function. Optionally, an element with the tag ITP_SCREEN_DESCRIPTION that holds a textual description/identification of the data record can be added to the fields of the entry. The content of the ITP_SCREEN_DESCRIPTION tag will be added to the KEY_RETRIEVAL record. If no ITP_SCREEN_DESCRIPTION element is indicated, KEY_RETRIEVAL will show a textual representation of all parameters.

You can refer to the KEY_RETRIEVAL key from within the content template with the expression @(ENTRY:RETRIEVAL).

DEFINE

In the DEFINE section one can define keys that can be referred to in the content template thus allowing to pass practically any value from the DID to the template. The DEFINE section typically contains a key that describes the parameters for the key retrieval and the data retrieval. This parameters key (for example PARAMS) describes the structure in which the parameters are passed to the DATA_RETRIEVAL and KEY_RETRIEVAL function.

You can refer to the keys from within the content template with the expression @(ENTRY:<NAME_KEY>).

RESULT_PATH

The result of the MQSeries request is returned in an XML structure. The RESULT_PATH specifies where in this XML structure the result of the KEY_RETRIEVAL and DATA_RETRIEVAL are located. 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"

It is possible to include references to the function name (@(ENTRY:RETRIEVAL) statements). Slashes need to be escaped (this is a requirement for DID strings in general). One may use backslashes instead:

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

Apart from this, it is possible to include @(PAR:…) and general @(ENTRY:…) statements as well. Including parameters may be necessary when the actual function name is passed as a parameter (and part of the result path). Including general entry references just makes some things easier, and may avoid having long path definitions.

Mixed Content elements

Mixed content elements in an XML File are elements that contain content as will as a substructure (subelements).

If an element Tag contains content as well as other elements with unique names, you have to specify an entry 'Tag' and a field Tag that contains that content. The other elements in the structure have to be returned as a field of the entry Tag.

Example

<Root>
    <Tag>
         This is data in the tag
         <Subtag1> This is data in subtag1 in tag</Subtag1>
         <Subtag2> This is data in subtag2 in tag</Subtag2>
    </Tag>
</Root>
This XML will result in the DID:
 DEFINE_ENTRY
    NAME                     Root                           (* Root *)
    MODEL_DOCUMENT_STATEMENT WITH
	DEFINE_FIELDS
      	Tag         C_CHAR LENGTH ( 255  )  DATABASE_FIELD "Tag"
	END_DEFINE_FIELDS
	DEFINE_SUBENTRIES
      	Tag                            (* Tag *)
	END_DEFINE_SUBENTRIES
  END_DEFINE_ENTRY
  DEFINE_ENTRY
    NAME                     Tag                            (* Tag *)
    MODEL_DOCUMENT_STATEMENT WITH
	DEFINE_FIELDS
      	Subtag1     C_CHAR LENGTH ( 255  )  DATABASE_FIELD "Subtag1"
         Subtag2     C_CHAR LENGTH ( 255  )  DATABASE_FIELD "Subtag2"
	END_DEFINE_FIELDS
  END_DEFINE_ENTRY

If an element Tag contains content as well as other elements that don't have unique names, you also have to specify an entry Tag and a field Tag that contains that content. The other elements (that have the same name) should be grouped together in a plural entry with that name. This entry should contain the field Self which is a special way of retrieving the data of these elements. The DATABASE_FIELD attribute for this Self field should be set to a single dot ("."). This complies with the XPath notation to address the current node.

<Root>
    <Tag>
		This is data in the tag
		<Subtag> This is data in p in tag</P>
		<Subtag> This is data in the second p in tag</P>
    </Tag>
</Root>
This XML will result in the DID:
  DEFINE_ENTRY
    NAME                     Root                           (* Root *)
    MODEL_DOCUMENT_STATEMENT WITH
	DEFINE_FIELDS
      Tag              C_CHAR LENGTH ( 255  )  DATABASE_FIELD "Tag"
	END_DEFINE_FIELDS
	DEFINE_SUBENTRIES
      Tag                            (* Tag *)
	END_DEFINE_SUBENTRIES
  END_DEFINE_ENTRY
  DEFINE_ENTRY
    NAME                     Tag                            (* Tag *)
    MODEL_DOCUMENT_STATEMENT WITH
	DEFINE_SUBENTRIES
      Subtag                         (* Subtag *)
	END_DEFINE_SUBENTRIES
  END_DEFINE_ENTRY
  DEFINE_ENTRY
    NAME                     Subtag                         (* Subtag *)
    MODEL_DOCUMENT_STATEMENT FORALL
	DEFINE_FIELDS
      Self             C_CHAR LENGTH ( 255  )  DATABASE_FIELD "."
	END_DEFINE_FIELDS
  END_DEFINE_ENTRY	

Fields

All fields have an optional DATABASE_FIELD attribute that specifies the XML tag of the field. If no DATABASE_FIELD is present, the name of the field will be taken as the XML tag. Note that XML tags are case sensitive. Only ASCII tag names can be specified.

Retrieving attributes

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

Example

The XML:

 <Root>
      <Var1 Attribute="x"> 
            Content of var1.
      </Var1>
 </Root>
Has to be specified as:
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 an attribute has to be set to @<name of the attribute> to retrieve the content of the attribute.

Note

A mixed content element cannot have an attribute with the same name as any of its sub tags/fields.

Addressing the current node

The content of the current node can be retrieved with a single dot (".").

Datatypes

Currently only the data types C_CHAR,W_CHAR and DOUBLE are supported for Fields in the XML MQSeries Connection.

Absent and Optional Fields

It may be desirable to make a distinction in a model between missing elements and elements that are present in the XML file, but empty. Therefore the XML MQSeries Connection supports optional fields. Such fields have a textual (C_CHAR) companion field in the DID with the following special DATABASE_FIELD specification:
*PRESENT:<tag name>
The *PRESENT prefix is case sensitive. This companion field will get the value Y if the field is present in the XML file and N otherwise. If you want to use this option, the setting AllowMissingFields should be disabled (set to N), otherwise ITP will mark all fields to be present anyway.

Example

Customer_number	C_CHAR LENGTH(255)	DATABASE_FIELD	CUST_ID
Surname	C_CHAR LENGTH(255)	DATABASE_FIELD	SURNAME
Initials	C_CHAR LENGTH(255)	DATABASE_FIELD	INITIALS
Sexe	C_CHAR LENGTH(255)	DATABASE_FIELD	SEXE
Has_partner	C_CHAR LENGTH(2)	DATABASE_FIELD	"*PRESENT:PARTNERNUMBER"

Multiple Occurrences of a Field

Strictly speaking, it is an error for an XML file to contain multiple occurrences of the same field in a single record. At the moment the DataManager does not check this for reasons of efficiency. Instead, it delivers an arbitrary field that matches, and it ignores the other fields.