Message set migration notes

This topic explains what you need to do with each message definition file when you migrate.

You need to be aware of the following information about each message definition file when you use the mqsimigratemsgsets command.

Notes to user

You are strongly recommended not to modify the message set file manually between export from Version 2.1 and import into WebSphere Business Integration Message Broker Version 5.0 because the results are not guaranteed. This can be indicated by the presence of the following warning and error messages in the report (BIP0141, BIP0142 through BIP0157, BIP0163)

Each new message definition file .mxsd is an annotated schema model, and each artifact in the message set is recreated and retains its existing properties in this new model, with the following exceptions:
  • The Name in the WebSphere Business Integration Message Broker Version 5.0 model is the Identifier from the Version 2.1 model. Note that If the object is an element with a prefixed identifier the prefix is removed, as the prefix in Version 2.1 was a way of indicating that this element was actually local.
  • Label, Short and Long Description and History are merged into a single Documentation property for WebSphere Business Integration Message Broker Version 5.0
  • Each compound type becomes an xsd:complexType and an xsd:group in WebSphere Business Integration Message Broker Version 5.0.
    The xsd:complexType so created can be local or global. The default is local, but is overridden to be global if any one of the following is true:
    1. The compound type is unreferenced
    2. The compound type has a Version 2.1 MRM base type
    3. The compound type is referenced by more than one element
    4. A message is based on the compound type
    5. The -g parameter is specified
    The xsd:group so created can be local or global. The default is local, but is overridden to be global if any of the following is true:
    1. The compound type is embedded directly within another compound type. See Embedded simple type for further information.
    2. The compound type has a Version 2.1 MRM base type. See Compound type with an MRM base type for further information.
    3. The compound type has a Version 2.1 type composition of 'simpleUnorderedSet' and a Version 2.1 type content of 'closed'

    Note that the type composition of 'simpleUnorderedSet' is dropped from the model in WebSphere Business Integration Message Broker Version 5.0. If type content is 'closed' then it is replaced by 'all' with a BIP0191 warning message, otherwise by 'unorderedSet' with a BIP0192 warning message.

    Type composition of 'empty' is replaced by an empty 'sequence' with a BIP0193 warning message.

  • Embedded messages with minOccurs or maxOccurs not equal to 1 have the occurs corrected to 1 with a BIP0162 warning message.
  • Each element becomes an xsd:element. The xsd:element so created can be local or global, depending on the following criteria applied in the specified order:
    1. If the element is unreferenced it is global
    2. If the element has a prefixed identifier and is a member of exactly one compound type it is local
    3. If the element is of a compound type with a Version 2.1 MRM base type it is local
    4. If the element is a member of more than one compound type it is global
    5. If the -g parameter is specified it is global
    6. Otherwise the element is local.

    In Version 2.1 a prefixed identifier was intended to indicate that an element was actually local. However, it is possible that an element with a prefixed identifier is actually used in more than one compound type, making it global. If this is so, a global element is created according to the preceding rules

    A BIP0195 warning message is also issued, because this is a misuse of prefixed identifiers, and can result in duplicate global elements being created. For example, A^X and B^X, but both are used more than once, resulting in two global elements with name X.

    The type of the xsd:element so created is either:
    1. A global xsd:complexType
    2. An anonymous local xsd:complexType
    3. A schema built-in xsd:simpleType. See Mapping of MRM simple types to schema simple types
    4. An anonymous xsd:simpleType that restricts a schema built-in xsd:simpleType
  • Any value constraints that belong to the element are processed as follows:
    1. A Default constraint sets the 'default' attribute of the element;
    2. A Null Permitted constraint sets the 'nillable' attribute of the element.
    3. A Date Template constraint changes the xsd:simpleType of the element. See Mapping of MRM simple types to schema simple types
    4. All others restrict the xsd:simpleType of the element by the application of xsd:facets.

    Any unreferenced value constraint is discarded with a BIP0158, BIP0159 or BIP0160 warning message

    Any value constraint that results in an illegal xsd:facet being created is not migrated, with a BIP0165 warning message.
    Note: For elements of type STRING only, value constraints MinInclusive and MaxInclusive are instead imported as hidden annotations for documentation purposes.
  • Element qualifiers are discarded with a once only BIP0167 warning message.
  • Each message becomes a message and an associated global xsd:element.
  • A message that used element qualifiers has the qualification discarded with a BIP0166 warning message.
  • Some physical format properties that were redundant in Version 2.1 and have been removed from the new model. If one of these properties is encountered with a non-default value, a BIP0164 (or other more specific) warning message is issued.
  • The TDS message set level property 'Century window' default value was always set to '53' in Version 2.1. For messaging standard 'SWIFT' this is incorrect, so the default for 'SWIFT' only is changed to '80'. This is reflected in an imported model.

