ITP DID language

The following specifics are introduced for the XML File Connection.

DID Module

You must use XMLFILE for the CONNECTION attribute in a DID Module that contains XML File Connection Entries. A DID can contain multiple XML File Connection DID Modules. In the DataManager configuration file you can specify a different default directory for each of these DID Modules.

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 XMLWEB

  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 to be compatible with older ITP/Server versions:

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

The DATA_RETRIEVAL attribute of an entry is required and specifies the XML tag that identifies the entry in the XML file. XML tags are case sensitive, and at the moment, only ASCII tags can be specified.

There are two types of entries for the XML File Connection. The type of an entry is specified in the 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 indeed 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 more efficient and keeps a clear correspondence between the XML input and the ITP output.

Example

NAME                     Customer
MODEL_DOCUMENT_STATEMENT FORALL
DATA_RETRIEVAL           "Customer"

Entries can be used as main entry, and as subentry. This has no consequences for the way these entries are defined - the same entry can be used in both ways -, but there are some differences in the way these entries are handled at runtime.

Mixed Content elements

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

If an element Tag contains content as well as other elements with unique names, the DID will generate an entry Tag and a field Tag that contains that content. The other elements in the structure are 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, the DID will also generate an entry Tag and a field Tag that contains that content. The other elements (that have the same name) are grouped together in a plural entry with that name. This entry contains the field 'Self' which is a special way of retrieving the data of these elements. The DATABASE_FIELD attribute for this Self field is 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 or the name of the attribute preceded by an @ in case of an attribute. 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>

Will be turned by the wizard into:

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 will be set to @<name of the attribute> to retrieve the content of the attribute.

If a mixed content element has an attribute with the same name as any of its sub tags/fields, the DID creation process will generate an error. To prevent this error from re-occurring rename the attribute in the DID document.

Addressing the current node

The content of the current node can be retrieved with a single dot ("."). In some situations the SDK/MP wizard generates a Self field that uses this special way of addressing the current node.

Datatypes

Currently only the data types C_CHAR,W_CHAR and DOUBLE are supported for Fields in the XML File 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 File 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, do not disable the setting AllowMissingFields. If you disable this setting you will get a fatal error.

Example

Customer_number DOUBLE             DATABASE_FIELD "CustomerNumber"
Surname         C_CHAR  LENGTH 255 DATABASE_FIELD "Surname"
First_name      C_CHAR  LENGTH 255 DATABASE_FIELD "FirstName"
Partner_number  DOUBLE             DATABASE_FIELD "PartnerNumber"
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 Data Manager does not check this for reasons of efficiency. Instead, it delivers an arbitrary field that matches, and it ignores the other fields.