Message set migration notes

This topic provides information that you need to know when migrating message sets to WebSphere Message Broker Version 6.0. It contains the following sections:

If you are using the Version 5.1 Message Brokers Toolkit, replace all references in this topic to "Version 5.0" with "Version 5.1".

Migrating from Version 2.1

To migrate message sets from Version 2.1 to Version 6.0, use the mqsimigratemsgsets command to convert your Version 2.1 message set export files (.mrp) into Version 6.0 message set projects. Before you run the command, refer to the Migrating Message Sets from Version 2.1 topic, which provides detailed notes on its operation.

Migrating from Version 5.0

To migrate message sets from Version 5.0 to Version 6.0, no migration commands are necessary. The content of a Version 5.0 message set project can be read by the Version 6.0 Message Brokers Toolkit and is converted automatically to Version 6.0 format when it is modified and saved for the first time.

General migration information

The following information is applicable whether you have migrated from Version 2.1 or Version 5.0.
  • The CWF property Repeat Count has been superseded by the logical property Max Occurs, bringing the CWF physical format in line with TDS and XML physical formats, which already use Max Occurs to determine the number of repeats. A warning appears in the Problems view of the message editor for each element or group that had a CWF Repeat Count value set. Right-click the warning and click Quick Fix to resolve the issue.
    Note: In Version 5.0, if the CWF property Repeat Count is not set and Min Occurs is not equal to Max Occurs, the number of repeats is taken to be one. In Version 6.0, the number of repeats is taken to be Max Occurs. It is not possible to issue a warning for this situation. Such a message model is not created by the COBOL or C importers, so it can occur only if you have created a CWF message model using the Version 5.0 message editor.
  • The TDS physical format prior to Version 6.0 included embedded message identification by Message Key. The Message Key technique has been deprecated and is superseded by a technique called Message Identity. A warning appears in the Problems view of the message editor for each message that has a TDS Message Key value, and for each element or attribute that has TDS Interpret Element Value property set to Message Key. Right-click the warning and click Quick Fix to resolve the issue.

    Continue to use TDS Message Key if the message set will ever be deployed to a Version 5.0 or Version 2.1 broker, because these brokers do not support the Message Identity technique of embedded message identification.

  • The TDS physical format property Data Pattern is now validated by the Message Brokers Toolkit to ensure that it is a valid XML Schema regular expression. Errors appear in the Problems view of the message editor, and you must correct them manually using the editor. In particular, there have been some errata issued against the XML Schema specification concerning the escaping of meta-characters, which can cause validation errors to appear. To correct the errors, you might need to escape the hyphen character ("-") or the curly brace characters ( "{" and "}"), using the backslash character ("\"); for example "\{" or "\-". If you receive such errors when using an IBM-supplied message set, contact IBM to obtain a corrected version of the message set.
  • The default value or fixed value of an element or attribute, and enumeration values of a simple type, are now checked against the length, maximum length and minimum length facets of the simple type, if supplied. If a value does not comply with the facets, an error appears in the Problems view of the message editor. Right-click the error and click Quick Fix to resolve the issue, if a quick fix is available. Otherwise, correct the problem manually using the editor. This error is most likely to be encountered if you import a COBOL copybook into the Version 5.0 Fix Pack 2 or earlier version of the Message Brokers Toolkit.
  • The CWF and TDS Encoding Null and Encoding Null Value properties have been removed from local attributes, global attributes and attribute references. In XML Schema, only elements can have a Nillable property, therefore a null value cannot be carried by a data field that is modelled as an attribute. If you had specified CWF or TDS Encoding Null values for attributes in Version 5.0, they were ignored.
  • The TDS Repeating Element Delimiter property has been removed from local attributes and attribute references. In XML Schema, attributes cannot repeat. If you had specified TDS Repeating Element Delimiter values for attributes in Version 5.0, they were ignored.
  • For an element or attribute with simple type xsd:gMonth, the default value for the CWF, XML, and TDS Datetime Format property is now "--MM". In Version 5.0, the default value is "--MM--". This has been corrected to comply with an XML Schema errata.
  • When you are migrating, you do not have to redeploy your message sets because message dictionaries are upgraded in the broker database to Version 6.0 format by the mqsimigratecomponents command. However, if you do not redeploy a message set, and you observe a ParserException, such as a "checked vector error" or an "access violation", when you first exercise a message flow that uses the message set, you will have to redeploy the message set. This can happen if the message dictionary contains previously undetected bad data. In Version 6.0, a message dictionary is checked on first use; in Version 2.1 and Version 5.0, this is not the case.

Behavioral changes in the MRM parser

The following information is applicable whether you have migrated from Version 2.1 or Version 5.0:
  • XML physical format. Version 6.0 is now sensitive to xsi:type attributes in the XML document and modifies its behavior accordingly. xsi:type attributes are no longer treated as self-defining attributes, so they appear in the message tree with the name ‘type’ instead of ‘@type’. If your message flow logic is sensitive to xsi:type attributes in the message tree, change your message flow to comply with the new behavior. To retain pre-Version 6.0 logic in your message flows, set the environment variable MQSI_IGNORE_XSI_TYPE to any value, and the pre-Version 6.0 behavior will be adopted.
  • XML physical format. DOCTYPE information in an XML document does not appear in the logical message tree when parsed, but it is preserved from input document to output document because the MRM keeps a copy of the DOCTYPE internally. Prior to Version 6.0, this was an exact copy of the bit stream. In Version 6.0, the copying process causes some formatting white space to be lost. For example, the element declaration below in an input DOCTYPE:
    <!ELEMENT e0 (e1|e2)+ >
    will appear in the output as:
    <!ELEMENT e0 (e1|e2)+>
    The new behavior is consistent with the way that the XML physical format processes white space in all other XML constructs.
  • TDS physical format. For a group with logical property Composition set to Choice and TDS property Data Element Separation set to Fixed Length, the parser always assumes that the length of the choice data is that of the longest child of the group, and will always read and write that number of characters. Ensure that your messages comply with this, otherwise the parser will treat data that follows the choice as part of the choice. Prior to Version 6.0, the parser did not enforce this rule.
  • TDS physical format. If TDS element property Encoding Null is set to NullPadFill, it is only acted upon if the corresponding Length property is being used actively when parsing or writing. Prior to Version 6.0, NullPadFill was acted upon whether or not the Length property was being used actively.
  • TDS physical format. TDS property Data Element Separation is set to All Elements Delimited or Variable Length Elements Delimited. A complex element is now always treated as having variable length, regardless of its own Data Element Separation setting. This means that in the message bit stream, a Delimiter is expected between the complex element and any subsequent element, and a Repeating Element Delimiter is expected between all instances of a complex element, even if the complex element has a fixed length. Prior to Version 6.0, the parser did not enforce this rule, and for Variable Length Elements Delimited, the writer did not output delimiters when the length of the complex element was known.
  • TDS physical format. TDS property Data Element Separation is set to Use Data Pattern. If the regular expression that is specified for a data pattern returns a zero length match, this is now treated as an element being present with a zero-length value. Prior to Version 6.0, a zero-length match was treated as an element being omitted.
  • TDS physical format. TDS property Data Element Separation is set to Tagged Delimited. An extraneous delimiter that occurs after the last child of the group in the bit stream is no longer tolerated and will cause a parsing exception. Prior to Version 6.0, the parser did not enforce this rule. If this is a problem, consider modelling the extraneous delimiter using the TDS Group Terminator property.
  • TDS physical format. TDS property Data Element Separation is set to Tagged Delimited. In Version 6.0, when parsing a Tagged Delimited group, the parser attempts to make sense of groups where the members appear out of order in the message bit stream, even if the group Composition property is set to Sequence or OrderedSet. However, if the group contains either an embedded message or a complex element or group that cannot be identified from the bit stream, all the members of the group must appear in the bit stream in the same order that they are defined in the model. If they appear out of order, the group will not be parsed correctly and will have unpredictable results. One symptom of this is the appearance of self-defining elements in the message tree, caused by a failure to match an element to the model.

    A specific example of this is where your message contains an embedded message and you are using either the Message Key or Message Identity technique to identify the embedded message. If the element that is providing the message key or message identity value fails to be matched with the model, the parser will not know whether to interpret its value as a message key or message identity.

    Prior to Version 6.0, the parser attempted to make sense of all out-of-order Tagged Delimited groups, with a consequent reduction in performance. In Version 6.0, if this is a problem, consider modeling the unordered content of the group as an embedded child group with Composition set to UnorderedSet.

    A complex element or group can be identified from the bit stream if it provides a group indicator, a tag, or a data pattern, or if its child members provide a group indicator, tag or data pattern.

    Despite its name, there are circumstances where members of a Tagged Delimited group do not need to provide a tag; specifically, if the member is an embedded message or is a complex element or group.

  • TDS physical format. The TDS Data Element Separation property is set to Tagged Encoded Length. When writing, the encoded length is output as the number of characters in the data, to match the interpretation when parsing. Prior to Version 6.0, the encoded length was output as the number of bytes in the data, which did not match the interpretation when parsing if the data was not SBCS.
  • TDS physical format. When writing, if the number of repeats of an element or group is fixed in the model but the actual occurrences in the logical message tree exceed the number of repeats, and the Data Element Separation property is not one of the "Tagged" separations, the extra occurrences are discarded and do not appear in the output. Prior to Version 6.0, the extra occurrences appear in the output. If the extra repeats are expected to appear in the output, specify maxOccurs=-1 to indicate that the number of repeats is unbounded.
  • All physical formats. When writing dateTime fields that have been given a Format property of I, the output form depends on the logical type of the field, as described in DateTime as string data. Prior to Version 6.0, the output form was incorrectly the full yyyy-MM-dd'T'HH:mm:ssZZZ form.
  • Validation of input and output messages has been improved to provide additional detection of invalid messages. In Version 6.0, it is therefore possible for a message to be flagged as invalid when it was incorrectly not flagged in previous versions.