What mqsimigratemsgsets creates

For each .mrp file encountered, a new message set project is created with a name derived from the message set name and level in Version 2.1. The utility does this by adding a suffix to the message set name for all Level values other than "1". This process restores the one-to-one mapping and enables the broker to locate just one message set given the name.

For example, a Version 2.1 message set with name "SWIFT" and Level "1", migrates in Version 5.0 to the message set name "SWIFT", whereas a Version 2.1 message set with name "SWIFT" and Level "2" migrates in Version 5.0 to "SWIFT_2"

A message set folder and associated messageSet.mset file is created within the new project. The following applies to the content of the message set:
  • The message set folder name is the same as the new project
  • The message set identifier is the identifier of the original Version 2.1 message set
  • The message set is created specifying that namespaces are not supported.
  • All physical format layers are recreated in the new message set
  • Any COBOL language binding layer is discarded with a BIP0174 warning message.
  • Any C language binding layer is discarded with a BIP0173 warning message
  • Any finalized state is discarded with a BIP0170 warning message
  • Any basing information is discarded with a BIP0172 warning message.
  • Any freeze timestamp is discarded with a BIP0169 warning message. Note that you always receive this message.
Each message category encountered in the .mrp file results in a new .category file being created. Note that the concept of a:
  • Transaction object is dropped in Version 5.0 and each transaction is replaced by the equivalent message category
  • Transaction category object is dropped in Version 5.0 and each transaction category is replaced by the equivalent message category, containing all the messages in all the transactions referenced by the transaction category.

A single message definition .mxsd file is created within the message set with the same name as the message set and in the default (notarget) namespace, unless the -part parameter is present.

If -part is specified, multiple .mxsd files can be created, if:
  • The number of messages, elements and compound types in the .mrp file exceeds 1000, and
  • The .mrp file can be partitioned into wholly disjoint subsets.

In Version 2.1 all elements and compound types were global. In Version 5.0 elements and complex types can be global or local. When you migrate a Version 2.1 message set, you will probably find that many elements and compound types that were global in Version 2.1 have been converted into local elements and complex types in Version 5.0, according to the rules stated above.

There are two reasons why you might want to override this behavior:
  • You prefer the Version 2.1 organization of your message set, where all objects are global. If you specify the -g parameter this organization is retained as far as is practical.
  • You make use of compound type Type content value Open defined.

    This means that the valid content of a compound type can be any object in the message set, subject to Type composition property rules. Typically in this case the compound type has not been modelled with any explicit content.

    This can cause the mqsimigratemsgsets command to incorrectly deduce that certain elements are to be made local rather than global. If you use Open defined and you find that after migration a runtime validation error BIP5372E occurs, when previously it did not, you should rerun the mqsimigratemsgsets command with the -g option.

Embedded simple type

Note to users

Embedded simple types within compound types need special treatment, because the schema model is unable to cope with this construct. As embedded simple types are deprecated, you are strongly recommended to replace the use of embedded simple types by taking advantage of the 'mixed' attribute of the containing complex type.

Embedded simple types were introduced primarily to model a complex XML element that contained data values interspersed between child elements. Each such data value was explicitly modelled by an embedded simple type, which acted as a placeholder for the value and also supplied its simple type.

