Migrating Message Sets from Version 2.1

To migrate message sets from Version 2.1 to Version 6.0 use the mqsimigratemsgsets command. It is not necessary to use this command when migrating from Version 5.0 to Version 6.0.

Conditions of the mqsimigratemsgsets command

Do not modify the message set file manually between export from Version 2.1 and import into WebSphere Message Broker Version 6.0 because this causes errors, indicated by those warning and error messages in the report: BIP0141, BIP0142 to BIP0157, and BIP0163.

Each new message definition file .mxsd is an annotated XML schema model, and each artifact in the message set is re-created and retains its existing properties in the new model, with the following exceptions:
  • The Name in the WebSphere Message Broker Version 6.0 model is the Identifier from the Version 2.1 model. 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 local.
  • Label, Short and Long Description, and History are merged into a single Documentation property for WebSphere Message Broker Version 6.0
  • Each compound type becomes an xsd:complexType and an associated xsd:group in WebSphere Message Broker Version 6.0.
    The xsd:complexType that is created in this way can be local or global. The default is local, but it becomes global if any one of the following conditions is true:
    • The compound type is unreferenced
    • The compound type has a Version 2.1 MRM base type
    • The compound type is referenced by more than one element
    • A message is based on the compound type
    • The -g parameter is specified
    The xsd:group that is created in this way can be local or global. The default is local, but it becomes global if any of the following conditions are true:
    • The compound type is embedded directly within another compound type.
    • The compound type has a Version 2.1 MRM base type.
    • The compound type has a Version 2.1 type composition of simpleUnorderedSet and a Version 2.1 type content of closed.
    The type composition of simpleUnorderedSet is dropped from the model in WebSphere Message Broker Version 6.0.
    • If type content is closed then it is replaced by composition all with a BIP0191 warning message.
    • Otherwise, it is replaced by composition 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 that is created in this way 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 has a prefixed identifier and the -pl parameter is specified, it is local.
    4. If the element is of a compound type with a Version 2.1 MRM base type, it is local.
    5. If the element is a member of more than one compound type, it is global.
    6. If the -g parameter is specified, it is global.
    7. Otherwise, the element is local.
    The type of the xsd:element that is created in this way can be:
  • Any value constraints that belong to the element are processed as follows:
    • A Default constraint sets the default attribute of the xsd:element.
    • A Null Permitted constraint sets the nillable attribute of the xsd:element.
    • A Date Template constraint changes the xsd:simpleType of the xsd:element. (See Mapping of MRM simple types to schema simple types.)
    • All others restrict the xsd:simpleType of the xsd: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, but gives 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, because there is no equivalent xsd:facet.
  • 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 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 the mqsimigratemsgsets command creates

For each .mrp file encountered, a new message set project is created with a name that is 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 6.0 to the message set name SWIFT, whereas a Version 2.1 message set with name SWIFT and Level 2 migrates in Version 6.0 to SWIFT_2.

A message set folder and associated messageSet.mset file is created within the new project. The following points apply 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 re-created 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 because the Version 2.1 export operation freezes the message set.
Each message category that is encountered in the .mrp file results in a new .category file being created. Note:
  • Each transaction is replaced by the equivalent message category, containing all the messages in the transaction.
  • Each transaction category is replaced by the equivalent message category, containing all the messages in all the transactions that are 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 file exceeds 1000, and
  • The .mrp file can be partitioned into wholly disjoint subsets.

In Version 2.1, all elements and compound types are global. In Version 6.0, xsd:elements and xsd: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 xsd:elements and xsd:complex types in Version 6.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 with a value of 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 make certain elements 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, rerun the mqsimigratemsgsets command with the -g parameter.

Prefixed identifiers

In Version 2.1, a prefixed identifier was intended to indicate that an element is 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 xsd: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 xsd:elements being created. For example, A^X and B^X, but both are used more than once, resulting in two global xsd:elements with name X.

If duplicates are created, run the mqsimigratemsgsets command again, specifying the -pl parameter. This forces all referenced elements with prefixed identifiers to be created as local xsd:elements.

Embedded simple type

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, replace them by taking advantage of the mixed attribute of the containing xsd:complex type.

Embedded simple types were introduced primarily to model a complex XML element that contained data values that were interspersed between child elements. Each such data value was modelled explicitly 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 the mixed attribute of xsd:complexType. However, this only states that text can appear before 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 an unnamed local xsd:element of the appropriate simple type. The type itself is a restriction of the real underlying xsd:simple type, with a special name (commencing ComIbmMrm_Anon).

Compound type with an MRM base type

This situation produces a BIP0161 warning message and needs special treatment because the schema model is unable to cope with this compound construct. Compound elements are deprecated, so replace the use of compound elements with the use of normal elements that reference the global xsd:complexType, as described in 1 below, 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 just between) child elements. It implies nothing about the location or data type of the text.

There is no exact equivalent in XML schema, so the following steps have been taken:
  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 xsd:element of the appropriate simple type (to model the MRM base type information). The simple type is a restriction of the real underlying xsd: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, because the MRM base type information is lost only when it was never used actively in a message.

The special data types that are 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 that is 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 (see the 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 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 reference
mqsimigratemsgsets command