In XML schema, there is no exact equivalent. The closest is use of the 'mixed' attribute of xsd:complexType. However, this only says that text can appear before and between (or between) child elements. It implies nothing about the location or data type of the text.

To retain this semantic, a schema extension is introduced, called the Embedded Simple Type. This is simply an unnamed local element of the appropriate simple type. The type itself is a restriction of the real underlying simple type, with a special name (commencing ComIbmMrm_Anon).

Compound type with an MRM base type

Note to users

This situation produces a BIP0161 warning message and needs special treatment, because the schema model is unable to cope with this 'compound' construct. As compound elements are deprecated, you are strongly recommended to replace the use of compound elements by the use of normal elements that reference the global xsd:complexType described in 1 and take advantage of the 'mixed' attribute.

Such compound types were introduced primarily to model a complex XML element that contained a data value as well as child elements. So an element of such a complex type has both complex content like a normal complex element, but also has a value like a simple element (the MRM base type information).

In XML schema, there is no exact equivalent. The closest is use of the 'mixed' attribute of the xsd:complexType. But this just says that text can appear before and between (or between) child elements. It implies nothing about the location or data type of the text.

As there is no exact equivalent in XML schema the following has been done:
  1. A global xsd:complexType and a global xsd:group are created in the usual way. The xsd:complexType additionally has the 'mixed' attribute set and its content is just a reference to the global xsd:group. This models the complex content, but loses the MRM base type information.
  2. A specific schema extension, the Compound Element is introduced. This is an amalgamation of a complex element and a simple element. It is implemented in schema terms as an element with an anonymous complex type, the content of that type being:
    • A local element of the appropriate simple type (to model the MRM base type information). The simple type is a restriction of the real underlying simple type, with a special name (commencing ComIbmMrm_BaseValue)
    • A group reference to the global xsd:group created in 1 above.

A compound element is created for each element that referenced the compound type. Note that this can be done only if the element was itself a member of another compound type.

The combination of these two things means that meaningful use of such compound types within a message is preserved, as the MRM base type information is lost only when it was never actively used in a message.

The special data types created by the situations described in the preceding sections, commencing ComIbmMrm are defined in an XML schema called .wmq21.mxsd, which is included in each message definition file created by the mqsimigratemsgsets command.

Mapping of MRM simple types to schema simple types

The simple type mapping is as follows:
MRM type Schema type
BINARY xsd:hexBinary
BOOLEAN xsd:boolean
DECIMAL xsd:decimal
DATETIME xsd:dateTime (also, see following table)
FLOAT xsd:float
INTEGER xsd:int
STRING xsd:string
For DATETIME type, the simple type mapping is potentially changed by the presence of a Date Template value constraint as follows:
MRM DATETIME Date Template Schema type
CCYY-MM-DDThh:mm:ss.s xsd:dateTime
CCYY-MM-DD xsd:date
CCYY-MM xsd:gYearMonth
CCYY xsd:gYear
--MM-DD xsd:gMonthDay
--MM xsd:gMonth
---DD xsd:gDay
Thh:mm:ss.s xsd:time

If the Date Template is not in the preceding list, the DATETIME is mapped to either an xsd:time or an xsd:dateTime with a BIP0175 warning message, depending on whether or not the Date Template had just a time component. However, note that this mapping can cause errors to appear in the task list after the import.

If the element concerned also had Version 2.1 Default Value, Min Inclusive, Max Inclusive, or Enumeration value constraints, the values for these do not match the lexical space for an xsd:time or xsd:dateTime, and so fail validation. These must be corrected manually using the editor.

The same task list error also appears for any Version 2.1 DATETIME type that supplied a Default Value, Min Inclusive, Max Inclusive, or Enumeration value constraint where the value was not fully specified. For example, Date Template 'CCYY-MM', Enumeration '2003' was allowed in Version 2.1 as it was interpreted as '2003-01' at runtime. However, in the new model the value must match the lexical space of the simple type and so must include the '-01'.

Related concepts
Message modeling concepts

Related tasks
Migrating a message set

Related reference
mqsimigratemsgsets command