WebSphere MQ Integrator


Working with Messages

Version 2.1

SC34-6039-01
WebSphere MQ Integrator


Working with Messages

Version 2.1

SC34-6039-01
 Note!
Before using this information and the product it supports, be sure to read the general information under Appendix G,
“Notices” on page 265.

Second edition (March 2002)

This edition applies to IBM® WebSphere® MQ Integrator Version 2.1 and to all subsequent releases and
modifications until otherwise indicated in new editions.
© Copyright International Business Machines Corporation 2000, 2002. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
 Contents
Figures . . . . . . . . . . . . . . vii Creating a logical message model: an overview . . 35
The message set in the Control Center . . . . 36
Tables . . . . . . . . . . . . . . . ix | How to create a logical message model . . . . 37
Message model objects . . . . . . . . . . 39
Names and identifiers . . . . . . . . . . 39
About this book . . . . . . . . . . . xi | Message set . . . . . . . . . . . . . 41
Who this book is for . . . . . . . . . . . xii | Element . . . . . . . . . . . . . . 45
What you need to know to understand this book. . xii | Message . . . . . . . . . . . . . . 47
Terms used in this book . . . . . . . . . . xii | Type. . . . . . . . . . . . . . . . 49
Where to find more information . . . . . . . xiii | Category . . . . . . . . . . . . . . 55
| Element qualifier . . . . . . . . . . . 56
Summary of changes . . . . . . . . xv | Transaction . . . . . . . . . . . . . 58
| Changes for this edition . . . . . . . . . . xv | Element value . . . . . . . . . . . . 59
| Relationships between MRM objects . . . . . . 62
Part 1. Introduction . . . . . . . . . 1 | Implications for the logical model when defining
| messages of different wire formats. . . . . . . 63
| Predefined and self-defining elements and
Chapter 1. Introduction . . . . . . . . 3 | messages . . . . . . . . . . . . . . 63
Basic message concepts . . . . . . . . . . . 3 | Null handling . . . . . . . . . . . . . 64
Messages supported by WebSphere MQ Integrator. . 4 | Setting the value of null . . . . . . . . . 65
Why use predefined messages? . . . . . . . 5 | Data conversion . . . . . . . . . . . . . 66
| The broker’s view of the logical message model . . 66
Chapter 2. Parsers . . . . . . . . . . 7 | An example of a message in the broker . . . . 66
How a message is interpreted . . . . . . . . 7 | Using ESQL to manipulate the message tree . . 69
Using the supplied input nodes and parsers . . . 8 Managing message sets . . . . . . . . . . 76
Using plug-in nodes and parsers . . . . . . 10 Message set states . . . . . . . . . . . 76
Message tree structures . . . . . . . . . . 11 Message set versions . . . . . . . . . . 77
Message tree . . . . . . . . . . . . . 12 | Example: modeling the Video customer message . . 78
Environment tree . . . . . . . . . . . 14
LocalEnvironment tree. . . . . . . . . . 14 | Chapter 5. Working with a Custom Wire
ExceptionList tree . . . . . . . . . . . 16 | Format layer . . . . . . . . . . . . 83
| Setting properties for CWF . . . . . . . . . 83
Part 2. Messages in the MRM | Message set properties for CWF . . . . . . 83
domain . . . . . . . . . . . . . . 21 | Element member properties for CWF . . . . . 86
| Null handling in CWF . . . . . . . . . . 106
| Multipart messaging in CWF . . . . . . . . 106
Chapter 3. The MRM domain . . . . . 23 | Data conversion with CWF . . . . . . . . . 106
| What is the MRM? . . . . . . . . . . . . 23 | The relationship between the logical model and
| Modeling an MRM message . . . . . . . . . 25 | CWF . . . . . . . . . . . . . . . . 107
| Example: one logical model, two physical models 26 | Type property Type Composition . . . . . . 107
| Identifying an MRM message to the broker. . . 27 | Type property Type Content . . . . . . . . 108
| The logical message model . . . . . . . . . 27 | Type property Type . . . . . . . . . . 108
| Cardinality and optional elements . . . . . . 28 | Element value property Default Value . . . . 109
| Constraining the model . . . . . . . . . 28 | Example: modeling the Video customer message
| The physical message representation . . . . . . 29 | using CWF . . . . . . . . . . . . . . 109
Using the MRM utilities . . . . . . . . . . 30
| Importing a message model from external
| Chapter 6. Working with an XML
| sources . . . . . . . . . . . . . . . 30
Importing a message model from another | Format layer . . . . . . . . . . . . 111
message repository . . . . . . . . . . . 31 | How the MRM supports self-defining elements . . 111
Generating information from the message model 31 | Setting properties for the XML wire format layer 112
Planning your MRM model . . . . . . . . . 32 | Message set properties for XML . . . . . . 112
| Message properties for XML . . . . . . . 115
| Element properties for XML . . . . . . . 116
Chapter 4. The MRM logical message
| Message rendering options . . . . . . . . . 119
model . . . . . . . . . . . . . . . 35 | Null handling in the XML wire format . . . . . 119

© Copyright IBM Corp. 2000, 2002 iii

| NULL value . . . . . . . . . . . . . 120 Adding message sets and message set
| Null element and NullValAttr . . . . . . . 120 components to the workspace . . . . . . . 175
| Multipart messages in the XML wire format . . . 121 Importing message set definitions . . . . . . 176
| Data conversion with XML . . . . . . . . . 122 Importing C and COBOL data structures . . . 176
| Importing DTDs . . . . . . . . . . . . 122 Importing a DTD . . . . . . . . . . . 177
| Rules for XML wire format properties . . . . . 122 Generating information from message sets . . . 178
| General rules . . . . . . . . . . . . 122 Generating documentation . . . . . . . . 178
| The relationship between the logical model and the Generating language bindings . . . . . . . 179
| XML wire format . . . . . . . . . . . . 123 Generating run time dictionaries . . . . . . 180
| Compound type properties . . . . . . . . 123 Generating MRM message set definitions in
| Compound type member properties . . . . . 125 XML DTDs . . . . . . . . . . . . . 181
| Example: modeling the Video customer message Setting up message flows to handle these messages 182
| using XML . . . . . . . . . . . . . . 126 Input nodes . . . . . . . . . . . . . 182
| Other XML rendering options . . . . . . . 128 Output nodes . . . . . . . . . . . . 182
Other nodes . . . . . . . . . . . . . 182
| Chapter 7. Working with Tagged
| Delimited String messages . . . . . 131 Chapter 9. C and COBOL default
| TDS message characteristics . . . . . . . . 131 mappings . . . . . . . . . . . . . 183
| Specifying data element separation methods to
| model a message . . . . . . . . . . . 133
Part 3. Messages in the XML and
| Specifying special characters to model a
| message . . . . . . . . . . . . . . 134 JMS domains . . . . . . . . . . 189
| Setting properties for TDS wire format . . . . . 135
| Message set properties . . . . . . . . . 136 Chapter 10. The XML domain . . . . 191
| Message properties . . . . . . . . . . 138 Overview. . . . . . . . . . . . . . . 191
| Type properties. . . . . . . . . . . . 138 XML Declaration . . . . . . . . . . . . 192
| Type member properties. . . . . . . . . 141 XmlDecl . . . . . . . . . . . . . . 192
| Element properties . . . . . . . . . . 141 Version . . . . . . . . . . . . . . 192
| Null handling with the TDS wire format . . . . 144 Encoding . . . . . . . . . . . . . . 192
| Multipart messages with the TDS wire format . . 145 Standalone . . . . . . . . . . . . . 193
| Data conversion with TDS . . . . . . . . . 146 XML Declaration example . . . . . . . . 193
| Rules for TDS wire format properties . . . . . 146 The XML message body . . . . . . . . . . 193
| General rules . . . . . . . . . . . . 146 Element . . . . . . . . . . . . . . 194
| Restrictions for nesting compound types . . . 147 Attribute . . . . . . . . . . . . . . 194
| Omission and truncation of elements . . . . 148 Content . . . . . . . . . . . . . . 194
| The relationship between the logical model and the XML message body example: elements,
| TDS wire format . . . . . . . . . . . . 149 attributes, and content . . . . . . . . . 194
| Industry standard formats . . . . . . . . . 150 CDataSection . . . . . . . . . . . . 195
| ACORD AL3 . . . . . . . . . . . . 150 EntityReferenceStart and EntityReferenceEnd 195
| EDIFACT . . . . . . . . . . . . . . 151 Comment. . . . . . . . . . . . . . 196
| SWIFT. . . . . . . . . . . . . . . 153 ProcessingInstruction . . . . . . . . . . 196
| X12. . . . . . . . . . . . . . . . 153 AsisElementContent . . . . . . . . . . 197
| Example: modeling the Video customer message Document Type Declaration . . . . . . . . 198
| using TDS . . . . . . . . . . . . . . 154 DocTypeDecl . . . . . . . . . . . . 198
NotationDecl . . . . . . . . . . . . 198
Chapter 8. Working with MRM Entities . . . . . . . . . . . . . . 199
messages in the Control Center . . . 159 ElementDef . . . . . . . . . . . . . 200
Creating message sets and message set components 159 AttributeList. . . . . . . . . . . . . 200
Creating message sets . . . . . . . . . 159 AttributeDef. . . . . . . . . . . . . 200
Adding wire format layers . . . . . . . . 161 DocTypePI . . . . . . . . . . . . . 201
Adding a language binding . . . . . . . 162 WhiteSpace and DocTypeWhiteSpace . . . . 201
Creating messages. . . . . . . . . . . 165 DocTypeComment. . . . . . . . . . . 201
Working with message sets . . . . . . . . . 169 XML DTD example . . . . . . . . . . 202
Checking in and checking out message sets and Setting up message flows to handle these messages 206
components . . . . . . . . . . . . . 169 Input nodes . . . . . . . . . . . . . 206
Reordering elements in compound types . . . 171 Output nodes . . . . . . . . . . . . 206
Editing message sets and components . . . . 171 Other nodes . . . . . . . . . . . . . 206
Changing the state of a message set . . . . . 174
Using copy and paste . . . . . . . . . 175 Chapter 11. The JMS domain. . . . . 209
Setting up message flows to handle these messages 209

iv WebSphere MQ Integrator Working with Messages

 Input nodes . . . . . . . . . . . . . 209 The MQMDE parser . . . . . . . . . . . 244
Output nodes . . . . . . . . . . . . 210 The MQRFH parser . . . . . . . . . . . 245
Other nodes . . . . . . . . . . . . . 210 The MQRFH2 parser . . . . . . . . . . . 246
The MQRMH parser . . . . . . . . . . . 247
The MQSAPH parser . . . . . . . . . . . 248
Part 4. Messages in the New Era
The MQWIH parser . . . . . . . . . . . 249
of Networks domains . . . . . . . 211 The SMQ_BMH parser . . . . . . . . . . 250

Chapter 12. The New Era of Networks | Appendix B. TDS Mnemonics . . . . 251
domains . . . . . . . . . . . . . 213
The NEONMSG domain. . . . . . . . . . 214 | Appendix C. DATETIME formats . . . 253
The NEONMSG message body parser . . . . 214 | DATETIME as STRING data . . . . . . . . 253
Setting up message flow nodes to handle | DATETIME as CWF BINARY data . . . . . . 256
NEONMSG messages . . . . . . . . . 216 | DATETIME as CWF encoded values. . . . . . 256
The NEON domain . . . . . . . . . . . 224 | DATETIME component defaults . . . . . . . 257
The NEON message body parser . . . . . . 224 | Message set defaults . . . . . . . . . . . 257
Setting up message flow nodes to handle NEON
messages . . . . . . . . . . . . . . 225
| Appendix D. Default TDS message set
Control Center support for New Era of Networks
messages . . . . . . . . . . . . . . . 227 | properties . . . . . . . . . . . . . 259

| Appendix E. TDS error report . . . . 261

Part 5. Messages in the BLOB
domain . . . . . . . . . . . . . 229 | Appendix F. PDF error codes. . . . . 263

Chapter 13. The BLOB domain . . . . 231 Appendix G. Notices . . . . . . . . 265

Setting up message flows to handle these messages 231
Input nodes . . . . . . . . . . . . . 231
Output nodes . . . . . . . . . . . . 232 Glossary of terms and abbreviations 269

Bibliography . . . . . . . . . . . . 275
Part 6. Appendixes . . . . . . . . 233
WebSphere MQ Integrator Version 2.1
cross-platform publications . . . . . . . . . 275
Appendix A. Element definitions for WebSphere MQ Integrator Version 2.1
message parsers . . . . . . . . . . 235 platform-specific publications . . . . . . . . 275
Data types of fields and elements . . . . . . 236 MQSeries Everyplace publications . . . . . . 275
Data types of the fields in MQSeries headers 236 New Era of Networks Rules and Formatter
Data types for elements in the Properties folder 236 Support for WebSphere MQ Integrator publications 276
Data types for elements in the DestinationData Softcopy books . . . . . . . . . . . . . 276
folder . . . . . . . . . . . . . . . 236 Portable Document Format (PDF) . . . . . 276
Data types for elements in an MRM message 237 MQSeries information available on the Internet . . 277
Data types for an unstructured (BLOB) message 237
The MQCFH parser . . . . . . . . . . . 238 Index . . . . . . . . . . . . . . . 279
The MQCIH parser . . . . . . . . . . . 239
The MQDLH parser . . . . . . . . . . . 240
Sending your comments to IBM . . . 287
The MQIIH parser. . . . . . . . . . . . 241
The MQMD parser . . . . . . . . . . . 242

Contents v
vi WebSphere MQ Integrator Working with Messages
 Figures
1. Message tree structure . . . . . . . . . 13 | 25. ACORD AL3 message basic structure 150
2. Example Environment tree structure . . . . 14 | 26. EDIFACT message high level structure 151
3. LocalEnvironment tree structure . . . . . 15 | 27. EDIFACT message display . . . . . . . 152
4. Example ExceptionList tree structure . . . . 17 28. Generated run time dictionary . . . . . . 181
5. Message and LocalEnvironment propagation 29. Example XML message document. . . . . 191
for an exception . . . . . . . . . . . 18 30. Example XML message syntax element tree 192
| 6. MRM processes in the Control Center, the 31. Example XMLDecl document . . . . . . 193
| Configuration Manager, and the broker . . . 24 32. Example XMLDecl tree structure . . . . . 193
| 7. The Message Sets view. . . . . . . . . 36 33. Example XML message body document 194
| 8. Message grouping within sets . . . . . . 42 34. Example XML message body tree structure 195
| 9. Elements and instantiations . . . . . . . 45 35. Example XML Entity reference document 195
| 10. Example message structure . . . . . . . 47 36. Example XML Entity reference tree structure 196
| 11. Messages defined in the Control Center 48 37. Example XML comment document . . . . 196
| 12. Structure of a compound type . . . . . . 50 38. Example XML comment tree structure 196
| 13. Valid children within a compound type 53 39. Example XML processing instruction
| 14. Messages within categories . . . . . . . 55 document . . . . . . . . . . . . . 196
| 15. Element qualification . . . . . . . . . 57 40. Example XML processing instruction tree
| 16. Messages within transactions . . . . . . 58 structure . . . . . . . . . . . . . 197
| 17. Example of an element value. . . . . . . 60 41. Example XML DTD document . . . . . . 202
| 18. MRM objects and their relationship to each 42. Example XML DTD tree structure . . . . . 202
| other . . . . . . . . . . . . . . . 63 43. Example XML IntSubset tree structures (Part
| 19. An example message . . . . . . . . . 67 1 of 3) . . . . . . . . . . . . . . 203
| 20. Example message tree . . . . . . . . . 68 44. Example XML IntSubset tree structures (Part
| 21. The Video Customer message . . . . . . 78 2 of 3) . . . . . . . . . . . . . . 204
| 22. Video customer example: tree structure created 45. Example XML IntSubset tree structures (Part
| by the parser . . . . . . . . . . . . 82 3 of 3) . . . . . . . . . . . . . . 205
| 23. Tags and special characters in a TDS message 132 46. Sample New Era of Networks input message 214
| 24. TDS and multipart messages . . . . . . 145 | 47. ISO8601 datetime examples . . . . . . . 255

© Copyright IBM Corp. 2000, 2002 vii

viii WebSphere MQ Integrator Working with Messages
 Tables
1. Exception list name-value elements . . . . 19 | 40. Video customer example with CWF: element
| 2. General message set properties . . . . . . 43 | member properties . . . . . . . . . . 109
| 3. Use of the message set property Message Type | 41. XML message set properties. . . . . . . 112
| Prefix . . . . . . . . . . . . . . 44 | 42. XML message properties . . . . . . . . 115
| 4. General element properties . . . . . . . 46 | 43. XML element properties . . . . . . . . 116
| 5. General element member properties on the | 44. XML element member properties . . . . . 117
| Connection pane . . . . . . . . . . . 46 | 45. The effect of rendering options on XML
| 6. General message properties . . . . . . . 48 | output . . . . . . . . . . . . . . 118
| 7. The MRM simple types . . . . . . . . 49 | 46. XML rendering options for element members 119
| 8. General compound type properties. . . . . 50 | 47. XML options for encoding null values 120
| 9. Compound type Type Composition options 52 | 48. Combinations of Type Composition and Type
| 10. Compound type Type Content options if Type | Content for XML message modeling . . . . 124
| Composition is set to Message . . . . . . 52 | 49. Connection pane properties and their
| 11. Compound type Type Content options if Type | application to DTD element declarations . . 125
| Composition is not set to Message . . . . . 53 | 50. Connection pane properties and their
| 12. Valid children in compound types dependent | application to DTD attribute list declarations . 126
| on Type Composition and Type Content . . . 53 | 51. Video customer example with XML: message
| 13. Repeated and duplicate elements in a | set properties . . . . . . . . . . . 126
| compound type . . . . . . . . . . . 54 | 52. Video customer example with XML: message
| 14. General compound type member properties on | properties . . . . . . . . . . . . . 127
| the Connection pane . . . . . . . . . 54 | 53. Video customer example with XML: element
| 15. General category properties . . . . . . . 56 | properties . . . . . . . . . . . . . 127
| 16. General element qualifier properties . . . . 57 | 54. Video customer example with XML: type
| 17. General transaction properties . . . . . . 59 | member properties . . . . . . . . . . 128
| 18. General element value properties . . . . . 60 | 55. Video customer example with XML: updated
| 19. General element value member properties on | type member properties . . . . . . . . 128
| the Connection pane . . . . . . . . . 61 | 56. Video customer example with XML: using
| 20. Valid combinations of element value types and | XMLElement rendering . . . . . . . . 129
| roles . . . . . . . . . . . . . . . 62 | 57. Video customer example with XML: using
| 21. NULL permitted for element based on simple | XMLAttribute rendering . . . . . . . . 129
| types. . . . . . . . . . . . . . . 65 | 58. Video customer example with XML: using
| 22. Resolved Null Permitted . . . . . . . . 65 | attribute names and values . . . . . . . 129
| 23. Default null values for CWF and TDS. . . . 65 | 59. TDS: delimiter types . . . . . . . . . 134
| 24. Output MRM message properties . . . . . 70 | 60. TDS: message set properties . . . . . . 136
| 25. Video customer message model example: | 61. TDS: message properties . . . . . . . . 138
| message set properties . . . . . . . . . 78 | 62. TDS: type properties . . . . . . . . . 138
| 26. Video customer message model example: | 63. TDS: type member properties . . . . . . 141
| message properties . . . . . . . . . . 79 | 64. TDS: element properties . . . . . . . . 141
| 27. Video customer message model example: type | 65. TDS: element types and properties . . . . 144
| properties . . . . . . . . . . . . . 80 | 66. Permitted options for nested compound types 148
| 28. Video customer message model example: | 67. TDS permitted combinations of Type
| element properties . . . . . . . . . . 80 | Composition and Data Element Separation. . 149
| 29. Video customer message model example: | 68. TDS permitted values for Type Content 149
| element member properties . . . . . . . 81 | 69. SWIFT message high level block structure 153
| 30. CWF message set properties . . . . . . . 84 | 70. Video customer example with TDS: message
| 31. CWF BINARY element member properties 86 | set properties . . . . . . . . . . . 154
| 32. CWF BOOLEAN element member properties 88 | 71. Video customer example with TDS: message
| 33. CWF DATETIME element member properties 89 | properties . . . . . . . . . . . . . 155
| 34. CWF DECIMAL element member properties 93 | 72. Video customer example with TDS: type
| 35. CWF FLOAT element member properties 96 | properties . . . . . . . . . . . . . 155
| 36. CWF INTEGER element member properties 99 | 73. Video customer example with TDS: type
| 37. CWF STRING element member properties 102 | member properties . . . . . . . . . . 155
| 38. CWF compound element member properties 105 | 74. Video customer example with TDS: element
| 39. Video customer example with CWF: message | properties (part 1 of 4) . . . . . . . . 155
| set properties . . . . . . . . . . . 109 | 75. Video customer example with TDS: element
| properties (part 2 of 4) . . . . . . . . 156

© Copyright IBM Corp. 2000, 2002 ix

| 76. Video customer example with TDS: element 96. MQDLH parser element names, types, and
| properties (part 3 of 4) . . . . . . . . 156 attributes . . . . . . . . . . . . . 240
| 77. Video customer example with TDS: element 97. MQIIH parser element names, types, and
| properties (part 4 of 4) . . . . . . . . 157 attributes . . . . . . . . . . . . . 241
| 78. The elements of the Video customer message 165 98. MQMD parser orphan element names, types,
| 79. The Video customer elements with simple and attributes . . . . . . . . . . . 242
| types . . . . . . . . . . . . . . 166 99. MQMD parser native element names, types,
| 80. The Video customer elements with compound and attributes . . . . . . . . . . . 242
| types . . . . . . . . . . . . . . 167 100. MQMDE parser element names, types, and
| 81. The Video customer compound elements 167 attributes . . . . . . . . . . . . . 244
| 82. Elements within the Video customer 101. MQRFH parser element names, types, and
| compound types . . . . . . . . . . 168 attributes . . . . . . . . . . . . . 245
83. Editing relationships and properties: 102. MQRFH2 parser element names, types, and
check-out requirements . . . . . . . . 172 attributes . . . . . . . . . . . . . 246
84. C datatypes and their default settings in the 103. MQRMH parser element names, types, and
MRM . . . . . . . . . . . . . . 184 attributes . . . . . . . . . . . . . 247
85. COBOL datatypes and their default settings 104. MQSAPH parser element names, types, and
in the MRM . . . . . . . . . . . . 185 attributes . . . . . . . . . . . . . 248
86. Comparison of the functions of the 105. MQWIH parser element names, types, and
NEONRulesEvaluation node and NeonRules attributes . . . . . . . . . . . . . 249
node . . . . . . . . . . . . . . 219 106. SMQ_BMH parser element names, types, and
87. Behavior of the NeonRules node reformat attributes . . . . . . . . . . . . . 250
action . . . . . . . . . . . . . . 220 | 107. TDS mnemonics and associated properties 251
88. Behavior of the NEONRulesEvaluation node | 108. DATETIME formatting symbols . . . . . 253
transform action . . . . . . . . . . 221 | 109. DATETIME formatting examples . . . . . 255
89. Data types for fields in MQSeries headers 236 | 110. DATETIME symbols for CWF binary data 256
90. Data types for elements in the Properties | 111. DATETIME component defaults . . . . . 257
folder . . . . . . . . . . . . . . 236 | 112. Message set defaults for DATETIME . . . . 257
91. Data types for elements in the | 113. Default message set property values for TDS
DestinationData folder . . . . . . . . 236 | (part 1 of 2) . . . . . . . . . . . . 259
92. Data types for elements in an MRM message 237 | 114. Default message set property values for TDS
93. Data types for elements in an unstructured | (part 2 of 2) . . . . . . . . . . . . 259
(BLOB) message . . . . . . . . . . 237 | 115. Default type property values for TDS (part 1
94. MQCFH parser element names, types, and | of 2) . . . . . . . . . . . . . . 260
attributes . . . . . . . . . . . . . 238 | 116. Default type property values for TDS (part 2
95. MQCIH parser element names, types, and | of 2) . . . . . . . . . . . . . . 260
attributes . . . . . . . . . . . . . 239 | 117. PDF error codes for MRM . . . . . . . 263

x WebSphere MQ Integrator Working with Messages

 About this book
This book provides guidance and reference information that helps you to design,
develop, and manipulate messages that you can use with WebSphere MQ
Integrator Version 2.1.
v Part 1, “Introduction” on page 1 explains the concepts of message design and
definition, and discusses the types of messages supported by WebSphere MQ
Integrator and how they are processed.
v Part 2, “Messages in the MRM domain” on page 21 introduces the Message
Repository Manager (MRM) domain and the characteristics of messages within
this domain. It provides guidance to help you create and manage message sets
in this domain, and to configure message flows to process these messages.
v Part 3, “Messages in the XML and JMS domains” on page 189 discusses the
support for XML messages, shows how XML Document Type Definitions (DTDs)
are interpreted, and provides information to help you configure message flows
to process these messages.
v Part 4, “Messages in the New Era of Networks domains” on page 211 provides
information about messages in the NEON and NEONMSG domains. It also
describes how to design and configure message flows to process these messages.
v Part 5, “Messages in the BLOB domain” on page 229 discusses messages in the
BLOB domain, and the way in which they can be processed by message flows.

| The following appendixes provide further information and examples:

| v Appendix A, “Element definitions for message parsers” on page 235 provides
| reference information about the parsers that are supplied by WebSphere MQ
| Integrator to interpret the headers that might be used by messages in the broker
| domain.
| v Appendix B, “TDS Mnemonics” on page 251 details the mnemonics that are
| recognized.
| v Appendix C, “DATETIME formats” on page 253 explains the valid settings for
| DATETIME fields, and the effects of using combinations of the options.
| v Appendix D, “Default TDS message set properties” on page 259 lists the default
| settings for the properties for industry standard messages such as SWIFT.
| v Appendix E, “TDS error report” on page 261 provides an example of a message
| generated when an error has been made in defining TDS message characteristics.
| v Appendix F, “PDF error codes” on page 263 lists the error codes that might occur
| in error messages or log information generated by PDF internal messages.

A glossary and bibliography are also provided.

For further information about the product, and planning for its use, refer to the
WebSphere MQ Integrator Introduction and Planning book.

© Copyright IBM Corp. 2000, 2002 xi

About this book

Who this book is for

This book is for designers and developers of messages that will be used with
WebSphere MQ Integrator Version 2.1.

What you need to know to understand this book

To understand this book, you must be familiar with the concepts of WebSphere
MQ Integrator, described in the WebSphere MQ Integrator Introduction and Planning
book. You must also understand the facilities provided for message flow design
and development by the Control Center, described in the WebSphere MQ Integrator
Using the Control Center book.

If you want to define messages to the MRM, you must also have some knowledge
of the interface provided to the message repository by the Control Center. The
Control Center online help provides this information.

If you want to use generic XML or JMS messages, or both, you must have a basic
understanding of XML documents and Document Type Definitions (DTDs).

If you plan to use existing messages defined to the NEON and NEONMSG
domains through the New Era of Networks Rules and Formatter interfaces for
MQSeries® Integrator products, or to enhance or add to those messages, you must
have knowledge of these previous releases and the interfaces provided. For further
information, see “New Era of Networks Rules and Formatter Support for
WebSphere MQ Integrator publications” on page 276.

Terms used in this book

IBM MQSeries, already an important part of the WebSphere software platform for
e-business, is being more tightly associated with WebSphere and is to be known as
WebSphere MQ, to reflect the fundamental part that it plays in dynamic e-business.
WebSphere MQ Integrator Version 2.1 is the first product to be renamed. MQSeries
products will be renamed as part of the WebSphere family with each new release.
References to WebSphere MQ products, resources, and concepts within this book
continue to refer to MQSeries to reflect existing product names.

Some parts of the New Era of Networks component of WebSphere MQ Integrator

use the term NEON. References to NEON do not refer to NEON Systems Inc.

WebSphere MQ Integrator for z/OS™ also runs on OS/390® V2R8, V2R9, and
V2R10. All references in this book to z/OS are also applicable to these releases of
OS/390 unless otherwise stated. Customization and configuration differences
between the z/OS and OS/390 operating systems are transparent to the user.

All references in this book to Microsoft® Windows NT® are also applicable to
Windows® 2000 unless otherwise stated. WebSphere MQ Integrator components
that are installed and operated on Windows NT can also be installed and operated
on Windows 2000.

The term UNIX® is used throughout this book to refer to the operating systems
AIX®, HP-UX, and Solaris where their behavior is common.

The term distributed system is used to collectively refer to Windows NT and UNIX
where their behavior is common.

xii WebSphere MQ Integrator Working with Messages

 About this book
The term install_dir is used to refer to the directory in which WebSphere MQ
Integrator has been installed.

All new terms introduced in this book are defined in “Glossary of terms and
abbreviations” on page 269.

This book uses the following shortened names:

v MQSeries: a general term for IBM MQSeries Messaging products.
v MQSeries Publish/Subscribe: the MQSeries Publish/Subscribe SupportPac™
available on the Internet for several MQSeries server operating systems (the
Internet URL is given in “Where to find more information”).
v DB2®: a general term to encompass IBM DB2 Universal Database® Enterprise
Edition, Connect Enterprise Edition, and Extended Enterprise Edition.

Where to find more information

You should refer to “Bibliography” on page 275 for sources of further information
about WebSphere MQ Integrator and for other MQSeries family publications.

About this book xiii

xiv WebSphere MQ Integrator Working with Messages
 Summary of changes
This section describes changes in this edition of WebSphere MQ Integrator Working
with Messages. Changes since the previous edition of the book are marked by
vertical lines to the left of the changes.

| Changes for this edition

| v Part 2, “Messages in the MRM domain” on page 21 has been restructured and
| extended to provide more comprehensive information about messages in this
| domain. General information about message models is followed by detailed
| discussion of each of the physical formats supported.
| v Additional support information has been added in Appendix B, “TDS
| Mnemonics” on page 251, Appendix C, “DATETIME formats” on page 253,
| Appendix D, “Default TDS message set properties” on page 259, and
| Appendix E, “TDS error report” on page 261.
| v Minor technical corrections and editorial changes have been made throughout
| the book.

© Copyright IBM Corp. 2000, 2002 xv

Changes

xvi WebSphere MQ Integrator Working with Messages

Part 1. Introduction
Chapter 1. Introduction . . . . . . . . . . 3
Basic message concepts . . . . . . . . . . . 3
Messages supported by WebSphere MQ Integrator. . 4
Why use predefined messages? . . . . . . . 5

Chapter 2. Parsers . . . . . . . . . . . . 7
How a message is interpreted . . . . . . . . 7
Using the supplied input nodes and parsers . . . 8
MQSeries header parsers . . . . . . . . 8
Maintaining header integrity . . . . . . . 9
The Properties parser . . . . . . . . . 10
Using plug-in nodes and parsers . . . . . . 10
Message tree structures . . . . . . . . . . 11
Message tree . . . . . . . . . . . . . 12
Environment tree . . . . . . . . . . . 14
LocalEnvironment tree. . . . . . . . . . 14
ExceptionList tree . . . . . . . . . . . 16
Exception handling paths in a message flow 18

© Copyright IBM Corp. 2000, 2002 1

2 WebSphere MQ Integrator Working with Messages
 Chapter 1. Introduction
| Applications communicate by exchanging data. Within the WebSphere MQ world,
| the collections of data that applications exchange are known as messages. The
| content and structure of each message is known and agreed by the applications
| that send and receive it. The ways in which WebSphere MQ Integrator interprets
| and processes messages is explained in this book.

This chapter introduces:

v “Basic message concepts”
v “Messages supported by WebSphere MQ Integrator” on page 4

Basic message concepts

The following terms are used in WebSphere MQ Integrator to identify aspects of
message definition and processing:
Message
v Information that you want to send from one application to another
v One or more elements of data, also known as fields, perhaps defined as
a C header or COBOL datastructure
v A structured collection of bits and bytes
Domain
v A grouping of messages that define that way in which they are
processed
Element of data
v A piece of business information
v A data type
v Part of a C or COBOL structure

Depending on the type of message you are handling, you might also need to
know:
Message Set
v A collection of messages
v A central repository or dictionary of message definitions
v The message data associated with a business project
Message Type
v A value that uniquely identifies a message
Message Format
v A value that identifies a defined content and structure for a message

| If applications are communicating through WebSphere MQ Integrator, the

| messages that they send pass through a broker. When a broker receives a message
| for processing, it must first interpret the message and convert the bits and bytes of
| the datastream to enable its content to be manipulated. After processing, the
| message must be reconstructed ready for passing on to the next application. The
| interpretation and reconstruction are done by a message parser. For more
| information about parsers, and how they work with messages, see Chapter 2,
| “Parsers” on page 7.

© Copyright IBM Corp. 2000, 2002 3

 Message concepts
| WebSphere MQ Integrator supplies a large number of message parsers that handle
| messages created in different formats. These are described in “Messages supported
| by WebSphere MQ Integrator”. It also provides parsers for all MQSeries headers
| that might be used by those messages, if the applications are using MQSeries as
| their communications transport layer.

| If the parsers supplied by WebSphere MQ Integrator do not handle the messages

| that your applications exchange, you can develop your own message parsers.
| These can be called by the broker when a message of this different format is
| received. The WebSphere MQ Integrator Programming Guide describes how you can
| do this.

Messages supported by WebSphere MQ Integrator

The following message types can be used by applications communicating through
WebSphere MQ Integrator brokers:
v Predefined. This group of messages comprises:
– Messages that have content and structure defined to the WebSphere MQ
Integrator Message Repository Manager (MRM). These messages are in the
domain MRM.
Within this domain, a single MRM message can be expressed in one or more
of the following wire formats (physical representations):
- Custom Wire Format (CWF)
- Tagged/Delimited
- XML
- PDF (a restricted wire format unique to WebSphere MQ Integrator, not to
be confused with the PDF for Adobe Acrobat documents)

These messages are defined from scratch or imported using the Control
Center. The definitions are stored and managed in the message repository by
the Configuration Manager.

For more information, see Chapter 3, “The MRM domain” on page 23 and
Chapter 4, “The MRM logical message model” on page 35.
– Messages in the domains NEON and NEONMSG.
These messages must be defined using the New Era of Networks Formatter
user interface. They are stored in the New Era of Networks database, which
must be accessible by every broker to which message flows that access these
formats are deployed.
For more information, see Chapter 12, “The New Era of Networks domains”
on page 213.
v Self-defining. This group of messages carry the information about their
structure, content, and format with them. These messages are in either the JMS
or the XML domain.
For more information, see Chapter 10, “The XML domain” on page 191 and
Chapter 11, “The JMS domain” on page 209.
v Undefined. These messages are undefined in that their content and structure is
unknown. These messages are in the BLOB domain.
For more information, see Chapter 13, “The BLOB domain” on page 231.

WebSphere MQ Integrator provides parsers to interpret the body (message or

business data) of these messages. For more information about parsers, and how
they work, see Chapter 2, “Parsers” on page 7.

4 WebSphere MQ Integrator Working with Messages

 Supported message types
Why use predefined messages?
Because WebSphere MQ Integrator supports a wide variety of messages, you might
initially find it difficult to know how to make best use of its message processing
for your messages.

Although WebSphere MQ Integrator supports both predefined and self-defining

messages, the facilities provided for processing predefined messages are more
comprehensive, and you are recommended to take the time to plan and define
your messages to the MRM. The benefits include:
v You can create messages that conform to industry standards such as SWIFT.
v You can model messages that use the XML standard.
| v You can use the facilities of the broker to transform messages between one
| defined format and another, without the need for specialized programming. For
| example, you can set up a message flow to provide data conversion, removing
| the need for data conversion exits in MQSeries.
v You can use all of the supplied message processing nodes, providing the full
range of support for message manipulation.
v You can control access to your message definitions, because they are stored in a
central repository that is accessible only through a controlled interface (the
Control Center).
v You can control when updates are made to message definitions, and by whom.
This helps to ensure that messages are used consistently through your
organization by all applications.
v You can reuse message definitions in whole or in part by creating new messages
based on existing messages.
v You can generate Document Type Definitions (DTDs) for use by your
applications or by another Configuration Manager.
v You can export definitions to C or COBOL language data structures for use by
your applications.
v You can create message definitions by importing DTDs that have been generated
from another Configuration Manager or from another external source.
v You can create message definitions by importing existing C and COBOL data
structures to benefit from message processing without change to your
applications that manipulate messages in these formats.

You are very likely to find that your applications and business processes use a
combination of messages, including those defined by C and COBOL data structures
and by industry standards such as SWIFT, and those that are dynamic and
self-defining.

The broker and the message flows that provide message processing support all
these messages. You can therefore integrate applications that handle different types
of messages by providing message flows that perform the necessary
transformations to allow these applications to exchange messages successfully.

Chapter 1. Introduction 5
Supported message types

6 WebSphere MQ Integrator Working with Messages

 Chapter 2. Parsers
WebSphere MQ Integrator supplies parsers that process messages in the message
domains identified in “Messages supported by WebSphere MQ Integrator” on
page 4. It also provides parsers for the MQSeries headers that can be included in
the messages processed by message flows.

| A parser is a specialized program that reads input messages and constructs output
| messages. On input, it interprets the physical structure of the message and creates
| a logical structure in the form of a tree that is independent of the physical
| characteristics of the message. On output, it extracts the message data from the
| logical tree structure, and constructs the output message according to the physical
| characteristics that you have specified.

A programming interface is also provided to enable you to develop your own

parsers if the supplied parsers do not meet your requirements.

This chapter explains how parsers process your messages:

v “How a message is interpreted”
v “Maintaining header integrity” on page 9
v “Message tree structures” on page 11

How a message is interpreted

When a message arrives at a broker, it is received by an input node configured in a
message flow. Before the message can be processed by the message flow, it must be
interpreted by a parser to create a logical tree representation of the message data.

| The tree format (described in detail in “Message tree structures” on page 11)
| contains identical content to the bits from which it is created, but it is easier to
| manipulate within the message flow. The message flow nodes provide an interface
| (ESQL) for you to query and update message content within the tree, and facilities
| that help you to write the ESQL that you need to make your required changes. For
| more details about ESQL, refer to the WebSphere MQ Integrator ESQL Reference
| book.

The input node of a message flow can be:

v One of the three input nodes that are supplied by WebSphere MQ Integrator.
These are MQInput, MQeInput, and SCADAInput.
v A plug-in input node that you have written yourself, or that you have acquired
from another software vendor. (A plug-in node must be written using the
programming interface defined in the WebSphere MQ Integrator Programming
Guide.)

© Copyright IBM Corp. 2000, 2002 7

 Interpreting a message
The parser invoked to interpret the incoming message can be:
v One supplied by WebSphere MQ Integrator. These are supplied for the
supported message domains MRM, XML (the generic XML parser), NEONMSG,
NEON, and BLOB.
v A plug-in parser that you have written yourself, or that you have acquired from
another software vendor. (A plug-in parser must be written using the
programming interface defined in the WebSphere MQ Integrator Programming
Guide.)

Using the supplied input nodes and parsers

The supplied input nodes process only messages that are received across the
MQSeries transport protocol (this includes messages from SCADA devices). These
messages must start with a Message Queue Message Descriptor (MQMD) header.

The input node first calls the MQMD parser. A message can have zero or more
additional headers following the MQMD. The list of supported header parsers is
given in “MQSeries header parsers”.

| The broker calls the appropriate parser to interpret each additional header,
| following the order determined by the chaining of the headers. Each header is
| parsed independently. The fields within the header are parsed in a particular order
| that is governed by the parser. You cannot predict or rely on the order chosen.

When all the headers have been parsed, the message body is parsed. The input
node uses information in the message headers or specified in its own properties to
determine how the message body is parsed:
v If the message has an MQRFH or MQRFH2 header, the domain identified in the
header is used to decide which message parser is invoked.
v If the message does not have an MQRFH or MQRFH2 header, or the header
does not identify the domain, but the properties of the input node indicate the
domain of the message, the parser specified by the node property is invoked.
The parser specified can be a plug-in parser.
v If the message has a valid MQMD, but the message domain cannot be identified,
the message is handled as a binary object (BLOB). The BLOB parser is invoked.

If you set up the message headers or the input node properties of a supplied input
node to identify a plug-in parser, the way in which it interprets the message and
constructs the logical tree might differ from that described here.

MQSeries header parsers

WebSphere MQ Integrator provides a parser for each of the following message
headers:
v MQCFH
v MQCIH
v MQDLH
v MQIIH
v MQMD
v MQMDE
v MQRFH
v MQRFH2
v MQRMH
v MQSAPH
v MQWIH
v SMQ_BMH

8 WebSphere MQ Integrator Working with Messages

 Interpreting a message
Each parser is called in turn by the input node, if the corresponding header is
present in the message.

For more information about the message header parsers, and their contents, refer
to Appendix A, “Element definitions for message parsers” on page 235.

Warning
No parser is provided for messages or parts of messages in format
MQFMT_IMS_VAR_STRING. Data in this format is often preceded by an MQIIH
header (format MQFMT_IMS). WebSphere MQ Integrator treats such data as a
BLOB. Therefore if you change the CodedCharSetId or the Encoding of such a
message in a message flow, the MQFMT_IMS_VAR_STRING data is not converted,
and the message descriptor or preceding header does not correctly describe
that part of the message. If you require data conversion of these messages to
be performed, you must define the message in the MRM, or provide a
plug-in parser.

Maintaining header integrity

The broker ensures that the integrity of the headers that precede a message body is
maintained. The format of each part of the message is defined, either by the
Format field in the immediately preceding header (if the following part is a
recognized MQSeries format) or by the values set in the MQRFH or MQRFH2
header (if it is not):
v The format of the first header is known, because this must be MQMD.
| v The format of any subsequent header in the message is set in the Format field in
| the preceding header.
| v The format of the body corresponds to the message domain and the parser that
| must be invoked for the message body (for example, MRM). This information is
| set either in the MQRFH or MQRFH2 header, or in the message domain
| property of the input node that receives the message.

This process is repeated as many times as is required by the number of headers

that precede the message body. You do not have to populate these fields yourself:
the broker handles this sequence for you.

| The broker completes this process to ensure that Format fields in headers correctly
| identify each part of the message. If it does not do this, MQSeries might be unable
| to deliver the message. Because the message body parser is not a recognized
| MQSeries header format, this is replaced in the last header’s Format field by the
| value MQFMT_NONE. The original value in that field is stored in the Domain
| field within the MQRFH or MQRFH2 header to retain the information about the
| contents of the message body. If there is no MQRFH or MQRFH2, the information
| is stored in the Properties folder (described in “The Properties parser” on page 10).

| For example, if the MQRFH2 header immediately precedes the message body and
| its Format field is set to XML, indicating that the message body must be parsed by
| the generic XML parser, the MQRFH2 Domain field is set to XML, and its Format
| field reset to MQFMT_NONE.

These actions might result in information explicitly stored by an ESQL expression

being replaced by the broker.

Chapter 2. Parsers 9
 Interpreting a message
The Properties parser
All message trees generated by IBM supplied parsers include a properties folder
for the message. This folder is created and inserted in the tree following all the
headers but before the message data, as shown in Figure 1 on page 13.

The properties folder contains a set of standard properties that you can manipulate
in the message flow nodes in the same way as any other property. The majority of
these fields map to fields in the supported MQSeries headers, and are passed to
the appropriate parser when a message is delivered from one node to another.

For example, the MQRFH2 header contains information about the message set,
type, and format. These are stored in the Properties folder as MessageSet,
MessageType, and MessageFormat. If you intend to access these values using
ESQL within the message processing nodes, you should refer to these values in the
Properties folder, not directly to the fields in the headers from which they are
derived.

| If the message is converted to a bit stream, for example in an output node, any
| properties remaining solely in the Properties parser (that is, not in any header in
| the output messages) are not included in any part of the output message.

| The Properties parser ensures that the values in the header fields match the values
| in the Properties folder on input to, and output from, every node. On exit from a
| node, the Properties parser invokes each header parser with the values that it
| currently contains. It then requests values back from the header parser and
| updates its own values. Therefore if you have coded ESQL in the node that
| updates values either in the Properties folder, or in the header, or both, these
| values will always match when the tree is passed on from that node. However, if
| you have updated a field in both the Properties folder and the header with
| different values, you will find that the value that you set in the header has been
| overwritten by the value that you set in the Properties folder.

The standard properties are described in “Data types for elements in the Properties
folder” on page 236.

Using plug-in nodes and parsers

If you want your broker to accept messages from a transport protocol other than
MQSeries, or you want it to provide some specific processing on receipt of a
message, you can use either the Java™ or the C language programming interface to
create a new plug-in input node.

| This interface does not automatically generate a properties folder for a message
| (this folder is discussed in “The Properties parser”). It is not a requirement for a
| message to have a properties folder, although you might find it useful to create
| one to provide a consistent message tree structure regardless of input node. If you
| want a properties folder to be created in a message, and you are using a plug-in
| input node, you must do this yourself.

If you need to process messages that do not conform to any of the defined
message domains, you can use the C language programming interface to create a
new plug-in parser.

You must refer to the node interface to understand how it uses parsers, and if you
can configure it to modify its behavior. If the node uses a plug-in parser, the tree

10 WebSphere MQ Integrator Working with Messages

 Interpreting a message
structure created for the message might differ slightly from that described in
“Message tree structures”. Potential differences are noted where they occur.

The plug-in node and parser interfaces are described in the WebSphere MQ
Integrator Programming Guide.

Message tree structures

When a message is parsed, four hierarchical trees are created to represent the data
contained in the message and its headers. These are discussed in the following
sections:
v “Message tree” on page 12
v “Environment tree” on page 14
v “LocalEnvironment tree” on page 14
v “ExceptionList tree” on page 16

The tree structure created by the parser is largely independent of any message
format (for example, XML), except for the subtrees that are created by the message
body parsers within the message tree. The format of the common tree is discussed
in this chapter. The format of the message body tree is message dependent.

Each of the four trees created has a root element (with a name that is specific to
each tree). A message tree is made up of a number of discrete pieces of information
called elements. The root element has no parent and no siblings (siblings are
elements that share a single parent). The root is parent to a number of child
elements. Each child must have a parent, it can have zero or more siblings, and it
can have zero or more children.

The four trees are created for both supplied and plug-in input nodes and parsers.

The input node passes the tree structure on to subsequent message processing
nodes in the message flow:
v All message processing nodes can read the four message trees.
v The Filter node and the nodes that provide database access (DataBase,
DataDelete, and so on) can modify only the Environment and LocalEnvironment
trees.
v The Compute node can modify the Environment, LocalEnvironment, and
Exception trees that it receives as input, and can pass these on to subsequent
nodes if it chooses. It can create a new output message tree, optionally using
information from the input message tree. It can pass on the original input
message tree, or a new output message tree. It can also create new output
LocalEnvironment and Exception trees.
| You must decide what input data is copied to an output message by the
| Compute node. When you configure the Compute node, you can request that
| the entire message tree is copied. However, if you want all or part of the
| LocalEnvironment or Exception input trees to be copied to the output trees, you
| must copy this data yourself using ESQL in the node, and you must amend the
| Compute Mode property of the Compute node to reflect your requirements.
If no exception occurs during processing of the message, the tree structure and
content received by an individual node is determined by the action of previous
nodes in the flow, as indicated above.

Chapter 2. Parsers 11
 Message tree structures
If an exception does occur in the message flow, the content of the four trees
depends on several factors:
v If the exception is returned to the input node, and the input node catch terminal
is not connected, the trees are discarded. If the message is transactional, it is
returned to the input queue for further processing. When the message is
processed again, a new tree structure is created. If the message is not
transactional, it is discarded.
| v If the exception is returned to the input node and the catch terminal is
| connected, the Message, Environment, and LocalEnvironment trees that were
| created originally by the input node, and propagated through the out terminal,
| are restored, but any updates that you made to their content in the nodes that
| followed the input node are retained. If the nodes following the input node
| include a Compute node that creates a new LocalEnvironment or Message tree,
| those new trees are lost. The Exception tree reflects the one or more exceptions
| that have been recorded.
| v If the exception is caught within the message flow by a TryCatch node, the
| Message, Environment, and LocalEnvironment trees that were previously
| propagated through the try terminal of the TryCatch node are restored and
| propagated through the catch terminal. Any updates that you made to their
| content in the nodes that followed the TryCatch node are retained. If the nodes
| following the TryCatch node include a Compute node that creates a new
| LocalEnvironment or Message tree, those new trees are lost. The Exception tree
| reflects the one or more exceptions that have been recorded.
For more information about referring to the tree structures (using correlation
names), and creating or modifying their content, and for examples of these actions,
see WebSphere MQ Integrator ESQL Reference.

When the message processing is complete, the Environment, LocalEnvironment,

and Exception trees are discarded.

Message tree
The root of a message tree is called “Root”. The message tree is always present,
and is passed from node to node within a single instance of a message flow.

The message tree includes all the headers present in the message, in addition to
the message body. It also includes the Properties folder (described in “The
Properties parser” on page 10). This folder is always created as the first element of
the root of the message tree. It has relevance only while the message is being
processed by a WebSphere MQ Integrator message flow.

The message tree structure is shown in Figure 1 on page 13.

If a supplied parser has created the message tree, the Properties element is
followed by one or more headers, the first of which (therefore the second element)
must be the MQMD. If there are additional headers included in the message, these
appear in the tree in the same order as in the message. The last element beneath
the root of the message tree is always the message body.

If a plug-in parser has created the message tree, the Properties element, if present,
is followed by the message body.

The message tree created by the NEON and NEONMSG parsers does not conform
to the message tree described here: for details of the New Era of Networks domain

12 WebSphere MQ Integrator Working with Messages

 Message tree
message trees, see “The NEONMSG message body parser” on page 214 and “The
NEON message body parser” on page 224.

Root

Properties MQMD Other headers Body

Element1/Format1

Element2/Field2 Element3/Field3

Figure 1. Message tree structure. This has been created by a supplied input node and parser
(indicated by the presence of the MQMD). A reference to Element2 would therefore be
Root.XML.Element1.Element2 or Body.Element1.Element2.

The Body element, a structure of child elements (described below) that is

determined by the parser, represents the message content (data). The message body
might be:
v MRM, if the message is defined to the message repository
v NEONMSG or NEON if the message is defined to the New Era of Networks
rules and formats database
v XML, if the message is self-defining
v A value that identifies a plug-in parser

Each element within the parsed tree can be one of three types:
Name element A name element has a string associated with it,
which is the name of the element. An example of a
name element is XMLElement, described in
“Element” on page 194.
Value element A value element has a value associated with it. An
example of a value element is XMLContent,
described in “Content” on page 194.
Name-value element A name-value element is an optimization of the
case where a name element contains only a value
element and nothing else. The element contains
both a name and a value. An example of a
name-value element is XMLAttribute, described in
“Attribute” on page 194.

For more information about referring to elements in this tree, see “Using ESQL to
manipulate the message tree” on page 69 and the WebSphere MQ Integrator ESQL
Reference book.

Chapter 2. Parsers 13
Environment tree
Environment tree
The root of the Environment tree is called “Environment”. This tree is always
present in the input message: an empty Environment tree is created when a
message is received and parsed by the input node. It has no structure or content
until and unless you populate it using ESQL statements to define that structure
and content. Its content, if any, is not referenced or acted upon by WebSphere MQ
Integrator. This is in contrast to the LocalEnvironment tree (described in
“LocalEnvironment tree”), parts of which are used by WebSphere MQ Integrator.

You are recommended to create information in the Environment tree within a

folder called “Variables” (although this is not enforced).

Figure 2 shows an example of an Environment tree, and the ESQL statements that
you might use to create the tree.

Environment

Variables

bread wine cheese colors country

name currency

SET Environment.Variables =
ROW(’granary’ AS bread, ’reisling’ AS wine, ’stilton’ AS cheese);
SET Environment.Variables.Colors[] =
LIST{’yellow’, ’green’, ’blue’, ’red’, ’black’};
SET Environment.Variables.Country[] = LIST{ROW(’UK’ AS name, ’pound’ AS currency),
ROW(’USA’ AS name, ’dollar’ AS currency)};

Figure 2. Example Environment tree structure

LocalEnvironment tree
The root of the LocalEnvironment1 tree is called “LocalEnvironment”. This tree is
always present in the input message: an empty LocalEnvironment tree is created
when a message is received by the input node and parsed.

You can use the LocalEnvironment tree to store variables that can be referenced
and updated by message processing nodes that occur later in the message flow.
You can also use the LocalEnvironment tree to define destinations (that are internal
and external to the message flow) to which a message can be sent.

Figure 3 on page 15 shows the LocalEnvironment tree structure within a message

parsed by a supplied parser. The children of Destination are protocol-dependent,

1. LocalEnvironment was known as DestinationList in earlier releases of MQSeries Integrator. You can use these two names
interchangeably.

14 WebSphere MQ Integrator Working with Messages

 LocalEnvironment tree
therefore if you have a plug-in parser, the tree structure below the Destination
element has different content than that shown in the figure.

LocalEnvironment

Variables Destination WrittenDestination

MQ MQDestinationList RouterList

Defaults DestinationData Defaults DestinationData DestinationData

Figure 3. LocalEnvironment tree structure. This has been created by an IBM supplied input
node and parser, not a plug-in node and parser, asindicated by the structure of the
Destination element.

In Figure 3, LocalEnvironment has three children:

Variables
This folder is optional. If you create local environment variables, you are
recommended to store them in a folder called “Variables”. It provides a
work area that you can use to pass information between nodes. This folder
is never inspected or modified by any supplied node.
The variables you set can be changed by any message processing node that
generates an output message (for more details about using these nodes, see
the WebSphere MQ Integrator ESQL Reference), and they persist in the local
environment from the point in the message flow at which they are created
until the message is committed. If the message flow rolls back, these
variables are lost.
The variables in this folder are only persistent within a single instance of a
message flow. If you have multiple instances of a message passing through
the message flow, and need to pass information between them, you must
use an external database.
Destination
This folder consists of a number of children that indicate the transport
types to which the message is directed (the Transport identifiers).
If the transport protocol is MQSeries, the elements are each a single name
element, which can be MQ, MQDestinationList, or RouterList. If more
than one element exists, they are processed sequentially.
If the transport protocol is not MQSeries, the elements are defined by the
transport protocol.
You can configure message flow output nodes to examine the list of
destinations and send the message to those destinations, by setting the
property Destination Mode to Destination List. If you do so, you must
create this folder and its contents to define those destinations. You must
give this folder the name Destination. If you do not do so, the output node
is unable to deliver the messages.

Chapter 2. Parsers 15
LocalEnvironment tree
If you prefer, you can configure the output node to send messages to a
single fixed destination, by setting the property Destination Mode to Queue
Name or to Reply To Queue. If you select either of these fixed options, the
destination list has no effect on broker operations and you do not have to
create this folder.
If you choose to set up a destination list, and the transport protocol is
MQSeries, MQ and MQDestinationList can both be used to contain
information for MQSeries destinations. MQDestinationList was available in
MQSeries Integrator Version 2.0, Version 2.0.1, and Version 2.0.2, from
which you can migrate to this product. It is still supported, but you are
recommended to use MQ for all new message processing. The two names
are not true aliases: whichever you choose to use, every reference to the
element must be to the same name.
You can construct the MQ (and MQDestinationList) elements to contain a
single optional Defaults element. The Defaults element, if created, must be
the first child and must contain a set of name-value elements that give
default values for the message destination and its PUT options for that
parent.
You can also create a number of elements called DestinationData within
MQ. Each of these can be set up with a set of name-value elements that
defines a message destination and its PUT options. The set of elements that
define a destination is described in “Data types for elements in the
DestinationData folder” on page 236.
RouterList has a single child element called DestinationData, which has a
single entry called labelName. If you are using a dynamic routing scenario
involving the RouteToLabel and Label nodes, you must set up the
Destination folder with a RouterList that contains the reference labels.
WebSphere MQ Integrator Using the Control Center illustrates how you can
use these nodes and the RouterList to provide dynamic routing.
WrittenDestination
This folder contains the addresses to which the message has been written.
Its name is fixed. It is created by the message flow when a message is
propagated through the out terminal of an output node. It includes
transport specific information (for example, if the output message has been
put to an MQSeries queue, it includes the queue manager and queue
names). If the out terminal of the output node it not connected to another
node, this folder is not created.

ExceptionList tree
The root of the ExceptionList tree is called “ExceptionList”, and the tree itself
consists of a set of zero or more exception descriptions. The ExceptionList tree is
populated by the message flow if an exception occurs. If no exception conditions
occur during message flow processing, the exception list associated with that
message consists of a root element only. This is, in effect, an empty list of
exceptions.

The ExceptionList tree can be accessed by other nodes within the message flow
that receive the message after the exception has occurred. It can be modified only
by the Compute node.

If an exception condition occurs, message processing is suspended and an

exception is thrown. Control is passed back to a higher level, that is, an enclosing
catch block. An ExceptionList is built to describe the failure condition, and the

16 WebSphere MQ Integrator Working with Messages

 ExceptionList tree
whole message, together with the LocalEnvironment and the newly-populated
ExceptionList, is propagated through an exception handling message flow path.

The child of the ExceptionList is always “RecoverableException”. There is

normally only one child of the root, although more than one might be generated in
some circumstances. The child of the ExceptionList contains a number of children,
the last of which provides further information specific to the type of exception,
which can be one of:
v RecoverableException
v ParserException
v ConversionException
v UserException
v DatabaseException

Figure 4 shows the structure of the exception list tree for a

“RecoverableException”:

ExceptionList

RecoverableException

Recoverable
File Line Function Type Name Label Text Catalog Severity Number Exception (1)

Insert Recoverable
File Line Function Type Name Label Text Catalog Severity Number (2) Exception (3)

Type Text

Figure 4. Example ExceptionList tree structure

The exception description structure can be both repeated and nested to produce an
ExceptionList tree. In this tree:
v The depth (that is, the number of parent-child steps from the root) represents
increasingly detailed information for the same exception.
v The width of the tree represents the number of separate exception conditions
that occurred before processing was abandoned. This number is usually one, and
results in an exception tree that consists of a number of exception descriptions
connected as children of each other.
v At the numbered points in Figure 4:
1. This child can be one of “RecoverableException”, “ParserException”,
“DatabaseException”, “UserException”, or “ConversionException”. All of
these have the children shown: if present, the last child is the same element
as its parent.
2. This element might be repeated.
3. If present, this child contains the same children as its own parent.

Chapter 2. Parsers 17
ExceptionList tree
For examples of all these types of exception list tree, see the WebSphere MQ
Integrator ESQL Reference book.

The children in the tree take the form of a number of name-value elements that
give details of the exception, and zero or more name elements whose name is
“Insert”. The NLS (National Language Support) message number identified in a
name-value element in turn identifies a WebSphere MQ Integrator error message.
All error messages are defined in detail in the WebSphere MQ Integrator Messages
book. The Insert values are used to replace the variables within this message and
provide further detail of the precise cause of the exception.

The name-value elements within the exception list (shown in Figure 4 on page 17)
are described in Table 1 on page 19.

Exception handling paths in a message flow

Exception handling paths start at a failure terminal (most message processing
nodes have these) or the catch terminal of an input node, a TryCatch node, or an
AggregateReply node, but are no different in principle from a normal message
flow path. Such a flow consists of a set of interconnected message flow nodes
defined by the designer of message flow. The exception handling paths differ in
the kind of processing that they do to record or react to the exception. For
example, they might examine the exception list to determine the nature of the
error, and take appropriate action or log data from the message or exception.

The LocalEnvironment and message tree that are propagated to the exception
handling message flow path are those at the start of the exception path, not those
at the point when the exception is thrown. Figure 5 illustrates this point:
v A message (M1) and LocalEnvironment (L1) are being processed by a message
flow. They are passed through the TryCatch node to Compute1.
v Compute1 updates the message and LocalEnvironment and propagates a new
message (M2) and LocalEnvironment (L2) to the next node, Compute2.
v An exception is thrown in Compute2. If the failure terminal of Compute2 is not
connected (point B), the exception is propagated back to the TryCatch node, but
the message and LocalEnvironment are not. Therefore the exception handling
path starting at point A has access to the first message and LocalEnvironment,
M1 and L1. The Environment tree is also available and retains the content it had
when the exception occurred.
v If the failure terminal of Compute2 is connected (point B), the message and
LocalEnvironment M2 and L2 are propagated to the node connected to that
failure terminal. The Environment tree is also available and retains the content it
had when the exception occurred.

Figure 5. Message and LocalEnvironment propagation for an exception

18 WebSphere MQ Integrator Working with Messages

 ExceptionList tree
Table 1. Exception list name-value elements
Name Type Description
1
File String C++ source file name
1
Line Integer C++ source file line number
1
Function String C++ source function name
2
Type String Source object type
2
Name String Source object name
2
Label String Source object label
1
Text String Additional text
3
Catalog String NLS message catalog name4
Severity3 Integer 1=information
2=warning
3=error
Number3 Integer NLS message number4
Insert3 Type Integer The data type of the value:
0=Unknown
1=Boolean
2=Integer
3=Float
4=Decimal
5=Character
6=Time
7=GMT Time
8=Date
9=Timestamp
10=GMT Timestamp
11=Interval
12=BLOB
13=Bit Array
14=Pointer
Text String The data value
Notes:
1. The File, Line, Function, and Text elements should not be used for exception handling
decision making. These elements ensure that information can be written to a log for use
by IBM service personnel.
2. The Type, Name, and Label elements define the object (usually a message flow node)
that was processing the message when the exception condition occurred.
3. The Catalog, Severity, and Number elements define an NLS message: the Insert
elements that contain the two name-value elements shown define the inserts into that
NLS message.
4. NLS message catalog name and NLS message number refer to a translatable message
catalog and message number.

Chapter 2. Parsers 19
ExceptionList tree

20 WebSphere MQ Integrator Working with Messages

 Part 2. Messages in the MRM domain
Chapter 3. The MRM domain . . . . . . . . 23 | Implications for the logical model when defining
| What is the MRM? . . . . . . . . . . . . 23 | messages of different wire formats. . . . . . . 63
| Modeling an MRM message . . . . . . . . . 25 | Predefined and self-defining elements and
| Example: one logical model, two physical models 26 | messages . . . . . . . . . . . . . . 63
| Identifying an MRM message to the broker. . . 27 | Null handling . . . . . . . . . . . . . 64
| The logical message model . . . . . . . . . 27 | Setting the value of null . . . . . . . . . 65
| Cardinality and optional elements . . . . . . 28 | NULL handling for base types . . . . . . 66
| Constraining the model . . . . . . . . . 28 | Data conversion . . . . . . . . . . . . . 66
| The physical message representation . . . . . . 29 | The broker’s view of the logical message model . . 66
Using the MRM utilities . . . . . . . . . . 30 | An example of a message in the broker . . . . 66
| Importing a message model from external | Accessing elements from an message flow
| sources . . . . . . . . . . . . . . . 30 | node. . . . . . . . . . . . . . . 68
Importing a message model from another | Accessing simple types from a message flow
message repository . . . . . . . . . . . 31 | node. . . . . . . . . . . . . . . 69
Generating information from the message model 31 | Accessing base types from a message flow
Planning your MRM model . . . . . . . . . 32 | node. . . . . . . . . . . . . . . 69
| Accessing compound types from a message
Chapter 4. The MRM logical message model . . 35 | flow node . . . . . . . . . . . . . 69
Creating a logical message model: an overview . . 35 | Using ESQL to manipulate the message tree . . 69
The message set in the Control Center . . . . 36 | Referencing elements . . . . . . . . . 71
| How to create a logical message model . . . . 37 | Referencing simple types . . . . . . . . 72
| Creating a simple message . . . . . . . 38 | Referencing base types . . . . . . . . 72
| Creating a more complex message . . . . . 38 | Referencing compound types . . . . . . 73
| Creating a multipart message . . . . . . 38 | Null handling . . . . . . . . . . . 74
Message model objects . . . . . . . . . . 39 Managing message sets . . . . . . . . . . 76
Names and identifiers . . . . . . . . . . 39 Message set states . . . . . . . . . . . 76
| Prefixed identifiers . . . . . . . . . . 40 Normal . . . . . . . . . . . . . . 76
| Message set . . . . . . . . . . . . . 41 Locked . . . . . . . . . . . . . . 76
| Control Center property panes . . . . . . 42 Frozen . . . . . . . . . . . . . . 76
| Message set properties. . . . . . . . . 43 Finalized . . . . . . . . . . . . . 77
| Element . . . . . . . . . . . . . . 45 Message set versions . . . . . . . . . . 77
| Control Center property panes . . . . . . 45 | Example: modeling the Video customer message . . 78
| Element properties . . . . . . . . . . 46
| Element member properties . . . . . . . 46 | Chapter 5. Working with a Custom Wire Format
| Message . . . . . . . . . . . . . . 47 | layer . . . . . . . . . . . . . . . . 83
| Control Center property panes . . . . . . 47 | Setting properties for CWF . . . . . . . . . 83
| Message properties . . . . . . . . . . 48 | Message set properties for CWF . . . . . . 83
| Type. . . . . . . . . . . . . . . . 49 | Element member properties for CWF . . . . . 86
| Control Center property panes . . . . . . 50 | BINARY . . . . . . . . . . . . . 86
| Compound type properties . . . . . . . 50 | BOOLEAN . . . . . . . . . . . . 88
| Compound type member properties . . . . 54 | DATETIME . . . . . . . . . . . . 89
| Category . . . . . . . . . . . . . . 55 | DECIMAL . . . . . . . . . . . . . 93
| Control Center property panes . . . . . . 55 | FLOAT . . . . . . . . . . . . . . 96
| Category properties. . . . . . . . . . 56 | INTEGER . . . . . . . . . . . . . 99
| Element qualifier . . . . . . . . . . . 56 | STRING . . . . . . . . . . . . . 102
| Control Center property panes . . . . . . 57 | Compound element . . . . . . . . . 105
| Element qualifier properties . . . . . . . 57 | Null handling in CWF . . . . . . . . . . 106
| Element qualifier member properties . . . . 58 | Multipart messaging in CWF . . . . . . . . 106
| Transaction . . . . . . . . . . . . . 58 | Data conversion with CWF . . . . . . . . . 106
| Control Center property panes . . . . . . 58 | The relationship between the logical model and
| Transaction properties . . . . . . . . . 59 | CWF . . . . . . . . . . . . . . . . 107
| Element value . . . . . . . . . . . . 59 | Type property Type Composition . . . . . . 107
| Control Center property panes . . . . . . 60 | Type property Type Content . . . . . . . . 108
| Element value properties . . . . . . . . 60 | Type property Type . . . . . . . . . . 108
| Element value member properties . . . . . 61 | Element value property Default Value . . . . 109
| Relationships between MRM objects . . . . . . 62

© Copyright IBM Corp. 2000, 2002 21

| Example: modeling the Video customer message Creating message sets and message set components 159
| using CWF . . . . . . . . . . . . . . 109 Creating message sets . . . . . . . . . 159
Creating a message set with the same name
| Chapter 6. Working with an XML Format layer 111 as an existing message set . . . . . . . 161
| How the MRM supports self-defining elements . . 111 Adding wire format layers . . . . . . . . 161
| Setting properties for the XML wire format layer 112 Using padding characters in wire formats 162
| Message set properties for XML . . . . . . 112 Adding a language binding . . . . . . . 162
| Inline DTDs and the DOCTYPE Text property 114 The C language layer. . . . . . . . . 163
| Message properties for XML . . . . . . . 115 The COBOL language layer . . . . . . 164
| Element properties for XML . . . . . . . 116 Creating messages. . . . . . . . . . . 165
| Element member properties for XML . . . 117 Identify the logical model . . . . . . . 165
| Message rendering options . . . . . . . . . 119 Create the elements of simple types . . . . 166
| Null handling in the XML wire format . . . . . 119 Create the compound types . . . . . . 167
| NULL value . . . . . . . . . . . . . 120 Create compound elements . . . . . . . 167
| Null element and NullValAttr . . . . . . . 120 Add elements to the compound types . . . 167
| Multipart messages in the XML wire format . . . 121 Create the message . . . . . . . . . 168
| Data conversion with XML . . . . . . . . . 122 Create a category . . . . . . . . . . 168
| Importing DTDs . . . . . . . . . . . . 122 Make elements repeatable . . . . . . . 168
| Rules for XML wire format properties . . . . . 122 Using the SmartGuides . . . . . . . . 168
| General rules . . . . . . . . . . . . 122 Working with message sets . . . . . . . . . 169
| The relationship between the logical model and the Checking in and checking out message sets and
| XML wire format . . . . . . . . . . . . 123 components . . . . . . . . . . . . . 169
| Compound type properties . . . . . . . . 123 Reordering elements in compound types . . . 171
| Compound type member properties . . . . . 125 Editing message sets and components . . . . 171
| Example: modeling the Video customer message Changing the state of a message set . . . . . 174
| using XML . . . . . . . . . . . . . . 126 Using copy and paste . . . . . . . . . 175
| Other XML rendering options . . . . . . . 128 Adding message sets and message set
components to the workspace . . . . . . . 175
| Chapter 7. Working with Tagged Delimited Importing message set definitions . . . . . . 176
| String messages . . . . . . . . . . . . 131 Importing C and COBOL data structures . . . 176
| TDS message characteristics . . . . . . . . 131 Importing a DTD . . . . . . . . . . . 177
| Specifying data element separation methods to Generating information from message sets . . . 178
| model a message . . . . . . . . . . . 133 Generating documentation . . . . . . . . 178
| Specifying special characters to model a Generating a message book. . . . . . . 178
| message . . . . . . . . . . . . . . 134 Generating a glossary . . . . . . . . 179
| Using mnemonics as special characters . . . 135 Generating language bindings . . . . . . . 179
| Setting properties for TDS wire format . . . . . 135 Generating run time dictionaries . . . . . . 180
| Message set properties . . . . . . . . . 136 Generating MRM message set definitions in
| Message properties . . . . . . . . . . 138 XML DTDs . . . . . . . . . . . . . 181
| Type properties. . . . . . . . . . . . 138 Setting up message flows to handle these messages 182
| Type member properties. . . . . . . . . 141 Input nodes . . . . . . . . . . . . . 182
| Element properties . . . . . . . . . . 141 Output nodes . . . . . . . . . . . . 182
| Null handling with the TDS wire format . . . . 144 Other nodes . . . . . . . . . . . . . 182
| Multipart messages with the TDS wire format . . 145
| Data conversion with TDS . . . . . . . . . 146 Chapter 9. C and COBOL default mappings . . 183
| Rules for TDS wire format properties . . . . . 146
| General rules . . . . . . . . . . . . 146
| Restrictions for nesting compound types . . . 147
| Omission and truncation of elements . . . . 148
| The relationship between the logical model and the
| TDS wire format . . . . . . . . . . . . 149
| Industry standard formats . . . . . . . . . 150
| ACORD AL3 . . . . . . . . . . . . 150
| EDIFACT . . . . . . . . . . . . . . 151
| SWIFT. . . . . . . . . . . . . . . 153
| X12. . . . . . . . . . . . . . . . 153
| Example: modeling the Video customer message
| using TDS . . . . . . . . . . . . . . 154

Chapter 8. Working with MRM messages in the

Control Center . . . . . . . . . . . . 159

22 WebSphere MQ Integrator Working with Messages

 Chapter 3. The MRM domain
| This chapter and the following chapters in this part of the book explain the
| message model for the Message Repository Manager (MRM). They introduce the
| concepts associated with the MRM, and build on these to explain how to model a
| message, its logical and physical representations, the message tree created by the
| MRM parser in a broker, how you can use ESQL within message flow nodes to
| manipulate that tree, and how to use the Message Sets view of the Control Center.

| Chapter 4, “The MRM logical message model” on page 35 to Chapter 7, “Working

| with Tagged Delimited String messages” on page 131 inclusive use a simple
| example of a video store to show you how you can model a message and use the
| options in the Control Center wire format layer tabs (CWF, XML, and TDS) to alter
| the physical representation of the message.
| v This chapter introduces the concepts at a high level, in preparation for more
| detailed discussion in the chapters that follow.
| v Chapter 4, “The MRM logical message model” on page 35 provides details of the
| MRM logical message model, including the purpose of the properties displayed
| in the Control Center, and how you can use them. It also discusses how the
| structures available in the model affect the representation of the model in the
| parsed message, and how you can write ESQL in a message flow node to access
| the data held in the tree structure.
| v Chapter 5, “Working with a Custom Wire Format layer” on page 83 details the
| properties that you can use to define a message that has a fixed format. This
| layer enables you to model legacy messages typically created using C headers
| and COBOL copybooks.
| v Chapter 6, “Working with an XML Format layer” on page 111 details the
| properties that you can use to model a message that has a physical
| representation of XML.
| v Chapter 7, “Working with Tagged Delimited String messages” on page 131
| details the properties that you can use to model a message that has a physical
| representation in the form of data fields that are delimited by user-defined tags
| and special characters.
| v Chapter 8, “Working with MRM messages in the Control Center” on page 159
| shows you how you can use the Control Center Message Sets view to define all
| these messages. It uses the information provided in the preceding chapters to
| provide practical examples of message modeling.

| What is the MRM?

| The MRM is a component within WebSphere MQ Integrator that:
| v Provides support for you to model messages in the Control Center, and store
| their definitions centrally in the message repository
| v Provides a parser that works in the broker to parse inbound messages and a
| message writer to construct outbound messages that conform to the message
| models that you have created

| The components involved in modeling and parsing are shown in Figure 6 on

| page 24.
|

© Copyright IBM Corp. 2000, 2002 23

 What is the MRM?
|
Control Center Configuration Broker
Manager
MRM
MRM Parser and
Modeler writer

Message
Repository
|
| Figure 6. MRM processes in the Control Center, the Configuration Manager, and the broker
|
| You can use the Control Center interface to the MRM modeler to help you to
| model the messages that you want WebSphere MQ Integrator to handle. When you
| check in a message definition that you have created in the Control Center, it is
| stored in the message repository by the Configuration Manager.

| The Control Center interacts with the Configuration Manager to provide some
| checks that your model is valid, and to store the model safely in the message
| repository from where it is accessible by users of the Control Center. The
| Configuration Manager can protect the message model both by checking the
| authorization of users that want to access it, and by providing locking mechanisms
| that prevent different users making conflicting updates.

| When you assign a message set that contains a set of one or more related messages
| to a broker, and deploy that assignment, the definitions saved in the message
| repository are retrieved and sent to the broker in the form of a message dictionary.
| A dictionary describes the message model associated with the message set. MRM
| message sets are the only type of message sets that can be deployed from the
| Control Center.

| You do not have to deploy New Era of Networks messages to a broker, but you
| must ensure that their definition is available to the broker. Refer to the WebSphere
| MQ Integrator Administration Guide for information about how to do this.

| All the other types of message set (XML, JMSMap, and JMSStream) do not
| generate a dictionary to describe the message set because the messages are treated
| by the broker as self-defining.

| When a message is received by a broker, it is parsed (as described in Chapter 2,

| “Parsers” on page 7). If the message (in its headers) or the input node (of the
| message flow that receives the message) identifies the message as an MRM
| message, the broker invokes the MRM parser. The parser determines additional
| information about message set, message type, and message format (also defined in
| either message header or input node) and matches these with a deployed message
| dictionary.

| The MRM parser uses the dictionary to interpret the data within the incoming
| message, and produces a tree structure to represent the message. The tree structure
| is the broker’s view of the logical message model. The message tree is independent
| of its physical representation. You can manipulate the contents of the tree in the
| nodes within a message flow, to add new business data or to alter existing
| business data, or both.

24 WebSphere MQ Integrator Working with Messages

 What is the MRM?
| The dictionary is also used by the MRM message writer when it constructs an
| output message. The MRM message writer maps the tree structure that has been
| processed within the broker to the physical format required by the outgoing
| message with reference to a dictionary. The output physical format does not have
| to be the same as the input physical format.

| For example, the input message might be in XML format, and the output message
| might be a fixed format COBOL structure. Or both input and output messages
| might be in XML format, but with the contents constructed differently. The
| definitions within the dictionary or dictionaries enable the parser to parse the one
| and construct the other, thus providing a different physical representation of the
| message data. This ability is a powerful facility that saves the message designer a
| considerable amount of coding effort.

| The MRM therefore allows you to make a clear separation between the logical
| representation of a message and the physical representation, and you can use the
| model of the data to interpret and to construct different physical representations.

| These concepts are explored further in:

| v “Modeling an MRM message”
| v “The logical message model” on page 27
| v “The physical message representation” on page 29
| v “Using the MRM utilities” on page 30

| The chapter concludes with the section “Planning your MRM model” on page 32
| that addresses the common questions that you might have about how you can plan
| for message modeling.

| Modeling an MRM message

| You can think of a message as a packet of data that is sent from one place to
| another. Usually a message is standalone and does not require any further data to
| convey its meaning. The sender and receiver of the message have agreed the
| structure of the message and what each field means.

| In the MRM, the message is considered in two parts:

| v The logical message model, described in “The logical message model” on
| page 27. This is the piece of the message that conveys the business data, devoid
| of its physical representation (how it appears in a bit stream on the wire). It is
| independent of platform and the way in which message is constructed.
| For example, if you define a message that conveys information about a debit of
| an individual’s bank account, it can be represented in different physical forms
| on the wire (in XML, or a fixed structure such as a COBOL copybook). The
| business meaning and data is the same in both cases: only the physical layout
| has changed.
| v The physical representation, described in “The physical message representation”
| on page 29. This is how the data is physically laid out on the wire. A single
| logical message model might have several different ways in which it can be
| physically represented.
| This can be very useful, because it handles situations in which you need to
| connect two different systems. For example, you might have a legacy style
| application that expects data to be passed to it the form of COBOL copybooks,
| that needs to communicate with a system that expects data in the form of XML.
| Both applications work with the same data, and it would be undesirable to alter

Chapter 3. The MRM domain 25

 Modeling an MRM message
| either application. By routing the messages through WebSphere MQ Integrator,
| you can use a single logical model with multiple physical representations to
| provide the transformation that is required.

| To model an MRM mesage, you must complete the following steps:

| 1. Create the logical model by building up the MRM objects to represent your
| message data.
| 2. Create the physical representations by adding the required wire format layers
| to the logical model. These representations are used by the MRM parser to
| produce a structure that conforms to the logical model.
| The structure is an abstraction of the original message, in a form that can be
| manipulated by ESQL in the nodes of a message flow. It is created by the
| parser is in the form of a tree (described in Chapter 2, “Parsers” on page 7).
| Even if the same message model is presented to WebSphere MQ Integrator in
| different physical representations, the parsed tree is the same. The elements
| within the tree and the structure of the tree convey the business meaning held
| within the message.

| Example: one logical model, two physical models

| The following example shows how a very simple message can be split into a
| logical model and separate physical models for the message data on the wire.

| The logical model defines the structure and order of the message. In the following
| example, the three elements are based on the simple type INTEGER, and C follows
| B follows A:
| int A;
| int B;
| int C;

| The CWF physical representation of this model indicates the number of bits that
| each integer takes up. An int element maps to CWF physical type INTEGER, and
| its length can be 1, 2, or 4 bytes.

| The XML physical representation of this model is as follows:

| <A>xxxxxxxx</A>
| <B>xxxxxxxx</B>
| <C>xxxxxxxx</C>

| where xxxxxxxx is the value of the integer represented as a string. (XML deals only
| with strings.)

| This shows that the logical model is unchanged. It is constant, regardless of the
| physical representation that you choose to model on top of it, using the wire
| format layers provided by the MRM. The MRM parser is able to transform the
| message from the input physical representation (which it parses to create an
| internal, physically independent tree) to any number of output representations that
| it constructs from this internal tree, based on the wire format layers that you have
| defined.

26 WebSphere MQ Integrator Working with Messages

 Modeling an MRM message
| Identifying an MRM message to the broker
| When a broker is processing messages, it must be able to determine certain
| message characteristics to ensure that it invokes the correct parser, and, if
| appropriate, access the correct message dictionary to be able to map the data
| correctly. These details can be obtained from one of two places:
| 1. The MQRFH or MQRFH2 header
| 2. The input node of the message flow
| You can use this option if the input message does not have an MQRFH or
| MQRFH2 header.

| The MQRFH or MQRFH2 header always takes precedence, if one is included in the
| message.

| The key pieces of data that must be specified are:

| v The message domain. This identifies the parser, which must be MRM.
| v The message set. This specifies the identifier that is automatically generated
| when you create the message set.
| v The message type. This specifies the identifier that you gave to the message
| when you created it. This identifies the message model.
| v The message format. This specifies the wire format layer identifier. It identifies
| the particular physical representation of the message as defined in the specified
| wire format layer.

| See Chapter 1, “Introduction” on page 3 for a further discussion of these terms.

| The logical message model

| The logical message model is the representation of the message devoid of any
| information that is platform-specific (for example, the number of bytes that are
| used to represent an integer), and any information that is associated with the
| message’s physical appearance, known as its rendering. The logical message model
| defines the structure of the data.

| Within the MRM, the logical message model is built up of at least the following
| entities:
| Message set
| A message set is a logical grouping of messages. When you have
| completed the definition of a message set, you can assign and deploy it to
| a WebSphere MQ Integrator broker. You cannot deploy at a more granular
| level, for example, by message.
| Message
| A message is a logical model that is built up of types and elements.
| Type A type can be simple type or compound type:
| v A simple type is one of seven core types that are supplied by the MRM
| to cover the basic data types. These include INTEGER and STRING. All
| seven types are described in Table 7 on page 49.
| v A compound type is one that you have defined yourself. It is used to
| represent groups of elements and types that create a substructure within
| a message. A message is always based on a single compound type, in
| effect the highest level (in COBOL, the ’01’ level) in the message.

Chapter 3. The MRM domain 27

 Logical message model
| Types can be thought of as library parts, in that you can use these parts to
| construct your final message. A type has no meaning until it instantiated as
| (or within) an element or message. You can never directly address a type,
| simple or compound, using ESQL from a message flow in the broker. It is
| the element or message within which you have instantiated the type that
| you can address.
| Element
| An element is a discrete piece of information. It is always based on a type
| (simple or compound), and is an instantiation of a type. Its content gives a
| meaning to the type. For example, the element is not a STRING, but is a
| Customer Name based on the simple type STRING. An element might be
| based on an INTEGER, but the meaning of the number contained is
| defined by the element representing (and therefore named) AccountBalance.
| The Customer Name and AccountBalance elements can be addressed directly
| using ESQL in the message flow.

| There are other constructs in the model: the list above describes the minimum set
| of entities that you must include to build a valid logical model that you can deploy
| to the broker. Detailed information about these and the additional constructs are
| provided in “Message model objects” on page 39.

| The logical message model is displayed in the Message Sets view in the Control
| Center. If you select an MRM entity from the message set tree in the left pane, for
| example an element, the logical message model properties for that entity are
| displayed in the right pane.

| Cardinality and optional elements

| When you have created the basic structure of a message using the Control Center,
| you must consider what level of complexity needs to be added to the model:
| v Can an element repeat? Is so how many times can it repeat? The default is that
| an element does not repeat, that is, there is one and only one instance.
| v Is an element optional or mandatory? The default is that an element is
| mandatory.

| You can modify these defaults for documentation purposes by updating the
| properties on the Connection pane for compound types and elements (see “Type”
| on page 49 and “Element” on page 45). However, these properties, and the
| conditions they define, are not enforced by the broker.

| Constraining the model

| When you have defined a logical message model, you might find that it is
| necessary to impose some constraints on the model that further clarify its intended
| purpose. For example:
| v Does an element have a minimum or a maximum length?
| v Does an element have a default value?

| You can model these constraints in the MRM using element values. You can add an
| element value to an element (or to an element qualifier) to specify the nature of the
| restriction. For example, you can define a maximum length for an element of type
| STRING. If you associate an element value with an element, a Connection pane is
| added to the element properties pane that defines the constraints in force. This is
| explained further in Chapter 4, “The MRM logical message model” on page 35.

28 WebSphere MQ Integrator Working with Messages

 Logical message model
| The majority of the constraints that you define for the components of the message
| are not checked by the broker. Most are provided for documentation purposes
| only, and are not validated during execution (when the parser interprets the
| message that has been received). For example, if you define a minimum and
| maximum value that an element can contain, and the element in an input message
| contains a larger value, the broker does not flag an error.

| The exceptions to this are maximum length (which is enforced), whether nulls are
| permitted, and the use of the default value for CWF.

| The physical message representation

| When you have completed the definition of the logical message model, you must
| define the physical characteristics of the message. These characteristics define a
| physical representation of the message, which is known as a wire format and is
| modeled as a layer on top of the logical message model. You must add a wire
| format layer for every physical representation that you need for the logical model.
| When you add a wire format layer, a new tab is added to the message set
| properties pane in the Control Center Message Sets view.

| The MRM supports the following wire formats:

| v Custom Wire Format (CWF). Use the CWF layer to support fixed format messages
| for applications that expect messages to be in the form of COBOL copybooks or
| C header files. This wire format is discussed in more detail in Chapter 5,
| “Working with a Custom Wire Format layer” on page 83.
| v XML (XML). Use the XML wire format layer to alter the rendering of an XML
| message, suppress DOCTYPE definition, and add information to the DOCTYPE
| of a outgoing message. This wire format is discussed in more detail in
| Chapter 6, “Working with an XML Format layer” on page 111.
| v Tagged Delimited String (TDS). Use the TDS layer to model messages that use
| delimiters between data elements, or that include tags to identify elements, or
| both. You can use this layer to support industry standard message sets (for
| example, SWIFT) that use delimiters to separate data fields, as well as defining
| your own message formats that use these techniques. TDS can be very useful
| when you are dealing with variable length data fields, because the ability to use
| delimiters to separate the fields and to specify the delimiter that you are using,
| enables the MRM parser to interpret the message looking for the user specified
| delimiter and thus produce the required tree that represents the message. This
| wire format is discussed in more detail in Chapter 7, “Working with Tagged
| Delimited String messages” on page 131.
| v Portable Data Format (PDF). This is a format unique to the MRM and is not the
| document format known as Adobe Acrobat PDF. This is a rarely used format,
| and is not discussed in detail. It is used internally by the MRM2. This is the
| default wire format if you do not specify a wire format in the Control Center.

| You can add multiple CWF, TDS, and XML wire format layers to a single message
| set. This allows you to define multiple physical representations of a single logical
| message to enable conversion from one format to another to be done by the broker.

2. You might see PDF error codes included in error messages and log information associated with internal messages. For an
explanation of these error codes, see Appendix F, “PDF error codes” on page 263.

Chapter 3. The MRM domain 29

 Physical message representation
| You can view wire format properties in the Control Center by selecting an MRM
| entity from the tree in the left pane (for example, an element) and selecting the
| associated wire format tab that is displayed with other properties tabs across the
| top of the properties pane to the right.

Using the MRM utilities

The MRM supplies a set of utilities that let you work with message sets in several
ways:
v It provides a set of importers that you can use to take an existing entity, for
example, a COBOL copybook, and produce the appropriate entities in the MRM.
These are described in “Importing a message model from external sources”.
v It provides a set of generators that you can use to create output, for example,
documentation from the message definitions in the message repository. These are
described in “Generating information from the message model” on page 31.
v It provides an import and export command that you can use to export message
definitions from one message repository and import them into another message
repository. This command is described in “Importing a message model from
external sources”.

| Importing a message model from external sources

| You can use your existing message structures defined in C or COBOL, or in an
| XML DTD, to create message models by importing them into the Control Center.
| This provides a quick way of populating the message repository with the messages
| that you are already using. The following importers are provided:
| v COBOL importer. This takes a COBOL copybook and creates and populates a
| logical message model and the associated CWF layer with the appropriate data.
| This is discussed further in “Importing C and COBOL data structures” on
| page 176.
| v C importer. This takes a C header file and creates and populates the logical
| message model and the associated CWF layer with the appropriate data. This is
| discussed further in “Importing C and COBOL data structures” on page 176.
| v DTD importer. This takes a DTD defined in a file on the Configuration Manager
| system and creates and populates the logical message model and the associated
| XML wire format layer. This is discussed further in Chapter 10, “The XML
| domain” on page 191.

| These importers work in slightly different ways:

| v The C and COBOL importers import directly into the message repository. The
| newly imported entities are checked in to the message repository automatically,
| and are not added to your local workspace. Therefore the components created
| by the importer do not initially appear in your Control Center Message Sets
| view. If you want to view the messages, you must add them to your workspace.
| If you want to make further changes or additions, you must check them out of
| the repository.
| v The DTD importer imports the DTD into your local repository and your Control
| Center workspace. It marks all the components that it creates as new objects.
| You can manipulate the imported definitions before you check them into the
| message repository.

30 WebSphere MQ Integrator Working with Messages

 Importing a logical message model
Importing a message model from another message repository
You can also import a message set that has been exported from another message
repository. This function is not available through the Control Center: you must use
the message set import command mqsiimpexpmsgset. This command imports
message set definitions that have been exported from another message repository.
The command is described in the WebSphere MQ Integrator Administration Guide.

Generating information from the message model

You can generate several forms of information from the message sets that you have
defined in the message repository. The information is always based on the message
set: you cannot generate information for lower level components (for example, a
message). When generated, these can be used for a variety of purposes:
v Run time dictionary. A run time dictionary is a file that contains message
format information. This message metadata describes:
– The logical format of all messages in a single message set.
– The information necessary to map a logical message structure of a given
message set to a serialized bit stream in the wire formats that are associated
with the message set.
A run time dictionary can be used by applications that use the Common
Messaging Interface (CMI). If you do not have any applications that use the
CMI, you do not need to generate a run time dictionary for any of your message
sets.

You must make the files that are generated accessible to your applications: this is
not done automatically. You cannot assign run time dictionaries to brokers
through the Control Center.

“Generating run time dictionaries” on page 180 details the process for generating
these files.
v Documentation. You can generate a glossary and a message book from a
message set. The files created by this action are for documentation purposes
only to record the contents of the message set. You might find this useful to
provide reference information for your message flow designers and application
developers.
“Generating documentation” on page 178 provides instructions for this process.
v Language bindings. You can create language bindings for both C and COBOL.
The files generated by this action are the C headers or COBOL copybooks that
represent the data structures that you have created in the message repository.
See “Generating language bindings” on page 179 for instructions on how to
complete this task.
| v DTDs. You can generate an XML Document Type Definition (DTD) file from the
| message set within the message repository. This is described in “Generating
| MRM message set definitions in XML DTDs” on page 181.
v Message set definitions. You can export a message set definition from the
message repository using the message set export command mqsiimpexpmsgset.
This command generates a file in XML format that can be imported into another
Configuration Manager. The command is described in the WebSphere MQ
Integrator Administration Guide. This function is not available through the Control
Center.

Chapter 3. The MRM domain 31

 Planning your MRM model

Planning your MRM model

If you want to define your message structures to the MRM, you must first decide
on the business structure of these messages (the data they will contain, the limits
on that data, the relationship between different fields, and so on). You can then
create one or more message sets to contain related messages that are used by your
applications.

The questions that you might consider in reaching your decisions include the
following:
v Are the messages brand new, or based on existing message definitions?
– You can import existing MRM message set definitions. For example, if you
can reuse a message set and its contents from another broker domain, you
can export the message set definition from that domain, and import it into
this domain.
Details of importing and exporting message sets are described in “Importing
a message model from external sources” on page 30.
– You can build messages based on existing C or COBOL data structures, by
creating a message set and importing the data structures into that message set
using options in the Message Sets view of the Control Center. You can only
import one data structure at a time. You must then complete the definition of
the messages using the types and elements created for you within the MRM
by the import action.
Details of importing and exporting C and COBOL data structures are
provided in “Importing C and COBOL data structures” on page 176 and
“Generating language bindings” on page 179.
– You can build messages based on DTDs, by creating a message set and
importing a DTD into that message set using options in the Message Sets
view of the Control Center. See “Importing a DTD” on page 177 for further
details.
– You can create new message sets by defining all the required components
yourself.
v What physical representations do the messages need?
You can add any combination (including none) of the following:
– The Custom Wire Format (CWF). This is generally used when you are
creating your message set from existing C or COBOL datastructures that you
have imported.
– The Tagged Delimited String Wire Format (TDS). You must use this
representation when you are dealing with tagged or delimited messages,
including industry standards. The Control Center specifically supports the
following TDS industry standard formats:
- ACORD AL3. These messages are used by insurance companies,
predominantly in the USA.
- EDIFACT and X12. These messages are used by the travel industry and by
some insurance establishments, particularly in Europe.
- SWIFT. These messages are widely used in the finance industry to define
messages for transactions and exchange.

You can also define your own tagged or delimited formats if you choose.
| – The XML Wire Format (XML). You must use this representation when you
| want the MRM to parse an inbound XML message, or generate an outbound
| XML message.

32 WebSphere MQ Integrator Working with Messages

 Planning your MRM model
You are very likely to find, for example, that you want legacy applications
(using message formats defined as data structures in C or COBOL) to
communicate with more recent applications that use the XML messaging
standard. The broker can handle conversion for you if you define both the CWF
and XML wire format characteristics on the message set.

If an inbound message has TDS wire format, and you want the outbound
message to be in XML format, you can add and complete the appropriate wire
format tabs. You might also want to convert from one tagged format (SWIFT, for
example) to another tagged format (EDIFACT perhaps). The ability to add wire
formats to your message set allows you to support your applications, whatever
the combination of formats they use.

If you do not add any of these wire formats to your message set, the broker
processes the message as a PDF (Portable Data Format) message (used internally
by the MRM).

Wire formats are discussed in detail in Chapter 5, “Working with a Custom Wire
Format layer” on page 83, Chapter 6, “Working with an XML Format layer” on
page 111, and Chapter 7, “Working with Tagged Delimited String messages” on
page 131.
v Do the messages need language bindings?
You can add language bindings to the message set for C or COBOL, or both.
Language bindings are used for exporting headers and datastructures.
For further information, see “Adding a language binding” on page 162.
v How can messages be organized?
You must create messages within a message set to enable their deployment to a
broker. You can deploy as many message sets to a broker as necessary. Therefore
you must decide the grouping of messages within a message set.
You can choose to put all messages that are used by all applications that access a
single broker into a single message set, and deploy that one message set to the
broker. You might define all the messages used by one application suite in a
message set. You can choose to put individual messages in a message set. You
can also use categories and transactions within the message set to organize the
messages it contains.
You must consider that you can only import and export message sets, you
cannot import or export a single message. Therefore you might want to limit the
size of your message sets to ensure the most efficient distribution of the required
messages around your enterprise.
It is also important to consider that you can only finalize at the message set
level. When you finalize a message set, the MRM prohibits further updates to
that message set. You might want to introduce this level of completeness in
small increments by limiting the contents of each message set.
See “Message set states” on page 76 for further explanation of this topic.
v What naming conventions are used in the business environment?
The larger your enterprise and your application set, the more important it is to
follow naming conventions for resources that are shared between users and
systems. This is true for your message sets in the MRM. Within a message set,
the MRM controls the required uniqueness of names, but it is your responsibility
to ensure that everything you define has a representative name.

Chapter 3. The MRM domain 33

Planning your MRM model
You must also consider that once you have created a component, there are some
properties that you cannot change without deleting and recreating the
component. These include:
– The name of a message set
– The type of an element
– The type of a message
– A component identifier
– Language bindings and physical layers added to the message set (they cannot
be removed)

34 WebSphere MQ Integrator Working with Messages

 Chapter 4. The MRM logical message model
| Chapter 3, “The MRM domain” on page 23 introduced you to the MRM as a
| message abstraction tool that enables you to create both the logical message model
| and its physical representation (wire format).

| This chapter describes the logical message model in detail:

| v How you create the logical message model in the Control Center.
| v How the logical message model is represented in the broker.
| v How you can use ESQL in message flow nodes to manipulate a message that is
| mapped to the logical model.
| v How you can change the state of a message set to manage its update

| In the final section, you can review the process for creating a logical message
| model. The example used is for a message set that defines the messages used by a
| video loan company. This example is further explored in the following three
| chapters, in which wire formats are created for each of the physical representations
| in which the video messages can be received.

| The following topics are discussed:

| v “Creating a logical message model: an overview”
| v “Message model objects” on page 39
| v “Relationships between MRM objects” on page 62
| v “Implications for the logical model when defining messages of different wire
| formats” on page 63
| v “Null handling” on page 64
| v “Data conversion” on page 66
| v “The broker’s view of the logical message model” on page 66
| v “Managing message sets” on page 76
| v “Example: modeling the Video customer message” on page 78

Creating a logical message model: an overview

“The logical message model” on page 27 introduced you to the MRM objects that
you must include in a message set to create a message model. These are:
v Message set
v Element
v Message
v Type

You can include other optional components to enhance your message model:
v Category
v Element qualifier
v Transaction
v Element value

© Copyright IBM Corp. 2000, 2002 35

 Creating a logical message model
These objects are described in detail in “Message model objects” on page 39, which
also provides you with information and examples that help you to decide if you
need to add the optional objects into your model.

This section takes a first look at the message set in the Control Center, and
summarises how to create your first message model. All the information in this
section is expanded later in this chapter.
v “The message set in the Control Center”
v “How to create a logical message model” on page 37

The message set in the Control Center

When you create a message set in the Message Sets view of the Control Center, a
folder is displayed for all the mandatory and optional objects. The top folder is for
the message set itself, and displays the name that you gave the message set when
you created it. The folders within the message set reflect the type of object that
they contain, for example, Message.

You can see the structure of a message set in Figure 7. The message set, VideoStore,
is used as a working example later in this chapter (in “Example: modeling the
Video customer message” on page 78), and in the following three chapters.

|
| Figure 7. The Message Sets view

There are two display panes in this view:

v Message set pane. This pane, on the left of the view, shows the message set in a
tree form. When you select an MRM object shown in the message set tree, its
associated properties are shown in the properties pane on the right of the view.
In Figure 7, the message set VideoStore is selected (it is shown as highlighted),
and its properties are displayed on the right.
v Properties pane. This pane shows the details of the MRM object selected in the
message set pane. There are usually multiple tabs that reflect the layers of the
model. Each property tab is visible across the top of the properties pane. You
can select each tab by name to view the associated properties.
Some property panes are applicable to all the MRM objects:
– The general pane. This displays the object properties. The tab in the property
pane shows the name that you have given to this MRM object. In Figure 7,
this tab is labelled VideoStore (and its contents are currently displayed).

36 WebSphere MQ Integrator Working with Messages

 Creating a logical message model
– The Description pane. This is provided for documentary purposes. There is a
pane entitled Description for every object.
| The properties Short Description and Long Description are displayed on this
| pane. These are free format text fields that allow you to specify text that
| describes the object. If you create documentation from the message set, this
| information is included. It is not used by the broker or parser.

Additional tabs might be visible in the right pane. In Figure 7 on page 36, you
can see four additional tabs, Run Time, XML, TDS, and CWF. These do not
define the logical model, but provide addditional information that relates to the
physical representations of the model. For further details about these tabs, see
“Message set” on page 41.

The characteristics of each object, the properties that you can configure to define
each one, and the additional panes that might be displayed for the object, are
described in detail in “Message model objects” on page 39. You can also read about
the relationships between the objects, and view examples.

| How to create a logical message model

| This section gives you an overview of how you can create a message model. It
| does not describe the process that you follow in the Control Center in detail: you
| can find that information in “Creating message sets and message set components”
| on page 159. It does not describe the properties of each object in detail: you can
| find these described in “Message model objects” on page 39.

| You create messages from reusable items that are defined as types and elements.
| You can consider a type as a library or generic part, an object that has no business
| meaning. It cannot be accessed by name using ESQL in a node within a message
| flow. It is merely a building block. When you instantiate a type as an element, you
| give it a meaning and context. You also give it an identifier, that you can use to
| access it from a message flow node.

| To illustrate types and elements, consider data that represents an address. You can
| create a type called Address, that defines a structure containing two strings, the
| first for a street, the second a town. The Address on its own has no context. Now
| create two elements, called CompanyAddress and CustomerAddress, and base
| both on the type Address. The two elements are different instantiations of the same
| type. That is, each element has a different meaning, context, and content, but the
| structure and characteristics of the elements is identical.

| Types and elements are reusable within the message set. You can use these in more
| than one message within the same message set, but you cannot use them across
| message sets. You can make a copy of an object from one message set to another. If
| you do so, the two are not linked, and updates that you make to one copy are
| never reflected in the other copy.

| You can create messages to suit many situations using the objects that have been
| described. This section first discusses a simple message, then explores that ways in
| which you can enhance the first message to fulfil more complex requirements.
| Each section introduces some of the properties of the components that it includes:
| check “Message model objects” on page 39 for details of these properties.

Chapter 4. The MRM logical message model 37

 Creating a logical message model
| Creating a simple message
| To create a simple message from scratch, you must first define the elements of the
| message that represent fields that contain data. You must start with the simple
| elements, the fields that equate to one of the seven MRM simple types (described
| in Table 7 on page 49).

| Next, you create one or more types to represent the structures within the message.
| The types that you create are the compound types, which represent groups of
| elements in a particular order. When you have created a type, you must add the
| simple elements to it.

| If you have a hierarchy of structures, you can now create compound elements, that
| is, elements that represent structures. You do this by defining an element based on
| a compound type rather than on a simple type.

| You must create a compound type to represent the whole message. This compound
| type can contain any number of simple and compound elements. Now you can
| create the message based on this compound type.

| You can also use the Message SmartGuide to create a message. For more
| information about this utility, see “Using the SmartGuides” on page 168.

| Creating a more complex message

| If you define your compound type in a particular way, you can create a more
| complex message by adding objects other than elements to the compound type. To
| achieve this you must define the compound type with its Type Composition
| property set to Sequence, and add simple or compound types directly to the
| compound type. (For more information about compound types, and their
| properties, see “Type” on page 49.)

| This option is particularly useful when you are modeling an XML message, in
| which case you must also add an XML wire format layer to the message set (refer
| to Chapter 6, “Working with an XML Format layer” on page 111 for further details).

| You can also define messages that include a choice of elements within a message:
| at a particular point in the message, the next element could be one of a number of
| elements, resolved only when the message is received and analyzed. To achieve
| this, you must define the compound type with its Type Composition property set to
| Choice.

| Creating a multipart message

| You can create a message that embeds one or more messages within its structure.
| This is known as a multipart message. You can create a message like this by
| creating a message as described above, and adding to it a compound type that you
| want to contain th embedded messages. Set the Type Composition property of this
| compound type to Message, and add previously defined messages to that
| compound type. (For more information about compound types, and their
| properties, see “Type” on page 49.)

| When you create a multipart message, you cannot base it on a compound type that
| is itself defined with Type Composition set to Message.

| Each wire format (CWF, XML, and TDS) has ways of identifying embedded
| messages. For further information, see Chapter 5, “Working with a Custom Wire

38 WebSphere MQ Integrator Working with Messages

 Creating a logical message model
| Format layer” on page 83, Chapter 6, “Working with an XML Format layer” on
| page 111, and Chapter 7, “Working with Tagged Delimited String messages” on
| page 131.

Message model objects

This section provides full details about each object, its characteristics, and its
properties. The first section discusses common name and identifier properties. The
required objects message set, element, message, and type (that you were
introduced to in “The logical message model” on page 27) are discussed next,
followed by the optional objects.
v “Names and identifiers”
v “Message set” on page 41
v “Element” on page 45
v “Message” on page 47
v “Type” on page 49
v “Category” on page 55
v “Element qualifier” on page 56
v “Transaction” on page 58
v “Element value” on page 59

The tabs that appear in the Properties pane in the Control Center when you select
an object in the tree in the Message sets pane might differ depending on the point
in the tree from which you select it. For example, if you select an element within
the Elements folder, no Connection pane is displayed. If you select the same
element in the Messages folder, you see a Connection pane that shows the
properties that exist due to the member of relationship that you have created by
including the element within the message. Not all MRM objects have a Connection
pane because not all MRM objects are associated with a member of relationship.
(Relationships between objects are discussed in “Relationships between MRM
objects” on page 62.)

Every object has a Description pane that is used for documentation only, and this
is not listed in the following sections. For a description of this pane, see “Creating
a logical message model: an overview” on page 35. Some objects also have a
History pane that provides additional properties that are also used for
documentation only. The History pane is listed where it appears.

Names and identifiers

Every MRM object in a message set definition has a name and an identifier:
Name Is a descriptive name for the object. It is typically a full and descriptive
name (for example, “Street Name” or “Account Number Length”), in
contrast to the component identifier, which is often an abbreviated name
and is subject to environmental conventions.
| You define the name when you create the object. You can change the name
| of the object after you have created it using the Rename action.
Names do not have to be unique, although you cannot create an object
with the same name as another object in the same folder (for example,
category) that is already in the workspace. If you want to create a second
object with the same name, you must remove the first instance from the
workspace, create the second instance, then add the first instance back into
the workspace. You can create a second object in a different folder in the

Chapter 4. The MRM logical message model 39

 Names and identifiers
workspace (for example, you can create an element called AccountData
and a compound type called AccountData).
Identifier
| Identifies a component uniquely within a message set. No two components
| of any kind in a message set can have the same identifier, and no two
| components of the same class (for example, two elements or two
| categories) can have identifiers that differ only by case. For example, you
| cannot define both an element with the identifier “ADDRESS” and an
| element with the identifier “address” in the same message set. You cannot
| define both an element with the identifier “ADDRESS” and a compound
| type with the name of “ADDRESS”.
| In the case of elements, the element identifier is used in application
| programs to access data values assigned to the element.
| An identifier must begin with an alphabetic character (A-Z, a-z) or an
| underscore (_). The remainder of the value, up to a maximum of 254
| characters, can contain alphanumeric (A-Z, a-z and 0–9), underscore (_),
| and period (.) characters. You can also specify the caret character (^) if you
| need to create a prefixed identifier. These are valid only for elements. Their
| use is described in “Prefixed identifiers”.
| When you create a message set, a unique identifier is automatically created
| for you. When you create any other object, you must define its identifier.
| You cannot change the identifier of an object after you have created it.

| Prefixed identifiers
| You might find that some of the messages that you want to model contain different
| elements that have a common name. This would usually be the case where the
| elements are included in two different types and represent different data. Another
| example is modeling an XML message where XML attributes frequently have the
| same name. In both cases, the elements might or might not have similar content.

| For example, your message might contain a type called A and another called B.
| Both types contain an element called X. The two elements called X are very
| different and must not be confused when the message is processed. Each element X
| can be considered local to the type in which it is defined, and has meaning only in
| that local context.

| The message might logically look something like this:

| Type A
| Element X
| Element Y
| Type B
| Element P
| Element Q
| Element X

| When you model this message, you could define the two elements with the same
| name but you must give the identifiers unique values. You can model this in two
| different ways:
| 1. You can modify the identifier of the second element X. You can do this perhaps
| by setting an identifier of X for the first element, and X1 for the second element.
| Or you could use the element’s parent to provide the distinction, perhaps
| setting an identifier of A_X for the first, and B_X for the second.

40 WebSphere MQ Integrator Working with Messages

 Names and identifiers
| When you reference these elements using ESQL, you must use their identifiers.
| If you choose the second example, you would reference:
| InputRoot.MRM.A.A_X
| InputRoot.MRM.B.B_X

| When you reference these elements in ESQL statements, these prefixed

| identifiers might become awkward if your type and element names and
| identifiers are more descriptive than A, B, and X. You can use the second option
| to resolve this.
| 2. You can use prefixed identifiers. These divide the identifier into a prefix and a
| suffix, separated by the caret character (^). The prefix is there solely to satisfy
| the identifier uniqueness rule, and the suffix is used to match the element to
| the dictionary (this works because the MRM parser understands the context in
| which a reference to X appears).
| In the example above, you could specify identifiers A^X and B^X. The identifier
| property is always displayed in the general properties pane in its full form, but
| when the message is displayed in tree format in a node, and when you use
| ESQL drag and drop, the prefix and the caret are removed and the suffix alone
| is used:
| InputRoot.MRM.A.X
| InputRoot.MRM.B.X

| You must follow the following rules that are associated with prefixed
| identifiers:
| a. You can only use prefixed identifiers for MRM-defined elements
| b. You cannot create a compound type that contains two elements that have
| identifiers that differ only by prefix, that is you cannot have two variations
| of the same local name within a single type.
| c. You can specify only a single caret in an identifier.
| d. You must avoid using a fully prefixed identifier when you enter your own
| ESQL (not using drag and drop). Just use the suffix. If you do not do so, the
| ESQL reference might fail to match to the correct field in the message.

| Use this method of defining identifiers for local elements in all situations where
| duplicates names exist.

| Message set
| A message set is a logical grouping of messages. Its characteristics are:
| v A message set is the MRM’s largest container object.
| v A message set defines the namespace of the identifiers. A single namespace is
| created for each message set.
| v You cannot share entities, for example elements, between message sets. You can
| copy entities from one message set to another.

| When you have completed a message set definition, you can assign and deploy it
| to a broker. You cannot deploy at a more granular level (for example, a message).

| Figure 8 on page 42 shows two message sets that are defined for a banking
| application. The first message set contains two messages that handle information
| about checking accounts (the message set name, CHECK_ACC_MSGSET, implies
| its purpose), and the second, SAVE_ACC_MSGSET, contains two messages
| concerned with savings accounts.
|

Chapter 4. The MRM logical message model 41

 Message set
|

MSG-1 MSG-2 MSG-3

CHECK_ACC_MSGSET

MSG-1 MSG-2 MSG-3

SAVE_ACC_MSGSET
|
| Figure 8. Message grouping within sets

Control Center property panes

The following Control Center property panes are associated with a message set:
v General Message Set pane. This is where you define the message set properties
described in “Message set properties” on page 43.
| v Run time pane. This pane displays the parser that you select when you create
| the message set. The broker invokes the parser to construct the output message.
| The value you specify here is used within the message flow if you use the ESQL
| drag and drop facility, for example in a Compute node.
| You must select one of the following options:
| – MRM. The parser that is used for a message set that you have defined to the
| MRM. This is the default value.
| – XML. The parser that is used for generic XML messages in the XML domain.
| These must be well formed, self-defining XML, because the broker provides
| no validation. These messages are discussed in Chapter 10, “The XML
| domain” on page 191.
| – NEONMSG. The parser that is used for New Era of Networks message sets, that
| you must define using the New Era of Networks Rules and Formatter
| Support utilities. These messages are discussed in Chapter 12, “The New Era
| of Networks domains” on page 213.
| – JMSMap and JMSStream. These options provide support for JMS messages
| which are treated by the broker as generic XML. These messages are
| discussed in Chapter 11, “The JMS domain” on page 209.

| If your application constructs messages for processing by WebSphere MQ

| Integrator, it can specify the parser name as the domain name in the MQRFH or
| MQRFH2 header. If the message does not have an MQRFH or MQRFH2 header,
| you can specify the parser name as the domain name in the input node of the
| message flow. (For more information about configuring message flows, see
| “Setting up message flows to handle these messages” on page 182.)
| v An additional pane is displayed for each wire format layer that you add to the
| message set. In Figure 7 on page 36, you can see that wire format layers for
| XML, TDS, and CWF have been added to the message set VideoStore. For details
| of the content of these three panes, see the appropriate wire format chapter.
| v An additional pane is displayed for each language binding that you add to the
| message set. For detail of their content, see Chapter 8, “Working with MRM
| messages in the Control Center” on page 159.

42 WebSphere MQ Integrator Working with Messages

 Message set
| Message set properties
| Table 2 defines the properties that you can set to customize the message set.
| Table 2. General message set properties
| Property Type Meaning
| Name STRING Specify a name for the message set when you create it. Use a name that
| enables you to quickly identify the purpose and content of the message set,
| and that conforms to any naming conventions that you must follow. The
| name you enter is displayed on the tab for the message set properties in the
| properties pane.

| You can specify a maximum of 254 characters.There are no restrictions on the

| first or subsequent characters that you can use. The name should normally be
| unique (but see “Creating a message set with the same name as an existing
| message set” on page 161).
| Identifier STRING This is a unique identifier that is automatically generated for you when you
| create the message set. You cannot change this property.
| Level INTEGER The shows the version of the message set, and is initially set to 1 (the default
| value). This value is set when you create the message set, and cannot be
| changed later. You can enter a higher value if you base this message set on an
| existing message set, although the use of this is not policed by the Control
| Center or the broker.
| Finalized BOOLEAN This property initially displays false, which indicates that you have not
| finalized the message set. You cannot change this property on this pane, but
| its value changes to true when you finalize the message set (see “Managing
| message sets” on page 76 for further information).

| When you have finalized a message set, you cannot change it or any of its
| components.
| Freeze DATETIME This property is initially empty, which indicates that you have not frozen the
| Timestamp message set. You cannot change this property on this pane, but its value
| changes to the date and time at which you freeze the message set (see
| “Managing message sets” on page 76 for further information).

| After you have frozen the message set, the Freeze Timestamp is always stored
| by the Configuration Manager in UTC (coordinated universal time), but it is
| displayed in a locale-dependent format and local time, for example 26 JUNE
| 2001 11:53:09 BST.
| Default Wire Enumerated Type Specify the default wire format that is used if a format cannot be deduced
| Format from the message’s MQRFH2 header, or was not specified as a property of
| the input node on which the message is received by a message flow. The
| default is empty (not set).
| Default Null Enumerated Type Select Yes or No (the default) from the drop-down list.
| Permitted
| If you select Yes, any element within the message set can contain values that
| are defined as MRM null values, unless the element has an associated
| element value constraint of role Null Permitted that is set to the Boolean
| False value.

| If you select No, if an element is to contain an MRM supplied null value, that
| element must have an element value constraint of role Null Permitted set to
| the Boolean True value.

| This property is used in combination with the Default Permitted role for an
| element value. See “Element value member properties” on page 61 for further
| information about this role.

Chapter 4. The MRM logical message model 43

 Message set
| Table 2. General message set properties (continued)
| Property Type Meaning
| Message Type STRING This property is used when you define multipart messages (see “How to
| Prefix create a logical message model” on page 37 for a definition and explanation
| of multipart messages).

| The value that you specify is used as an absolute or relative path to the
| innermost message from the outermost, and is used as a prefix to the value of
| the Message Type property specified for the outermost message (specified
| either in the MQRFH2 header of the message, or in the input node of the
| message flow).

| If you set a value, it must be in the form id1/id2/.../idn where id1 is the
| identifier of the outermost message, id2 is the identifier of the next element
| or message, and idn is the identifier of the innermost message. The default
| value is blank (not set).

| Table 3 shows how this value is combined with the Message Type property of
| an input message.
| Base Message STRING When you create a message set, you can base it on another existing finalized
| Set message set if you choose. You can choose from a list of finalized message
| sets displayed in the dialog. After creation, this property displays the
| identifier (not the name) of the message set on which it is based. If the
| message set is not based on another message set, this field is empty (not set).
|

| Table 3 shows the implications of using the property Message Type Prefix. Note that
| identifiers might be elements or messages.
| Table 3. Use of the message set property Message Type Prefix
| Message Type property Message Type Prefix not set Message Type Prefix set
| example
| Simple Message Type: Results in the simple Message Type: Results in the path Message Type:
| id id /idP1/.../idPn/id
| Path Message Type: Results in the path Message Type: Results in the combined path Message
| id1/.../idm /id1/.../idm Type:
| /idP1.../idPn/id1/.../idm
| Simple absolute Message Results in the simple Message Type: Results in the simple Message Type:
| Type: id id
| /id
| An error is raised if Message Type Prefix is
| set to any value other than id.
| Path absolute Message Type: Results in the path Message Type: Results in the path Message Type:
| /id1/.../idm /id1/.../idm /id1/.../idm

| An error is raised if all identifiers in

| Message Type Prefix do not match the
| corresponding identifiers in the resulting
| path.
|

| The message set does not have any properties that are dictated by membership of
| a larger entity, because this is the largest entity defined by the MRM.

44 WebSphere MQ Integrator Working with Messages

 Element
| Element
| An element is a discrete piece of information contained in the message, that has a
| specific meaning agreed by the applications that create and process the message.
| For example, your message might include a string that your applications have
| agreed is a Customer Name. An element is always based on a type, either simple or
| compound.

| The characteristics of an element are:

| v An element is an instantiation of a compound type or a simple type. It has a
| business meaning and can be accessed by name from ESQL in a message flow
| node.
| v You can add a constraint to an element to further define the rules and
| restrictions that control its content. See “Element qualifier” on page 56 and
| “Element value” on page 59 for further information.

| Figure 9 shows three elements. ELEMENT1 and ELEMENT2 are instantiations of

| the simple type STRING. ELEMENT3 is an instantiation of another compound
| type, TYPE1. TYPE1 is defined with its Type Composition property set to EMPTY and
| thus has no children (see “Type” on page 49 for further explanaiton of compound
| types).
|
|
ELEMENT1 ELEMENT2 ELEMENT3
(element) (element) (element)

references references references

STRING STRING TYPE1

(simple type) (simple type) (compound type)

|
| Figure 9. Elements and instantiations

| Control Center property panes

| The following Control Center property panes are associated with an element:
| v General Element pane. This is where you define the element properties
| described in “Element properties” on page 46.
| v History pane. This is used to add documentation to the definition.
| v Connection pane. This is used to detail properties associated with member
| relationships. When you instantiate an element in a compound type, additional
| properties are associated with the member relationship that define rules
| associated with cardinality within the structure of the parent compound type.
|

Chapter 4. The MRM logical message model 45

 Element
| Element properties
| Table 4 defines the properties that you can set to customize the element.
| Table 4. General element properties
| Property Type Meaning
| Name STRING Specify a name for the element when you create it.
| Identifier STRING Specify an identifier for the element when you create it.
| Suspended BOOLEAN Select Yes or No from the drop-down list. You can consider suspend as a soft
| from Use delete.

| A suspended element does not appear in extracted documentation. You cannot add
| suspended elements to messages, types, or qualifiers. You can add an element
| value to a suspended element.

| You cannot create an object in the suspended state. If you want to suspend an
| object, you must check in the newly created object, and check it out again to make
| this update.
| Type Enumerated Specify the name of the compound type or simple type on which this element is
| Type based. You cannot change this after you have created the element.
|

| Element member properties

| When you include an element as a child within a compound type, the additional
| properties defined in Table 5 are displayed on the Connection pane.

| An additional pane is displayed for each wire format layer that you add to the
| message set. For details of their content, see Chapter 5, “Working with a Custom
| Wire Format layer” on page 83, Chapter 6, “Working with an XML Format layer”
| on page 111, and Chapter 7, “Working with Tagged Delimited String messages” on
| page 131.
| Table 5. General element member properties on the Connection pane
| Property Type Meaning
| Repeat BOOLEAN You can set this to Yes (if the compound type includes one or more repeating
| elements) or No (if it does not).
| Min Occurs INTEGER Specify the minimum number of times that the object within the compound type
| can repeat. This property is only valid if you have set Repeat to Yes.
| Max Occurs INTEGER Specify the maximum number of times that the object within the compound type
| can repeat. This property is only valid if you have set Repeat to Yes.

46 WebSphere MQ Integrator Working with Messages

 Message
| Message
| A message defines the data that is passed between applications. A message model
| is built up of types and elements.

| The characteristics of a message are:

| v A message defines a message model.
| v A message definition is always based on a single compound type that defines
| the structure of the message.

| Figure 10 shows a message, MSG1, that is based on the compound type

| TOP_COMPOUND_TYPE.
|
|
MSG1
(message)

references

TOP_COMPOUND_TYPE
(compound type)

|
| Figure 10. Example message structure

| Figure 11 on page 48 shows the way in which the message in the VideoStore
| message set is constructed in the Control Center. The message Customer is defined
| on the compound type CustomerType (this is identified in the property Type that
| you can see in the general properties pane for the message that is highlighed in the
| left pane). The tree structure on the left has been expanded so that you can see the
| full structure within the message. For further details about this message, see
| “Example: modeling the Video customer message” on page 78.

| Control Center property panes

| The following Control Center property panes are associated with a message:
| v General Message pane. This is where you define the message properties
| described in “Message properties” on page 48.
| v History pane. This is used to add documentation to the definition.
| v An additional pane is displayed for each TDS or XML wire format layer that
| you add to the message set. For details of their content, see the appropriate wire
| format chapter.
|

Chapter 4. The MRM logical message model 47

 Message
|

|
| Figure 11. Messages defined in the Control Center

Message properties
Table 6 defines the properties that you can set to customize the message.
Table 6. General message properties
Property Type Meaning
Name STRING Specify a name for the message when you create it.
| Identifier STRING Specify an identifier for the message when you create it.
| Suspended BOOLEAN Select Yes or No from the drop-down list. You can consider suspend as a soft
| from Use delete.

| A suspended message is not deployed to the broker, nor does it appear in

| extracted documentation. You cannot add suspended messages to message
| categories, nor to transactions. You can add elements to a suspended message.

| You cannot create an object in the suspended state. If you want to suspend an
| object, you must check in the newly created object, and check it out again to make
| this update.
| Type Enumerated Set this property to the name of the compound type that defines the structure for
| Type this message by selecting a type from the list displayed. You cannot change the
| type of a message after you have created it and checked it in.
| Mode This is set to null and you cannot change it. This property is reserved for future
| use.
|

| A message has no properties associated with membership of a message set,

| category, or transaction.

48 WebSphere MQ Integrator Working with Messages

 Type
| Type
| Types are like types in any programming language, and are the building blocks
| that you use to describe data:
| v Some data types are supplied by the system on which the program is running,
| for example integer and char. In the MRM, supplied types are known as simple
| types.
| v In programming languages, you can also declare structures, or groups of related
| elements. The structure declaration is effectively a template for the data
| contained within it. In the MRM, these are known as compound types. You must
| create your own compound types; they are not supplied. They are used to
| represent substructures of groups of elements and types within the message. A
| message is always based on a single compound type, the top level structure
| declaration.
| The characteristics of a type are:
| v Simple types are defined by the MRM. You cannot alter them in any way. You
| cannot check them out of the message repository. You can add simple types to,
| or remove them from, your workspace, but they do not have to be present in
| your workspace to use them within the message set.
| The simple types supplied are BINARY, BOOLEAN, DATETIME, DECIMAL,
| FLOAT, INTEGER, and STRING.
| Table 7. The MRM simple types
| Simple Type Description
| BINARY Use this when the data content does not conform to any numeric or
| character representation, for example for a BLOB message. Do not confuse
| this type with the COBOL BINARY datatype.
| BOOLEAN Use this when the element can only have one of two values: true or
| false.
| DATETIME Use this type for data that contains information about dates, or times, or
| both.
| DECIMAL Use this for any decimal number up to 31 digits, with or without a
| decimal point.
| FLOAT Use this type for real numbers, including fractions and numbers that are
| outside the range of DECIMAL and INTEGER. Note that rounding might
| occur when processing large numbers.
| INTEGER Use this for whole numbers. If you are using this with a CWF layer, an
| INTEGER must be between –2147483648 and +2147483647.
| STRING Use this type for character data.
|
| v Compound types are formed from elements and from simple and compound
| types to represent a structure.
| You can define a compound type with a base type: a base type allows you to
| specify the type of the value associated with the compound type itself, not with
| any of its children. A base type must be one of the MRM simple types.

| Figure 12 on page 50 shows a compound type, TOP_COMPOUND_TYPE, that has

| been defined to contain three elements, ELEMENT1, ELEMENT2, and ELEMENT3.
|

Chapter 4. The MRM logical message model 49

 Type
|
TOP_COMPOUND_TYPE
(compound type)

member of member of member of

ELEMENT1 ELEMENT2 ELEMENT3

(element) (element) (element)

|
| Figure 12. Structure of a compound type

Control Center property panes

The following Control Center property panes are associated with a compound
type:
v General Compound Type pane. This is where you define the compound type
properties described in “Compound type properties”.
v History pane. This is used to add documentation to the definition.
v Connection pane. This is used to detail properties associated with member
relationships. When a compound type has been instantiated in another
compound type, additional properties are associated with the member
relationship that define rules associated with cardinality within the structure of
the parent compound type. These are defined in “Compound type member
properties” on page 54.
v An additional pane is displayed for each TDS and XML wire format layer that
you add to the message set. For details of their content, see the appropriate wire
format chapter.

Compound type properties

Table 8 defines the properties that you can set to customize the compound type.
Table 8. General compound type properties
Property Type Meaning
Name STRING Specify a name for the compound type when you create it.
| Identifier STRING Specify an identifier for the compound type when you create it.
| Suspended from BOOLEAN Select Yes or No from the drop-down list. You can consider suspend as a
| Use soft delete.

| If you suspend a type, a message that is based on this type is not

| deployed to the broker, nor is the message included in generated
| documentation. You cannot add a suspended type to a message, a type, or
| an element. You can add elements to a suspended type.

| You cannot create an object in the suspended state. If you want to suspend
| an object, you must check in the newly created object, and check it out
| again to make this update.

50 WebSphere MQ Integrator Working with Messages

 Type
| Table 8. General compound type properties (continued)
| Property Type Meaning
| Type Enumerated Type Set this property to specify the type of value associated with the
| compound type itself (not its children).

| The default value is null (which means that the compound type has no
| value).

| If specified, the Type must be a simple type (BINARY, BOOLEAN,

| DATETIME, DECIMAL, FLOAT, INTEGER, STRING).

| You cannot change this property after you have created the compound
| type.

| For example, in Figure 12 on page 50, you could define

| TOP_COMPOUND_TYPE with a value associated with it, that is
| completely independent of the values set for any of the three elements
| (which could be of any simple or compound type). If the value is
| INTEGER, you set this property Type to INTEGER.
| Type Enumerated Type Available options for Type Composition are given in Table 9 on page 52.
| Composition
| Type Content Enumerated Type Available options for Type Composition are given in Table 10 on page 52 and
| Table 11 on page 53.
|

| Type Composition: The Type Composition property describes how the message tree
| is structured, and is used in combination with the property Type Content. The valid
| combinations and the structure that they model is shown in Table 12 on page 53.

| Type Composition determines, for example, if the elements within the tree can
| appear in any order, or if the order is predefined.

| If you include a compound type within another compound type, you must set Type
| Composition for the enclosing compound type to Sequence.

| If you set this property to Ordered Set or Sequence, the order of elements in the
| input message when the message is parsed, and the order in the logical tree when
| the output message is constructed by the parser, is important. If the order is not
| correct, the parser might generate an error, or might produce unexpected results.
| Therefore you must take care to include ESQL SET statements in the correct order
| when you create a message in a Compute node.

| For further information about the effect of using this property with CWF, see
| “Type property Type Composition” on page 107.

| Table 9 on page 52 shows the valid settings for Type Composition. Valid children in a
| compound type, that depend on both Type Composition and Type Content, are shown
| in Table 12 on page 53. Valid combinations of repeated and duplicate elements, also
| dependent on Type Composition, are shown in Table 13 on page 54.

Chapter 4. The MRM logical message model 51

 Type
| Table 9. Compound type Type Composition options
| Option Meaning
| Empty If you select this option, you cannot define any children for this compound type. This
| option has no meaning for CWF. For XML, it models a DTD content model of EMPTY.
| Choice If you select this option, you can define children that are simple types, compound types,
| or elements. Only one of the defined children of the compound type can be present, but
| repeating children are allowed.

| Use this option if you want to model C unions and COBOL REDEFINES (see Chapter 5,
| “Working with a Custom Wire Format layer” on page 83), or an XML DTD element that
| uses choice (see Chapter 6, “Working with an XML Format layer” on page 111). Some
| industry standard tagged/delimited messages (for example SWIFT) use this format (see
| Chapter 7, “Working with Tagged Delimited String messages” on page 131).
| Unordered Set If you select this option, you can define only elements as children. The elements can
| repeat but cannot be duplicated. Child elements can appear in any order.

| If you have migrated messages from WebSphere MQ Integrator Version 2.0, Version 2.0.1,
| and Version 2.0.2, this is the default value set for these message sets.
| Ordered Set If you select this option, you can define only elements as children. These elements, if
| present, must appear in the specified order, and they can repeat but cannot be
| duplicated. This is the default value for new compound types.
| Sequence If you select this option, you can only define children that are simple types, compound
| types, or elements. These children, if present, must appear in the specified order. They
| can repeat and can be duplicated.
| Simple Unordered Set If you select this option, you can define only elements that are based on simple types as
| children. Child elements can be in any order but cannot repeat and cannot be duplicated.
| Use this option to model an XML DTD attribute list declaration.
| Message If you select this option, you can define only messages as children. They can repeat, but
| they cannot be duplicated. Like Choice, only one of the defined children can be present.

| Use this option to model multipart messages, which are used in some industry
| standards, for example, SWIFT. For more information, see the section on multipart
| messages in Chapter 5, “Working with a Custom Wire Format layer” on page 83,
| Chapter 6, “Working with an XML Format layer” on page 111, and Chapter 7, “Working
| with Tagged Delimited String messages” on page 131.
|

| Type Content: Type Content specifies where the objects that are included within
| the compound type are defined, if at all. It is used in combination with Type
| Composition, and valid combinations are shown in Table 12 on page 53. This
| property is not validated by the broker.

| Table 10 shows the valid settings for Type Content if Type Composition is set to
| Message, and Table 11 on page 53 shows the valid settings for Type Content if Type
| Composition is not set to Message.
| Table 10. Compound type Type Content options if Type Composition is set to Message
| Option Meaning
| Open When a message is parsed, this compound type can contain any message, not just those that you
| have defined in this message set. You can use this option for sparse messages (see “Predefined
| and self-defining elements and messages” on page 63 for a definition of sparse messages).
| Closed When a message is parsed, this compound type can only contain the messages that are members
| of this compound type. This is always the case for messages represented in CWF format.
| Open Defined When a message is parsed, this compound type can contain any message defined within the
| message set.
|

52 WebSphere MQ Integrator Working with Messages

 Type
Table 11. Compound type Type Content options if Type Composition is not set to Message
Option Meaning
Open When a message is parsed, this compound type can contain any compound types, simple types,
and elements, not just those that you have defined in this message set (see “Predefined and
self-defining elements and messages” on page 63 for a definition of sparse messages).
Closed When a message is parsed, this compound type can only contain the compound types, simple
types, and elements that are members of this compound type. This is always the case for messages
represented in CWF format.
Open Defined When a message is parsed, this compound type can contain any compound type, simple type, and
element that you have defined within the message set.

| Combinations of Type Composition and Type Content: Figure 13 shows the objects
| that you can use within a compound type definition. Table 12 shows how the
| choices that you make are affected by the settings you choose for the Type
| Composition and Type Content properties.
|
|
Compound type

member of member of member of

Compound Simple
type Element type

|
| Figure 13. Valid children within a compound type

| Table 12. Valid children in compound types dependent on Type Composition and Type Content
| Type Composition Type Content Valid children
| Empty Closed None
| Empty Open None
| Empty Open Defined None
| Choice Closed Elements, simple types, compound types
| Unordered Set Open Elements
| Unordered Set Closed Elements
| Unordered Set Open Defined Elements
| Ordered Set Open Elements
| Ordered Set Closed Elements
| Ordered Set Open Defined Elements
| Sequence Open Elements, simple types, compound types
| Sequence Closed Elements, simple types, compound types
| Sequence Open Defined Elements, simple types, and compound types
| Simple Unordered Set Open Elements based on a simple type
| Simple Unordered Set Closed Elements based on a simple type
| Simple Unordered Set Open Defined Elements based on a simple type
| Message Open Messages

Chapter 4. The MRM logical message model 53

 Type
| Table 12. Valid children in compound types dependent on Type Composition and Type Content (continued)
| Type Composition Type Content Valid children
| Message Closed Messages
| Message Open Defined Messages
|

| Repeats and duplicates: Table 13 defines the valid combinations of repeated and
| duplicate elements within a compound type, dependent on the Type Composition
| property value.
| v A repeated element is an element that is included once within the compound
| type, and is defined with the property Repeat set to Yes (on the Connection
| pane). Repeated elements are therefore always contiguous and are always
| specified in the form A[n].
| v A duplicate element is an element included more than once anywhere within the
| compound type. Duplicate elements do not have to be contiguous.

| For an example of how to set up a repeating element, see “Make elements

| repeatable” on page 168.
| Table 13. Repeated and duplicate elements in a compound type
| Example Elements in type Unordered Set Ordered Set Sequence Simple
| Unordered Set
| No repeats, no A, B, C Yes Yes Yes Yes
| duplicates
| Repeated element A[n], B, C Yes Yes Yes No
| (contiguous)
| Duplicate element A A, A, B, C No No Yes No
| (contiguous)
| Duplicate element A A, B, C, A No No Yes No
| (non-contiguous)
|

| Compound type member properties

| When you include a compound type as a child within another compound type,
| additional properties are associated with the compound type’s member
| relationship with its parent compound type, and are displayed on the Connection
| pane. These properties are described in Table 14. These properties all define the
| compound types cardinality.

| For an example of how to set up a repeating element, see “Make elements

| repeatable” on page 168.
| Table 14. General compound type member properties on the Connection pane
| Property Type Meaning
| Repeat BOOLEAN You can set this to Yes (if the whole structure represented by this compound type
| can occur more than once), or No (if it cannot). (If individual elements within this
| compound type repeat, you must set the Repeat property in the appropriate
| element member property pane within this compound type.)
| Min Occurs INTEGER Specify the minimum number of times that the object within the compound type
| can repeat. This property is only valid if you have set Repeat to Yes.
| Max Occurs INTEGER Specify the maximum number of times that the object within the compound type
| can repeat. This property is only valid if you have set Repeat to Yes.

54 WebSphere MQ Integrator Working with Messages

 Category
| Category
| A category is an optional entity that you can use to logically group the messages
| or transactions that you have defined in your message set.

| The characteristics of the category are:

| v A category is a logical business grouping of messages or transactions within a
| message set.
| v There are two types of category:
| – Message categories. You can add only messages to this category. You can
| include the same message in multiple categories.
| – Transaction categories. You can add only transactions to this category. You can
| include the same transaction in multiple categories.

| You cannot mix messages and transactions within a category.

| v You can use message categories if you choose to display message definitions in a
| logically partitioned fashion.
| v If you want to generate language bindings or documentation, you must define a
| category and add messages to it.
| v Category information is never included in a run time dictionary.

| Figure 14 shows three message categories defined in the banking example message
| set CHECK_ACC_MSGSET. The three categories have been created to hold
| messages specific to credits, debits, and enquiries.
|
|

MSG-1 MSG-2 MSG-3 MSG-4

CREDIT_CAT ENQ_CAT

MSG-5 MSG-6

DEBIT_CAT

CHECK_ACC_MSGSET
|
| Figure 14. Messages within categories

| Control Center property panes

| The following Control Center property panes are associated with a message
| category:
| v General Category pane. This is where you define the category properties
| described in “Category properties” on page 56.
| v History pane. This is used to add documentation to the definition.
| v An additional pane is displayed for each language binding that you add to the
| message set. For detail of their content, see “Adding a language binding” on
| page 162.
|

Chapter 4. The MRM logical message model 55

 Category
| Category properties
| Table 15 defines the properties that you can set to customize the category.
| Table 15. General category properties
| Property Type Meaning
| Name STRING Specify a name for the category when you create it.
| Identifier STRING Specify an identifier for the category when you create it.
| Suspended BOOLEAN Select Yes or No from the drop-down list. You can consider suspend as a soft
| from Use delete.

| A suspended category does not appear in extracted documentation. You can add
| messages to a suspended message category, and transactions to a suspended
| transaction category.

| You cannot create an object in the suspended state. If you want to suspend an
| object, you must check in the newly created object, and check it out again to
| make this update.
|

| A message category has no properties associated with membership of a message

| set

| Element qualifier
| An element qualifier defines additional information that makes the definition of an
| element more specific. You can use an element qualifier to add constraints to the
| model.

| The characteristics of an element qualifier are:

| v It is used to qualify an element. When you have associated an element qualifier
| with an element, you can add a value constraint to the element qualifier in a
| similar fashion to adding a value constraint to an element (defined in Table 20
| on page 62).
| You can use element qualifiers, like element values, to associate rules or
| restrictions with an element.
| v You can associate several element qualifiers with an element. When you include
| the element in a message, you can select the most appropriate element qualifier
| (and thus any value constraint associated with the element qualifier) by checking
| out the message, and updating the element qualification pane of the selected
| element. If there is a conflict between a value constraint associated directly with
| an element and a value constraint associated indirectly with an element through
| an element qualifier, the element qualifier takes precedence.

| When you have defined an element qualifier, you can add a constraint to it, for
| example, a minimum length. You can associate the element value with an element
| qualifier, and associate the element qualifier with the element, by updating the
| Element Qualification pane. This relationship is shown in Figure 15 on page 57.
|

56 WebSphere MQ Integrator Working with Messages

 Element qualifier
|
ELEMENT1 MSG1
(element) (message)

references member of

ELEMQUAL
(element qualifier)

member of

MAXLEN
(element value)

references

INTEGER
(simple type)

|
| Figure 15. Element qualification

You can also use element values to add constraints to an element. This is described
in “Element value” on page 59.

Control Center property panes

The following Control Center property panes are associated with an element:
v General Element Qualifier pane. This is where you define the element properties
described in “Element qualifier properties”.
v History pane. This is used to add documentation to the definition.
v Element Qualification pane. This is used to detail properties associated with
member relationships. When you have associated an element qualifier with an
element included in a message, additional properties are associated with the
member relationship.

Element qualifier properties

Table 16 defines the properties that you can set to customize the element qualifier.
Table 16. General element qualifier properties
Property Type Meaning
Name STRING Specify a name for the element qualifier when you create it.
| Identifier STRING Specify an identifier for the element qualifier when you create it.
| Suspended BOOLEAN Select Yes or No from the drop-down list. You can consider suspend as a soft
| from Use delete.

| You can add element values to a suspended element qualifier.

| You cannot create an object in the suspended state. If you want to suspend an
| object, you must check in the newly created object, and check it out again to
| make this update.
| Element Name Enumerated Specify the name of the element with which this qualifier is associated. You can
| Type only select an element from the displayed list of elements that already exist
| within this message set.
|

Chapter 4. The MRM logical message model 57

 Element qualifier
Element qualifier member properties
You can associate an element qualifier with an element instantiated within a
message by updating the Element Qualification pane displayed when you view the
instantiated element. This pane includes the cardinality settings (Repeat, Min Occurs
and Max Occurs) usually found on the Connection pane. These properties are
identical to those defined in Table 14 on page 54.

The member relationship affects the path from the root of the message to the
element identified by the element qualifier. If you update the cardinality, for
example to make the element mandatory, you force all the elements down the path
to this element to be mandatory even if the Connection pane specifies optional.
The change to the element qualifier overrides the corresponding properties on the
| related objects, and might result in unexpected behavior.

| Transaction
| A transaction is an optional entity that you can use to group a set of messages that
| you consider to be a single business transaction. Do not confuse this with a
| transaction that is determined by XA coordination. Its use is simply to group
| messages that serve a related purpose.

| The characteristics of a transaction are:

| v A transaction can contain one or more messages that are defined to this message
| set. A single message can be included in more than one transaction.
| v You can use a transaction to partition message definitions.
| v Transaction information is never included in a run time dictionary.

| The banking example message set has been enhanced to include a transaction
| category CREDIT_CAT, that contains transaction CREDIT_TXN, as shown in
| Figure 16. The transaction contains two messages, a request message and a reply
| message, that together make up each credit and debit operation. The reply message
| acknowledges the success or failure of the operation.
|
|

REQ-MSG REPLY-MSG

CREDIT_TXN

CREDIT_CAT
|
| Figure 16. Messages within transactions

| Control Center property panes

| The following Control Center property panes are associated with a message
| transaction:
| v General Transaction pane. This is where you define the transaction properties
| described in “Transaction properties” on page 59.
| v History pane. This is used to add documentation to the definition.
| v An additional pane is displayed for each language binding that you add to the
| message set. For detail of their content, see “Adding a language binding” on
| page 162.

58 WebSphere MQ Integrator Working with Messages

 Transaction
| Transaction properties
| Table 17 defines the properties that you can set to customize the transaction.
| Table 17. General transaction properties
| Property Type Meaning
| Name STRING Specify a name for the transaction when you create it. The name must be unique
| within the message set.
| Identifier STRING Specify an identifier for the transaction when you create it.
| Suspended BOOLEAN Select Yes or No from the drop-down list. You can consider suspend as a soft
| from Use delete.

| You can add messages to a suspended transaction. You cannot add a suspended
| transaction to a transaction category.

| You cannot create an object in the suspended state. If you want to suspend an
| object, you must check in the newly created object, and check it out again to make
| this update.
|

| A message transaction has no properties associated with membership of a message

| set

| Element value
| You can use an element value to build constraints into your message model.

| The characteristics of an element value are:

| v An element value allows you to associate, by reference, a value with a simple
| type, which can be added to an element or element qualifier to set a value
| constraint on the associated element. The nature of the constraint is known as
| the Role (for example, maximum length). The roles available, and their meaning,
| are defined in Table 19 on page 61.
| You can use element values to associate rules or restrictions with an element. For
| example, if you have defined a string element, you can add an element value to
| define the element’s maximum length. Or you might restrict the valid content of
| a field to a set of fixed values, using an element value with a role of
| Enumeration.
| An element can have several element value constraints associated with it. It is
| possible to have two conflicting value constraints associated with an element,
| one added directly to the element, the second added through definition of an
| element qualifier. In this case, the element qualifier always takes precedence.
| v Value constraints of Null Permitted and Default Value are used by the broker,
| Max Length is enforced by the broker. The remaining value constraints are not
| enforced by the broker. They are for documentation purposes only.

| In the example in Figure 17 on page 60, the element ELEMENT1 is defined based
| on simple type STRING. If you want to limit the size of this string to 10 characters,
| you can define an element value, MAXLEN, instantiate it as a simple type of
| INTEGER, and set its value to 10. You can then associate the element value with
| the element ELEMENT1 by adding a value constraint with a role of Max Length to
| the element and selecting the element value MAXLEN.
|

Chapter 4. The MRM logical message model 59

 Element value
|
ELEMENT1
(element)

member of

MAXLEN
(element value)

references

INTEGER
(simple type)

|
| Figure 17. Example of an element value

Control Center property panes

The following Control Center property panes are associated with an element value:
v General Element Value pane. This is where you define the element value
properties described in “Element value properties”.
v History pane. This is used to add documentation to the definition.
v Connection pane. This is used to detail properties associated with member
relationships. When an element value has been associated with an element or
element qualifier, an additional property, Role, is associated with the member
relationship. Role defines the type of value constraint (defined in “Element value
member properties” on page 61.

Element value properties

Table 18 defines the properties that you can set to customize the element value.
Table 18. General element value properties
Property Type Meaning
Name STRING Specify a name for the element value when you create it.
| Identifier STRING Specify an identifier for the element value when you create it.
| Suspended BOOLEAN Select Yes or No from the drop-down list. You can consider suspend as a soft
| from Use delete.

| You cannot add suspended element values to elements or element qualifiers.

| You cannot create an object in the suspended state. If you want to suspend an
| object, you must check in the newly created object, and check it out again to
| make this update.
| Type Enumerated Specify the type of the element value. Select one of the simple types, except
| Type BINARY which cannot be specified. You cannot change this property after you
| have created the element value and checked it in.

| There is no need for an element value of type BINARY due to the absence of an
| enumeration role for BINARY value constraints. The data held in a BINARY
| element is treated as a group of bits and is not validated against enumerated
| values. If you create an element value under an element or element qualifier in
| the message set tree (rather than as an individual object in the Element Values
| folder), you must create it in a particular role. In this case its Type is set
| automatically in the context of that role, and you cannot change it.

60 WebSphere MQ Integrator Working with Messages

 Element value
| Table 18. General element value properties (continued)
| Property Type Meaning
| Value Dependent on Specify the value of the element value. This property is restricted by your choice
| Role of the Role that this element value is to take when you associate it with an
| element (defined in “Element value member properties”). Refer to Table 20 on
| page 62 for valid combination of Value and Role properties.

| For some element data types, take these restrictions into account when you set
| Value:
| v If the element with which you associate this element value is BOOLEAN, enter
| one of the following values for the Value property: 0, 1, true, or false.
| v If the element with which you associate this element value is DATETIME, enter
| an ISO compatible string for the Value property. For details of valid strings, see
| Appendix C, “DATETIME formats” on page 253.
| v If the element with which you associate this element value is STRING, enter
| only alphanumeric characters for the Value property.
|

| Element value member properties

| When you have associated an element value with an element or element qualifier,
| one additional property is associated with the member relationship and is
| displayed on the Connection pane. This property is described in Table 19. Table 20
| on page 62 shows which roles are valid in combination with which simple types.
| Table 19. General element value member properties on the Connection pane
| Property Type Meaning
| Role Enumerated Type Specify the nature of the constraint that the value is performing on the associated
| element. Set this to one of the following:
| v Enumeration. Use this to indicate that the element value defines one of a list of
| fixed values that the contents of the associated element must match.
| v Default Value. Set this to indicate that the element value defines the default
| value for the associated element.
| v Null Permitted. If you want to override the setting of the Default Null Permitted
| property that you set at the message set level (see “Message set properties” on
| page 43), define an element value of type BOOLEAN and sets its value to true
| (to indicate that a null value is permitted) or false (to indicate that it is not).
| Associate the element value with the element with Role set to Null Permitted.
| For further information, see “Null handling” on page 64.
| v Min Length. Set this to indicate that the element value defines a minimum length
| for the associated element.
| v Max Length. Set this to indicate that the element value defines a maximum length
| for the associated element.
| v Min Inclusive. Set this to indicate that the element value defines the minimum
| value that the associated element can take.
| v Max Inclusive. Set this to indicate that the element value defines the maximum
| value that the associated element can take.
| v Scale. Set this to define the maximum number of digits that can be present in the
| fractional part of the value for a DECIMAL element.
| v Date Template. Set this to indicate which sub-fields of DATETIME can be present
| for the element.
|

Chapter 4. The MRM logical message model 61

 Element value
| Table 20. Valid combinations of element value types and roles
| Type Enumeration Default Null Min Len Max Min Max Scale Date
| Value Permitted Len Inclusive Inclusive Template
| BINARY (1) (2) (2)
| BOOLEAN (3) (3) (1)
| DATETIME (3) (3) (1) (3) (3) (4)
| DECIMAL (3) (3) (1) (3) (3) (2)
| FLOAT (3) (3) (1) (3) (3)
| INTEGER (3) (3) (1) (3) (3)
| STRING (3) (3) (1) (2) (2) (3) (3)

| Notes:
| 1. The type of the element value object must be BOOLEAN.
| 2. The type of the element value object must be INTEGER.
| 3. The type of the element value object must be the same as that of the element.
| 4. The type of the element value object must be STRING.
|
|
| Relationships between MRM objects
| You can associate MRM objects with one another in two ways (shown in Figure 18
| on page 63):
| v By Reference. For example, an element references its underlying type (which
| might be INTEGER, STRING, and so on).
| v Member of. For example, a compound type might be formed from three elements.
| These elements are members of the compound type. You can view and modify
| additional properties associated with the member of relationship. For example,
| does the element repeat within this compound type, and is it mandatory or
| optional?

| Figure 18 on page 63 shows the required and optional components of a message

| set. The optional components are shaded, the required objects are unshaded. The
| relationships between all objects are marked.
|

62 WebSphere MQ Integrator Working with Messages

 Wire format implications

Message
Set

Reference
Message Transaction Member
Category Category Transaction

Member Member
Message

Reference Member

Member
Reference Compound
Type
Member

Member

Reference Reference Element

Element
Qualifier

Member Member

Simple Type Reference Element

Value

Figure 18. MRM objects and their relationship to each other

| Implications for the logical model when defining messages of different

| wire formats
| When you create a logical message model, it includes no consideration of the
| physical representation of the message. There are certain constructs in the logical
| model that lend themselves very well to modeling different aspects of the physical
| characteristics of the messages that are sent and received by your applications. The
| details of these are covered in the chapters on each of the wire formats supported:
| v For CWF, see “The relationship between the logical model and CWF” on
| page 107
| v For XML, see “The relationship between the logical model and the XML wire
| format” on page 123
| v For TDS, see “The relationship between the logical model and the TDS wire
| format” on page 149

| Predefined and self-defining elements and messages

| The MRM supports both predefined and self-defining messages:
| v A predefined message is a message that is completely defined to the MRM: the
| message has been completely defined in the message repository through the
| Control Center, and the MRM parser in the broker has a dictionary that details
| all the elements that are expected to be present in the message (the message set
| definition has been deployed to the broker). If elements are missing, or
| additional elements are encountered, the broker flags this as an error.

Chapter 4. The MRM logical message model 63

 Wire format implications
| v A self-defining message is a message that is self-describing and contains
| information within its own data that defines the elements. You do not need to
| define a self-defining message to the MRM parser.

| CWF is used to model fixed format messages and thus the message and all the
| elements in the message must be predefined. The CWF cannot handle elements
| that are not defined in the model, because C headers and COBOL copybooks
| cannot be dynamically changed.

| The TDS layer supports both predefined and self-defining messages, and can be
| used to model both types of message, or a message that is a combination of the
| two. The XML layer provides support for self-defining messages and self-defining
| elements. Both layers can handle elements that are not defined within the model.

| In addition, you can create partial definitions of messages, in which some elements
| have been defined to the MRM, but others are self-defining. This is very useful if
| you want to update just part of a very large message. You can choose to define to
| the MRM only the sections of message that are to be altered: the remaining
| elements are treated as self-defining. This technique is referred to as a sparse
| message model.

| The XML domain and the generic XML parser (described in Chapter 10, “The XML
| domain” on page 191) only support self-defining messages, which means that
| validation is limited because there is no dictionary in the parser against which to
| validate the message. If a message is interpreted as self-defining by the parser, you
| can define the message to the MRM through the Control Center (but you do not
| need to deploy the message set to the broker). This helps you with message flow
| design because it allows you to use drag and drop to generate ESQL in message
| flow nodes.

| Null handling
| There are two types of null representation in the MRM:
| 1. Explicit null. A null value is explicitly stated with a value. This value can be
| assigned and queried using ESQL. Explicit nulls can be used in all wire formats
| except PDF (where null is always assumed to be –1).
| 2. Implicit null. A null value is absent from a message and is therefore implied.
| This is valid for the XML wire format layer, but is not applicable for CWF and
| TDS, where there is no concept of implicit NULL.

| For more information about using null values in ESQL, see “Querying null values
| in an input message” on page 74 and “Setting null values in an output message”
| on page 74.

| Within the MRM you can set various elements to NULL. Table 21 on page 65
| shows which elements are allowed to take NULL values, depending on their MRM
| simple type.

64 WebSphere MQ Integrator Working with Messages

 Null handling
| Table 21. NULL permitted for element based on simple types
| Element based on simple type NULL permitted
| BINARY XML only (see Chapter 6, “Working with an XML
| Format layer” on page 111)
| BOOLEAN Yes
| DATETIME Yes
| DECIMAL Yes
| FLOAT Yes
| INTEGER Yes
| STRING Yes
|

| To enable an element to have an MRM-defined null value, do one of the following:

| 1. Set the message set property Default Null Permitted to Yes.
| 2. Create an element value of type BOOLEAN with value true, and add this
| element value to your element, specifying a Role of Null Permitted. This
| overrides the message set property.
| Table 22. Resolved Null Permitted
| Message set Default Null Element value role Null Resolved Null Permitted
| Permitted Permitted
| No (not valid) false (null is not permitted)
| No true true (null is permitted)
| No false false
| Yes (not valid) true
| Yes true true
| Yes false false
|

| Setting the value of null

| You can set the value of null. Table 23 defines the default null values for CWF and
| TDS layers. For further discussion of these settings, see Chapter 5, “Working with a
| Custom Wire Format layer” on page 83 and Chapter 7, “Working with Tagged
| Delimited String messages” on page 131.
| Table 23. Default null values for CWF and TDS
| Logical type Encoding Null Encoding Null Val
| BINARY Not applicable Not applicable
| BOOLEAN Not applicable Not applicable
| DATETIME NULLPadFill An empty string
| DECIMAL NULLLogicalValue 0
| FLOAT NULLLogicalValue 0
| INTEGER NULLLogicalValue 0
| STRING NULLLogicalValue An empty string
|

Chapter 4. The MRM logical message model 65

 Null handling
| NULL handling for base types
| There is a distinction in the message tree between a value missing and a value
| having a null value.

| If a compound type has a base type (defined in “Type” on page 49), it implicitly
| has a value. If it does not, it has no value. When a base type is present without a
| value, a null event is output. For an example of how these are handled, see “Null
| handling” on page 74 in “Using ESQL to manipulate the message tree” on page 69.

| Data conversion
| If you are processing messages that originate from applications running on
| different systems, or in different locales, or both, you must consider if message
| data needs to be converted. For further discussion of data conversion
| considerations, refer to the section “Planning for data conversion” in the WebSphere
| MQ Integrator Introduction and Planning book.

| If you use WebSphere MQ Integrator facilities to provide data conversion, these are
| governed by the choice of wire format layer. For further details, see:
| v “Data conversion with CWF” on page 106
| v “Data conversion with XML” on page 122
| v “Data conversion with TDS” on page 146

| If your messages use the MQSeries transport protocol, you can also use MQSeries
| facilities. See the MQSeries Application Programming Reference book.

| The broker’s view of the logical message model

| You have seen how to model a message in the Control Center. When you assign
| your message set to the broker, and deploy it (in the form of a run time
| dictionary), and a message belonging to this message set is received by the broker,
| the MRM parser matches the message to the dictionary and creates a
| representation of the message in the form of a tree.

| The tree it creates is a structure that is devoid of any information associated with
| the physical characteristics of the message. It is made up of items (called elements)
| that represent the components in your message model.

| You can clearly see the tree format that is created if you trace a message (from the
| root of the message tree) using a Trace node in a message flow.

| An example of a message in the broker

| Consider the example of message MSG 1, which is based on the top level message
| compound type. Its structure is shown in Figure 19 on page 67.
|

66 WebSphere MQ Integrator Working with Messages

 The broker’s view of the message model
|
MSG 1

Element Fred
(based on simple type STRING)

Element George
(based on compound type
with a base type of STRING)

Element Nick
(based on simple type STRING)

Element Ian
(based on simple type STRING)

Embedded compound type

Embedded simple type (STRING)

Element Jo
(based on compound type)

Element Kate
(based on simple type STRING)
|
| Figure 19. An example message
|
| You could represent this message in XML with the following content:
| <Fred>hello<Fred>
| <George>world
| <Nick>nice</Nick>
| <Ian>hot</Ian>day
| <Jo>
| <Kate>today</Kate>
| </Jo>
| </George>

| The message, MSG 1, contains elements (instantiated simple and compound types),
| embedded simple types, and embedded compound types. One of the compound
| types (George) has a base type associated with it. The message tree that is created
| from this message is shown in Figure 20 on page 68.
|

Chapter 4. The MRM logical message model 67

 The broker’s view of the message model
|
MRM

George
Fred (with associated value)

STRING
Nick Ian Jo
(ambiguous)

Kate

|
| Figure 20. Example message tree
|
| The first tree element is MRM. This corresponds to the tree element Body in the
| message tree structure shown in Figure 1 on page 13. If the message is parsed by
| the MRM parser, the first element is always MRM. The parser creates a named
| element in the tree that corresponds to each MRM element that you have defined
| in your message model (whether it is an instantiated simple or compound type).
| The parser allocates a name to each element in the tree that equates to the
| identifier of the equivalent element in the message model.

| However, if the model includes an embedded compound type (a compound type

| embedded in another compound type) that has not been instantiated as an
| element, the embedded compound type does not get allocated an element in the
| tree. Therefore, in this example, the elements Nick and Jo appear as a sibling of
| Ian, even though you might expect them to be another level down in the tree. If
| the compound type they are included in had been instantiated as an element, these
| two elements would indeed be at a lower level in the tree.

| Embedded simple types do not have a name because they are not instantiated as
| an element, therefore the tree contains an ambiguous element. The embedded
| simple type appears as an element in the tree, and has a value, but it has no
| associated name.

| The element George, which is based on a compound type that has an associated
| base type, has a value (data) associated with it. However, the element Jo, which is
| also based on a compound type, has no value (data) associated with it because the
| compound type has no base type defined.

| Accessing elements from an message flow node

| Assume that you have created a message flow that handles the message MSG 1. If
| you have included a Compute node in this message flow, and you want to update
| the element Nick with the value horrid, you must use the following assignment:
| SET OutputRoot.MRM.George.Nick=’horrid’;

| If you want to update element Kate with the value yesterday you must:
| SET OutputRoot.MRM.George.Jo.Kate=’yesterday’;

68 WebSphere MQ Integrator Working with Messages

 The broker’s view of the message model
| You use the structure and arrangement of the elements in the tree to access each
| element by following the relevant parent and child relationships from the tpo of
| the tree downwards, until you reach the required element. (OutputRoot is one of a
| number of correlation names that you can use in ESQL to refer to specific parts of
| the message tree. See the WebSphere MQ Integrator ESQL Reference book for details
| of these names.)

| You can see from these examples that the name that you defined for the message
| model does not appear in the ESQL. You must address each element in the ESQL
| using the model element identifier, not the name.

| For further general information about using ESQL to access elements, see
| “Referencing elements” on page 71.

| Accessing simple types from a message flow node

| If you want to update the embedded simple type with the value night, you must
| include the following statement in the ESQL in your Compute node:
| SET OutputRoot.MRM.George.*[3] = ’night’;

| This statement sets the third child of the element George to night. Because this
| statement is addressing an ambiguous element in the tree (an embedded simple
| type that has no name), you can only set its value if you know its specific position
| in the tree.

| For further general information about using ESQL to access simple types, see
| “Referencing simple types” on page 72.

| Accessing base types from a message flow node

| The element George has been defined with a base type. If you want to update the
| base type to contain the value England, code the following ESQL:
| SET OutputRoot.MRM.George = ’England’;

| The base type becomes the value (data) associated with the element’s underlying
| compound type.

| For further general information about using ESQL to access base types, see
| “Referencing base types” on page 72.

| Accessing compound types from a message flow node

| You can see from MSG 1 that embedded compound types do not appear in the
| tree, and there is no tree element associated with them. Only the children of the
| embedded compound type can be seen in the tree. If an embedded compound type
| has a base type associated with it, you must use the same technique you used for
| the embedded simple type to address the base type of the embedded compound
| type. Therefore the base type of an embedded compound type is handled in the
| same way as an embedded simple type in the tree.

| For further general information about using ESQL to access compound types, see
| “Referencing compound types” on page 73.

| Using ESQL to manipulate the message tree

| Now that you have seen a simple message tree, and how you can access that tree,
| this section further explores how you can use ESQL to manipulate the contents of
| the MRM messages in the nodes of a message flow.

Chapter 4. The MRM logical message model 69

 Using ESQL
| For detailed information about ESQL in general, and for full reference information
| about the functions and statements supported, see the WebSphere MQ Integrator
| ESQL Reference book.

| If you want your message flow to process MRM messages, you must ensure that
| the following properties are set. If the message is an MQSeries message, these can
| be set either in the input node or in the MQRFH2 header of the incoming message
| (if they are set in both, the contents of the MQRFH2 header take precedence). If the
| message is not an MQSeries message, these properties must be set in the input
| node of the message flow:
| v Message Domain
| v Message Set
| v Message Type
| v Message Format

| For further information about the MQRFH2 header, see the WebSphere MQ
| Integrator Programming Guide. For further information about input node properties,
| see the Control Center online help.

| When the output message is generated, you can set these properties using ESQL.
| The output properties do not have to be the same as the input properties:
| Table 24. Output MRM message properties
| Property Value
| Message Domain MRM
| Message Set Message set identifier
| Message Type Message identifier (see note)
| Message Format PDF or wire format identifier
| Note: If you are using multipart messages, refer to Table 3 on page 44 for details of how
| MessageType is used.
|

| For example, to set the output message properties for an output MRM message,
| use the following ESQL:
| SET OutputRoot.Properties.MessageDomain = ’MRM’;
| SET OutputRoot.Properties.MessageSet = ’DH06JOE06S001’;
| SET OutputRoot.Properties.MessageType = ’m_mess101’;
| SET OutputRoot.Properties.MessageFormat = ’XML’;

| or
| SET OutputRoot.Properties.MessageFormat = ’CWF’;

| or
| SET OutputRoot.Properties.MessageFormat = ’TDS’;

| You must set the message domain to MRM even if the output message format is
| XML.

| If you select the property Use as Message Body by checking the check box in the
| Compute node properties dialog, this sets the Message Set and Message Type
| properties for the output message (propagated from this node) to be the same as
| those for the message received by this node.

70 WebSphere MQ Integrator Working with Messages

 Using ESQL
| The message objects that you have defined within the MRM are set as part of the
| message body. When you refer to these defined MRM objects using ESQL, you
| must identify the parser name as MRM (the start of the message tree, as shown in
| Figure 20 on page 68). For example:
| SET OutputRoot.MRM.Field1 = InputBody.Field1 + 1;

| In ESQL, element identifiers are usually used to reference and update MRM
| elements. The exception is when simple types are present in the message. If you
| are using multipart messages, the simple type references must be further qualified
| by the message identifier if the message is not the first message object in the bit
| stream.

| Referencing elements
| If you want to copy an element from input to output without changing it, use the
| following ESQL:
| SET OutputRoot.MRM.Name.FirstName = InputBody.Name.FirstName;

| If you want to copy an element from input to output, and update it, for example
| by folding to uppercase or by calculating a new value:
| SET OutputRoot.MRM.Name.FirstName = UPPER(InputBody.Name.FirstName);
| SET OutputRoot.MRM.Borrowed.Cost = InputBody.Borrowed.Cost * 1.5;

| If you want to set a STRING element to a constant value, you can:

| SET OutputRoot.MRM.Name.Title = ’Mr’;

| To set an INTEGER or DECIMAL element to an integer value:

| SET OutputRoot.MRM.Address.HouseNo = 99;

| To set a FLOAT element to a non-integer value:

| SET OutputRoot.MRM.FloatElement1 = 1.2345e2;

| To set a BINARY element to a constant value:

| SET OutputRoot.MRM.BinaryElement1 = X’F1F1’;

| To set a BOOLEAN element to a constant value (the value 1 equates to true):

| SET OutputRoot.MRM.BooleanElement1 = true;
| SET OutputRoot.MRM.BooleanElement1 = 1;

| Multiple occurrences of elements: To set an occurrence of an element, use the

| occurrence number within brackets to indicate which instance of the element to
| process. For example:
| SET OutputRoot.MRM.Borrowed[1].VideoTitle = ’MRM for experts’;

| If you have set the Type Composition property of the compound type that contains
| the element to Sequence, you can add the same element to the compound type
| more than once (a duplicate). These instances do not have to be contiguous, but
| you must use the same method to refer to them.

| For example, if you create a compound type with Type Composition of Sequence that
| contains the following elements:
| StringElement1
| IntegerElement1
| StringElement1

Chapter 4. The MRM logical message model 71

 Using ESQL
| use the following ESQL to set the value of the first occurrence of StringElement1:
| SET OutputRoot.MRM.StringElement1[1] = ’FRED’;

| and the following assignment to set the value of the second occurrence:
| SET OutputRoot.MRM.StringElement1[2] = ’BILL’;

| Referencing simple types

| A simple type does not have an identifier that uniquely defines it in ESQL,
| therefore if you want to interrogate or update a simple type, you must reference it
| in relation to other known objects in the message.

| If you are working with the following XML message:

| <Mess1><Elem1>abc</Elem1><Elem2>abc<Child1>def</Child1></Elem2></Mess1>

| you can model this using the following objects:

| Message
| The message Identifier property is set to Mess1, the Type property is set to
| tMess1.
| Type The compound type Identifier property is set to tMess1, the Type Composition
| property is set to Sequence. The compound type contains the following
| objects:
| Simple Type
| STRING
| Element
| The element Identifier property is set to Elem1, the Type property is
| set to simple type STRING.
| Element
| The element Identifier property is set to Elem2, the Type property is
| set to compound type tElem2.
| Type The compound type Identifier property is set to tElem2, the Type Composition
| property is set to Ordered Set, the Type property (the compound type’s
| base type) is set to null. This compound type contains the following object:
| Element
| The element Identifier property is set to Child1, the Type property is
| set to simple type STRING.

| If you want to set the value of Elem1 to xyz, use the following ESQL:
| SET OutputRoot.MRM.Elem1.*[1] = ’xyz’;

| A simple type does not have facilities for null handling that many elements have.
| If you set a simple type to null, it is deleted from the message.

| Referencing base types

| You can assign a base type to an element that has a value in addition to children,
| unless it is the compound type that represents the entire message.

| The sample Video message, described in “Example: modeling the Video customer
| message” on page 78, has an element Name that has child elements Title and
| FirstName. It also has a base type of STRING. You can use this to model an
| incoming XML message like this:
| <Customer><Name>Edwards<Title>Mr</Title><FirstName>Peter</FirstName></Customer>

72 WebSphere MQ Integrator Working with Messages

 Using ESQL
| If you want to set the value of Title to Mrs in ESQL, code the following:
| SET OutputRoot.MRM.Name.Title = ’Mrs’;

| To set the value of Name to Morgan in ESQL, code the following:

| SET OutputRoot.MRM.Name = ’Morgan’;

| You do not reference the message or compound type identifiers in these

| statements.

| Referencing compound types

| A compound type does not have an identifier that uniquely defines it in ESQL,
| therefore if you want to interrogate or update a compound type, you must
| reference it in relation to other known objects in the message. Often a compound
| type is for logical grouping purposes only and it is the elements within that
| compound type that you want to access using ESQL.

| Referencing embedded messages: If you have defined a multipart message, this

| means that you have at least one message embedded within another. Within the
| overall compound type that represents the outer messages, you can model the
| inner message in one of the following ways:
| v An element with its Type property set to a compound type that that has been
| defined with Type Composition set to Message
| v A compound type with Type Composition property set to Message

| The ESQL that you need to write to manipulate the inner message varies
| depending on which of the above models you have used. For example, assume
| you have defined:
| v An outer message with Identifier set to M_outer.
| v An inner message with Identifier set to M_inner1. This inner message is defined
| as an element with Identifier set to E_outer1 and Type set to a compound type
| that has its Type Composition property set to Message. The first child element of
| the message M_inner1 has Identifier set to E_inner11.
| v A second inner message with Identifier set to M_inner2. This second inner
| message is defined as a compound type. The first child element of message
| M_inner2 has Identifier set to E_inner21.

| If you want to set the value of E_inner11, enter:

| SET OutputRoot.MRM.E_outer1.M_inner1.E_inner11 = ’FRED’;

| If you want to set the value of E_inner21, enter:

| SET OutputRoot.MRM.M_inner2.E_inner21 = ’FRED’;

| If you copy message headers from the input message to the output message, and
| your input message type contains a path, only the outermost identifier in the path
| is copied to the output message type.

| Compound types with Type Composition set to Choice: If you define messages
| within message sets that include XML and TDS wire formats, it is usually clear
| from the message data which option of a choice has been taken because the tags in
| the message represent one of the choice’s options. However, if your messages have
| CWF wire format, or are untagged TDS messages, it is not clear from the message
| data, and the application programs processing the message must determine which

Chapter 4. The MRM logical message model 73

 Using ESQL
| option of the choice has been selected. This is known as unresolved choice handling.
| For further information, see the information about a value of Choice in “Type
| property Type Composition” on page 107.

| Null handling
| Nulls are handled differently in input and output messages.

| Querying null values in an input message: If you want to check the value of an
| element, you would code ESQL like the following:
| IF InputBody.Elem2.Child1 = ’xyz’ .....

| If you want to compare this element to NULL, code the statement:

| IF InputBody.Elem2.Child1 IS NULL

| Assuming that nulls are permitted for this element (defined in Table 21 on
| page 65), this statement tests if the element exists in the input message, or if it
| exists and contains the MRM-supplied null value. The behavior of this test
| depends on the wire format:
| v For an XML element, if the XML tag or attribute is not in the bit stream, this test
| returns TRUE.
| v For an XML element, if the XML tag or attribute is in the bit stream and contains
| the MRM null value, this test returns TRUE.
| v For an XML element, if the XML tag or attribute is in the bit stream and does
| not contain the MRM null value, this test returns FALSE.
| v For a delimited TDS element, if the element has no value between the previous
| delimiter and its delimiter, this test returns TRUE.
| v For a delimited TDS element, if the element has a value between the previous
| delimiter and its delimiter which is the same as the MRM-defined null value for
| this element, this test returns TRUE.
| v For a delimited TDS element, if the element has a value between the previous
| delimiter and its delimiter which is not the MRM-defined null value, this test
| returns FALSE.
| v For a CWF or fixed length TDS element, if the element’s value is the same as the
| MRM-defined null value for this element, this test returns TRUE.
| v For a CWF or fixed length TDS element, if the element’s value is not the same as
| the MRM-defined null value, this test returns FALSE.

| If you want to determine if the field is missing, rather than present but with null
| value, you can use the ESQL CARDINALITY function.

| Setting null values in an output message: If you want to set a value of an

| element in an output message, you would use an ESQL statement similar to the
| following:
| SET OutputRoot.MRM.Elem2.Child1 = ’xyz’;

| You can also use the equivalent statement:

| SET OutputRoot.MRM.Elem2.Child1 VALUE = ’xyz’;

74 WebSphere MQ Integrator Working with Messages

 Using ESQL
| These two ESQL statements achieve the same result if you are setting the element
| to a specific non-null value. However, if you want to set the value to null, these
| two statements do not give the same result:
| 1. If you set the element to NULL using the following statement, the element is
| deleted from the message tree:
| SET OutputRoot.MRM.Elem2.Child1 = NULL;

| The content of the output bit stream would depend on the wire format:
| v For an XML element, neither the XML tag or attribute nor its value would be
| included in the output bit stream.
| v For a Delimited TDS element, neither the tag (if appropriate) nor its value
| would be included in the output bit stream. The absence of the element
| would typically be conveyed by two adjacent delimiters.
| v For a CWF or Fixed Length TDS element, the content of the output bit
| stream depends on whether the element has an element value of type
| Default. If it does have this value, the default value is included in the bit
| stream. If it does not, an exception is raised.

| This is called implicit null processing.

| 2. If you set the value of this element to NULL as follows:
| SET OutputRoot.MRM.Elem2.Child1 VALUE = NULL;

| the element is not deleted from the message tree. Instead, a special value of
| NULL is assigned to the element. The content of the output bit stream depends
| on the settings of the wire format null handling properties.

| This is called explicit null processing.

| If you set a compound element to NULL, this deletes that element and all its
| children.

| Null handling for base types: You can work with null values for base types. For
| example, message m1 is defined as follows:
|
|
m1

s1 base type INTEGER

element1

element2
|
| You can use the following ESQL:
| SET OutputRoot.MRM.m1.s1.element1 = 5;

| If the output message is rendered in XML, and you have set the message set
| property Encoding Num Null in the XML wire format layer to NullAttribute, and
| the element member property Member Render for s1 to XMLElementAttrVal, the
| following output message is constructed:
| <m1>
| <s1 null="true">
| <element1>5</element1>
| </s1>
| </m1>

Chapter 4. The MRM logical message model 75

 Using ESQL
| A second input message is received with the following contents:
| <m1>
| <s1>
| <element1>5</element1>
| </s1>
| </m1>

| If this input message is processed by a Compute node that also modifies the input
| message, the null attribute also appears in the output message generated from this
| input message, because the omission of the value for the base type of s1 is
| equivalent to the presence of a null value.

Managing message sets

A message set has a number of properties and other characteristics that you can
view and modify in the Control Center. Some properties must be specified when
you create the message set, others can be added and modified after creation. A
message set also has a state, that indicates for example, if it is new or locked.

You can create message sets based on existing (finalized) message sets, both to
provide new versions of a single message set (with all versions retaining the same
name), and to use common characteristics and content from one message set in
another (where the new message set has a different name).

Message set states

| The state of a message set varies in line with development, testing, and production
| cycles. You can change the state of a message set in the Control Center, for
| example to lock the message set when you have completed development. You
| cannot move to all states from all others: where restrictions apply, they are noted
| in the description of the state.

The possible states of the message set are discussed in the following sections. For
information about changing states, see “Changing the state of a message set” on
page 174.

Normal
If a message set is not locked (checked out), frozen, or finalized, it is considered to
be in normal working state. It can be checked out, updated, and checked in. This
state is not explicitly displayed in the Control Center: it is inferred by the message
not being locked, frozen, or finalized.

When you create a new message set, it is automatically checked in, then checked
out, and you see the key icon appear against the new message set. A message set
is never shown in new state (with the new icon against it). This is because its
identifier must be unique, and its uniqueness is guaranteed by its being recorded
in (and therefore checked in to) the message repository. Components of the
message set (for example, an element) do appear as new when they are first
created.

Locked
The state of a message set while it is checked out (locked) by a Control Center
user. A message set must be locked to your user ID before you can change any of
its properties. A message set must also be locked to you before you can freeze it.

Frozen
This is the state of a message set that is not expected to change (for example, on
entry to a test phase). It is indicated by the existence of a Freeze date in the

76 WebSphere MQ Integrator Working with Messages

 Message set states
message set properties. Neither the message set itself nor its contents can be
changed when it is in this state, nor can they be checked out. If you want to make
subsequent changes, you must unfreeze the message set by selecting Unfreeze.

You cannot freeze a message set if any component of the message set is checked
out, or if a component definition it contains is incomplete.

A message set must move to the frozen state from the locked state, and both state
changes must be requested by the same user.

| If you import a message set from another message repository using the
| mqsiimpexpmsgset command, its state after import is Frozen.

Finalized
A message set and its components in this state cannot be changed or checked out.
Finalized state is indicated by the message property Finalized being set to true.

You are not allowed to finalize a message set if any component of the message set
is checked out or if a component definition it contains is incomplete.

A message set can move to the finalized state from any other state. However, if it
moves from the locked state to the finalized state, both state changes must be
requested by the same user.

When you have finalized a message set, no further changes can be made to its
contents. However, you can create a new message set based on the finalized
message set, within which you can define new messages. You can also make
limited changes to the existing messages in the new message set. For more
information, see “Message set versions”.

Message set versions

A message set can be based on another message set, provided that the message set
on which it is based has been finalized. You might want to use this facility to
maintain separate versions of a message set, reflecting the evolution of a message
set through maintenance and other fixes.

When a message set is based on another message set, it contains a copy of the
complete contents of the base message set. Within the new message set, new
messages can be defined, and limited modifications can be performed on existing
messages.

A message set can have the same name as another message set in the same
message repository if:
v The new message set is based on the message set of the same name.
v The message set on which it is based has a higher level number than any other
message set with the same name in the same repository.
v The level number of the new message set is higher than that of the message set
on which it is based.

Chapter 4. The MRM logical message model 77

 Modeling the Video customer message

| Example: modeling the Video customer message

| Figure 21 shows the Video customer message that is used an example in this
| chapter and in the three wire format chapters that follow.
|
Customer

Name Address IdType Borrowed Magazine

HouseNo Street Town VideoTitle DueDate Cost

Title FirstName PassportNo DrivingLicenseNo CreditCardNo

Figure 21. The Video Customer message

| This is a simple message model that shows you how you can build up a logical
| message model and its associated wire format layers. An example of what a
| message that conforms to the model looks like is given for each of the three wire
| formats, in the following chapters.

| The example message is defined for a chain of video rental stores. The message
| model contains data pertinent to a customer who is borrowing videos. Data
| contained in messages includes:
| v Customer name.
| v Customer address.
| v The type of identifier that is used as proof of identity when a customer opens an
| account with the video store.
| v The videos that are currently on loan to the customer, the name of the video,
| when it is due back, and the rental fee. A maximum of three videos can be on
| loan at any one time.
| v Whether the customer has a copy of this month’s magazine.

| To model this message in the MRM, you must first define a message set,
| “VideoStore”. Table 25 lists the message set properties and their values.
| Table 25. Video customer message model example: message set properties
| Property Value
| Name VideoStore
| Level 1
| Finalized false
| Freeze Time Stamp (not set)
| Default Wire Format (not set)
| Default Null Permitted No
| Message Type Prefix (not set)
| Identifier (set automatically when you create the message set)
|

| You can now define the message “Customer”, and the top level compound type on
| which it is based. In the example, this is called “CustomerType”. You must define

78 WebSphere MQ Integrator Working with Messages

 Modeling the Video customer message
| the compound type before you define the message, because you need to specify a
| valid (defined) compound type when you define the message. The compound type
| for the whole message, CustomerType, is defined with Type Composition set to
| Sequence, and Type Content to Open.

| Table 26 lists the message properties and their values.

| Table 26. Video customer message model example: message properties
| Property Value
| Name Customer
| Mode null
| Identifier Customer
| Suspended from Use No
| Type CustomerType
|

| You must define each of the elements shown in the tree in Figure 21 on page 78
| with the appropriate simple type. The elements based on simple types are:
| v Title of type STRING
| v FirstName of type STRING
| v HouseNo of type INTEGER
| v Street of type STRING
| v Town of type STRING
| v PassportNo of type STRING
| v DrivingLicenseNo of type STRING
| v CreditCardNo of type STRING
| v VideoTitle of type STRING
| v DueDate of type DATETIME
| v Cost of type DECIMAL

| Some of these elements belong to the top level compound type that defines the
| message structure (CustomerType). Others belong to other substructure. You must
| define each of the four substructures as a compound type:
| v Name. This includes elements Title and FirstName. Its identifier is set to
| NameType, and it is defined with Type Composition set to Ordered Set, and Type
| Content to Open. This means that duplicate elements are not allowed, but other
| elements, not defined in this type, are allowed. That is, self-defining elements
| can be included in the message at this point. NameType is also defined to
| include a base type, which means that a value can be associated with the
| compound type itself. This value is defined as type STRING, and is used to
| contain the customer’s last name.
| v Address. This includes elements HouseNo, Street, and Town. Its identifier is set
| to AddressType, and it is also defined with Type Composition set to Ordered Set,
| and Type Content to Open.
| v IdType, which includes the elements PassportNo, DrivingLicenseNo and
| CreditCardNo as children. IdType represents a type with Type Composition set to
| Choice, and therefore Type Content is automatically set to Closed.
| v Borrowed, which includes the elements VideoType, DueDate, and Cost as
| children. It is defined with BorrowedType, which has Type Composition set to
| Sequence, and Type Content to Closed. Therefore duplicates are allowed, but no

Chapter 4. The MRM logical message model 79

 Modeling the Video customer message
| additional elements are permitted in this type other than the named ones (no
| self-defining child elements are allowed).

| Table 27 lists the compound type properties and their values. Accept the default
| values for all properties not listed. If you define the elements before the compound
| types, you can add the elements when you create the compound types. If you
| create the compound types first, you can add the elements afterwards.
| Table 27. Video customer message model example: type properties
| Type name Type Composition Type Content Identifier Type
| CustomerType Sequence Open CustomerType (not set)
| AddressType Ordered Set Open AddressType (not set)
| BorrowedType Sequence Closed BorrowedType (not set)
| IdType Choice Closed IdType (not set)
| NameType Ordered Set Open NameType STRING
|

| Now you must instantiate the compound types:

| v AddressType. This has business meaning, and you need to access this in the
| message tree created by the broker from an input message. Therefore define it as
| an element, Address.
| v BorrowedType. This also has business meaning and you need to access this in in
| the message tree. Define this as an element, Borrowed.
| v NameType. This has business meaning and you need to access this type in the
| message tree. Define it as an element, Name.
| v IdType. This is used to group data, and does not have any business meaning in
| its own right. You do not need to define this as an element, but you do need to
| include it in the parent compound type, CustomerType.

| You can now add the child elements to the compound types to complete the final
| message structure. Table 28 lists the element properties and their values.
| Table 28. Video customer message model example: element properties
| Element name Identifier Type
| Address Address AddressType
| Borrowed Borrowed BorrowedType
| Name Name NameType
| Title Title STRING
| FirstName FirstName STRING
| HouseNo HouseNo INTEGER
| Street Street STRING
| Town Town STRING
| PassportNo PassportNo STRING
| CreditCardNo CreditCardNo STRING
| DrivingLicenseNo DrivingLicenseNo STRING
| VideoTitle VideoTitle STRING
| DueDate DueDate DATETIME
| Cost Cost DECIMAL

80 WebSphere MQ Integrator Working with Messages

 Modeling the Video customer message
| Table 28. Video customer message model example: element properties (continued)
| Element name Identifier Type
| Magazine Magazine BOOLEAN
|

| When you add the elements or compound elements to the compound types in
| which they are required, you create a member relationship with the parent
| compound type, and additional properties associated with the element’s cardinality
| and whether it is mandatory or optional are associated with this relationship.
| These options are shown on the Connection pane when you select the element
| where it appears within the compound type within the left pane of the Message
| Sets view of the Control Center.

| When you first add the element or compound type to its parent compound type,
| the Connection pane options are set with default values. The defaults define that
| each element or embedded compound type occurs once and only once, and does
| not repeat (it is mandatory).

| You can accept these defaults for all the elements and compound types except for
| the Borrowed element, because a customer can have up to three videos on loan at
| any one time. Change the Connection pane properties as shown in Table 29, which
| also lists the element member properties and their values. Remember that the
| options that you specify on the Connection pane are not verified by the broker.
| Table 29. Video customer message model example: element member properties
| Child element or compound Parent compound type Repeat Min Occurs Max Occurs
| type
| HouseNo AddressType No 1 (not set)
| Street AddressType No 1 (not set)
| Town AddressType No 1 (not set)
| VideoTitle BorrowedType No 1 (not set)
| Due Date BorrowedType No 1 (not set)
| Cost BorrowedType No 1 (not set)
| PassportNo IdType No 1 (not set)
| DrivingLicenseNo IdType No 1 (not set)
| CreditCardNo IdType No 1 (not set)
| Title NameType No 1 (not set)
| FirstName NameType No 1 (not set)
| Name CustomerType No 1 (not set)
| Address CustomerType No 1 (not set)
| IdType CustomerType No 1 (not set)
| Borrowed CustomerType Yes 0 3
| Magazine CustomerType No 1 (not set)
|

Chapter 4. The MRM logical message model 81

 Modeling the Video customer message
| You have now completed the definition of the logical message model. You can now
| add the wire format layers to define the different physical representations of the
| underlying message. The way that you do this for each of the three wire format
| layers is described in Chapter 5, “Working with a Custom Wire Format layer” on
| page 83, Chapter 6, “Working with an XML Format layer” on page 111, and
| Chapter 7, “Working with Tagged Delimited String messages” on page 131.

| When a message that conforms to this model is received by a message flow in the
| broker, it is parsed by the MRM parser (as described in Chapter 2, “Parsers” on
| page 7) and a tree structure is created, shown in Figure 22. The tree structure is
| independent of the physical characteristics of the message.
|
|
MRM

Name Address PassportNo Magazine

OR
DrivingLicenseNo
Title FirstName HouseNo Street Town OR
CreditCardNo

Borrowed[0..3]

VideoTitle DueDate Cost

|
| Figure 22. Video customer example: tree structure created by the parser
|
| As you can see, Borrowed can be repeated up to a maximum of three times. The
| embedded compound type IdType is not present in the tree, because it was never
| instantiated as an element. It is represented as an unresolved choice: only one of
| the three nodes shown (PassportNo, DrivingLicenseNo, or CreditCardNo) will be
| present in a real message tree. You can resolve the choice in the message flow node
| when you code an ESQL statement to set or query the value.

82 WebSphere MQ Integrator Working with Messages

|

| Chapter 5. Working with a Custom Wire Format layer

| Custom Wire Format is the term given to the physical representation of a message
| that has a number of data elements adjacent to each other that do not have
| delimiters. Without a knowledge of the message structure, you cannot distinguish
| one element from the next. To interpret the values of individual elements, you
| must know their order and the length of each element. A CWF message is usually
| mapped to a C structure or a COBOL copybook.

| This chapter covers the following topics:

| v “Setting properties for CWF”
| v “Null handling in CWF” on page 106
| v “Multipart messaging in CWF” on page 106
| v “Data conversion with CWF” on page 106
| v “The relationship between the logical model and CWF” on page 107
| v “Example: modeling the Video customer message using CWF” on page 109
|
| Setting properties for CWF
| If you add a CWF layer to your message set, a new properties pane is created. This
| allows you to set additional properties for the message set, and for element
| members (elements that are members of compound types or messages). There are
| no CWF properties for messages or types.
| v “Message set properties for CWF”
| v “Element member properties for CWF” on page 86

| Message set properties for CWF

| Table 30 on page 84 defines the properties that you can set for the message set.
| Some of the message set properties (marked with an asterisk (*)) are relevant only
| if the message being processed is not using MQSeries as the transport protocol. If
| the transport protocol is MQSeries, values are derived from the message headers
| (for example, MQMD), and the message set properties, if set, are ignored.

© Copyright IBM Corp. 2000, 2002 83

 Message set properties for CWF
| Table 30. CWF message set properties
| Property Type Meaning
| Custom Wire Format STRING Enter an identifier for the wire format layer. The first three characters must
| Identifier be CWF, subsequent characters must be alphanumeric. The default value is
| CWF.

| If you are deploying this message set to a broker that is at MQSeries

| Integrator Version 2.0.1, or Version 2.0.2, the maximum length of the
| identifier you can specify is 8 bytes. For WebSphere MQ Integrator brokers,
| the maximum length is 120 bytes.

| If you add more than one CWF layer to a single message set, you must
| specify a different CWF identifier for each one.

| When you create a message that you want to be interpreted according to

| this message model, you can either set this value in the <Fmt> tag of the
| NameValueData field in the MQRFH2 header, or in the Message Format
| property of the MQInput node in a message flow (if the message does not
| have an MQRFH2 header).

| The wire format identifier is not the same as the name of the wire format
| layer (although you could define it to have the same value). When you
| create a wire format layer, you must enter a name, and this value is used
| for display purposes only in the Control Center to identify the pane on
| which the wire format layer properties are displayed. In all references
| outside the Control Center (for example, in the MQRFH2 header of a
| message) the wire format identifier must be used, not the name.
| Default CCSID* INTEGER
| Enter a numerical value for the default Coded Character Set Identifier. The
| default is 500.

| If the input message is an MQSeries message, the equivalent attribute set

| for the queue manager is used and this property is ignored.
| Byte Order* Enumerated Select either Big Endian (the default) or Little Endian from the drop-down
| Type list to specify the byte order of numbers that are represented as binary
| integers.

| In C, this is equivalent to data type short or long. In COBOL, this is

| equivalent to a PIC 9 COMP, COMP-4, COMP-5 or BINARY data type.

| Your choice must match the encoding with which messages are created. Big
| Endian is normally the correct option for messages created on UNIX or
| z/OS, Little Endian for Windows NT.
| Packed Decimal Byte Enumerated Select Big Endian (the default) or Little Endian from the drop-down list to
| Order* Type specify the byte order of numbers that are represented as packed decimal.
| In COBOL, this is equivalent to PIC 9 COMP-3 data type. (There is no
| equivalent data type in C.)

| Your choice must match the encoding with which messages are created. Big
| Endian is normally the correct option for messages created on UNIX or
| z/OS, Little Endian for Windows NT.
| Float Format* Enumerated Select one of S390 (the default), IEEE, or Reverse IEEE from the drop-down
| Type list to specify the byte order of numbers in the message that are
| represented as floating point.

84 WebSphere MQ Integrator Working with Messages

 Message set properties for CWF
| Table 30. CWF message set properties (continued)
| Property Type Meaning
| Byte Alignment Enumerated Specify the boundary on which the start of messages must be aligned.
| Type Select one of the following from the drop-down list:
| v 1 byte
| v 2 bytes
| v 4 bytes
| v 8 bytes (this is the default value)
| v 16 bytes
| Byte Alignment Pad STRING Specify the character to be used to fill fields for Byte Alignment in one of
| the following ways:
| v Select either SPACE or NUL (not NULL) from the drop-down list.
| v Enter a character between quotes, for example "c" or ’c’, where c is any
| alphanumeric character. The default is 0.
| v Enter a hexadecimal character code in the form 0xYY where YY is a
| hexadecimal value. The maximum length of the entered string is 10.
| Boolean True Value STRING Enter up to eight hexadecimal digits. Do not include the hexadecimal
| indicator 0x preceding this number. Each digit is a half byte. The maximum
| length is 4 bytes. You must enter an even number of digits (a whole
| number of bytes). This value must be different from, but the same length
| as, the Boolean False value. The default value is 00000001.
| Boolean False Value STRING Enter up to eight hexadecimal digits. Do not include the hexadecimal
| indicator 0x preceding this number. Each digit is a half byte. The maximum
| length is 4 bytes. You must enter an even number of digits (a whole
| number of bytes). This value must be different from, but the same length
| as, the Boolean True value. The default value is 00000000.
| Boolean Null Value STRING Enter up to eight hexadecimal digits. Do not include the hexadecimal
| indicator 0x preceding this number. Each digit is a half byte. The maximum
| length is 4 bytes. You must enter an even number of digits (a whole
| number of bytes). This value can be the same as either Boolean True or
| Boolean False value, or different. The default value is 00000000.
| Default DateTime DATETIME Specify the default format for elements of type DATETIME. You can
| Format override this property for a DATETIME element within a compound type.
| The default value for this property is yyyy-MM-dd’T’HH:mm:ssZZZ.

| For more information about DATETIME formats, see Appendix C,

| “DATETIME formats” on page 253.
| Default Time Zone STRING The value that you set for this property is used if the value that you
| ID specified for the Default DateTime Format property does not include Time
| Zone information. The default is +00:00.
| Century Window INTEGER Specify the year from (and including) which a year specified with
| two-digits must be interpreted as 19xx. If a two–digit year is less that this
| value, it is interpreted as 20xx. Specify a value between 0 and 99 inclusive.
| The default is 53.
| First Week of Year Enumerated Specify the number of days of the new year that must fall within the first
| Type week.

| The start of a year usually falls in the middle of a week. If the number of
| days in that week is less than the value defined here, the week is
| considered to be the last week of the previous year; hence week 1 starts
| some days into the new year. Otherwise it is considered to be the first
| week of the new year; hence week 1 starts some days before the new year.

| Enter the minimum length of the first week of the year in days. The value
| must be between 1 and 7 inclusive. The default is 4.

Chapter 5. Working with a Custom Wire Format layer 85

 Message set properties for CWF
| Table 30. CWF message set properties (continued)
| Property Type Meaning
| First Day of Week Enumerated Select the day on which each new week starts from the drop-down list. The
| Type default is Monday.
|

| Element member properties for CWF

| The fields displayed on the CWF pane vary according to whether the element
| member is a compound element or a simple element. For simple elements, CWF
| properties vary according to the associated simple type:
| v “BINARY”
| v “BOOLEAN” on page 88
| v “DATETIME” on page 89
| v “DECIMAL” on page 93
| v “FLOAT” on page 96
| v “INTEGER” on page 99
| v “STRING” on page 102

| The properties for compound elements are described in “Compound element” on

| page 105.

| BINARY
| The properties for an element member of simple type BINARY are defined in
| Table 31.
| Table 31. CWF BINARY element member properties
| Property Type Meaning
| Physical Type Fixed value The value defaults to Binary. You cannot edit it.
| Length Type Enumerated Type Select one of the following from the drop-down list:
| v Count (described below)
| v Value Of (described below)
| Length Count INTEGER If you have set Length Type to Count, enter the number of bytes to specify
| the value of the element length. The minimum value is 0, the maximum
| value is 2147483647. The default is none (not set).
| Length Value Of Enumerated Type If you have set Length Type to Value Of, select the name of the INTEGER
| element that specifies the length of this element, in bytes, from the
| drop-down list of INTEGER elements that are defined as siblings of the
| current element, and occur before it in the structure of the message.

| For information about reordering elements, see “Reordering elements in

| compound types” on page 171.

| Press the Delete key to reset the property to its default empty value.
| Length Units Enumerated Type Select one of the following from the drop-down list:
| v Bytes. This is the default value.
| v End of Bitstream. This is only valid if the element is the last in the
| message. If you select this value, you do not need to enter a value for
| Length Count or Length Value Of.

86 WebSphere MQ Integrator Working with Messages

 BINARY properties
| Table 31. CWF BINARY element member properties (continued)
| Property Type Meaning
| Skip Count INTEGER Specify the number of bytes to skip before reading or writing this element.
| The default is 0, the minimum value is 0, and the maximum value is
| 999999. Use this value to model a message defined by a COBOL data
| structure containing FILLER fields.

| For example, if you define two elements of two bytes each and the second
| has a Skip Count of five, the five bytes that occur between the first and
| second elements are ignored. When an output message is written, Skip
| Count bytes are assigned the value x’00’.
| Byte Alignment Enumerated Type Specify how the element is aligned from the start of the message. Select one
| of:
| v 1 Byte. This is the default value.
| v 2 Bytes
| v 4 Bytes
| v 8 Bytes
| v 16 Bytes
| Repeat Count Type Enumerated Type This is only displayed if you have set the Repeat property on the
| Connection pane to Yes.

| You can select one of the following:

| v Count (described below)
| v Value Of (described below)
| Repeat Count INTEGER If you have set the Repeat property on the Connection pane to Yes and the
| Repeat Count Type to Count, enter the number of occurrences of this element.
| The minimum value is 0 (both zero and one mean that a single occurrence
| is expected), the maximum value is 2147483647.
| Repeat Count Enumerated Type If you have set the Repeat property on the Connection pane to Yes and the
| Value Of Repeat Count Type property to Value Of, select the name of the INTEGER
| element the value of which specifies the number of occurrences of this
| element from the drop-down list of INTEGER elements that are defined as
| siblings of the current element, and occur before it in the structure of the
| message.

| For information about reordering elements, see “Reordering elements in

| compound types” on page 171.
|

| NULL values are not defined for BINARY types. The properties Encoding Null and
| Encoding Null Value, present for other types, are therefore not set.

Chapter 5. Working with a Custom Wire Format layer 87

 BOOLEAN properties
| BOOLEAN
| The properties for an element member of simple type BOOLEAN are defined in
| Table 32.
| Table 32. CWF BOOLEAN element member properties
| Property Type Meaning
| Physical Type Fixed value The value defaults to Boolean. You cannot edit it.
| Skip Count INTEGER The number of bytes to skip before reading or writing this element. The
| default is 0, the minimum value is 0, and the maximum value is 999999.
| You can use this value to model a message defined by a COBOL data
| structure containing FILLER fields.

| When a message is written, Skip Count bytes have the value x’00’.
| Byte Alignment Enumerated Type Specify how the element is aligned from the start of the message. Select one
| of:
| v 1 Byte. This is the default value.
| v 2 Bytes
| v 4 Bytes
| v 8 Bytes
| v 16 Bytes
| Repeat Count Type Enumerated Type This is only displayed if you have set the Repeat property on the
| Connection pane to Yes.

| You can select one of the following:

| v Count (described below)
| v Value Of (described below)
| Repeat Count INTEGER If you have set the Repeat property on the Connection pane to Yes and the
| Repeat Count Type to Count, enter the number of occurrences of this element.
| The minimum value is 0 (both zero and one mean that a single occurrence
| is expected), the maximum value is 2147483647.
| Repeat Count Enumerated Type If you have set the Repeat property on the Connection pane to Yes and the
| Value Of Repeat Count Type property to Value Of, select the name of the INTEGER
| element the value of which specifies the number of occurrences of this
| element from the drop-down list of INTEGER elements that are defined as
| siblings of the current element, and occur before it in the structure of the
| message.

| For information about reordering elements, see “Reordering elements in

| compound types” on page 171.
|

| BOOLEAN fields with null values are rendered using the message set property
| Boolean Null Value. The properties Encoding Null and Encoding Null Value, present
| for other types, are therefore not set here.

88 WebSphere MQ Integrator Working with Messages

 DATETIME properties
| DATETIME
| The properties for an element member of simple type DATETIME are defined in
| Table 33.
| Table 33. CWF DATETIME element member properties
| Property Type Meaning
| Physical Type Enumerated Type Select one of the following from the drop-down list:
| v Fixed Length String. The element’s length is determined by other length
| properties below. This is the default value.
| v Length Encoded String 1. The element’s first byte contains the length of
| the string following the length byte in length units. The maximum length
| of a Length Encoded String 1 element is 255 length units.
| v Length Encoded String 2. The element’s first two bytes contain the
| length of the string following the 2 length bytes in length units. The
| maximum length of a Length Encoded String 2 element is 65535 length
| units.
| v Null Terminated String. The string ends with the hexadecimal NULL
| character, X’00’.
| v Packed Decimal. The DATETIME is coded as a Packed Decimal number.
| It is valid only if the Format String property represents numeric-only
| data.
| v Binary. The DATETIME is encoded as a binary sequence of bytes. If you
| select this option, the range of symbols that you can specify for the
| Format String property is less than the range of symbols you can specify
| if you select a string option (see Appendix C, “DATETIME formats” on
| page 253 for details).
| v Time Seconds. This value supports C time_t and Java Date and Time
| objects. It is valid only if the Format String property represents
| numeric-only data.
| v Time Milliseconds. This value supports C time_t and Java Date and
| Time objects. It is valid only if the Format String property represents
| numeric-only data.
| Length Type Enumerated Type If you have selected a Physical Type of Fixed Length String, Packed
| Decimal, or Binary, select one of the following from the drop-down list:
| v Count (described below)
| v Value Of (described below)

| If you have selected another Physical Type, this property is invalid.

| Length Count INTEGER If you have selected a Physical Type of Fixed Length String, Packed
| Decimal, and Binary, and have set Length Type to Count, enter the number of
| length units for the element.

| The minimum value that you can specify is 1 for all three physical types.

| The maximum value that you can specify is 256 for Fixed Length String,
| 10 for Packed Decimal, and 2147483647 for Binary.

| The default value is empty (not set).

| Length Value Of Enumerated Type If you have set Length Type to Value Of, select the name of the INTEGER
| element that specifies the length of this element from the drop-down list of
| INTEGER elements that are defined as siblings of the current element, and
| occur before it in the structure of the message.

| For information about reordering elements, see “Reordering elements in

| compound types” on page 171.

| Press the Delete key to reset the property to its default empty value.

Chapter 5. Working with a Custom Wire Format layer 89

 DATETIME properties
| Table 33. CWF DATETIME element member properties (continued)
| Property Type Meaning
| Length Units Enumerated Type If you have selected a Physical Type of Fixed Length String, Length
| Encoded String 1, Length Encoded String 2, or Null Terminated String,
| select one of the following from the drop-down list:
| v Bytes. This specifies that X bytes are processed where X is the value of
| Length Count, or of the INTEGER specified in Length Value Of. Use this
| option for SBCS character sets. This is the default.
| v Characters. The meaning of this option depends on the value that you
| have set in the message’s CCSID or that you have set for the message set
| property Default CCSID
| – If you have specified an SBCS CCSID, X bytes are processed where X is
| the value of Length Count or of the INTEGER specified by Length Value
| Of.
| – If you have specified a DBCS CCSID, Y bytes are processed, where Y is
| the value of Length Count or of the INTEGER specified in Length Value
| Of multiplied by two.
| – If you have specified an MBCS CCSID, the parser reads 1 character at
| a time and determines whether the character comprises 1 or more
| bytes. The parser performs Z reads, where Z is the value of Length
| Count or of the INTEGER specified in Length Value Of.
| v Character Units. This specifies that the size of character unit is
| determined by the value that you have set in the MQSeries message, or
| for the message set property Default CCSID. The number of bytes
| processed is the size of character unit multiplied by the value of Length
| Count, or of the INTEGER specified in Length Value Of.
| v End of Bitstream. All data until end of bit stream is processed. This
| option is valid only if the element is the last in the message. If you select
| this value, you do not need to enter a value in Length Count or Length
| Value Of.

| If you have selected another value for Physical Type, select one of the
| following from the drop-down list:
| v Bytes. This is the default value.
| v End of Bitstream.
| Signed BOOLEAN If you have set the Physical Type property to Packed Decimal, Time Seconds,
| or Time Milliseconds, select either Yes (the default) or No from the
| drop-down list. If you have selected another value for Physical Type, this
| property is invalid.
| Sign Orientation This property is reserved for future use.
| Byte Alignment Enumerated Type Specify how the element is aligned from the start of the message. Select one
| of:
| v 1 Byte. This is the default value.
| v 2 Bytes
| v 4 Bytes
| v 8 Bytes
| v 16 Bytes
| String Justification Enumerated Type If you have set the Physical Type property to Fixed Length String, select
| Left Justify (the default value) or Right Justify from the drop-down list.
| If you have selected another value for Physical Type, this is set to Not
| Applicable.

90 WebSphere MQ Integrator Working with Messages

 DATETIME properties
| Table 33. CWF DATETIME element member properties (continued)
| Property Type Meaning
| Padding Character STRING The padding character is used to fill out the remaining character positions
| when the string length is less than the specified string size. If you have set
| the Physical Type property to Fixed Length String, and the String
| Justification property is either Left Justify or Right Justify, set this
| character in one of the following ways:
| v Select either SPACE or NUL (not NULL) from the drop-down list.
| v Enter a character between quotes, for example "c" or ’c’, where c is any
| alphanumeric character.
| v Enter a hexadecimal character code in the form 0xYY where YY is a
| hexadecimal value.
| v Enter a Unicode value in the form U+xxxxxx where xxxxxx is a Unicode
| value specified in hexadecimal. The maximum length of the string you
| can enter is 10.
| v Select the default value of an empty string.
| Format String DATETIME Specify a template for date and time. The default value is
| yyyy-MM-dd’T’HH:mm:ss for every setting of Physical Type.

| If you set the Physical Type to Binary, the template is restricted to those
| components defined in Table 110 on page 256. If you set the Physical Type to
| Packed Decimal, TimeSeconds, or TimeMilliseconds, the template is
| restricted to those components that represent numbers. In these cases, you
| must update this Format String property.

| See Appendix C, “DATETIME formats” on page 253 for details of datetime

| formats.
| Skip Count INTEGER Specify the number of bytes to skip before reading or writing this element.
| The default is 0, the minimum value is 0, and the maximum value is
| 999999. You can use this property to model a message defined by a COBOL
| data structure containing FILLER fields.

| When a message is written, Skip Count bytes have the value x’00’.
| Repeat Count Type Enumerated Type This is only displayed if you have set the Repeat property on the
| Connection pane to Yes.

| You can select one of the following:

| v Count (described below)
| v Value Of (described below)
| Repeat Count INTEGER If you have set the Repeat property on the Connection pane to Yes, and the
| Repeat Count Type to Count, enter the number of occurrences of this element.
| The minimum value is 0 (both zero and one mean that a single occurrence
| is expected), the maximum value is 2147483647.
| Repeat Count Enumerated Type If you have set the Repeat property on the Connection pane to Yes and the
| Value Of Repeat Count Type property to Value Of, select the name of the INTEGER
| element the value of which specifies the number of occurrences of this
| element from the drop-down list of INTEGER elements that are defined as
| siblings of the current element, and occur before it in the structure of the
| message.

| For information about reordering elements, see “Reordering elements in

| compound types” on page 171.

Chapter 5. Working with a Custom Wire Format layer 91

 DATETIME properties
| Table 33. CWF DATETIME element member properties (continued)
| Property Type Meaning
| Encoding Null Enumerated Type Select one of the following options from the drop-down list. The option that
| you select determines the value that you must set for the property Encoding
| Null Value:
| v NULLPadFill. This is only valid if Physical Type is Fixed Length String.
| The field is filled with the value specified by the Padding Character. This
| is the default value.
| v NULLLogicalValue. The Encoding Null Value property is first converted to
| an actual value, and rendered in the way specified for the field.
| v NULLLiteralValue. This specifies that Encoding Null Value contains a value
| that is directly substituted as if it is a string. Use this option if you want
| to use the Encoding Null Value to test or compare the content of the field
| in the message.
| Encoding Null STRING If you set the Encoding Null property to NULLPadFill, this property is
| Value disabled (grayed out).

| If you set the Encoding Null property to NULLLogicalValue, you must set
| this property to an ISO8601 datetime format. These formats are described in
| note 6 on page 255 in “DATETIME as STRING data” on page 253. For
| example, specify a value conforming to yyyy-MM-dd’T’HH:mm:ss such as
| 1970-12-01.

| If you set the Encoding Null property to NULLLiteralValue, you must set
| this property to a value that conforms to the pattern that you have set in
| the propertyFormat String. If you have set Physical Type to Fixed Length
| String, the value that you specify for this property must be of the same
| length as the field.
|

92 WebSphere MQ Integrator Working with Messages

 DECIMAL properties
| DECIMAL
| The properties for an element member of simple type DECIMAL are defined in
| Table 34.
| Table 34. CWF DECIMAL element member properties
| Property Type Meaning
| Physical Type Enumerated Type Select one of the following from the drop-down list:
| v Integer. This equates to the data type SHORT or LONG in C, or the
| COMP, COMP-4, COMP-5, or BINARY numeric data type in COBOL.
| v Packed Decimal. This equates to the COMP-3 data type in COBOL.
| v Extended Decimal. This equates to the data type PIC 9 USAGE DISPLAY
| in COBOL. This is the default value.

| The representation of numeric elements can be affected by the Encoding

| and CodedCharSetId attributes that are set for the MQSeries queue
| manager:
| v Elements that have Physical Type set to Integer and Packed Decimal are
| represented in the appropriate MQSeries Encoding value.
| v Elements that have Physical Type set to Extended Decimal are represented
| in the MQSeries CodedCharSetId value.
| Length Count INTEGER Enter the number of bytes to specify the element length:
| v If the Physical Type is Integer, select a value from drop-down menu. The
| default is 4.
| v If the Physical Type is Packed Decimal, enter a value between 1 and 10.
| v If the Physical Type is Extended Decimal, enter a value between 1 and 256.
| (Numbers greater than the maximum COBOL PICTURE clause of 18 are
| assumed to be 18.)
| Length Units Enumerated Type Select one of the following from the drop-down list:
| v Bytes. This is the default value.
| v End of Bitstream. All data until end of bit stream is processed. This is
| only valid if the element is the last in the message. If you select this
| value, you do not need to enter a value for Length Count.
| Signed BOOLEAN Select either Yes (the default) or No from the drop-down list.
| Sign Orientation Enumerated Type If you have set Physical Type to Extended Decimal and you have set Signed
| to Yes, choose from the following options that represent the COBOL options
| for displaying numeric data:
| v Included Leading. This sets a bit in the first byte on if the number is
| negative. No setting is made if the number is positive. For example, the
| ASCII hexadecimal representation of the number 22 is x’3232’. Using
| this option, the number +22 would be x’3232’ and the number -22
| would be x’7232’. This is the default value.
| v Separate Leading. This sets the first byte of the element to ’+’ if the
| number is positive and to ’–’ if the number is negative. For this option,
| the length must include the sign byte.
| v Included Trailing. This sets a bit in the last byte on if the number is
| negative. No setting is made if the number is positive. Using this option,
| the number +22 would be x’3232’ and the number -22 would be
| x’3272’.
| v Separate Trailing. This sets the last byte of the element to ’+’ if the
| number is positive and to ’–’ if the number is negative. For this option,
| the length must include the sign byte.
| If you have set Physical Type to any other value, the value Not Applicable is
| set for you.

Chapter 5. Working with a Custom Wire Format layer 93

 DECIMAL properties
| Table 34. CWF DECIMAL element member properties (continued)
| Property Type Meaning
| Byte Alignment Enumerated Type Specify how the element is aligned from the start of the message. Select one
| of:
| v 1 Byte. This is the default value.
| v 2 Bytes
| v 4 Bytes
| v 8 Bytes
| v 16 Bytes
| String Justification Enumerated Type If you have set the Physical Type property to Extended Decimal, select Left
| Justify or Right Justify (the default value) from the drop-down list. If
| you have selected another value for Physical Type, this is set to Not
| Applicable.
| Padding Character STRING The padding character is used to fill out the remaining character positions
| when the string length is less than the specified string size. If you have set
| Physical Type to Extended Decimal and String Justification to either Left
| Justify or Right Justify, select this character in one of the following
| ways:
| v Select either SPACE or NUL (not NULL) from the drop-down list.
| v Enter a character between quotes, for example "c" or ’c’, where c is any
| alphanumeric character.
| v Enter a hexadecimal character code in the form 0xYY where YY is a
| hexadecimal value.
| v Enter a Unicode value in the form U+xxxxxx where xxxxxx is a Unicode
| value specified in hexadecimal. The maximum length of the string you
| can enter is 10.
| v Select the default value of an empty string.
| Virtual Decimal INTEGER Specify the number of places to the left (for a positive value) or right (for a
| Point negative value) that a decimal point should be moved from its assumed
| position. For example, a DECIMAL element containing 1234 with a Virtual
| Decimal value of 3 is 1.234. This is equivalent to ’V’ or ’P’ in a COBOL
| picture clause. There is no C equivalent
| Skip Count INTEGER Enter the number of bytes to skip before reading or writing this element.
| The default is 0, the minimum value is 0, and the maximum value is
| 999999. Use this property to model a message defined by a COBOL data
| structure containing FILLER fields.

| When a message is written, skip count bytes have the value x’00’.
| Repeat Count Type Enumerated Type This is only displayed if you have set the Repeat property on the
| Connection pane to Yes.

| You can select one of the following:

| v Count (described below)
| v Value Of (described below)
| Repeat Count INTEGER If you have set the Repeat property on the Connection pane to Yes, and the
| Repeat Count Type to Count, enter the number of occurrences of this element.
| The minimum value is 0 (both zero and one mean that a single occurrence
| is expected), the maximum value is 2147483647.

94 WebSphere MQ Integrator Working with Messages

 DECIMAL properties
| Table 34. CWF DECIMAL element member properties (continued)
| Property Type Meaning
| Repeat Count Enumerated Type If you have set the Repeat property on the Connection pane to Yes and the
| Value Of Repeat Count Type property to Value Of, select the name of the INTEGER
| element the value of which specifies the number of occurrences of this
| element from the drop-down list of INTEGER elements that are defined as
| siblings of the current element, and occur before it in the structure of the
| message.

| For information about reordering elements, see “Reordering elements in

| compound types” on page 171.
| Encoding Null Enumerated Type Select one of the following options from the drop-down list:
| v NULLPadFill. This is only valid if Physical Type is Extended Decimal. The
| field is filled with the value specified by the Padding Character. Encoding
| Null Value must be set to an empty string.
| v NULLLogicalValue. The Encoding Null Value is transformed to match the
| required format for the field. This is the default value.
| v NULLLiteralValue. The Encoding Null Value is directly substituted as if it
| is a string. You can specify a nonnumeric value for Encoding Null Value.
| Encoding Null STRING The use of this property depends on the Encoding Null property, described
| Value above. The default value is zero.
|

Chapter 5. Working with a Custom Wire Format layer 95

 FLOAT properties
| FLOAT
| The properties for an element member of simple type FLOAT are defined in
| Table 35.
| Table 35. CWF FLOAT element member properties
| Property Type Meaning
| Physical Type Enumerated Type Select one of the following from the drop-down list:
| v Integer. This equates to the data type SHORT or LONG in C or the
| COMP, COMP-4, COMP-5, or BINARY numeric data type in COBOL.
| v Float. This equates to the data type FLOAT or DOUBLE in C or the
| COMP-1 or COMP-2 data type in COBOL. This is the default value.
| v Packed Decimal. This equates to the COMP-3 data type in COBOL.
| v Extended Decimal. This equates to the data type PIC 9 USAGE DISPLAY
| in COBOL.

| The representation of numeric elements can be affected by the Encoding

| and CodedCharSetId attributes that are set for the MQSeries queue
| manager:
| v Elements that have Physical Type set to Integer, Packed Decimal, and
| Float are represented in the appropriate MQSeries Encoding value.
| v Elements that have Physical Type set to Extended Decimal are represented
| in the MQSeries CodedCharSetId value.
| Length Count INTEGER Enter the number of bytes to specify the element length:
| v If you set the Physical Type to Float, select a value from the drop-down
| list. The default value is 8.
| v If you set the Physical Type to Integer, select 1, 2, or 4 (the default) from
| the drop-down list.
| v If you set the Physical Type to Packed Decimal, enter a value between 1
| and 10.
| v If you set the Physical Type to Extended Decimal, enter a value between 1
| and 256. (Numbers greater than the maximum COBOL PICTURE clause
| of 18 are assumed to be 18.)
| Length Units Enumerated Type Select one of the following from the drop-down list:
| v Bytes. This is the default value.
| v End of Bitstream. All data until end of bit stream is processed. This is
| only valid if the element is the last in the message. If you select this
| value, you do not need to enter a value for Length Count.
| Signed BOOLEAN Select either Yes or No (unsigned, the default) from the drop-down list. If
| you have set Physical Type to Float, this is set to Yes.

96 WebSphere MQ Integrator Working with Messages

 FLOAT properties
| Table 35. CWF FLOAT element member properties (continued)
| Property Type Meaning
| Sign Orientation Enumerated Type If you have set Physical Type to Extended Decimal, and you have set Signed
| to Yes, choose from the following values that represent the COBOL options
| for displaying numerical data:
| v Included Leading. This sets a bit in the first byte on if the number is
| negative. No setting is made if the number is positive. For example, the
| ASCII hexadecimal representation of the number 22 is x’3232’. Using
| this option, the number +22 would be x’3232’ and the number -22
| would be x’7232’. This is the default value.
| v Separate Leading. This sets the first byte of the element to ’+’ if the
| number is positive and to ’–’ if the number is negative. For this option,
| the length must include the sign byte.
| v Included Trailing. This sets a bit in the last byte on if the number is
| negative. No setting is made if the number is positive. Using this option,
| the number +22 would be x’3232’ and the number -22 would be
| x’3272’.
| v Separate Trailing. This sets the last byte of the element to ’+’ if the
| number is positive and to ’–’ if the number is negative. For this option,
| the length must include the sign byte.
| If you have set Physical Type to any other value, the value Not Applicable is
| set for you.
| Skip Count INTEGER Enter the number of bytes to skip before reading or writing this element.
| The default is 0, the minimum value is 0, and the maximum value is
| 999999. Use this property to model a message defined by a COBOL data
| structure containing FILLER fields.

| When a message is written, Skip Count bytes have the value x’00’.
| Byte Alignment Enumerated Type Specify how the element is aligned from the start of the message. Select one
| of:
| v 1 Byte. This is the default value.
| v 2 Bytes
| v 4 Bytes
| v 8 Bytes
| v 16 Bytes
| String Justification Enumerated Type If you have set the Physical Type property to Extended Decimal, select Left
| Justify or Right Justify (the default value) from the drop-down list. If
| you have selected another value for Physical Type, this is set to Not
| Applicable.
| Padding Character STRING The padding character is used to fill out the remaining character positions
| when the string length is less than the specified string size. If you have set
| Physical Type to Extended Decimal and String Justification to either Left
| Justify or Right Justify, select this character in one of the following
| ways:
| v Select either SPACE or NUL (not NULL) from the drop-down list.
| v Enter a character between quotes, for example "c" or ’c’, where c is any
| alphanumeric character.
| v Enter a hexadecimal character code in the form 0xYY where YY is a
| hexadecimal value.
| v Enter a Unicode value in the form U+xxxxxx where xxxxxx is a Unicode
| value specified in hexadecimal. The maximum length of the string you
| can enter is 10.
| v Select the default value of an empty string.

Chapter 5. Working with a Custom Wire Format layer 97

 FLOAT properties
| Table 35. CWF FLOAT element member properties (continued)
| Property Type Meaning
| Virtual Decimal INTEGER Specify the number of places to the left (for a positive value) or right (for a
| Point negative value) that a decimal point should be moved from its assumed
| position. For example, a FLOAT element containing 1234 with a Virtual
| Decimal value of 3 is 1.234.

| This is not applicable if you have set Physical Type to Float.

| Repeat Count Type Enumerated Type This is only displayed if you have set the Repeat property on the
| Connection pane to Yes.

| You can select one of the following:

| v Count (described below)
| v Value Of (described below)
| Repeat Count INTEGER If you have set the Repeat property on the Connection pane to Yes, and the
| Repeat Count Type to Count, enter the number of occurrences of this element.
| The minimum value is 0 (both zero and one mean that a single occurrence
| is expected), the maximum value is 2147483647.
| Repeat Count Enumerated Type If you have set the Repeat property on the Connection pane to Yes and the
| Value Of Repeat Count Type property to Value Of, select the name of the INTEGER
| element the value of which specifies the number of occurrences of this
| element from the drop-down list of INTEGER elements that are defined as
| siblings of the current element, and occur before it in the structure of the
| message.

| For information about reordering elements, see “Reordering elements in

| compound types” on page 171.
| Encoding Null Enumerated Type Select one of the following options from the drop-down list:
| v NULLPadFill. This is only valid if Physical Type is Extended Decimal. The
| field is filled with the value specified by the Padding Character. Encoding
| Null Value must be set to an empty string.
| v NULLLogicalValue. The Encoding Null Value is transformed to match the
| required format for the field. This is the default value.
| v NULLLiteralValue. The Encoding Null Value is directly substituted as if it
| is a string. You can specify a nonnumeric value for Encoding Null Value.
| Encoding Null STRING The use of this property depends on the Encoding Null property, described
| Value above. The default value is zero.
|

98 WebSphere MQ Integrator Working with Messages

 INTEGER properties
| INTEGER
| The properties for an element member of simple type INTEGER are defined in
| Table 36.
| Table 36. CWF INTEGER element member properties
| Property Type Meaning
| Physical Type Enumerated Type Select one of the following from the drop-down list:
| v Integer. This equates to the data type SHORT or LONG in C or the
| COMP, COMP-4, COMP-5 , or BINARY numeric data type in COBOL.
| v Packed Decimal. This equates to the COMP-3 data type in COBOL.
| v Extended Decimal. This equates to the data type PIC 9 USAGE DISPLAY
| in COBOL.

| The representation of numeric elements can be affected by the Encoding

| and CodedCharSetId attributes that are set for the MQSeries queue
| manager:
| v Elements that have Physical Type set to Integer and Packed Decimal are
| represented in the appropriate MQSeries Encoding value.
| v Elements that have Physical Type set to Extended Decimal are represented
| in the MQSeries CodedCharSetId value.
| Length Count INTEGER Enter the number of bytes to specify the value of the element length:
| v If you have set Physical Type to Integer, choose a value from the
| drop-down menu. Choices are 1 byte, 2 bytes, and 4 bytes (the default).
| v If you have set Physical Type to Packed Decimal, enter a value between 1
| and 6.
| v If you have set Physical Type to Extended Decimal, enter a value between
| 1 and 11.
| Length Units Enumerated Type Select one of the following from the drop-down list:
| v Bytes. This is the default value.
| v End of Bitstream. All data until end of bit stream are processed. This is
| only valid if the element is the last in the message. If you select this
| value, you do not need to enter a value for Length Count.
| Signed BOOLEAN Select either Yes or No (unsigned, the default) from the drop-down list.
| Sign Orientation Enumerated Type If you have set Physical Type to Extended Decimal, and you have set Signed
| to Yes, choose from the following values that represent the COBOL options
| for displaying numerical data:
| v Included Leading. This sets a bit in the first byte on if the number is
| negative. No setting is made if the number is positive. For example, the
| ASCII hexadecimal representation of the number 22 is x’3232’. Using
| this option, the number +22 would be x’3232’ and the number -22
| would be x’7232’. This is the default value.
| v Separate Leading. This sets the first byte of the element to ’+’ if the
| number is positive and to ’–’ if the number is negative. For this option,
| the length must include the sign byte.
| v Included Trailing. This sets a bit in the last byte on if the number is
| negative. No setting is made if the number is positive. Using this option,
| the number +22 would be x’3232’ and the number -22 would be
| x’3272’.
| v Separate Trailing. This sets the last byte of the element to ’+’ if the
| number is positive and to ’–’ if the number is negative. For this option,
| the length must include the sign byte.
| If you have set Physical Type to any other value, the value Not Applicable is
| set for you.

Chapter 5. Working with a Custom Wire Format layer 99

 INTEGER properties
| Table 36. CWF INTEGER element member properties (continued)
| Property Type Meaning
| Skip Count INTEGER Enter the number of bytes to skip before reading or writing this element.
| The default is 0, the minimum value is 0, and the maximum value is
| 999999. Use this property to model a message defined by a COBOL data
| structure containing FILLER fields.

| When a message is written, skip count bytes have the value x’00’.
| Byte Alignment Enumerated Type Specify how the element is aligned from the start of the message. Select one
| of:
| v 1 Byte. This is the default value.
| v 2 Bytes
| v 4 Bytes
| v 8 Bytes
| v 16 Bytes
| String Justification Enumerated Type If you have set the Physical Type property to Extended Decimal, select Left
| Justify or Right Justify (the default value) from the drop-down list. If
| you have selected another value for Physical Type, this is set to Not
| Applicable.
| Padding Character STRING The padding character is used to fill out the remaining character positions
| when the string length is less than the specified string size. If you have set
| Physical Type to Extended Decimal and String Justification to either Left
| Justify or Right Justify, you can select this character in one of the
| following ways:
| v Select either SPACE or NUL (not NULL) from the drop-down list.
| v Enter a character between quotes, for example "c" or ’c’, where c is any
| alphanumeric character.
| v Enter a hexadecimal character code in the form 0xYY where YY is a
| hexadecimal value.
| v Enter a Unicode value in the form U+xxxxxx where xxxxxx is a Unicode
| value specified in hexadecimal. The maximum length of the string you
| can enter is 10.
| v Select the default value of an empty string.
| Repeat Count Type Enumerated Type This is only displayed if you have set the Repeat property on the
| Connection pane to Yes.

| You can select one of the following:

| v Count (described below)
| v Value Of (described below)
| Repeat Count INTEGER If you have set the Repeat property on the Connection pane to Yes, and the
| Repeat Count Type to Count, enter the number of occurrences of this element.
| The minimum value is 0 (both zero and one mean that a single occurrence
| is expected), the maximum value is 2147483647.
| Repeat Count Enumerated Type If you have set the Repeat property on the Connection pane to Yes and the
| Value Of Repeat Count Type property to Value Of, select the name of the INTEGER
| element the value of which specifies the number of occurrences of this
| element from the drop-down list of INTEGER elements that are defined as
| siblings of the current element, and occur before it in the structure of the
| message.

| For information about reordering elements, see “Reordering elements in

| compound types” on page 171.

100 WebSphere MQ Integrator Working with Messages

 INTEGER properties
| Table 36. CWF INTEGER element member properties (continued)
| Property Type Meaning
| Encoding Null Enumerated Type Select one of the following options from the drop-down list:
| v NULLPadFill. This is only valid if Physical Type is Extended Decimal. The
| field is filled with the value specified by the Padding Character. Encoding
| Null Value must be set to an empty string.
| v NULLLogicalValue. The Encoding Null Value is transformed to match the
| required format for the field. This is the default value.
| v NULLLiteralValue. The Encoding Null Value is directly substituted as if it
| is a string. You can specify a nonnumeric value for Encoding Null Value.
| Encoding Null STRING The use of this property depends on the Encoding Null property, described
| Value above. The default value is zero.
|

Chapter 5. Working with a Custom Wire Format layer 101

 STRING properties
| STRING
| The properties for an element member of simple type STRING are defined in
| Table 37.
| Table 37. CWF STRING element member properties
| Property Type Meaning
| Physical Type Enumerated Type Select one of the following from the drop-down list:
| v Fixed Length String. The element’s length is determined by other length
| properties below. This is the default value.
| v Length Encoded String 1. The element’s first byte contains the length of
| the string following the length byte in length units. The maximum length
| of a Length Encoded String 1 element is 255 length units.
| v Length Encoded String 2. The element’s first two bytes contain the
| length of the string following the 2 length bytes in length units. The
| maximum length of a Length Encoded String 2 element is 65535 length
| units. The two length bytes are in the format of the MQSeries queue
| manager Encoding.
| v Null Terminated String. The string ends with the hexadecimal NULL
| character, X’00’.
| Length Type Enumerated Type If you have selected a Physical Type of Fixed Length String, select one of
| the following from the drop-down list:
| v Count (described below)
| v Value Of (described below)

| If you have selected another Physical Type, this property is invalid.

| Length Count INTEGER If you have selected a Physical Type of Fixed Length String or Binary, and
| have set Length Type to Count, enter the number of length units for the
| element.

| The minimum value that you can specify is 0 (zero), the maximum value
| that you can specify is 2147483647

| The default value is empty (not set).

| Length Value Of Enumerated Type If you have set Length Type to Value Of, select the name of the INTEGER
| element that specifies the length of this element from the drop-down list of
| INTEGER elements that are defined as siblings of the current element, and
| occur before it in the structure of the message.

| For information about reordering elements, see “Reordering elements in

| compound types” on page 171.

| Press the Delete key to reset the property to its default empty value.

102 WebSphere MQ Integrator Working with Messages

 STRING properties
| Table 37. CWF STRING element member properties (continued)
| Property Type Meaning
| Length Units Enumerated Type Select one of the following from the drop-down list:
| v Bytes. This specifies that X bytes are processed where X is the value of
| Length Count, or the value of the INTEGER specified in Length Value Of.
| Use this option for SBCS character sets. This is the default.
| v Characters. The meaning of this option depends on the value that you
| have set in the message’s MQMD CCSID field, or that you have set for
| the message set property Default CCSID:
| – If you have specified an SBCS CCSID, X bytes are processed where X is
| the value of Length Count or the value of the INTEGER specified by
| Length Value Of.
| – If you have specified a DBCS CCSID, Y bytes are processed, where Y is
| the value of Length Count multiplied by two, or the value of the
| INTEGER specified in Length Value Of multiplied by two.
| – If you have specified an MBCS CCSID, the parser reads one character
| at a time and determines whether the character comprises one or more
| bytes. The parser performs Z reads, where Z is the value of Length
| Count or the value of the INTEGER specified in Length Value Of.
| v Character Units. This specifies that the size of character unit is
| determined by the value that you have set in the in the message’s
| MQMD CCSID field, or that you have set for the message set property
| Default CCSID. The number of bytes processed is the size of character
| unit multiplied by the value of Length Count, or the size of character unit
| multiplied by the value of the INTEGER specified in Length Value Of.
| v End of Bitstream. All data until end of bit stream is processed. This
| option is valid only if the element is the last in the message. If you select
| this value, you do not need to enter a value in Length Count or Length
| Value Of.
| Skip Count INTEGER Enter the number of bytes to skip before reading or writing this element.
| The default is 0, the minimum value is 0, and the maximum value is
| 999999. You can use this property to model a message defined by a COBOL
| data structure containing FILLER fields.

| When a message is written, Skip Count bytes have the value x’00’.
| Byte Alignment Enumerated Type Specify how the element is aligned from the start of the message. Select one
| of:
| v 1 Byte. This is the default value.
| v 2 Bytes
| v 4 Bytes
| v 8 Bytes
| v 16 Bytes
| String Justification Enumerated Type If you have set the Physical Type property to Fixed Length String, select
| Left Justify (the default value) or Right Justify from the drop-down list.
| If you have selected another value for Physical Type, this is set to Not
| Applicable.

Chapter 5. Working with a Custom Wire Format layer 103

 STRING properties
| Table 37. CWF STRING element member properties (continued)
| Property Type Meaning
| Padding Character STRING The padding character is used to fill out the remaining character positions
| when the string length is less than the specified string size. If you have set
| the Physical Type property to Fixed Length String, and the String
| Justification property is either Left Justify or Right Justify, specify this
| character in one of the following ways:
| v Select either SPACE or NUL (not NULL) from the drop-down list.
| v Enter a character between quotes, for example "c" or ’c’, where c is any
| alphanumeric character.
| v Enter a hexadecimal character code in the form 0xYY where YY is a
| hexadecimal value.
| v Enter a Unicode value in the form U+xxxxxx where xxxxxx is a Unicode
| value specified in hexadecimal. The maximum length of the string you
| can enter is 10.
| v Select the default value of an empty string.
| Repeat Count Type Enumerated Type This is only displayed if you have set the Repeat property on the
| Connection pane to Yes.

| You can select one of the following:

| v Count (described below)
| v Value Of (described below)
| Repeat Count INTEGER If you have set the Repeat property on the Connection pane to Yes, and the
| Repeat Count Type to Count, enter the number of occurrences of this element.
| The minimum value is 0 (both zero and one mean that a single occurrence
| is expected), the maximum value is 2147483647.
| Repeat Count Enumerated Type If you have set the Repeat property on the Connection pane to Yes and the
| Value Of Repeat Count Type property to Value Of, select the name of the INTEGER
| element the value of which specifies the number of occurrences of this
| element from the drop-down list of INTEGER elements that are defined as
| siblings of the current element, and occur before it in the structure of the
| message.

| For information about reordering elements, see “Reordering elements in

| compound types” on page 171.
| Encoding Null Enumerated Type Select one of the following options from the drop-down list:
| v NULLPadFill. This is only valid if Physical Type is Fixed Length String.
| The field is filled with the value specified by the Padding Character.
| Encoding Null Value must be set to an empty string.
| v NULLLogicalValue. The Encoding Null Value is transformed to match the
| required format for the field. This is the default value.
| v NULLLiteralValue. The Encoding Null Value is directly substituted as if it
| is a string. You can specify a nonnumeric value for Encoding Null Value.
| Encoding Null STRING The use of this property depends on the Encoding Null property, described
| Value above. The default value is empty (not set).
|

104 WebSphere MQ Integrator Working with Messages

 Compound element member properties
| Compound element
| The properties for an element member of a compound type are defined in Table 38.
| Table 38. CWF compound element member properties
| Property Type Meaning
| Length Count INTEGER Enter the number of bytes to specify the value of the element length. The
| minimum value is 0, the maximum value is 2147483647, the default value is
| empty (not set). Set this property only if the compound type on which this
| element is based has a base Type which has a value other than null.

| See “Type property Type” on page 108 for further information.

| Length Units Enumerated Type Select one of the following from the drop-down list:
| v Bytes. This is the default value.
| v End of Bitstream. All data until end of bit stream is processed. This is
| only valid if the element is the last in the message. If you select this
| value, you do not need to enter a value for Length Count. Set this
| property only if the compound type on which the element is based has a
| base Type that has a value other than Null.
| Skip Count INTEGER Enter the number of bytes to skip before reading or writing this element.
| The default is 0, the minimum value is 0, and the maximum value is
| 999999. You can use this property to model a message defined by a COBOL
| data structure containing FILLER fields.

| When a message is written, skip count bytes have the value x’00’.
| Byte Alignment Enumerated Type Specify how the element is aligned from the start of the message. Select one
| of:
| v 1 Byte. This is the default value.
| v 2 Bytes
| v 4 Bytes
| v 8 Bytes
| v 16 Bytes
| Repeat Count Type Enumerated Type This is only displayed if you have set the Repeat property on the
| Connection pane to Yes.

| You can select one of the following:

| v Count (described below)
| v Value Of (described below)
| Repeat Count INTEGER If you have set the Repeat property on the Connection pane to Yes, and the
| Repeat Count Type to Count, enter the number of occurrences of this element.
| The minimum value is 0 (both zero and one mean that a single occurrence
| is expected), the maximum value is 2147483647.
| Repeat Count Enumerated Type If you have set the Repeat property on the Connection pane to Yes and the
| Value Of Repeat Count Type property to Value Of, select the name of the INTEGER
| element the value of which specifies the number of occurrences of this
| element from the drop-down list of INTEGER elements that are defined as
| siblings of the current element, and occur before it in the structure of the
| message.

| For information about reordering elements, see “Reordering elements in

| compound types” on page 171.
|

| Null values are not defined for compound elements: the properties Encoding Null
| and Encoding Null Value, present for other types, are therefore not set.

Chapter 5. Working with a Custom Wire Format layer 105

 Null handling
|
| Null handling in CWF
| The CWF wire format layer supports handling of null values within messages. The
| rules for whether nulls are permitted are described in “Null handling” on page 64.
| The NULL properties that you set for the message set are applicable for all the
| defined objects within the message set.
|
| Multipart messaging in CWF
| If you define a message to contain other messages, you must define all the
| embedded messages in the same message set as the outermost message. You must
| also define all embedded messages with the same wire format as the outermost
| message.

| You must set the property Type Composition for the compound type on which the
| outermost message is based to Message. You can define this compound type to
| contain one or more messages, but only one of these can appear in the bit stream.

| In CWF, there is no way to identify within the bit stream of the message body
| which embedded message appears, so you must define this choice in one of two
| ways:
| v You can set the Message Type property (either in the input message’s MQRFH2
| header, or in the input node properties) to be a path, which contains the
| hierarchy of messages or elements or both from the outermost message to the
| innermost message. For further information, see the description and use of the
| message set property Message Type Prefix in Table 2 on page 43 and Table 3 on
| page 44.
| v You can code ESQL to reference the messages contained in the compound type.
| The first message that you reference in this way is assumed to be the selected
| message.

| CWF can only use the Message Type property to resolve the hierarchy of the first
| embedded message structure. If you have defined the outer message to contain
| more than one compound type that defines embedded messages, you must resolve
| the message choice within the second and subsequent compound types using
| ESQL.
|
| Data conversion with CWF
| You can convert an MRM message to a different code page or encoding, or both.
| To do this, you should set the CodedCharSetId and Encoding fields in the
| appropriate output MQSeries header to the target value. The appropriate MQSeries
| header is the header that precedes and is adjacent to the output message body.

| The Data Conversion performed is dependent on the simple type of each element:
| v BINARY elements are not converted.
| v BOOLEAN elements are not converted.
| v DATETIME elements are handled as either BINARY, STRING, or packed
| decimals. If a DATETIME element is defined as BINARY, it is not converted. If it
| is defined as STRING, it is converted as a STRING element (described below). If
| it is defined as a packed decimal value, it is converted as a DECIMAL with
| Physical Type set to Packed Decimal (described below).

106 WebSphere MQ Integrator Working with Messages

 Data conversion with CWF
| v DECIMAL elements with Physical Type set to Extended Decimal are converted to
| the target CodedCharSetId. Elements with other Physical Type settings are
| converted to the target Encoding.
| v FLOAT elements with Physical Type set to Extended Decimal are converted to the
| target CodedCharSetId. Elements with other Physical Type settings are converted
| to the target Encoding.
| v INTEGER elements with Physical Type set to Extended Decimal are converted to
| the target CodedCharSetId. Elements with other Physical Type settings are
| converted to the target Encoding.
| v STRING elements are converted to the target CodedCharSetId (the Length of an
| element that has Physical Type of Length Encoded String 2 is converted to the
| target Encoding).

| An example MQSeries message has an MQMD header, an MQRFH2 header, and a

| message body. To convert this message to a mainframe CodedCharSetId and
| Encoding, code the following ESQL:
| SET OutputRoot.MQMD.CodedCharSetId = 500;
| SET OutputRoot.MQMD.Encoding = 785;
| SET OutputRoot.MQRFH2.CodedCharSetId = 500;
| SET OutputRoot.MQRFH2.Encoding = 785;
|
| The relationship between the logical model and CWF
| When you use add a CWF layer to the message set, this assumes a fixed format for
| each message. Every element within the message must therefore be set, either
| explicitly (by copy or assignment), implicitly (by copy or assignment of a
| containing object) or by default (an element value with its Role set to Default
| Value has been associated with the element).

| There are also rules that affect the following properties that define the relationship
| between the logical model and CWF:
| v “Type property Type Composition”
| v “Type property Type Content” on page 108
| v “Type property Type” on page 108
| v “Element value property Default Value” on page 109

| Type property Type Composition

| A CWF message is always output with the elements in the sequence specified in
| the MRM message definition. However, you do not always have to specify ESQL
| that builds the elements in that sequence. The rules for coding ESQL are given for
| each value for the Type Composition property. See the WebSphere MQ Integrator
| ESQL Reference book for details of the ESQL statements referred to here.
| Sequence
| You must build the output message to match the sequence of the elements,
| or types, or both, in the message. You can normally do this is using ESQL
| SET statements to assign a value to each element or type. The first SET
| statement sets the value of the first element or type in the message, the
| second SET sets the value for the second element or type, and so on. You
| can vary this sequence of statements using ESQL ATTACH, CREATE, and
| MOVE statements.
| If the elements or types have default values, and you do not build the
| message in the correct sequence, those elements built out of sequence will
| contain their default values, not the values that you set. This is because

Chapter 5. Working with a Custom Wire Format layer 107

 Relationship with the logical model
| elements built out of sequence are assumed to be self-defining, and for
| CWF these are discarded when the message is written to the bit stream.
| Ordered Set
| You must build the output message to match the sequence of the elements
| in the message. You can normally do this using ESQL SET statements to
| assign a value to each element. The first SET statement sets the value of
| the first element in the message, the next SET sets the value for the second
| element, and so on. You can vary this sequence of statements using ESQL
| ATTACH, CREATE, and MOVE statements.
| If the elements have default values, and you do not build the message in
| the correct sequence, those elements built out of sequence will contain their
| default values, not the values that you set. This is because elements built
| out of sequence are assumed to be self-defining, and for CWF these are
| discarded when the message is written to the bit stream.
| Unordered Set
| You can build elements of the output message in any sequence.
| Simple Unordered Set
| You can build elements of the output message in any sequence.
| Empty CWF cannot process elements within a compound type if Type Composition
| is set to Empty.
| Choice
| A choice cannot be resolved purely from the data. The receiving program
| (for example, a message flow) must interpret the data and decide which
| option of the choice the message instance contains.
| This process is known as Unresolved Choice handling. The first reference in
| the application to any one of the choice elements resolves the choice to the
| option containing that element.
| For example, a message contains element A, followed by a choice of either
| B or C. The value of A determines whether the following element is B or
| C. You can code ESQL within the message flow as follows:
| IF (A=1) THEN
| SET VARIABLE1 = InputBody.B; /* choice resolves to B
| ELSE SET VARIABLE1 = InputBody.C; /* choice resolves to C
| END IF;

| The unresolved choice handling process is also relevant to TDS fixed or

| delimited messages (that is, not tagged messages).
| Message
| See “Multipart messaging in CWF” on page 106 for details of this option.

| Type property Type Content

| CWF is a fixed format and all elements must be present in a message. Therefore
| Type Content is ignored. On output, all elements must be set explicitly (for example,
| using ESQL SET), set implicitly (using a tree copy function), or must have a default
| value defined.

| Type property Type

| A type specified for a compound type (also referred to as a base type) is normally
| used to model XML in which an element has a value in addition to children. If a

108 WebSphere MQ Integrator Working with Messages

 Relationship with the logical model
| message of this format is to be reformatted to CWF, the value of the element shares
| CWF compound element characteristics, described in “Compound element” on
| page 105.

| Refer to “Using ESQL to manipulate the message tree” on page 69 for details of
| how to manipulate the base type with ESQL.

| Element value property Default Value

| If you output a CWF message and do not set values for all elements, each element
| for which you do not explicitly or implicitly set a value inherits a default value, if
| you have defined one. To define a default, you must create an element value, and
| associate it with the element with Role set to Default Value.
|
| Example: modeling the Video customer message using CWF
| You can model the video customer message, shown in Figure 21 on page 78, using
| the default settings for the CWF wire format layer for most properties.

| You must modify the message set properties shown in Table 39.
| Table 39. Video customer example with CWF: message set properties
| Property Value
| Boolean True Value 31
| Boolean False Value 30
| Boolean Null Value 00
|

| The only other CWF properties that you need to set are for the element members
| within compound types. These are shown in Table 40.
| Table 40. Video customer example with CWF: element member properties
| Compound Type Element Property Value
| CustomerType Name Length Count 20
| NameType Title Length Count 3
| NameType FirstName Length Count 30
| AddressType HouseNo Physical Type Extended Decimal
| AddressType HouseNo Length Count 5
| AddressType Street Length Count 20
| AddressType Town Length Count 20
| IdType PassportNo Length Count 20
| IdType DrivingLicenseNo Length Count 20
| IdType CreditCardNo Length Count 20
| CustomerType Borrowed Repeat Count 2
| BorrowedType VideoTitle Length Count 20
| BorrowedType DueDate Length Count 11
| BorrowedType DueDate Format String dd-MMM-yyyy
| BorrowedType Cost Physical Type Extended Decimal
| BorrowedType Cost Length Count 4

Chapter 5. Working with a Custom Wire Format layer 109

Modeling the Video customer message using CWF

110 WebSphere MQ Integrator Working with Messages

|

| Chapter 6. Working with an XML Format layer

| If you want to render your logical message model as an XML message, you must
| add an XML wire format layer to your message set. To invoke the MRM XML
| parser for this particular XML wire format layer, set the <Fmt> in the MQRFH2
| header, or the Message Format property of the input node, to the identifier that you
| specify on the XML wire format layer.

| You must check in a message set before you can add a physical wire format layer.
| You must check in the resources of the message set and check out each in turn
| before you can view the wire format layer pane against each of the MRM objects.

| The XML wire format layer pane is described for each of the MRM objects. This
| pane is in addition to the panes discussed in Chapter 4, “The MRM logical
| message model” on page 35.

| This chapter discusses the following topics:

| v “How the MRM supports self-defining elements”
| v “Setting properties for the XML wire format layer” on page 112
| v “Message rendering options” on page 119
| v “Null handling in the XML wire format” on page 119
| v “Multipart messages in the XML wire format” on page 121
| v “Data conversion with XML” on page 122
| v “Importing DTDs” on page 122
| v “Rules for XML wire format properties” on page 122
| v “The relationship between the logical model and the XML wire format” on
| page 123
| v “Example: modeling the Video customer message using XML” on page 126
|
| How the MRM supports self-defining elements
| XML messages are by their nature self-describing: each piece of data is prefixed by
| a tag name or an attribute name. Therefore, it is possible to parse the message
| without the aid of a dictionary. The MRM supports XML self-defining messages
| that have no dictionary, and self-defining elements within a predefined message (a
| sparse message model).

| In the part of the message that has been defined to the MRM, some elements
| might not have been defined. Because the compound type property Type Content is
| not validated by the broker, the broker assumes a setting of Open for XML
| messages. This means that self-defining elements are always allowed. If the MRM
| parser encounters a self-defining element in an incoming message, it outputs the
| element in the same position in the outgoing message.

| If an input message contains elements that are interpreted as self-defining, but the
| output message requires fully predefined elements (for example, it has CWF wire
| format), the parser might fail or produce unexpected results.

© Copyright IBM Corp. 2000, 2002 111

 Setting XML layer properties
|
| Setting properties for the XML wire format layer
| The following sections describe the properties that you can set in the Control
| Center for the XML wire format at each level within the MRM model:
| v “Message set properties for XML”
| v “Message properties for XML” on page 115
| v “Element properties for XML” on page 116

| Message set properties for XML

| Table 41 defines the properties for the XML layer for the message set. If the
| message set is based on another message set, you cannot change the properties
| marked with a dagger (†).
| Table 41. XML message set properties
| Property Type Meaning
| XML Wire Format STRING Specify an identifier that is unique within the message set. This
| Identifier† can be up to 254 alphanumeric characters.

| The wire format identifier is not the same as the name of the
| wire format layer (although you can define it to have the same
| value). When you create a wire format layer, you must enter a
| name, which is used for display purposes only in the Control
| Center to identify the tab on which the wire format layer
| properties are displayed. In all references outside the Control
| Center (for example, in the MQRFH2 header of a message) the
| wire format identifier must be used, not the name.
| Suppress XML Declaration Enumerated Type Select Yes or No from the drop-down list. If you select Yes, the
| declaration (for example, <?xml version=’1.0’
| encoding=’ccsid’>) is suppressed and the encoding is taken
| from the MQMD.
| Standalone Document Enumerated Type Select Yes or No from the drop-down list. If you select Yes, the
| broker does not attempt to load an external subset. It is
| effectively ignored other than to be included in the declaration.
| Suppress DOCTYPE Enumerated Type Select Yes or No from the drop-down list. If you select Yes, the
| DOCTYPE (DTD) declaration is suppressed.
| DOCTYPE System ID STRING Specify the System ID for DOCTYPE external DTD subset (if
| DOCTYPE is present). This is normally set to the name of the
| generated (or imported) DTD for a message set.

| If Suppress DOCTYPE is set to Yes, this property is ignored and

| cannot be changed (the field is disabled). The default value is
| empty (not set).
| DOCTYPE Public ID STRING Specify the Public ID for DOCTYPE external DTD subset (if
| DOCTYPE is present, and System ID is specified).

| If Suppress DOCTYPE is set to Yes, this property is ignored and

| cannot be changed (the field is disabled). The default value is
| empty (not set).

112 WebSphere MQ Integrator Working with Messages

 Message set properties
| Table 41. XML message set properties (continued)
| Property Type Meaning
| DOCTYPE Text STRING Use this property to add additional DTD declarations. It is not
| parsed by the XML parser and thus it might not be valid XML.
| You can include ENTITY definitions or internal DTD
| declarations. It is a string (up to 32KB) in which new line and
| tab characters are replaced by \n and \t respectively.

| The content is parsed, and appears in the output message. If

| there is an inline DTD, the content of this property takes
| precedence.

| If you have set Suppress DOCTYPE to Yes, this property is

| ignored and cannot be changed (the field is disabled).

| The default value is empty (not set).

| Root Tag Name† STRING Specify the name of the message set root tag. You can leave
| this property blank, in which case no wrapper tags are used
| for messages (that is, the message tag is the root of the
| document). The name can be followed by a space and
| additional text for attribute/value pairs to appear with the root
| tag.

| The default value is MRM.

| Enable Versioning Support† Enumerated Type Specify if versioning support is enabled. Select either Yes or No
| from the drop-down list. This property specifies whether XML
| namespace definitions are coded for the root tag in the
| message, together with namespace qualifiers for any elements
| that do not belong to the default namespace. These namespace
| definitions are used to represent the message set dependency
| information, which is used to support the exchange of
| messages between applications that are based on different
| customizations of the same message set.

| The default is Yes.

| Boolean True Value STRING Specify the string that is used to encode and recognize
| BOOLEAN true values. When an XML document is parsed, the
| string 1 is always accepted as true for a BOOLEAN element.
| Enter a string of up to 254 characters.

| The default is true. 1 is also valid.

| Boolean False Value STRING Specify the string that is used to encode and recognize
| BOOLEAN false values. When an XML document is parsed,
| the string 0 is always accepted as false for a BOOLEAN
| element. Enter a string of up to 254 characters.

| The default is false. 0 is also valid.

Chapter 6. Working with an XML Format layer 113

 Message set properties
| Table 41. XML message set properties (continued)
| Property Type Meaning
| Encoding Null Num Enumerated Type Specify the null encoding for numeric fields. This provides a
| method of affirming by comparison that the element is null.
| You must select one of the following values from the
| drop-down list:
| v NULLEmpty. The empty string is used as the comparison. This
| is the default value.
| v NULLAttribute. The property Encoding Null Num Val of the
| parent element is used.
| v NULLValue. The value of property Encoding Null Num Val is
| used.
| v NULLElement. The property Encoding Null Num Val of the
| child element is used.
| v NULLValAttr. This option is valid only for elements
| instantiated in a compound type with property Member
| render set to XMLElementAttrVal or XMLElementAttrIDVal. The
| value attribute is omitted from the comparison.
| Encoding Null Num Val Specify the value to qualify the Encoding Null Num property, if
| you have set that to NULLAttribute, NULLValue, or NULLElement.
| Refer to Table 47 on page 120 for further information.
| Encoding Null Non-Num Specify the null encoding for non-numeric fields. This is a
| method of affirming that the element is null. The options are
| identical to those available for property Encoding Null Num.
| Encoding Null Non-Num Specify the value to qualify the Encoding Null Non-Num
| Val property. Refer to Table 47 on page 120 for further information.
|

| Inline DTDs and the DOCTYPE Text property

| You can include inline DTDs in your messages, and you can specify additional
| information by setting the property DOCTYPE Text, but you must be aware of the
| action taken by the parser when it constructs an output message:
| 1. If you take any action that causes the output message to be regenerated, for
| example if you configure a Compute node to create a new output message by
| coding ESQL statements like SET OutputRoot.MRM.Field1 = xxx:
| v If you have set the property Suppress DOCTYPE for the message set in which
| you have defined this message to Yes, both DOCTYPE information (specified
| in the DOCTYPE Text property for the message set or message) and inline
| DTD are excluded from the output message.
| v If you have set the property Suppress DOCTYPE for the message set in which
| you have defined this message to No, any information that you have specified
| in the DOCTYPE Text property for the message set or message is included in
| the output message, but the inline DTD is excluded.
| 2. If you do not take any action that causes the output message to be regenerated,
| the parser generates an output message that is a direct copy of the input
| message. This occurs if you have configured a Compute node in the message
| flow to copy the message using SET OutputRoot = InputRoot (explicitly, or by
| checking the Copy entire message check box), and you do not modify the
| message in any way in this or any other node. In this case the inline DTD is
| retained in the ouput message but any information that you specify in the
| DOCTYPE Text property for the message set or message is not included.

114 WebSphere MQ Integrator Working with Messages

 Message properties
| Message properties for XML
| Table 42 defines the properties for the XML layer for the message. If the message
| set is based on another message set, you cannot change the properties marked with
| a dagger (†).
| Table 42. XML message properties
| Property Type Meaning
| DOCTYPE System ID STRING Specify the System ID for DOCTYPE external DTD subset. It
| overrides the equivalent message set property setting for this
| particular message.

| If the message set property Suppress DOCTYPE is set to Yes, this

| parameter is ignored and cannot be changed (the field is disabled) .

| The default value is empty.

| DOCTYPE Public ID STRING Specify the Public ID for DOCTYPE external DTD subset. It overrides
| the equivalent message set property setting for this particular
| message.

| If the message set property Suppress DOCTYPE is set to Yes, this

| parameter is ignored and cannot be changed (the field is disabled) .

| The default value is empty.

| DOCTYPE Text STRING Enter optional additional text to include within the DOCTYPE. It
| overrides the message set property for this particular message.

| If the message set property Suppress DOCTYPE is set to Yes, this

| parameter is ignored and cannot be changed (the field is disabled) .

| The default value is empty.

| Root Tag Name† STRING Specify the name of the root tag for a message bit stream XML
| document. It overrides the message set property set for this message.

| The default value is empty.

| XML Name STRING Enter the XML tag name for the message body in the XML document
| (message bit stream). This can be the root tag name in the document,
| or nested within other tags, depending on the Root Tag Name property.
| It must be a valid XML name.

| The default value is the message identifier.

| Render Enumerated Type Set this property to one of the following values in the drop-down list:
| v XMLElement. This causes the message body to be rendered within
| the XML element that you specified in XML Name.
| v XMLAttrid. This causes the message name to be rendered as an
| attribute of the Root tag.
| ID Attribute Name STRING Specify the name of the attribute used to identify the message if the
| Render property is set to XMLElement. It must be a valid XML Attribute
| Name.

| This property is ignored and cannot be changed (the field is disabled)

| if the Render property is set to XMLElementAttrID

| The default value is id.

Chapter 6. Working with an XML Format layer 115

 Message properties
| Table 42. XML message properties (continued)
| Property Type Meaning
| ID Attribute Value STRING Specify the value of the attribute used to identify a message if the
| Render property is set to XMLElementAttrID.

| This property is ignored and cannot be changed (the field is disabled)

| if the Render property is set to XMLElement.

| The default value is the message identifier.

|

| Element properties for XML

| Table 43 defines the properties for the XML layer for the element.
| Table 43. XML element properties
| Property Type Meaning
| XML Name STRING Enter a value for the XML element name. This property specifies the name
| for the XML start tag or attribute for the element in an XML document
| (message).

| This can be used to provide name mapping when the MRM identifier needs
| to be different from the XML name, for example because of different
| namespace rules. It must be a valid XML name.

| If you do not set a value, it defaults to that of the element’s identifier. If the
| element’s identifier is a prefixed identifier, it defaults to the identifier with
| the caret character (^) replaced by an underscore (_).

| For further details about prefixed identifiers, see “Prefixed identifiers” on

| page 40.
| Encoding Enumerated Type This is only valid if the data type of the element is BINARY. Select one of
| the following values from the drop-down list:
| v CDatahex (the default). Hexadecimal values in this field are specified with
| the CDATA qualifier, for example <e1><![CDATA[62]]></e1>
| v hex. Hexadecimal values in this field are specified as digits only, for
| example <e1>62</e1>
| v base64. Values in this field are specified as digits only, coded in base 64
| (not base 16, hexadecimal)
| Format STRING Specify a format string that specifies the rendering of the value for
| DATETIME elements.

| The default is yyyy-MM-dd’T’hh:mm:ssZZZ.

| See Appendix C, “DATETIME formats” on page 253 for details of datetime

| formats.
|
|

116 WebSphere MQ Integrator Working with Messages

 Element properties
| Element member properties for XML
| When you have instantiated an element within a compound type, the XML wire
| format pane has additional member properties, defined in Table 44.
| Table 44. XML element member properties
| Property Type Meaning
| Member XML STRING Specify the actual name (for XML start tag or attribute) of the child
| Name element in the XML document (message bit stream). This only applies
| when the child references an element.

| The value that you specify takes precedence over the XML Name that you
| specified for the element, and can be used to provide name mapping
| when the MRM identifier needs to be different from the XML name, for
| example, because of different namespace rules. This must be a valid XML
| Name.

| The default value is the element XML Name.

| Member Render Enumerated Type Specify how the instantiated element or type is rendered (output) in the
| resulting XML document. Select one of the following values from the
| drop-down list:
| v XMLElement. If you select this value, the element (or type) is rendered
| as a child XML element of the parent compound type. The identity of
| the child is determined by the tag name of the child. The value is the
| content of the child element.
| This is the default value.
| v XMLAttribute. If you select this value, the element (or type) is rendered
| as an attribute of the parent Render as an attribute of the parent XML
| element. The identity of the child is determined by the attribute name.
| The value is the attribute value. This is only valid for simple elements.
| v XMLElementAttrId. If you select this value, the element (or type) is
| rendered as a child XML element of the parent compound type. The
| identity of the child is determined by the value of a specified attribute
| of the child. The value is the content of the child element. You must
| add an attribute to the child element with an attribute name as
| specified in Member ID Attribute Name and a value as specified in
| Member ID Attribute Value.
| v XMLElementAttrVal. If you specify this value, the element (or type) is
| rendered as a child XML element of the parent compound type. The
| identity of the child is determined by the tag name of the child. The
| value is the value of a specified attribute. The name of the attribute is
| specified in Member Value Attribute Name.
| v XMLElementIdVal. This option combines the two options,
| XMLElementAttrId and XMLElementAttrVal. The element is rendered as
| a child of the parent compound type. The identity of the child is
| determined by the value of Member ID Attribute Name. The value is the
| value of Member ID Attribute Value.

| Table 45 on page 118 shows some examples of how these rendering

| options effect the XML output.
| Member ID STRING Specify the name of the attribute used to identify the child. This must be
| Attribute Name a valid XML Attribute Name. This property is ignored and cannot be
| changed (the field is disabled) if Member Render is set to XMLElement,
| XMLAttribute, or XMLElementAttrVal.

| The default value is id.

Chapter 6. Working with an XML Format layer 117

 Element properties
| Table 44. XML element member properties (continued)
| Property Type Meaning
| Member ID STRING Specify the value of the attribute used to identify the child. This property
| Attribute Value is ignored and cannot be changed (the field is disabled) if Member Render
| is set to XMLElement, XMLAttribute, or XMLElementAttrVal.

| The default value is the identifier of the child.

| Member Value STRING Specify the name of the attribute used for the value of the child. This
| Attribute Name must be a valid XML Attribute Name. This is only used if required by
| the setting of Member Render.

| The default value is val.

| Member Format STRING Specify a format string that specifies the rendering of the value for
| DATETIME elements.

| See Appendix C, “DATETIME formats” on page 253 for details of

| datetime formats.

| For member elements other than DATETIME, this property is ignored

| and cannot be changed (the field is disabled).

| The default value is empty (not set).

| Member STRING Select one of the following values from the drop-down list if the data
| Encoding type of the element is BINARY. :
| v CDatahex (the default)
| v hex
| v base64
|

| Table 45 shows examples of the values that you can set for the Member Render
| property.
| Table 45. The effect of rendering options on XML output
| XML Member Render Result
| option
|| <X> XMLElement Member XML Name = A
| <A>value of element</A>
| </X>
|
|| <X A=’value of element’/> XMLAttribute Member XML Name = A

|| <X> XMLElementAttrID Member XML Name = Field

|| <Field id=’A’>value of element</Field> Member ID Attribute Name = id
| </X> Member ID Attribute Value = A
|
|| <X> XMLElementAttrVal Member XML Name = A
|| <A val=value of element/> Member Value Attribute Name = val
| </X>
|
|| <X> XMLElementIDVal Member XML Name = Field
|| <Field id=’A’ val=’value of element’/> Member ID Attribute Name = id
| </X> Member ID Attribute Value = A
| Member Value Attribute Name = val
|

118 WebSphere MQ Integrator Working with Messages

 Rendering options
|
| Message rendering options
| There are four properties on the XML layer that you can use to affect how the
| XML messages are rendered. These are shown in Table 46. In this table, the
| member element is referred to as child, and has the value Cvalue. The parent is
| referred to as parent. For example:
| <parent><child>Cvalue</child></parent>

| See also Table 45 on page 118 for the effects that your choices have on output
| messages.
| Table 46. XML rendering options for element members
| Example XML Member Render Member Id Member Id Member Value
| property value Attribute Name Attribute Value Attribute Name
|| <parent> XMLElement (default) not applicable not applicable not applicable
| <child>Cvalue</child>
| </parent>
| <parent child=’Cvalue’/> XMLAttribute not applicable not applicable not applicable
|| <parent> XML ElementAttrId Fred XXXX not applicable
| <child Fred=’XXXX’>
| Cvalue
| </child>
| </parent>
|| <parent> XMLElementAttrVal not applicable not applicable George
| <child George=’Cvalue’/>
| </parent>
|| <parent> XMLElementAttrIdVal Fred XXXX George
| <child George=’Cvalue’
| Fred=’XXXX’/>
| </parent>
|
|
| Null handling in the XML wire format
| The XML wire format layer supports handling of null values within messages. The
| rules for whether nulls are permitted are described in “Null handling” on page 64.
| NULL properties for XML are set for a message set only and apply to all the
| defined objects within the message set.

| You can use the following two NULL encoding properties to represent the numeric
| and non-numeric encoding for NULL within the XML layer:
| v Encoding Null Num
| v Encoding Null Non-Num

| These represent the numeric and non-numeric encoding for NULL within the XML
| layer:
| v The numeric data types are:
| – DECIMAL
| – FLOAT
| – INTEGER
| v The non-numeric data types are:
| – BINARY
| – BOOLEAN
| – DATETIME
| – STRING

Chapter 6. Working with an XML Format layer 119

 Null handling in XML
| Each of these encodings has five enumerated values:
| v NULLEmpty (Default)
| v NULLValue
| v NULLAttribute
| v NULLElement
| v NULLValAttr

| Table 47 defines the options for encoding null values.

| Table 47. XML options for encoding null values
| Encoding Null Num Encoding Null Num Val Example XML
| Encoding Null Non-Num Encoding Null Non-Num Val
| NULLEmpty (default) not applicable <child></child>
| NULLAttribute null <child null=’true’>¹
| NULLValue zzz <child>zzz</child>
| NULLElement null <child><null/></child>
| NULLValAttr not applicable <child></child>²

| Notes:
| 1. The value of Boolean True is used.
| 2. This is only valid for XMLElementAttrVal and XMLElementAttrIdVal element rendering,
| as specified in Table 45 on page 118. Marking an element as being rendered in this way
| is equivalent to removing the attribute of the element that detailed the element’s value.
|

| You do not have to supply additional clarification for NULLEmpty and NULLValAttr,
| but if you select NULLValue, NULLAttribute, or NULLElement, you must define
| further values to be assigned to represent the NULL condition in the Encoding Null
| Num Value and Encoding Null Non-Num Value message set properties (see Table 47).

| If you select NULLValue, NULLAttribute, or NULLElement, the value that you enter for
| the Encoding Null Num and Encoding Null Non-Num properties are converted to
| their logical value. When an output message is constructed, the logical value is
| written in the same way as any other value. When the input message is parsed, the
| converted logical value is compared against the converted message data.

| NULL value
| Unlike the TDS and CWF layer, when you set the Encoding Null Num property to
| NULLValue, the value is taken as a literal. A direct comparison is done with the text
| string, and no logical data conversion is performed.

| For example, if you set the message set property Encoding Null Num to the value
| NULLValue, and you set Encoding Null Num Val to 0, a FLOAT value of 0.0 or a
| DECIMAL value of +0 does not match NULL.

| If you set Encoding Null Num to NULLEmpty, this is equivalent to setting Encoding
| Null Num to NULLValue and Encoding Null Num Val to "".

| Null element and NullValAttr

| In XML there are two conventions for storing a value:
| 1. It can be stored as an XML attribute with element member property Member
| Render set to XMLAttribute, XMLElementAttrVal, or XMLElementAttrIdVal. For
| example, <element1 val="12"></element1>.

120 WebSphere MQ Integrator Working with Messages

 Null handling in XML
| 2. It can be stored as XML content with element member property Member Render
| set to XMLElement or XMLElementAttrId. For example, <element1>12</element1>.

| If you set the message set property Encoding Null Num to NULLElement, there is no
| way to represent a null value for an attribute value. If a null value is present in the
| tree (from ESQL or another format), an attribute with an empty string is written in
| the output message.

| Conversely, if you have set the message set property Encoding Null Num or
| Encoding Null Non-Num to NULLValAttr, there is no way to represent a null value
| for a value rendered as XML content. If a null value is present in the tree, when
| writing an empty string, an element with no character content is written out
| instead.
|
| Multipart messages in the XML wire format
| If you define a message to contain other messages, the embedded messages can be
| self-defining. If they are not, you must define them in the same message set as the
| outermost message, You must also define all embedded messages with the same
| wire format as the outermost message.

| You must set the property Type Composition for the compound type on which the
| outermost message is based to Message. You can define this compound type to
| contain one or more messages, but only one of these can appear in the bit stream.

| When you configure a message flow to process these messages, you can set the
| Message Type property in the input node properties. Alternatively, you can specify
| this in the input message’s MQRFH2 header. The value you set must be a path that
| contains the hierarchy of messages or elements, or both, from the outermost
| message to the innermost message. All messages or elements, or both, must exist in
| this path. For further information, see the description and use of the message set
| property Message Type Prefix in Table 2 on page 43 and Table 3 on page 44.

| You can define the outer message to contain more than one compound type that
| defines embedded messages, and you can define an embedded message to contain
| another embedded message. An embedded message, wherever it occurs, must start
| with the tag for that message. An embedded message within an embedded
| message must start with the tag for that message, and must complete with its end
| tag before the end tag of its embedding message. If an embedded message follows
| a previous embedded message, it must start with its tag after the end tag of the
| previous embedded message.

| You might not know in advance which message has been embedded. If you need
| to know, you can code ESQL in the message flow to query the FIELDNAME of the
| first child of the compound element. This returns the message identifier of the
| inner message.

| For example, you have defined a message that includes two embedded messages.
| When an input message is received, it must contain one of the two defined
| embedded messages, which have identifiers of membMsg1 and membMsg2. Your outer
| message includes an element embMsgId that is based on a compound type with Type
| Composition set to Message.

Chapter 6. Working with an XML Format layer 121

 Multipart messages
| Code the following ESQL to identify which embedded message is present, and to
| process elements within the embedded messages:
| DECLARE FldName CHARACTER;
| SET FldName = FIELDNAME(InputBody.embMsgId1.*[1]);
| IF (FldName = ’membMsg1’ ) THEN
| SET OutputRoot.MRM.embMsgId1.membMsg1.embInt1 = InputBody.embMsgId1.membMsg1.embInt1 + 1;
| ELSE IF (FldName = ’membMsg2’ ) THEN
| SET OutputRoot.MRM.embMsgId1.membMsg2.embInt1 = InputBody.embMsgId1.membMsg2.embInt1 + 1;
| END IF;
|
| Data conversion with XML
| All XML message data is handled as strings. All data is therefore subject to CCSID
| conversion only.
|
| Importing DTDs
| You can use the supplied DTD importer to import simple DTDs to create MRM
| message definitions. It creates message, element, and type definitions in the logical
| model, that map to ELEMENT and ATTLIST declarations in the DTD. It also sets
| XML layer properties to correspond to DTD declarations. It sets the Member Render
| property for element members to either XMLElement or XMLAttribute. It does not
| support rendering options XMLElementAttrID, XMLElementAttrVal, or
| XMLElementAttrValId.

| The DTD importer ignores attribute datatypes such as ENTITY and ID. It sets the
| compound type property Type Composition to Choice, Sequence, or Simple
| Unordered Set to model the DTD. It models mixed content element declarations
| using a compound type with an associated base type.

| The DTD importer updates the Connection pane properties to show the cardinality,
| although this is not validated by the broker.

| If you have complex DTDs that require more flexible logical message model
| definitions, you are recommended to create these models yourself.
|
| Rules for XML wire format properties
| When you use the XML wire format, you must conform to a number of rules that
| apply to the setting of properties:
| v Cardinality for type members is not validated, for example if the type member is
| mandatory, and if it repeats.
| v The MRM does not support external entities, therefore the broker does not
| search for entities defined outside the current document. External entity
| references or DTDs located externally are not referenced.
| v The value of the Type Content property of a compound type is not checked. For
| XML messages, the broker assumes this is set to Open, therefore self-defining
| elements might be present in the message in addition to those defined to the
| MRM.

| General rules
| You must consider the following general rules when you model a DTD in the
| MRM:
| v For every <!ELEMENT....> in a DTD, you must define an associated element in
| the MRM model

122 WebSphere MQ Integrator Working with Messages

 General rules
| v For each use of parentheses in an expression, for example A,(C|D)*, you must
| define an associated compound type.
| v For every attribute list <ATTLIST....> you must define a compound type in the
| MRM model with property Type Composition set to Simple Unordered Set.
| v A DTD element that has an attribute list associated with it must be based on a
| compound type with Type Composition property set to Sequence. The compound
| type associated with the attributes must be a child of this type.
| v You must specify all rules associated with cardinality on the Connection pane.
|
| The relationship between the logical model and the XML wire format
| The logical model allows you to model the following DTD constructs:
| v The five flavours of DTD element declaration:
| – Empty elements.
| – Elements with no content restriction.
| – Elements containing only character data, using the compound type’s base
| type.
| – Elements containing only elements. The child elements are related using
| sequence and choice constructs.
| – Elements with a mixed content - the child elements and data are related using
| sequence and choice constructs. The data elements (#PCDATA) can be modeled
| using simple types.
| v DTD attribute list declarations, using a simple unordered list
| v The cardinality rules associated with DTD element declarations (mandatory, ?, +,
| *)
| v Attribute behavior (#REQUIRED, #IMPLIED, #FIXED, default value)

| Compound type properties

| Set the MRM properties for the compound type to map to the XML constructs that
| you require:
| v Type. Set this property to one of the MRM simple types (BINARY, STRING, and
| so on). This allows you to allocate a value to the compound type itself, in
| addition to any children you define for it. It is referred to as the compound
| type’s base type. The default is null, that is, the compound type has no type. For
| example:
| <!!ELEMENT> name (#PCDATA|A|B)

| is equivalent to:
| <name>abcdef<A>xx</A><B>zz</B></name>

| Use this to model the #PCDATA content model.

| v Type Composition and Type Content. These are used in conjunction with the
| compound type’s base type to model the five DTD element content models:
| – Empty elements
| – Elements with no content restriction
| – Elements that contain character data only
| – Elements that contain elements only. Choice and Sequence are used to
| describe their relationship.
| – Elements with a mixed content. Choice and Sequence are used to describe
| their relationship.

Chapter 6. Working with an XML Format layer 123

 Relationship with the logical model
| Table 48 shows the various combinations of Type Composition and Type Content,
| and what you can model in the DTD using the combinations.
| – Type Composition. You can set this property to one of the following values:
| - Empty. You cannot add any children to this compound type. It models a
| content model of EMPTY and ANY. For example:
| <!ELEMENT name EMPTY>
| <!ELEMENT name ANY>

| Modeling a content model of ANY might appear a little strange when no

| elements can be explicitly added to the compound type, but if you set Type
| Content to Open, anything can appear in the XML document. If you set Type
| Content to Closed, you are modeling a Type Content of Empty.
| - Choice. Only one of the defined children can be present in the message.
| Repeating children are allowed. This models a DTD choice, for example:
| <!ELEMENT name (A|B|C)>
| - Sequence. Children must appear, if present, in the specified order.
| Repeating children are allowed. This models a DTD element sequence list,
| for example:
| <!ELEMENT name (A,B,C)>
| - Simple Unordered Set. Children can be in any order but cannot repeat.
| Children must be based on a simple type. This models a DTD attribute list,
| for example:
| <!ATTLIST elemname attr1 attr2 attr3>
| – Type Content. You can set this property to one of the following values (note
| that these are not validated by the broker):
| - Open. The compound type can contain any valid children (compound types,
| simple types, or elements) not just those that you have added to this
| compound type. You would use this in conjunction with a Type Composition
| of Empty to model a content model of ANY, that is:
| <!ELEMENT name ANY>

| You can also model sparse XML messages using this setting.
| - Closed. The compound type can only contain the child elements that you
| have added to it.
| - Open Defined. The compound type can contain any valid children defined
| within the message set. You might find this very useful when you are
| dealing with multipart messages, where this compound type has a
| previously defined message embedded within it.
| - Message. Used for multipart message support, described in “Multipart
| messages in the XML wire format” on page 121.
| Table 48. Combinations of Type Composition and Type Content for XML message modeling
| Type Composition Type Content Valid children Application
| Empty Closed None Models <!ELEMENT name EMPTY> with no
| attributes
| Empty Open None Models <!ELEMENT name ANY>, any
| elements are allowed
| Empty Open Defined None Models multipart messages
| Choice Closed Elements, simple types, Models choice in DTD element
| and compound types declaration.

124 WebSphere MQ Integrator Working with Messages

 Relationship with the logical model
| Table 48. Combinations of Type Composition and Type Content for XML message modeling (continued)
| Type Composition Type Content Valid children Application
| Sequence Open Elements, simple types, Models a DTD sequence that has
| and compound types self-defining elements
| Sequence Closed Elements, simple types, Models a sequence in a DTD element
| and compound types declaration that has only predefined
| elements
| Sequence Open Defined Elements, simple and Models multipart messages
| compound types
| Simple Unordered Set Open Elements based on a Models attribute lists that contain
| simple type self-defining elements
| Simple Unordered Set Closed Elements based on a Models a DTD attribute list
| simple type
| Simple Unordered Set Open Defined Elements based on a Models multipart messages
| simple type
|

| You can model mixed content element content if you set Type Composition to
| Sequence and Type Content to Choice, and including a simple type of STRING (that
| is, an ambiguous element) as a child of the compound type. The simple type of
| STRING models the #PCDATA. Alternatively, you can model the string as a base type
| of type STRING. This is preferable because you can access the base type by name
| in the message flow ESQL, and the base type is not ambiguous.

| Compound type member properties

| Table 49 and Table 50 on page 126 show how you can set the Connection pane
| properties to model DTDs. Table 49 applies to cardinality of DTD element
| declarations and Table 50 on page 126 applies to DTD attribute list declarations.
| None of these are validated by the broker.
| Table 49. Connection pane properties and their application to DTD element declarations
| Semantics DTD element definition Connection pane settings
| <!ELEMENT element–content–model>
| Mandatory element Repeat = No
| (Non-repeating) Min Occurs = 1
| Max Occurs = 1
| Optional element? Repeat = No
| (Non-repeating) Min Occurs = 0
| Max Occurs = 1
| At least one element+ Repeat = Yes
| (Mandatory and repeating) Min Occurs = 1
| Max Occurs >= 1
| Any number including none ”element* Repeat = Yes
| (Optional and repeating) Min Occurs = 0
| Max Occurs >= 0
|

| Table 50 on page 126 shows the different types of behavior for the attributes in a
| DTD attribute list declaration (modeled as a Simple Unordered Set).

Chapter 6. Working with an XML Format layer 125

 Relationship with the logical model
| Table 50. Connection pane properties and their application to DTD attribute list declarations
| Semantics DTD Attribute behavior Connection pane settings Element Value constraint
| Mandatory #REQUIRED Repeat = No Not applicable
| Min Occurs = 1
| Max Occurs >= 1
| Optional (Default) #IMPLIED Repeat = No Not applicable
| Min Occurs = 0
| Max Occurs >= 1
| Default Value “default–value” Repeat = No Default value
| Min Occurs = 1 Element constraint
| Max Occurs >= 1
| Fixed Value #FIXED“value” Repeat = No Default value
| Min Occurs = 1 Element constraint
| Max Occurs >= 1
|
|
| Example: modeling the Video customer message using XML
| You can model the video customer message, shown in Figure 21 on page 78, using
| the default settings for the XML wire format layer. The default property values
| result in everything rendered as an element, with the tag name set to the identifier
| of the associated MRM element. Some alternatives to this default behavior are
| presented in “Other XML rendering options” on page 128.

| If you accept the defaults, the message is rendered in XML as follows:

| <MRM>
| <Customer>
| <Name>Farman
| <Title>Mrs</Title>
| <FirstName>Nicci</FirstName>
| </Name>
| <Address>
| <HouseNo>3</HouseNo>
| <Street>Caledonian Close</Street>
| <Town>Yaleham</Town>
| </Address>
| <PassportNo>kjdshfkj846</PassportNo>
| <Borrowed>
| <VideoTitle>Shrek</VideoTitle>
| <DueDate>20020430</DueDate>
| <Cost>3.00</Cost>
| </Borrowed>
| <Magazine>0</Magazine>
| </Customer>
| </MRM>

| Table 51 shows the message set properties.

| Table 51. Video customer example with XML: message set properties
| Property Value
| XML Wire Format Identifier XML
| Suppress XML Declaration No
| Standalone Document (not set)
| Suppress DOCTYPE No
| DOCTYPE System ID www.mrmnames.net/D02TLU007K001
| DOCTYPE Public ID D02TLU007K001

126 WebSphere MQ Integrator Working with Messages

 Modeling the Video customer message using XML
| Table 51. Video customer example with XML: message set properties (continued)
| Property Value
| DOCTYPE Text (not set)
| Root Tag Name MRM
| Enable Versioning Support Yes
| Boolean True Value 1
| Boolean False Value 0
| Encoding Null Num NullEmpty
| Encoding Null Num Val (not applicable)
| Encoding Null Non-Num NULLEmpty
| Encoding Null Non-Num Val (not applicable)
|

| Table 52 shows the message properties.

| Table 52. Video customer example with XML: message properties
| Property Value
| DOCTYPE System ID www.mrmnames.net/D02TLU007K001
| DOCTYPE Public ID D02TLU007K001
| DOCTYPE Text (not set)
| Root Tag Name MRM
| Render XMLElement
| XML Name Customer
| ID Attribute Name (not applicable)
| ID Attribute Value (not applicable)
|

| Table 53 shows the element properties.

| Table 53. Video customer example with XML: element properties
| Element name XML Name
| Address Address
| Borrowed Borrowed
| Name Name
| Title Title
| FirstName FirstName
| HouseNo HouseNo
| Street Street
| Town Town
| PassportNo PassportNo
| DrivingLicneseNo DrivingLicenseNo
| CreditCardNo CreditCardNo
| VideoTitle VideoTitle
| DueDate DueDate
| Cost Cost

Chapter 6. Working with an XML Format layer 127

 Modeling the Video customer message using XML
| Table 53. Video customer example with XML: element properties (continued)
| Element name XML Name
| Magazine Magazine
|

| Table 54 shows the type member properties. The additional two properties
| displayed for each type member, Member ID Attribute Name, Member ID Attribute
| Value, and Member Value Attribute Name, are all not applicable for this example.
| Table 54. Video customer example with XML: type member properties
| Child element name Member Render property Member XML Name property
| Title XMLElement Title
| FirstName XMLElement FirstName
| HouseNo XMLElement HouseNo
| Street XMLElement Street
| Town XMLElement Town
| VideoTitle XMLElement VideoTitle
| DueDate XMLElement DueDate
| Cost XMLElement Cost
| PassportNo XMLElement PassportNo
| DrivingLicenseNo XMLElement DrivingLicenseNo
| CreditCardNo XMLElement CreditCardNo
|

| Other XML rendering options

| There are many combinations of the ways in which elements and attributes can be
| rendered. For example, if you decide that you want to render the title of the video
| that the customer has borrowed as an attribute of the Borrowed element, the
| extract of the message now appears like this:
| <Borrowed Name="Shrek">
| <DueDate>20020430</DueDate>
| <Cost>3.00</Cost>
| </Borrowed>

| Table 55 shows the updates you must make to the type member properties to
| achieve this.
| Table 55. Video customer example with XML: updated type member properties
| Child element name Member Render property Member XML Name property
| VideoTitle XMLAttribute Name
|

| You can mix the rendering within a type: for example, you can have one child
| rendered as an element and another as an attribute. The following are all valid
| representations of the Name field, where the Name is Bloggs, Title is Mr and First
| Name is Fred:
| <Name>Bloggs<Title>Mr</Title><FirstName>Fred</FirstName></Name>
|
| <Name="Bloggs"<Title="Mr"/><FirstName="Fred"/>/>
|
| <Name>Bloggs<Title id="Mr"/><FirstName="Fred"/></Name>

128 WebSphere MQ Integrator Working with Messages

 Modeling the Video customer message using XML
| To control rendering for this element, check out the parent compound type
| (NameType in this example). Select the element within the compound type (Name,
| Title, or FirstName) and update the Member properties on the XML tab:
| v To render Name, Title, and FirstName as XML elements (the first example
| <Name>Bloggs<Title>Mr</Title><FirstName>Fred</FirstName></Name>), set the
| following properties:
| Table 56. Video customer example with XML: using XMLElement rendering
| Child element name Member Render Member XML Name
| Name XMLElement Name
| Title XMLElement Title
| FirstName XMLElement FirstName
|
| v To render Name, Title, and FirstName as XML attributes (the second example
| <Name="Bloggs"<Title="Mr"/><FirstName="Fred"/>/>), set the following
| properties:
| Table 57. Video customer example with XML: using XMLAttribute rendering
| Child element name Member Render Member XML Name
| Name XMLAttribute Name
| Title XMLAttribute Title
| FirstName XMLAttribute FirstName
|
| v To render Title as an element whose identity is determined by an attribute (id
| in the third example <Name>Bloggs<Title
| id="Mr"/><FirstName="Fred"/></Name>), set the following:
| Table 58. Video customer example with XML: using attribute names and values
| Member Render Member XML Name Member ID Member ID
| Attribute Name Attribute Value
| XMLAttribute Title id Mr
|
|

Chapter 6. Working with an XML Format layer 129

Modeling the Video customer message using XML

130 WebSphere MQ Integrator Working with Messages

|

| Chapter 7. Working with Tagged Delimited String messages

| The Tagged Delimited String (TDS) wire format is designed to model messages
| that consist of text strings. Examples of TDS messages are those that conform to
| the ACORD AL3, EDIFACT, SWIFT, and X12 standards. The TDS wire format
| allows a high degree of flexibility when defining message formats, and is not
| restricted to modeling specific industry standards. You can therefore use the TDS
| format to model your own messages.

| You can add more than one TDS wire format to a single message set. This enables
| you to transform messages from one tagged/delimited format to another.

| The following sections explain the TDS format in more detail, describe the values
| that you can set in the Control Center for the TDS wire format, and give an
| example of how the format can be used to model a message:
| v “TDS message characteristics”
| v “Setting properties for TDS wire format” on page 135
| v “Null handling with the TDS wire format” on page 144
| v “Multipart messages with the TDS wire format” on page 145
| v “Data conversion with TDS” on page 146
| v “Rules for TDS wire format properties” on page 146
| v “The relationship between the logical model and the TDS wire format” on
| page 149
| v “Industry standard formats” on page 150
| v “Example: modeling the Video customer message using TDS” on page 154
|
| TDS message characteristics
| There are a number of features of text string messages that are common across
| many formats. The following sections give an overview of the main features that
| are supported by the TDS wire format:
| v The text strings in the message can have a tag or a label preceding the data
| value. The tag is a string that uniquely identifies the data value. The TDS format
| allows you to associate a tag with each element when you define the element in
| the Control Center.
| v The message can contain various special characters or strings in addition to the
| tags and text string data values. The TDS format supports a number of different
| types of special characters or strings. Some messages have a special character or
| string that separates each data value from the next. In the TDS format this is a
| known as a delimiter. In formats that have a tag before each data value, the tag
| can be separated from its data value by a special character or string. In the TDS
| format this is known as a Tag Data Separator.
| v A message can be split into a number of substructures in a similar manner to a
| to COBOL or C structure. You can model each of these substructures separately
| by defining compound types or elements for each one. Compound types and
| elements are described in Chapter 4, “The MRM logical message model” on
| page 35. A substructure can have a special character or string that indicates its
| start within the data. This is known in the TDS format as a Group Indicator. A
| substructure can also have a special character or string that indicates its end in
| the data. In the TDS format this is known as a Group Terminator. A Group

© Copyright IBM Corp. 2000, 2002 131

 TDS message characteristics
Indicator and Group Terminator can also be defined for the whole message.
Group Indicators and Group Terminators are optional for the message and each
substructure.
v Some text strings within a message can be of fixed length, so it is not necessary
for a delimiter between each data value. This is supported by the TDS format.
The way that the text strings in the message are separated from one another is
known in the TDS format as the Data Element Separation.
v The substructures within a message can use different types of Data Element
Separation and use different special characters. Therefore the TDS format allows
the user to define different types of Data Element Separation and special
| characters for each compound type within the message.

| A small example data message is shown in Figure 23 with each of its components
| labelled:
| v At the top level, each data value has a tag associated with it, each tag is
| separated from its data value using a Tag Data Separator of colon (:), and the
| data values are separated from each other using the delimiter asterisk (*).
| v The Group Indicator for the message is the left brace ({) and the Group
| Terminator is the right brace(}).
| v The data values Data2 and Data3 are in a substructure in which there are no
| tags, and each data element is separated from the next using the delimiter plus
| (+). The Group Indicator for this substructure is the left bracket ([) and the
| Group Terminator is the right bracket (]).
| v The data values Data4 and Data5 are in a substructure in which the values are
| fixed length, and are therefore not separated by a delimiter. The Group Indicator
| for this substructure is the less than symbol (<) and the Group Terminator is the
| greater than symbol (>).
|
|
Delimiter Delimiter Delimiter
Tag Data Tag Data Tag Data
Separator Separator Separator
Tag Tag Tag

{Tag1:Data1*Tag2:[Data2+Data3]*Tag3:<Data4Data5>}

Group Group
Terminator Terminator
Group Group Group
Indicator Indicator Indicator
|
| Figure 23. Tags and special characters in a TDS message

| The following sections describe Data Element Separation and the special characters
| in more detail:
| v “Specifying data element separation methods to model a message” on page 133
| v “Specifying special characters to model a message” on page 134
|

132 WebSphere MQ Integrator Working with Messages

 Data element separation
| Specifying data element separation methods to model a
| message
| Elements of data in a TDS message are identified according to the data element
| separation method that you must specify for the Data Element Separation property
| for a compound type. Depending on the value that you have set for Data Element
| Separation, the properties Tag Data Separator and Delimiter (that you can set for a
| message set and a compound type) might also be required to identify each
| element.

| The methods that you can specify for each compound type are described below.
| The examples given are all based on a compound type that contains three elements
| of type STRING. The Tag Data Separator, where used, is the colon (:), and the
| Delimiter, where used, is the asterisk (*).
| Tagged Delimited
| Each data value is preceded by a tag that is specified in as an element
| property. If the tag is specified as fixed length, each data value follows
| immediately after the tag. If the tag is not specified as fixed length the tag
| is separated from the next element by a tag data separator. Each data value
| is separated from the next by a delimiter. There is no delimiter after the
| last element in the compound type.
| The following example shows tags of fixed length:
| tag1data1*tag2data2*tag3data3

| The following example shows tags of variable length:

| tag1:data1*tag11:data2*tag111:data3
| Tagged Fixed Length
| This method is the same as Tagged Delimited, except that the data values
| are always fixed length. Therefore, no delimiter is required after each data
| value.
| The following example shows tags of fixed length:
| tag1data1tag2data2tag3data3

| The following example shows tags of variable length:

| tag1:data1tag11:data2tag111:data3
| All Elements Delimited
| The data values have no tag, but each data value is separated from the
| next by a delimiter.
| The following example shows this:
| data1*data2*data3
| Variable Elements Delimited
| If a data element is fixed length, the next data value follows immediately
| after it. If the data element is variable length, the next data value is
| separated from it by the delimiter. There are no tags.
| The following example shows element 2 as fixed length, and elements 1
| and 3 as variable length:
| data1*data2data3

Chapter 7. Working with Tagged Delimited String messages 133

 Data element separation
| Fixed Length
| All elements are fixed length, and each data value immediately follows the
| next with no delimiter. There are no tags.
| The following example shows this:
| data1data2data3
| Fixed Length AL3
| This method is the same as Fixed Length, but it also notifies the parser to
| implement a number of rules in relation to missing elements, length
| encoding, and versioning that are predefined in the ACORD AL3 standard.
| Undefined
| This value is set automatically when you set the Type Composition property
| of a compound type to Message, and you cannot set it to any other value.
| You are also unable to set values for the TDS Type properties Group
| Indicator, Group Terminator, Tag Data Separator, Tag Length, and Delimiter.
| You cannot select Undefined if you have not set the Type Composition
| property to Message.
| For more information about Type Composition set to Message, see “Multipart
| messages with the TDS wire format” on page 145.

| Specifying special characters to model a message

| You can specify a number of different types of special character in the Control
| Center. You can specify special character values for message sets, types, and type
| members. The values that you set for a type override the corresponding values set
| for the message set in which it is defined.

| You can specify a special character value in one of the following ways:
| 1. As a literal string of one or more characters.
| 2. As a mnemonic value.
| 3. As a combination of both mnemonics and literals.

| The types of special character are described in Table 59.

| Table 59. TDS: delimiter types
| Special character Description Where set
| type
| Group Indicator This is a string that indicates the start of Message set, type
| a group or compound type within a
| message
| Group Terminator This is a string that indicates that the end Message set, type
| of a group or compound type within a
| message
| Tag Data Separator This is the string that is used to separate Message set, type
| a tag from its data.
| Delimiter This is the string used to separate data Message set, type
| elements from one another
| Repeating Element This is the string used to separate Type member
| Delimiter repeating data elements from one
| another
|

134 WebSphere MQ Integrator Working with Messages

 Special characters
| Therefore, if you create a compound type and set Data Element Separation property
| to Tagged Delimited, the Group Indicator property to left brace ({) , the Group
| Terminator to right brace (}), the Tag Data Separator to colon (:), and the Delimiter to
| asterisk (*), the bit stream has the following format:
| {tag1:data1*tag2:data2*tag3:data3}

| In some message formats, a special character is specified before each element or

| after each element, as shown in the following two examples:
| :data1:data2:data3
|
| data1:data2:data3:

| You can model these formats by using a combination of the Data Element Separation
| method, the Delimiter value, the Group Indicator value, and the Group Terminator
| value.

| For the first example, specify Data Element Separation as All Elements Delimited,
| Delimiter as colon (:), and Group Indicator as colon (:).

| For the second example, specify Data Element Separation as All Elements
| Delimited, Delimiter as colon (:), and Group Terminator as colon (:).

| Using mnemonics as special characters

| A mnemonic value is a value that is contained between the characters < and >. The
| broker translates the mnemonic value to obtain the actual value of the special
| character. In some cases, the mapping from mnemonic to actual value is static.
| Some of the mnemonics are specific to a message standard. These mappings have
| default values, but the defaults can be overridden by a service string specified in
| the message when it is parsed.

| In addition to special characters, mnemonics can also be used in the message set
| Decimal Point, Escape Character, and Reserved Characters properties.

| Mnemonics can be specified in one of two ways:

| 1. <Mnemonic_Name> where Mnemonic_Name can comprise alphanumeric characters
| and underscore (_) characters.
| 2. <U+xxxx> where xxxx are hexadecimal numbers. The delimiter is interpreted as
| the Unicode character that corresponds to the hexadecimal value.

| For more details about the supported mnemonics, see Appendix B, “TDS
| Mnemonics” on page 251.
|
| Setting properties for TDS wire format
| The following sections describe the properties that you can set in the Control
| Center for the TDS wire format at each level within the MRM model to control the
| characteristics of the object. The values that you set for the message set are used as
| the default values for the corresponding properties for the compound type.
| v “Message set properties” on page 136
| v “Message properties” on page 138
| v “Type properties” on page 138
| v “Type member properties” on page 141
| v “Element properties” on page 141

Chapter 7. Working with Tagged Delimited String messages 135

 Message set properties
| Message set properties
| Table 60 shows the message set properties that you can set for the TDS layer.
| Appendix D, “Default TDS message set properties” on page 259 shows the defaults
| for each of the industry standards for each of these properties.
| Table 60. TDS: message set properties
| Property Name Type Meaning
| TDS Wire Format STRING Specify the identifier that the broker uses to recognize this TDS format.
| Identifier This is the value that must be used as the format on the input node or
| in the MQRFH2 header.

| The property must have a non-empty value. It must start with a letter
| or an underscore (_), followed by alphanumeric characters, underscore
| (_) period (.), or hyphen (–).

| You cannot change this property if the message set is based on an

| existing message set.

| The wire format identifier is not the same as the name of the wire
| format layer (although you could define it to have the same value).
| When you create a wire format layer, you must enter a name, and this
| value is used for display purposes only in the Control Center to
| identify the tab on which the wire format layer properties are
| displayed. In all references outside the Control Center (for example, in
| the MQRFH2 header of a message) the wire format identifier must be
| used, not the name.
| Messaging Standard Enumerated Specify the standard to be used for this wire format layer. Select one of
| Type the following values from the drop-down list:
| ACORD AL3
| EDIFACT
| SWIFT
| UNKNOWN
| X12

| Select UNKNOWN if you are defining your own tagged/delimited

| messages, or are using an standard not included in the list above.

| The value selected controls the default values for a number of the other
| properties.
| Default CCSID INTEGER CCSID (Coded Character Set Identification) specifies the mapping
| between character codes and symbols. You must specify a code set that
| is supported by WebSphere MQ Integrator (defined in the WebSphere
| MQ Integrator Administration Guide).

| This property stores the default CCSID for the message bit stream, but
| this value can be overridden when the message is processed.

136 WebSphere MQ Integrator Working with Messages

 Message set properties
| Table 60. TDS: message set properties (continued)
| Property Name Type Meaning
| Trim Fix Len String Enumerated Specify if fixed length strings must be trimmed. You can select from:
| Type No Trim
| Leading White Spaces
| Trailing White Spaces
| Trim Both
| Trim Padding Chars

| The trim of padding characters occurs from the left or right depending
| on the Justification property for the element.

| You might need to use this if you have data input that is mapped to a
| numeric simple type. For example, if the input data has leading spaces,
| you can set this property to Leading White Spaces to avoid data
| conversion problems processing these fields.
| Group Indicator STRING Specify the value of a special character or string that precedes the data
| belonging to a group or compound type within the bit stream.

| If you set the type property Group Indicator, it overrides this value.
| Group Terminator STRING Specify the value of a special character or string that terminates data
| belonging to a group or a compound type within the bit stream.

| If you set the type property Group Terminator, it overrides this value.
| Tag Data Separator STRING Specify the value of a special character or string that separates the Tag
| from the data. The Tag Data Separator and Tag Length properties are
| mutually exclusive.

| If you set the type property Tag Data Separator, it overrides this value.
| Tag Length INTEGER Specify the length of a tag value. When the message is parsed, this
| allows tags to be extracted from the bit stream if the Tag Data Separator
| property is not set.

| The Tag Data Separator and Tag Length properties are mutually exclusive.
| If you set the type property Tag Data Separator, it overrides this value.
| Delimiter STRING Specify the value of a special character or string that specifies the
| delimiter used between data elements.

| If you set a value for this property for the type, it overrides this value.
| Decimal Point STRING Specify the character that is used to separate the whole part of a
| number from its fraction.
| Escape Character STRING Specify the escape character that is used to allow special reserved
| characters (such as delimiters) to be included as part of data.
| Reserved Chars STRING Specify the special reserved characters that must be preceded by the
| escape character if they are to be included as part of the data.

| The Escape Character itself is usually also included in this list. If the set
| of reserved characters is to be updated dynamically (in the case of
| EDIFACT and X12 when delimiters and so on are specified in service
| strings), this list of reserved characters must be specified by the
| mnemonics supplied.

| If you have specified reserved characters, an Escape Character must also

| be specified.

Chapter 7. Working with Tagged Delimited String messages 137

 Message set properties
| Table 60. TDS: message set properties (continued)
| Property Name Type Meaning
| Output Compression Enumerated Select from the enumerated list of possible types of output compression.
| Technique Type These are hardcoded rules specific to the particular type of messaging
| standard that you have selected.

| Select either None or SimpleAL3CharCompression from the drop-down

| list.

| This property is not relevant for EDIFACT, SWIFT, or X12. If the

| Messaging Standard property is set to one of these, this property is
| grayed out; you cannot set a value.
| Input Compression Enumerated Select from the enumerated list of possible types of input compression.
| Technique Type These are hardcoded rules specific to the particular type of messaging
| standard that you have selected.

| Select either None or SimpleAL3CharCompression from the drop-down

| list.

| This property is not relevant for EDIFACT, SWIFT, or X12. If the

| Messaging Standard property is set to one of these, this property is
| grayed out and you are unable to set a value
| Boolean True STRING Specify the value of the string representing the boolean true value.
| Representation
| Boolean False STRING Specify the value of the string representing the boolean false value.
| Representation
| Boolean Null STRING Specify the value of the string representing the boolean null value.
| Representation
|

| Message properties
| Table 61. TDS: message properties
| Property Type Meaning
| Message Key STRING Specify a unique value that identifies the message in the bit stream. This
| property is required if the message is embedded within another message.
| For further information, see “Multipart messages with the TDS wire format”
| on page 145.
|

| Type properties
| Table 62. TDS: type properties
| Property Type Meaning
| Group Indicator STRING Specify the value of a special character or string that precedes the data
| belonging to a group or compound type within the bit stream.

| This property inherits, as default, the property value that you set for
| the message set. This is only valid if the type is a structure and not a
| simple type.

138 WebSphere MQ Integrator Working with Messages

 Type properties
| Table 62. TDS: type properties (continued)
| Property Type Meaning
| Group Terminator STRING Specify the value of a special character or string that terminates the
| data item identified by the Group Indicator. If this property is set to a
| non-NULL value, it overrides the Group Terminator property set for the
| message set.

| This property inherits, as default, the property value that you set for
| the message set.

| This is only valid if the type is a structure and not a simple type.
| Tag Data Separator STRING Specify the value of a special character or string that separates the Tag
| from the data. If this property is set to a non NULL value, it overrides
| the Tag Data Separator property that you set for the message set.

| This property inherits, as default, the property value that you set for
| the message set.

| This is only valid if the type is a structure and not a simple type.
| Tag Length INTEGER If you specify a nonzero value, it overrides the corresponding message
| set property value. The Tag Length and Tag Data Separator properties for
| Type are mutually exclusive, and therefore you can specify a
| non-empty value for only one of these properties.

| This property inherits, as default, the property value that you set for
| the message set.

| This is only valid if the type is a structure and not a simple type.

Chapter 7. Working with Tagged Delimited String messages 139

 Type properties
| Table 62. TDS: type properties (continued)
| Property Type Meaning
| Data Element Enumerated Type Specify the method used to separate the data elements within the type.
| Separation* Select one of the following values:
| v Tagged Delimited. This value indicates that all elements within the
| compound type are separated by the value specified in the Delimiter
| property. Each data element is identified by a tag. If you set this
| property to Tagged Delimited, you must set the Tag property for all
| child elements, and you must set the Delimiter property to a
| non-empty value. See Table 64 on page 141.
| v Tagged Fixed Length. This data element separation is equivalent to
| Fixed Length, but you must supply a Tag name for each of the child
| elements of this compound type. The same validation rules apply as
| for separation technique equal to Fixed Length, that is each child
| element must have a Length or Length Value Of property assigned to
| it.
| v All Elements Delimited. This value indicates that all elements
| within the compound type are separated by the value specified in
| the Delimiter property.
| v Variable Elements Delimited. This value indicates that some of the
| elements within the compound type might be of variable length: if
| they are, they must be delimited by the value specified in the
| Delimiter property.
| v Fixed Length. This value indicates that all elements within the
| compound type are fixed length. The next data element is accessed
| by adding the value of the Length property to the offset (see
| Table 64 on page 141). If you set the Data Element Separation property
| of a compound type to Fixed Length, you must also set the Data
| Element Separation property of all compound children of this type to
| Fixed Length.
| v Fixed Length AL3. This value has a similar meaning to the
| separation type Fixed Length, but also indicates to the parser that a
| number of predefined rules with regard to missing optional
| elements, encoded lengths, and versioning must be applied. If you
| set the Data Element Separation property of a compound type to
| Fixed Length AL3, you must also set the Data Element Separation
| property of all compound children of this type to Fixed Length AL3.
| v Undefined. Select this to define your own tagged/delimited formats.
| If you set the Type Composition property of a compound type to
| Message, this value is set automatically and you cannot change it to
| any other value.
| Delimiter STRING Specifies the special character or string that defines the delimiter used
| between data elements. This property must be set if the Data Element
| Separation property is set to either Variable Elements Delimited, All
| Elements Delimited, or Tagged Delimited This property inherits, as
| default, the property value that you set for the message set. It is only
| valid if the type is a compound type, not a simple type.
|

140 WebSphere MQ Integrator Working with Messages

 Type member properties
| Type member properties
| Table 63. TDS: type member properties
| Property Type Meaning
| Repeating Element STRING Specify the delimiter to be used between repeating elements. This
| Delimiter property is only applicable if the Repeat property is set to Yes and the
| Data Element Separation property for the type is set to All Elements
| Delimited or Variable Elements Delimited.
| Length Value Of STRING Specify the identifier of a sibling INTEGER element, the value of which
| dictates the length of the element in question. The sibling element must
| be defined before the current element within the message structure.

| This property is applicable for simple elements, excluding INTEGER.

| You must set a value if a length is required, and the Length property
| has a value of 0. You must specify a length if the Data Element
| Separation property is set to Fixed Length.
|

| Element properties
| Table 64 describes all possible properties that can be specified for an element.
| However, not all the properties are applicable to every type of element. Table 65 on
| page 144 shows which properties are displayed for each element type.
| Table 64. TDS: element properties
| Property Type Meaning
| Tag STRING Specify the Tag Value used to identify the element in a message bit stream If
| the element is simple and the Data Element Separation property of the
| compound type or types in which the element is a child is Tagged Delimited
| or Tagged Fixed Length, this property must contain a non-empty value.

| If the element is of a compound type, the property can contain an empty

| value if the Data Element Separation property of its parent is Tagged Delimited
| or Tagged Fixed Length.

| The value for this property must be unique for every element in the message
| set, that is, no two elements in the message set can contain the same value for
| this property.
| Length INTEGER Specify the expected length of the element in characters (except in the case of
| binary elements in which case the length value represents the length in bytes).

| This property applies to simple elements and to compound elements with a

| base type

| If this property has a value of 0, the Length Value Of property is checked for a
| value.

| If the Data Element Separator property for the type (defined in Table 62 on
| page 138) is set to Fixed Length or Fixed Length AL3, either this property (or
| the Length Value of property) must contain a non 0 (or non NULL) value.

| Regardless of the value of the Data Element Separation property, if the type of
| the simple element is BINARY, either the Length or Length Value Of property
| must be set.

Chapter 7. Working with Tagged Delimited String messages 141

 Element properties
| Table 64. TDS: element properties (continued)
| Property Type Meaning
| Justification Enumerated Specify the justification of the element where the data being written or parsed
| Type is less than the fixed length value. This property is only used when a value is
| output as a fixed length string.

| Select one of the following values from the drop-down list:

| Not Applicable
| Left Justify
| Right Justify
| Padding CHAR Specify the padding character to be inserted or interpreted on the writing or
| Character parsing of a fixed length element where the data is less than the fixed length
| value.

| This property is only used when a value is output as a fixed length string.
| Interpret Element Enumerated Specify if values stored within this element must be interpreted as having
| Value Type significance for the parser and, if so, the type of interpretation that must
| occur. This interpretation is generally standard specific and is therefore hard
| coded.

| The possible values for this property are:

| None (the default value)
| EDIFACT Service String
| X12 Service String
| Message Key
| Virtual Decimal INTEGER Specify a number representing the position of an implied decimal point
| Point within a number.

| If the VDP is a positive number, then the position of the decimal point is
| counted back from the right hand side of the number. For example, 1234,
| VDP=3 represents 1.234.

| If the VDP is negative, the decimal point is placed VDP number of places
| after the end of the number. For example, 1234, VDP = -3 represents 1234000.

| If the VDP is 0, the precision property is checked for the formatting of the
| FLOAT or DECIMAL element.
| Precision INTEGER Specify the number of digits that follow the decimal point.

| If the precision is 0, when the FLOAT or DECIMAL is written to the bit

| stream, data is truncated so that the decimal part is lost. For example, if the
| value stored in the tree is 123.45, and Precision is 0, the value written to the
| bit stream is 123. Similarly, if Precision is less than the number of digits
| following the decimal point, data is truncated. For example, 123.4567 with
| Precision set to 2 results in 123.45 written to the bit stream.

| If Precision is greater than the number of digits following the decimal point,
| the FLOAT or DECIMAL is padded with additional zero digits after the
| decimal point. For example, for Number = 12.345 and Precision set to 5,
| Number becomes 12.34500 on output.

| If Precision is set to the mnemonic All Significant Digits (-1), all significant
| digits after the decimal point are written to the output bit stream.
| Format STRING Specify the format of the element. If the logical type of the element is
| DATETIME, this property can be set according to the standard described in
| the DATETIME section, for example, dd-MMM-yyyy.

| For further details on DATETIME formats, see Appendix C, “DATETIME

| formats” on page 253.

142 WebSphere MQ Integrator Working with Messages

 Element properties
| Table 64. TDS: element properties (continued)
| Property Type Meaning
| Sign Orientation Enumerated Select the value that indicates the positioning of a sign symbol within a
| Type numeric value, from the drop-down list:
| v None
| v Leading
| v Trailing

| If the value for this property is set to None, this is interpreted as having no
| sign, and an exception is thrown if a negative number is processed (on either
| input or output).

| If the value for this property is set to Leading, this indicates that the sign is
| positioned ahead of the number, for example, –1234. Similarly, if this property
| is set to Trailing, the sign follows the number, for example, 1234–.

| If there is no explicit sign set, the number is assumed to be positive.

| Positive Sign STRING Specify the value that represents the positive symbol
| Negative Sign STRING Specify the value that represents the negative symbol.
| Encoding Null Enumerated Select one of the following options from the drop-down list. The option that
| Type you select determines the value that you must set for the property Encoding
| Null Value:
| v NULLPadFill. This is only valid if Physical Type is Fixed Length String. The
| field is filled with the value specified by the Padding Character. This is the
| default value.
| v NULLLogicalValue. The Encoding Null Value property is first converted to an
| actual value, and rendered in the way specified for the field.
| v NULLLiteralValue. This specifies that Encoding Null Value contains a value
| that is directly substituted as if it is a string. Use this option if you want to
| use the Encoding Null Value to test or compare the content of the field in the
| message.

| For information about these options, see “Null handling with the TDS wire
| format” on page 144.
| Encoding Null STRING If you set the Encoding Null property to NULLPadFill, this property is disabled.
| Value
| If you set the Encoding Null property to NULLLogicalValue, you must set this
| property to an ISO8601 datetime format. These formats are described in note
| 6 on page 255 in “DATETIME as STRING data” on page 253. For example,
| specify a value conforming to yyyy-MM-dd’T’HH:mm:ss such as 1970-12-01.

| If you set the Encoding Null property to NULLLiteralValue, you must set this
| property to a value that conforms to the pattern that you have set in the
| propertyFormat. If you have set Physical Type to Fixed Length String, the
| value that you specify for this property must be of the same length as the
| field.
|
| Table 65 on page 144 outlines which of the element level properties are present for
| an element, depending on the logical type of the simple element, or, in the case of
| a compound element with a base type associated with it, depending on the logical
| type of the base type. In the case of an embedded simple type, or an embedded
| compound type with a base type associated with it, the presence or absence of
| these properties is applicable to the type member table.

Chapter 7. Working with Tagged Delimited String messages 143

 Element properties
| Table 65. TDS: element types and properties
| Element Property BINARY BOOLEAN DATETIME DECIMAL FLOAT INTEGER STRING
| Tag Present Present Present Present Present Present Present
| Length Present Not present Present Present Present Present Present
| Justification Not present Not present Present Present Present Present Present
| Padding Character Not present Not present Present Present Present Present Present
| Interpret Element Value Not present Not present Not present Not present Not Not Present
| present present
| Virtual Decimal Point Not present Not present Not present Present Present Present Not
| present
| Precision Not present Not present Not present Present Present Present Not
| present
| Format Not present Not present Present Not present Not Not Not
| present present present
| Sign Orientation Not present Not present Not present Present Present Present Not
| present
| Positive Sign Not present Not present Not present Present Present Present Not
| present
| Negative Sign Not present Not present Not present Present Present Present Not
| present
| Encoding Null Present Not present Present Present Present Present Present
| Encoding Null Value Present Not present Present Present Present Present Present
|
|
| Null handling with the TDS wire format
| TDS supports handling of null values within messages. The rules for whether nulls
| are permitted are described in “Null handling” on page 64. You can use the
| message set property Boolean Null Representation to specify the value to be used for
| Boolean Null representation. You can use the element properties Encoding Null and
| Encoding Null Value to control how null handling is represented for individual
| elements.

| You can select the Encoding Null property from the three enumerated values
| NULLPadFill, NULLLogicalValue, and NULLLiteralValue:
| v You can use the NULLPadFill option only for fixed length elements. If you select
| this option, the element is filled with the value specified by the Padding Character
| property. If you select this option, the Encoding Null Value property is disabled.
| v If you select the NULLLogicalValue option, the value entered for the Encoding
| Null Value property is converted to its logical value. For writing, the logical
| value is written in the same way as any other value. For parsing, the converted
| logical value is compared against the converted message data.
| v If you select the NULLLiteralValue option, the value entered for the Encoding
| Null Value property is directly substituted as if it were a string value. For fixed
| length elements, the literal value must be of the same length as the element. The
| value is case insensitive.

| The use of the Encoding Null Value property is dependent on the value that you
| select for the Encoding Null property described above. NULL values are not defined
| for BINARY types. The properties Encoding Null and Encoding Null Value are
| therefore not set for BINARY types.

144 WebSphere MQ Integrator Working with Messages

 Multipart messages with TDS
|
| Multipart messages with the TDS wire format
| If you want, you can embed a message within another message to create a
| multipart message. An instance of where this is useful is when a message has the
| following type of format:
|
|
Message

Message Header

Message Key

Message Body

Message Trailer
|
| Figure 24. TDS and multipart messages
|
| In this type of format, you can consider the Message Header and Message Trailer
| as an envelope for the message body. The Message Header and Message Trailer
| have a fixed format, but you can define the Message Body with different formats.

| The TDS format allows you to define an envelope Message containing the Message
| Header and Message Trailer definitions that includes a placeholder where the
| Message Body is to be defined. You can create this placeholder by inserting a
| compound type or compound element, with the Type Composition property set to
| Message, at the location where the Message Body is to be placed within the
| envelope Message definition. You must define each of the individual Message
| Bodies as separate Messages. You must define all Message Bodies in the same
| Message Set as the Envelope Message, unless they are self-defining. The wire
| format of the Envelope Message and the Message Bodies must all be TDS.

| An element in the Message Header contains a value that identifies the format of
| the Message Body. The MRM allows you to define an element in the envelope
| Message that has the element property Interpret Element Value set to Message Key.
| This element must be of type STRING. This element is used when the message is
| processed in the broker to locate the correct definition for the Message Body.
| Therefore the element in the Message Header that identifies the format of the
| message body must have its element property Interpret Element Value set to Message
| Key. This element must always precede the place in the envelope Message at which
| the Message Body is to be inserted.

| To allow the correct Message Body to be located when a message is processed by

| the broker, you must define each of the Messages that can be present as the
| Message Body with the message property Message Key set to a unique value. The
| value of the element in the envelope message that has the Interpret Element Value
| property set to Message Key must match a value that you have set in one of
| Message Key properties for the Message Body.

| For example, assume you have defined a message that has property Message Key
| set to 100. If this is the message body that is included in the whole message when
| it is received by the broker, the element in the envelope message that has the
| property Interpret Element Value set to Message Key must have its value set to 100.

Chapter 7. Working with Tagged Delimited String messages 145

 Data conversion with TDS
|
| Data conversion with TDS
| All TDS message data is handled as strings. All data is therefore subject to CCSID
| conversion only. This includes the special characters used as delimiters, data
| separators, and so on.
|
| Rules for TDS wire format properties
| When you use the TDS wire format, you must conform to a number of rules that
| apply to the setting of values of properties. These rules that are checked at deploy
| time, not at check in time. If an inconsistency is found, error BIP1836E is displayed
| in the Control Center. Details of the error are written into file TDS.log in the
| <install_dir>/log directory on the Configuration Manager’s system. An example
| of the log generated is shown in Appendix E, “TDS error report” on page 261.

| General rules
| This section describes the general rules for each value that you can set for the Data
| Element Separation property of a type.
| Tagged Delimited
| v The Tag property for each and every simple child element must contain
| a non-empty value
| v The Delimiter property must contain a non-empty value
| Variable Elements Delimited
| The Delimiter property must contain a non-empty value.
| All Elements Delimited
| The Delimiter property must contain a non-empty value.
| Fixed Length
| All compound child elements with a non-boolean base type and
| non-boolean simple child elements must have either a nonzero value in
| their Length property, or a non-empty value for their Length Value Of type
| member property.
| Fixed Length AL3
| All compound child elements with a non-boolean base type and
| non-boolean simple child elements must have either a nonzero value in
| their Length property, or a non-empty value for their Length Value Of type
| member property.
| Tagged Fixed
| v All compound child elements with a non-boolean base type and
| non-boolean simple child elements must have either a nonzero value in
| their Length property or a non-empty value for their Length Value Of type
| member property.
| v The Tag property for each and every simple child element must contain
| a non-empty value.

146 WebSphere MQ Integrator Working with Messages

 General rules
| The following rules also apply:
| v If you have set the type’s Data Element Separation property to Fixed Length,
| Fixed Length AL3, or Tagged Fixed, you must set either the Length or Length
| Value Of property for all simple elements under this parent, and you must set
| the Length property for all compound elements under this parent that contain a
| base type.
| v Elements specified in a Length Value Of property must be simple elements of
| type INTEGER, they must exist in the same structure as the referring element,
| and they must appear before the referring element in that structure.
| v Compound elements with a base type must have an empty Length Value Of type
| member property. This is because the Length Value Of element would occur after
| the referring element in the parent structure, which is disallowed by the
| previous rule.
| v Regardless of the setting of the type’s Data Element Separation property, if the
| type of a simple element is BINARY, you must set either the Length or Length
| Value Of property.
| v For fixed length elements, the Justification property must be set to something
| other than Not Applicable, and the Padding Character property cannot be an
| empty value.
| v If any element within a message has its Interpret Element Value property set to
| Message Key, the Message Key property must be set for all messages within the
| message set.
| v If you have set the Repeat property in the type member Connection tab to Yes,
| you must set a value for the Max Occurs property in the following two
| situations:
| – If you have defined an element as a member of a compound type that has the
| property Data Element Separation set to Fixed Length
| – If you have defined a fixed length element as a member of a compound type
| that has the property Data Element Separation set to Variable Elements
| Delimited
| When it is invoked by the broker to interpret an input message, the parser
| assumes that the number of occurrences of the element is equal to the value that
| you set for Max Occurs. When the parser constructs an output message, if there
| are less than Max Occurs elements, the missing elements are inserted with
| default values.

| Restrictions for nesting compound types

| If you nest compound types within a message, there are a number of restrictions
| on the values that you can set for the Data Element Separation property for both
| parent and child types. This applies to both compound elements and embedded
| compound types. For example, you cannot set the parent property to Fixed Length
| and the child property to Tagged Delimited, because the length of the Tagged
| Delimited compound element or type would not be known, and would therefore
| conflict with the parent definition. These restrictions are listed in Table 66 on
| page 148. (Parent refers to any parent of a child, not just the immediate parent.)

Chapter 7. Working with Tagged Delimited String messages 147

 Nesting compound types
| Table 66. Permitted options for nested compound types
| Parent (right) Tagged Delimited All Elements Fixed Length Fixed Length Tagged Fixed
| Delimited and AL3 Length
| Child (below) Variable Elements
| Delimited
| Tagged Delimited Allowed Allowed Not allowed Not allowed Not allowed
| All Elements Allowed Allowed Not allowed Not allowed Not allowed
| Delimited,
| Variable Elements
| Delimited
| Fixed Length Allowed Allowed Allowed Allowed Allowed
| Fixed Length AL3 Allowed Allowed Allowed Allowed Allowed
| Tagged Fixed Allowed Allowed Not allowed¹ Not allowed¹ Allowed
| Length
| Note:
| 1. Tagged Fixed cannot exist at the inner level if any outer level has a separation technique of Fixed Length or
| Fixed Length AL3. This is because an item of Tagged Fixed can repeat a variable number of times. Fixed Length
| and Fixed Length AL3 is parsed by moving a set number of bytes: with a variable number of repeats, it is not
| possible to calculate the number of bytes that need to be parsed.
|

| Omission and truncation of elements

| If you have created a message in which some elements are optional, it is possible
| that not all elements appear in an input message. If the elements are in a
| compound type in which the elements are separated by a delimiter and have no
| tag (you have set the Data Element Separation property of the type to All Elements
| Delimited or Variable Elements Delimited), any elements that are missing from
| the end of the compound type must be indicated by the application that creates the
| message in one of two ways:
| 1. If you have set the Delimiter property for the compound type to a value that
| does not match the value that you have set for the Delimiter property for any of
| the compound type’s parent types, the elements at the end of the message can
| be indicated by the occurrence of a Delimiter of one of its parents after the last
| actual element in the compound type data.
| This is known as the truncation method.
| For example, you define a compound element C that has four optional
| elements. You set the Delimiter property to the character plus (+). You define
| compound element P, and set the Delimiter property of P to asterisk (*). You add
| three elements to P, the first is a string, the second is compound element C, and
| the third is a string.
| When a particular instance of the message is received by the broker, all the
| elements of P are present, but only the first two elements of C are present. The
| data in the message appears as follows if the truncation method is used (where
| Pn are the values of the elements of P and Cn the values of the elements of C):
| P1*C1+C2*P3

| When the parser encounters the second asterisk delimiter, it determines that the
| last two elements of compound element C are not present, and the next element
| is the third element of P.
| 2. If the Delimiter of the compound type matches that of one of its parents, the
| truncation method cannot be used. This is because the parser cannot determine
| whether the delimiter after the last element is for the current compound type,

148 WebSphere MQ Integrator Working with Messages

 Omission and truncation
| or for one of its parents. Therefore a delimiter must be included in the message
| data for each missing element to ensure that the parser can match the elements
| with the model.
| This is known as the omission method.
| For example, you define P and C as in the previous example, but set the
| Delimiter property for P to plus (+). When the same message is received by the
| broker (all elements of P are present, the first two elements of C are present),
| the data in the message appears as follows:
| P1+C1+C2+++P3

| Two delimiter characters have been inserted in the message data for the
| missing elements of compound element C. If the truncation method had been
| used, the parser would have interpreted the data value P3 as the value of the
| third element of compound element C and not the third element of compound
| element P.
|
| The relationship between the logical model and the TDS wire format
| There are a number of restrictions on the value that you can set for the Data
| Element Separation property for compound types, and the values that you can set
| for the Type Composition and Type Content defined in the logical model. These
| restrictions are listed in Table 67 and Table 68.
| Table 67. TDS permitted combinations of Type Composition and Data Element Separation
| Composition Tagged Delimited All Elements Fixed Length Fixed Length AL3 Tagged Fixed
| Delimited and
| Variable Elements
| Delimited
| Empty Allowed Allowed Allowed Allowed Allowed
| Choice Allowed Allowed Allowed Allowed Allowed
| Simple Allowed Not allowed Not allowed Not allowed Not allowed
| Unordered Set
| Unordered Set Allowed Not allowed Not allowed Not allowed Allowed
| Ordered Set Allowed Allowed Allowed Allowed Allowed
| Sequence Allowed Allowed Allowed Allowed Allowed
|
| Table 68. TDS permitted values for Type Content
| Composition Tagged Delimited All Elements Fixed Length Fixed Length Tagged Fixed
| Delimited and AL3
| Variable Elements
| Delimited
| Closed Allowed Allowed Allowed Allowed Allowed
| Open Defined Allowed Not allowed Not allowed Not allowed Allowed
| Open Allowed Not allowed Not allowed Not allowed Not allowed
|

Chapter 7. Working with Tagged Delimited String messages 149

 Industry standard formats
|
| Industry standard formats
| WebSphere MQ Integrator supports the ACORD AL3 , EDIFACT, SWIFT, and X12
| standards. The default property values for each of these standards are defined in
| Appendix D, “Default TDS message set properties” on page 259. If you use these
| defaults, or override some of these defaults where necessary, you can model all
| these industry standard formats.

| WebSphere MQ Integrator supplies a number of SupportPacs, including those that

| supply predefined message sets for the SWIFT and EDIFACT standards. For details
| of these and other SupportPacs available, refer to “MQSeries information available
| on the Internet” on page 277.

| More details about each of these industry standards is provided:

| v “ACORD AL3”
| v “EDIFACT” on page 151
| v “SWIFT” on page 153
| v “X12” on page 153

| ACORD AL3
| The basic structure of an ACORD AL3 message is shown in Figure 25.
|
|
ACORD Message

Message Header Group Transaction (1 or More) Message Trailer Group

Transaction Header Group Transaction Control Group ( OPTIONAL) Data Group Segments ( 1 Or More)

|
| Figure 25. ACORD AL3 message basic structure
|
| You can select the value Fixed Length AL3 for the Data Element Separation property
| for compound types within a message that conforms to the ACORD AL3 standard.
| This allows different versions of the ACORD AL3 standard to be supported using
| the same message set. This value is similar to the value Fixed Length except for
| the following:
| 1. A question mark (?) in the left-most position of an element means that it is
| skipped
| 2. A sequence of question marks is inserted for all missing optional elements.
| 3. Any <CR><LF> after the last element is ignored

| The ACORD AL3 standard supports a simple compression technique. This is

| supported in WebSphere MQ Integrator by setting the message set properties Input
| Compression Technique and Output Compression Technique to
| SimpleAL3CharCompression.

150 WebSphere MQ Integrator Working with Messages

 ACORD AL3
| Each group with an ACORD AL3 message has a header consisting of a one digit
| number, three letters, plus a three digit total length count. These first seven
| characters can be modeled as a tag. The data within the headers is fixed length.
| Therefore the header type used for the overall message can be modeled as follows:
| Data Element Separation = Tagged Fixed length
| Tag Length = 7

| The Transaction Group contains other groups, and is therefore modeled in the
| same way as the overall message. The Message Header Group and the Message
| Trailer group just consist of fixed length elements, therefore the type used can be
| modeled as:
| Data Element Separation = Fixed Length

| EDIFACT
| The high level structure of an EDIFACT message is shown in Figure 26.
|
|
Interchange

Service String Advice Interchange Header ` Either Functional OR Interchange Trailer `

UNA UNB Groups Only Messages UNZ

Functional Group Hdr-UNG ` Message Message Functional Group Trailer- UNE `

Message Header - UNH ` Data Segment Data Segment Message Trailer- UNT `

TAG + Simple Data Element + Composite Data Element `

Code : Value Value Component Data Element : Component Data Element

Value Value
|
| Figure 26. EDIFACT message high level structure
|

Chapter 7. Working with Tagged Delimited String messages 151

 EDIFACT
| You can model the top level interchange of an EDIFACT message by setting the
| following properties for the compound type on which the message is based:
| Type Composition = Sequence
| Type Content = Closed
| Tag Data Separator = <EDIFACT_TAGDATA_SEP>
| Data Element Separation = Tagged Delimited
| Delimiter = <EDIFACT_CS>

|
|

|
| Figure 27. EDIFACT message display
|
| The message shown in Figure 27 has the following four children:
| v The embedded compound type Service String advice. Set the type properties as
| follows:
| Type Composition = Sequence
| Type Content = Closed
| Tag Length = 3
| Data Element Separation = Tagged Fixed Length
| v The Interchange Header element. Set the type properties as follows:
| Type Composition = Sequence
| Type Content = Closed
| Group Terminator = <EDIFACT_GROUP_TERM>
| Data Element Separation = All Elements Delimited
| Delimiter = <EDIFACT_DS>
| v The embedded compound type Segment 1. Set the type properties as follows:
| Type Composition = Choice
| Type Content = Closed
| Tag Data Separator = <EDIFACT_TAGDATA_SEP>
| Data Element Separation = Tagged Delimited
| Delimiter = <EDIFACT_CS>
| v The Interchange Trailer element. Set the type properties as follows:
| Type Composition = Sequence
| Type Content = Closed
| Group Terminator = <EDIFACT_GROUP_TERM>
| Data Element Separation = All Elements Delimited
| Delimiter = <EDIFACT_DS>

| Within an EDIFACT message, you can define the delimiters to be used in the
| message itself using the optional Service String Advice element. To enable this
| element to be recognized as an EDIFACT Service String, you must set the element
| property Interpret Element Value to EDIFACT Service String. You must also set the
| delimiter values to the mnemonic values that are defaulted when you set the
| Message Standard property to EDIFACT.

152 WebSphere MQ Integrator Working with Messages

 SWIFT
| SWIFT
| The high level block structure of a SWIFT message is shown in Table 69
| Table 69. SWIFT message high level block structure
| Block name Format
| Basic header {1:...}
| Application header {2:...}
| User header {3:...}
| Text {4:...}
| Trailer {5:...}
|

| When they are concatenated in a message, the blocks appear as:

| {1:...}{2:...}{3:...}{4:...}{5:...}

| You can model this setting the following type properties for the message:
| Data Element Separation = Tagged Delimited
| Group Indicator = {
| Delimiter = }{
| Group Terminator = }
| Tag Data Separator = :

| Each block is modeled as a compound element with element Tag property values
| of 1,2,3,4, and 5 respectively.

| The text body of the message has the following format:

| {4:
| :20:X
| :32A:940930USD1,
| .....
| :72:/A/
| –}

| You can model the compound type of the Text body by setting the following type
| properties:
| Data Element Separation = Tagged Delimited
| Group Indicator = <CR><LF>:
| Delimiter = <CR><LF>:
| Group Terminator = <CR><LF>–
| Tag Data Separator = :

| The Tag property of the elements within the body has values of 20, 32A, 72, and so
| on.

| X12
| If you are working with X12 messages, you can define the delimiters to be used in
| the message itself using the mandatory Interchange Control Header element. To
| enable this element to be recognized as an X12 Service String, you must set the
| element property Interpret Element Value to X12 Service String. You must also set
| the delimiter values to the mnemonic values defaulted by setting the Message
| Standard property to X12.

Chapter 7. Working with Tagged Delimited String messages 153

 Modeling the Video customer message using TDS
|
| Example: modeling the Video customer message using TDS
| Figure 21 on page 78 shows the logical structure of the Video Customer example
| modeled in “Example: modeling the Video customer message” on page 78. The
| following sections show how you can model a message with this content using
| TDS representation.

| A sample of the video customer message with the TDS format that is to be
| modeled is shown below (the data has been split into separate lines for
| readability):
| {Name:[Bloggs*Title:Mr*FirstName:Fred]&
| Address:[HouseNo:12*Street:Willow Avenue*Town:Salisbury]&
| PassportNo:NJ123456TT&
| Borrowed:[Gladiator+22-DEC-2001+3.00]&
| Borrowed:[Harry Potter+23-DEC-2001+3.75]&
| Magazine:1}

| The CustomerType compound type property Data Element Separation is set to

| Tagged Delimited, therefore all the top level elements have tags. The NameType
| and AddressType types also have the Data Element Separation property set to
| Tagged Delimited, therefore their child elements also have tags. However, the
| BorrowedType compound type has the Data Element Separation property set to All
| Elements Delimited. Therefore its child elements have no tags, but each element is
| separated by a delimiter.

| Because the format of the message does not conform to an industry standard, you
| must set the property Messaging Standard to UNKNOWN. All of the delimiters for each
| type are specified explicitly for that type, they are not defaulted from the message
| set properties. The tables in this section, listed below, show the TDS properties that
| have been set for each component to model the message. Within each table, the
| characters n/a indicate that the property is not present for that element.
| v Message set properties, Table 70
| v Message properties, Table 71 on page 155
| v Type properties, Table 72 on page 155
| v Type member properties, Table 73 on page 155
| v Element properties, Table 74 on page 155, Table 75 on page 156, Table 76 on
| page 156, and Table 77 on page 157
| Table 70. Video customer example with TDS: message set properties
| Property Value
| TDS wire format identifier TDS
| Messaging standard UNKNOWN
| Default CCSID 367
| Trim Fix Len String No Trim
| Group Indicator
| Group Terminator
| Tag Data Separator
| Tag Length
| Delimiter
| Decimal Point .
| Escape Character

154 WebSphere MQ Integrator Working with Messages

 Modeling the Video customer message using TDS
| Table 70. Video customer example with TDS: message set properties (continued)
| Property Value
| Reserved Chars
| Output Compression Technique None
| Input Compression Technique None
| Boolean True Representation 1
| Boolean False Representation 0
| Boolean Null Representation 0
|
| Table 71. Video customer example with TDS: message properties
| Property Value
| Message Key
|
| Table 72. Video customer example with TDS: type properties
| Type AddressType BorrowedType CustomerType IdType NameType
| Property
| Group [ [ { [
| Indicator
| Group ] ] } ]
| Terminator
| Tag Data : : : :
| Separator
| Tag Length
| Data Element Tagged All Elements Tagged Tagged Tagged
| Separation Delimited Delimited Delimited Delimited Delimited
| Delimiter * + & & *
|
| Table 73. Video customer example with TDS: type member properties
| Property Value
| Repeating element delimiter There are no values set for any of the type members
| Length Value Of There are no values set for any of the type members
|
| Table 74. Video customer example with TDS: element properties (part 1 of 4)
| Element Name Title FirstName Address
| Property
| Tag Name Title FirstName Address
| Length n/a
| Justification Left Justify Left Justify Left Justify n/a
| Padding Character ’0’ SPACE SPACE n/a
| Interpret Element Value None None None n/a
| Virtual Decimal Point n/a n/a n/a n/a
| Precision n/a n/a n/a n/a
| Format n/a n/a n/a n/a
| Sign Orientation n/a n/a n/a n/a

Chapter 7. Working with Tagged Delimited String messages 155

 Modeling the Video customer message using TDS
| Table 74. Video customer example with TDS: element properties (part 1 of 4) (continued)
| Element Name Title FirstName Address
| Property
| Positive Sign n/a n/a n/a n/a
| Negative Sign n/a n/a n/a n/a
| Encoding Null NULLLogicalValue NULLLogicalValue NULLLogicalValue n/a
| Encoding Null Value n/a
|
| Table 75. Video customer example with TDS: element properties (part 2 of 4)
| Element HouseNo Street Town
| Property
| Tag HouseNo Street Town
| Length
| Justification Right Justify Left Justify Left Justify
| Padding Character ’0’ SPACE SPACE
| Interpret Element Value n/a None None
| Virtual Decimal Point n/a n/a n/a
| Precision All significant digits n/a n/a
| Format n/a n/a n/a
| Sign Orientation None n/a n/a
| Positive Sign n/a n/a
| Negative Sign – n/a n/a
| Encoding Null NULLLogicalValue NULLLogicalValue NULLLogicalValue
| Encoding Null Value
|
| Table 76. Video customer example with TDS: element properties (part 3 of 4)
| Element PassportNo DrivingLicenseNo CreditCardNo Borrowed
| Property
| Tag PassportNo DrivingLicenseNo CreditCardNo Borrowed
| Length n/a
| Justification Left Justify Left Justify Left Justify n/a
| Padding Character SPACE SPACE SPACE n/a
| Interpret Element Value None None None n/a
| Virtual Decimal Point n/a n/a n/a n/a
| Precision n/a n/a n/a n/a
| Format n/a n/a n/a n/a
| Sign Orientation n/a n/a n/a n/a
| Positive Sign n/a n/a n/a n/a
| Negative Sign n/a n/a n/a n/a
| Encoding Null NULLLogicalValue NULLLogicalValue NULLLogicalValue n/a
| Encoding Null Value n/a
|

156 WebSphere MQ Integrator Working with Messages

 Modeling the Video customer message using TDS
| Table 77. Video customer example with TDS: element properties (part 4 of 4)
| Element VideoTitle DueDate Cost Magazine
| Property
| Tag Magazine
| Length n/a
| Justification Left Justify Left Justify Right Justify n/a
| Padding Character SPACE ’0’ ’0’ n/a
| Interpret Element Value None n/a n/a n/a
| Virtual Decimal Point n/a n/a n/a
| Precision n/a n/a All significant digits n/a
| Format n/a dd-MMM-yyyy n/a n/a
| Sign Orientation n/a n/a None n/a
| Positive Sign n/a n/a – n/a
| Negative Sign n/a n/a n/a n/a
| Encoding Null NULLLogicalValue NULLLogicalValue NULLLogicalValue n/a
| Encoding Null Value n/a

Chapter 7. Working with Tagged Delimited String messages 157

Modeling the Video customer message using TDS

158 WebSphere MQ Integrator Working with Messages

 Chapter 8. Working with MRM messages in the Control Center
This chapter provides implementation information for using MRM messages. It
provides instructions on how to use the Control Center to define, modify, and
enhance message sets and their components. It discusses the following topics:
v “Creating message sets and message set components”
v “Working with message sets” on page 169
v “Importing C and COBOL data structures” on page 176
v “Generating information from message sets” on page 178
v “Setting up message flows to handle these messages” on page 182

You are referred to the Control Center online help throughout this chapter: the
help contains reference information for the resources that you define and manage
using the Control Center. For examples, properties of message set, messages, and
so on that have specific values or ranges of values are detailed in the online help.

Creating message sets and message set components

The following sections describe how you can use the Control Center facilities to
create message sets and their components.
v “Creating message sets”
v “Adding wire format layers” on page 161
v “Adding a language binding” on page 162
v “Creating messages” on page 165

Creating message sets

You must create a message set before you can create any content. To create a new
message set:
1. Right-click the Message Sets root and click Create —> Message Set, or select
Create —> Message Set from the Message Sets menu in the task bar. This
displays the “Create a new Message Set” dialog, containing three tabs of
message set properties.
2. On the Message Set tab, type a name for this new message set in the Name
field. VideoStore is the name used in the Video customer message example.
This property is mandatory.
3. Accept the default values for all other properties on this tab and the Run Time
tab. For information about other values that you can specify for the message set
properties, see “Message set properties” on page 43.
| When you accept the default parser (the MRM parser) that is set on the Run
| Time tab, note that in certain situations the parser optimizes the parsing and
| construction of messages. For example, if you use the ESQL statement SET
| OutputRoot = InputRoot, and you do not subsequently modify any of message
| contents, the parser directly copies the input bit stream to the output bit stream
| and does not regenerate the bit stream.
| Because the parser does not regenerate the message, the properties that you
| have set in the wire format layer are not acted upon. For example, if you set
| the message set property Boolean True to yes and the input message includes a
| boolean element with a value of 1 (which is also interpreted as true by the
| parser), the output message is identical and is not updated to reflect the
| message set property value. ENTITY references are also preserved in this way.

© Copyright IBM Corp. 2000, 2002 159

 Creating message sets
| However, if the parser does regenerate the bit stream, the values in the wire
| format layer that are relevant to the output message take precedence over those
| specified in the input message. In the example above, the boolean element in
| the output message is overwritten with the value of yes.
| If you have configured your message flow to modify any element in the
| message, the parser regenerates the entire output bit stream. It also regenerates
| the bit stream if, for example, you configure a Compute node in the message
| flow by checking the check box for the Copy message headers property and code
| ESQL statements that copy elements from the input message to the output
| message.
| You would usually build a logical model to specify the rendering options for a
| message, and both your input messages and your output messages conform to
| the model. You will notice a difference in output message content only if the
| input messages deviate from the format specified by the model (while perhaps
| remaining logically equivalent, for example in the use of whitespace or ENTITY
| references.
4. Click Finish to complete the definition of this message set. The message set is
now created and the MRM generates a unique identifier for the message set,
which you cannot change.
When you have created the message set, you can add physical format layers, or
language bindings, or both. You are strongly recommended to add these before
you define (or create by importing) any lower level components in the message set.
The lower level components that have properties for these layers display these
properties when they are created.

If you add layers to the message set after you have created lower level
components, you must check in all lower level components before you can do so.
When the layer has been added successfully, you must either check out and check
in the lower level components that you want to view or modify to refresh their
properties, or use the Refresh button, or select View—>Refresh from Shared.
v If this message set is to contain legacy messages (for example, if message
definitions are to be imported into this message set), you must add a CWF layer.
Right-click the message set, select Add—>Physical Format...—>Custom Wire
Format.... Enter a name for the format and click Finish. A new tab is created with
the name you specified. For details about the CWF layer, see Chapter 5,
“Working with a Custom Wire Format layer” on page 83.
You might also want to add a language binding to the message set for legacy
messages. To do this, select Add—>Language Binding...—>C Language... or
Add—>Language Binding...—>COBOL Language.... The dialog displays a fixed
name for the bindings (you cannot change this name). Click Finish. A new tab is
created with the fixed name.
You can add a language binding for both C and COBOL if you choose. However,
you can only add one for each language.
v If this message set is to contain tagged or delimited messages (for example,
SWIFT), you must add a TDS layer. Right-click the message set, select
Add—>Physical Format...—>Tagged/Delimited Format.... Enter a name for the
format and click Finish. A new tab is created with the name you specified. For
more details about the TDS layer, see Chapter 7, “Working with Tagged
Delimited String messages” on page 131.
v If this message set is to contain XML messages, you must add an XML wire
format layer. Right-click the message set, select Add—>Physical Format...—>XML
Format.... Enter a name for the format and click Finish. A new tab is created with

160 WebSphere MQ Integrator Working with Messages

 Creating message sets
the name you specified. For more details about the XML wire format layer, see
Chapter 6, “Working with an XML Format layer” on page 111..

When you have added a physical format layer or a language binding to the
message set, you cannot remove it. You must delete the message set and recreate it
if you want to remove it. However, you do not have to use the layers that you
have added.

A locked entry appears under Message Sets root in the Message Sets pane. When
the new message set entry is highlighted in the Message Sets pane, its properties
appear in the Properties pane.

When you are ready to share a new message set with other Control Center users,
you can check it into the shared repository. You can do this before the message set
contains any message definitions, if you want. For more information about
checking in message sets, see “Checking in and checking out message sets and
components” on page 169.

Now that you have defined a message set, you are ready to define the messages
that will belong to it. This process is described in “Creating messages” on page 165.

At any time you can view the message set properties that have been set. If you
want to modify any of these properties, you must first check out the message set.
For details of the message set properties, see “Message set properties” on page 43.

Creating a message set with the same name as an existing

message set
You can create a message set with the same name as an existing one if you:
v Finalize the existing message set (or sets) with this name.
v Remove all existing message sets with this name from the shared repository
before you create the new one.
v Create the new message set:
– Enter the existing name for the new message set name
– Specify as the base message set the existing message set that has the highest
level (if there is more than one). If you specify a message set with a lower
level number, the create will fail.
– Specify a level number for the new message set that is higher than the highest
level of all existing finalized message sets with this name.

Adding wire format layers

If you add a wire format layer to the message set after you have created lower
level components, you must refresh the view to display the additional properties
(by checking out and in the components, or using the Refresh button, or selecting
View—>Refresh from Shared.

When you add elements to a compound type after you have added a wire format
layer, you must check in the compound type before you can view or modify the
type member properties: these properties are not displayed when the type member
is created, but only when you check in the parent.

To add a wire format layer:

1. Right-click the message set and select Add—>Physical Format....
The following three options are presented: select the one that you want to add.
a. Add—>Physical Format...—>Custom Wire Format...

Chapter 8. Working with MRM messages in the Control Center 161

 Adding wire formats
b. Add—>Physical Format...—>Tagged/Delimited Format...
c. Add—>Physical Format...—>XML Format...
| 2. Complete the dialog displayed for the wire format by providing a name for the
| physical layer. This name is not the wire format identifier. You must specify the
| wire format identifier when you configure the wire format layer. The name that
| you enter here is used for display purposes only and appears on the tab in the
| Control Center properties pane to identify the tab that contains the properties
| for this wire format layer.
3. Click OK. The new physical layer is added on a new tab alongside the existing
tabs that display the message set properties.
| 4. You can now review and modify the additional properties of the message set
| for the layer that you have added. These are detailed in Chapter 5, “Working
| with a Custom Wire Format layer” on page 83, Chapter 6, “Working with an
| XML Format layer” on page 111, and Chapter 7, “Working with Tagged
| Delimited String messages” on page 131.

You can add more than one layer for each wire format if you choose. If you do so,
each name must be unique. You can also add more than one type of physical
format to a single message set if you choose.

Using padding characters in wire formats

All MRM padding characters defined in wire formats are subject to character
conversion, regardless of whether they are defined as SPACE, specified character,
hexadecimal value or numeric. If you are converting a message from one code
page to another, you must ensure that the converted value of the padding
character is valid for this code page.

For example, when converting from ASCII to code page 500, if you have specified
the numeric 8 as your padding character, this is converted from 0x08 to 0x16, the
ASCII and EBCDIC representations of ’back space’.

There is currently a restriction that the value of your padding character should not
be greater than 0x7F. Also you should note that if you enter a hexadecimal or
numeric value, it is considered to be the character represented by that number in
UTF-8.

For a fuller discussion of data conversion considerations, see Chapter 9, “Planning

your WebSphere MQ Integrator network”, in WebSphere MQ Integrator Introduction
and Planning.

Adding a language binding

If you want to import C or COBOL files to create MRM definitions, or you want to
generate the headers or copybooks from MRM definitions, you must add the
appropriate language binding to the message set. You can add one C language
binding, or one COBOL language binding, or both. You cannot add multiple
language bindings for either language.

If you add a language binding at the message set level, you can view, set, and
modify its properties. You can also view and modify properties at the category,
transaction, message, and element levels.

When you have created your message set, you can add one or two language
bindings. You are recommended to do this before you create the lower level
components of the message set: if you do so, the language bindings properties for

162 WebSphere MQ Integrator Working with Messages

 Adding language bindings
the lower level components are added, where appropriate, by the MRM, and are
visible when you check in those components. You can modify them later by
checking out the components.

If you add a language binding to the message set after you have created lower
level components, you must check out these components to view the additional
properties.

To add language bindings to your message set:

1. Right-click the message set and select Add—>Language Binding....
The following two options are presented: select the one that you want to add.
a. Add—>Language Binding...—>C Language...
b. Add—>Language Binding...—>COBOL Language...
2. Click OK. The new language binding layer is added on a new tab alongside
the existing tabs that display the message set properties.
3. Review and modify the additional properties listed in the following sections.

You can only add one language binding per language per message set.

The C language layer

When you add a C language layer to the message set, a new tab, C Language, is
added to the properties pane. It defines properties that identify names for header
files generated from this message set using the Message Sets —> Generate option. It
is displayed for the message set, for categories, for transactions, for messages, and
for elements.
v For the message set you can specify:
Main Header File Name
Is the name of the generated header file that contains C structure
definitions of the messages in this message set.
Orphan Header File Name
Is the name of the generated header file that contains definitions of C
structures (types) that are not used by any message in this message set.
v For each defined message category and transaction category you can specify:
Category Header File Name
Provides the name of the header file into which structure definitions for
all messages or transactions in this category are generated.
Include in Main Header
Specifies whether this header file is included from the main header file
for the message set.
| C Language Name
| Provides the name used for this category as a field within C structure
| definitions. By default, the category identifier is used.
| v For each defined transaction you can specify:
| Transaction Header File Name
| Provides the name of the header file into which structure definitions for
| all messages in this transaction are generated.
| Include in Main Header
| Specifies whether this header file is included from the main header file
| for the message set.

Chapter 8. Working with MRM messages in the Control Center 163

 Adding language bindings
| C Language Name
| Provides the name used for this transaction as a field within C structure
| definitions. By default, the transaction identifier is used.
v For each defined element you can specify:
C Language Name
Provides the name used for this element as a field within C structure
definitions. By default, the element identifier is used.
| If you include more than one instance of the same element within a
| compound type (a duplicate element), you must specify a different value
| for this property for each instance. If you let this property default, error
| BIP1951 is raised when you check in the element after initial check in.
v For each defined type you can specify:
C Language Name
Provides the name for the C structure definition that is generated for the
type. By default, the type identifier is used.
File Name
Provides a name for a header file to be generated containing a structure
definition for the type. This value is optional, and is not usually
specified: the structure definitions for types appear only in the category
header files.

The COBOL language layer

When you add a C language layer to the message set, a new tab, C Language, is
added to the properties pane. It defines properties that identify names for copy
books generated from this message set using the Message Sets —> Generate option.
It is displayed for the message set, for categories, for transactions, for messages,
and for elements.
v For the message set you can specify:
Main Copy Book Name
The name of the main copy book generated from this message set.
v For each defined message category and transaction category you can specify:
Category Copy Book Name
Provides the name of the copy book file into which structure definitions
for all messages or transactions in this category are generated. By
default, the category identifier is used.
| v For each defined transaction you can specify:
| Transaction Copy Book Name
| Provides the name of the copy book file into which structure definitions
| for the transaction are generated.
| COBOL Language Name
| Provides the name used for the COBOL structure definition that is
| generated for the transaction. By default, the transaction identifier is
| used.
v For each defined message you can specify:
COBOL Language Name
Provides the name used for the COBOL structure definition that is
generated for the message. By default, the message identifier is used.
Message Copy Book Name
Provides the name of the copy book file into which the structure
definition for the message is generated.

164 WebSphere MQ Integrator Working with Messages

 Adding language bindings
v For each defined element you can specify:
COBOL Language Name
Provides the name used for this element as a field within COBOL
structure definitions. By default, the element identifier is used.
| If you include more than one instance of the same element within a
| compound type (a duplicate element), you must specify a different value
| for this property for each instance. If you let this property default, error
| BIP1951 is raised when you check in the element after initial check in.
v For each defined type you can specify:
COBOL Language Name
Provides the name for the COBOL structure definition that is generated
for the type. By default, the type identifier is used.
Structure Copy Book Name
Provides a copy book file name into which the structure definition for
the type is generated.

Creating messages
This section describes how to create a message, using the message shown in
Figure 21 on page 78 to illustrate the process. The example here uses only the basic
components and default properties of the MRM. You can add wire formats to these
components to refine the message definition and make it most appropriate for your
business and operating environment.

The Control Center provides a SmartGuide that you can use to create both
messages and compound types. For further information, see “Using the
SmartGuides” on page 168.

For a comprehensive description of the properties and possible use of every

message component, refer to Chapter 4, “The MRM logical message model” on
page 35.

Identify the logical model

Before you start to define anything, you must determine, at a high level, the logical
model that you want to implement:
v What are the elements required in this message?
v Which elements have member relationships with other elements?
v What type of data is associated with each element?

Table 78 indicates the high-level properties for the Video customer message.
| Table 78. The elements of the Video customer message
| Element Child Of Datatype Other properties
| Name STRING Holds surname, and can contain
| only those elements defined as
| children in the model
| Title Name STRING Maximum length of 3
| First Name Name STRING
| Address Can contain only those elements
| defined as children in the model
| HouseNo Address INTEGER

Chapter 8. Working with MRM messages in the Control Center 165

 Creating messages
| Table 78. The elements of the Video customer message (continued)
| Element Child Of Datatype Other properties
| Street Address STRING
| Town Address STRING
| IdType Choice of one of its children
| PassportNo IdType STRING
| DrivingLicenseNo IdType STRING
| CreditCardNo IdType STRING
| Borrowed Repeats to allow for multiple
| borrowed videos. Can contain only
| those elements defined as children
| in the model
| VideoTitle Borrowed STRING
| DueDate Borrowed DATETIME In the form dd-MMM-yy
| Cost Borrowed DECIMAL
| Magazine Borrowed BOOLEAN
|

Create the elements of simple types

Right-click the message set and select Create—>Element. In the Create a new
Element dialog, give the element a name and identifier (shown in Table 79) and
select the appropriate simple type from the Type drop-down list. Click Finish to
create the element. Repeat for all the elements of simple type in the message.
| Table 79. The Video customer elements with simple types
| Element Name Element Identifier Datatype
| Name Name STRING
| Title Title STRING
| First Name FirstName STRING
| Address Address STRING
| HouseNo HouseNo INTEGER
| Street Street STRING
| Town Town STRING
| PassportNo PassportNo STRING
| DrivingLicenseNo DrivingLicenseNo STRING
| CreditCardNo CreditCardNo STRING
| VideoTitle VideoTitle STRING
| DueDate DueDate DATETIME
| Cost Cost DECIMAL
| Magazine Magazine BOOLEAN
|

166 WebSphere MQ Integrator Working with Messages

 Creating messages
Create the compound types
Right-click the message set and select Create—>Compound Type. In the Create a new
Compound Type dialog, give the type a name and identifier (shown in Table 80).

The Type Composition field specifies how this type is made up (the default is
Ordered Set). The Type Content field specifies how flexible the content of the type
can be (the default is Open). For further information about the values that you can
choose for these properties, and their meaning, see the Control Center online help.
Click Finish to create the compound type.

(The Type Composition of the parent compound type must be either Choice or
Sequence if the compound type contains another compound type.)

Repeat this procedure for all of the compound types in the message. They are
listed in Table 80. The Travel Request compound type is used as the type of the
whole message.
| Table 80. The Video customer elements with compound types
| Compound type Name Identifier Type Composition Type Content
| Name NameType Ordered Set Open
| Address AddressType Ordered Set Open
| IdType IdType Choice Closed
| Borrowed BorrowedType Sequence Closed
| CustomerType CustomerType Sequence Open
|

Create compound elements

Right-click the message set and select Create—>Element. In the Create a new
Element dialog, give the element a name and identifier (these are shown in
Table 81) and select the appropriate compound type from the Type drop-down list.
| Table 81. The Video customer compound elements
| Element Name Element Identifier Compound Type
| Name Name NameType
| Address Address AddressType
| Borrowed Borrowed BorrowedType
|

Add elements to the compound types

In the Types folder, right-click a compound type and select Add—>Element. All the
elements in your workspace, of simple and compound types, are displayed. Hold
down the Ctrl key and select the elements listed in Table 82 on page 168. If the
compound type has a Type Composition of Choice or Sequence, you can also select
Add—>Compound Type.

Chapter 8. Working with MRM messages in the Control Center 167

 Creating messages
| Table 82. Elements within the Video customer compound types
| Compound Type Add the following
| NameType Title, FirstName
| AddressType HouseNo, Street, Town
| IdType PassportNo, DrivingLicenseNo, CreditCardNo
| BorrowedType VideoTitle, DueDate, Cost
| CustomerType Name, Address, IdType, Borrowed, Magazine
|

Reorder elements within compound types: The order of the elements in the
compound type is important because WebSphere MQ Integrator checks that the
order of the elements in the message that is received in the input node of a
message flow matches the order of the elements in the definition.

If you need to reorder elements within the compound types, follow the process
described in “Reordering elements in compound types” on page 171.

Create the message

| Right-click the message set and select Create—>Message. In the Create a new
| Message dialog, give the message a name (Customer), an identifier (Customer) and
| select the correct type (CustomerType).

Create a category
| Right-click the message set and select Create—>Message Category. In the Create a
| new Message Category dialog, give the category a name and an identifier. For
| example you could call the category CustomerCategory and give it the identifier
| CustomerCategory. Click Finish to create the category.

| Add the message to the category: In the Categories folder, right-click the category
| and select Add—>Message. Select the Customer message.

Make elements repeatable

| The Video customer message contains one repeating element. The Borrowed
| element repeats up to a maximum of three times (representing three possible video
| hires).

You must ensure that the type containing the repeating elements is checked out. In
this example, the type Borrowed must be checked out to allow you to update the
Borrowed element to make it repeating.

For the Borrowed element, select the Connection tab in the properties pane. Update
the Repeat property to Yes and the Max Occurs property to 3. Click Apply.

Using the SmartGuides

The definition of the example Video customer message shown in Figure 21 on
page 78 shows only a subset of what you can do and the range of messages you
can define, to help you understand the basic structure and content of message
definition.

You can also create this and other messages and compound types using the
SmartGuides.

168 WebSphere MQ Integrator Working with Messages

 SmartGuides
The SmartGuide provides a quick method of defining messages because it assumes
that all the building blocks of the message or compound type are available and do
not have to be defined. It does, however, allow you to define elements of both
simple and compound types.

You can also use the Compound Type SmartGuide to create compound types (this
also lets you create elements), and you can specify that you want the compound
type to also be created as a message.

To create a message using the SmartGuide:

1. In the Message Sets pane of the Message Sets view, right-click the folder of the
message set you want to add definitions to and click Create with SmartGuide
—>Message.
The Create a new Message dialog is displayed.
2. Enter the name for this new message in the Name field.
3. If you want to define new elements for this message, select the Create Element
tab. If you want to add existing elements to the message, Add Element tab.
You can do either or both of these in any order. At the bottom of both of these
tabs, the current content of the message is displayed.
You cannot add simple types or base types to your message using the
SmartGuide.
4. Click Finish. The message you have created is now included in the Messages
folder of the message set. A compound type is also created for this message,
with an identifier of t_ followed by the name of the type (t_message1). This is
included in the Types folder.

The procedure for creating a compound type is almost identical.

The SmartGuide also allows you to reorder elements within the message or
compound type you are creating: this makes it easier to view and check the order
of elements while you complete the message or compound type structure.

Working with message sets

When you have created a message set, you can perform many actions against it.
These are discussed in the following sections:
v “Checking in and checking out message sets and components”
v “Reordering elements in compound types” on page 171
v “Editing message sets and components” on page 171
v “Changing the state of a message set” on page 174
v “Using copy and paste” on page 175
v “Adding message sets and message set components to the workspace” on
page 175

Checking in and checking out message sets and components

If you want to check in a message set, right-click the folder of the message set in
the Message Sets view. Select Check In from the menu.

The message set is checked into the shared configuration and is saved in the
message repository. It still appears in your workspace, but the Key icon against its
folder has disappeared. It is now unlocked.

When you check in a message set, any checked out objects in the message set are
not checked in by this action. You must check in these objects individually.

Chapter 8. Working with MRM messages in the Control Center 169

Checking in and checking out
Alternatively, you can select one of the more comprehensive check in options
(available from the File menu) when you check in the message set:
v File —> Check In —> All in Workspace checks in all objects that are contained
within your current workspace (which is identified on the title bar of the Control
Center).
v File —> Check In —> All (Save to Shared) checks in all objects in your local
repository (that is, within all locally-available workspaces).
v File —> Check In —> List displays a list of objects that are currently checked
out to you, and allows you to select one or more to check in.

When you have checked in a message set, it is available to other users from the
shared configuration.

When you create components within the message set, you can create and check
these in individually. However, because components within a message set are very
often related and interdependent, the Control Center checks the status of other
components when you check in.

If other components must be checked in at the same time to preserve the integrity
of the message set, the Check In Confirmation dialog is presented. This contains a
list of all the objects that will be checked in on this one action, in addition to the
object that you selected.

If you do not want to check in all these objects at this time, you cannot check in
the original object. Click Cancel to terminate the check in request. If you can
confirm that you want all the listed objects to be checked in, click OK.

If you want to make further changes to the message set, you must first check it out
of the shared configuration:
1. In the Message Sets pane, right-click the folder of the message set you want to
edit.
2. Click Check Out.
The message set is checked out of the shared configuration. Its entry in the
Messages Pane has a Key icon against it to remind you that the definition is
checked out.

When you check out a message set, objects in the message set (messages, elements,
and so on) are not checked out by this action. You must check out these objects
individually.

You can check out any message component individually. You can also check out a
message, element, or compound type with its dependent hierarchy by selecting
Check Out List.... This option is only available for these three components. When
you select this option, the Check Out List dialog is displayed.

The dialog shows all the objects that are related in some way to the selected object.
For example, if you highlight a message and select this item, the compound type
for the message is also listed (even if you have not added it to your current
workspace).

The list of objects is displayed in a tree format, and reflects the order of folders in
the message tree in the left pane (within the folders, the objects are sorted by
name). The folders themselves are not eligible for selection. By default all items

170 WebSphere MQ Integrator Working with Messages

 Checking in and checking out
shown are selected. You can choose to deselect any one or more of these items. If
you deselect them all, the Check Out button is disabled.

You can choose to cancel this operation by selecting Cancel.

If you click Check Out, the required check outs are performed. If some of the
items have not been checked out because they are already checked out to another
user, the operation completes, and an error message dialog is displayed showing
all the objects that could not be checked out, and the identity of the user that has
them locked.

Reordering elements in compound types

The order of the elements in the compound type is important because WebSphere
MQ Integrator checks that the order of the elements in the message that is received
in the input node of a message flow matches the order of the elements in the
definition.

Order can also be important if you define elements with a length or a repeat value
that is defined by another element (by setting the Length Type property to Value
Of, or the Repeat Count Type property to Value Of) in the CWF or TDS layers. If
you set Value Of, the element that defines the length or the number of repeats
must be in integer, and it must appear before the element that uses that value.
Therefore you might need to reorder the elements within the compound type to
ensure that this condition is met.

The reorder action is only supported for compound types.

Right-click the compound type that you want to reorder, and select Reorder. The
Reorder Elements SmartGuide is displayed, and lists the elements that are defined
within the compound type. You can move these elements up or down to change
the order. You cannot add new elements using this option. You cannot reorder
external elements (those with the global icon).

Click Finish to confirm your new order: the new order is reflected in the tree in
the left pane.

Editing message sets and components

You can edit the properties of message sets and components. You can also edit the
relationships between components (for example, you can remove an element from
a compound element), and you can delete components or remove them from the
workspace.

Although you can undo many of the actions you can take in the Control Center,
you cannot undo the action if you have deleted a message set, deleted an element,
or deleted a compound type. Undo is available on the Edit menu, and is grayed
out if you cannot undo the action just completed.

All properties you can edit are displayed in the Properties pane of the Message
Sets view. For example, if you highlight an element in the Message Sets pane, its
properties, including those you can edit, are displayed in the Properties pane.
When you change the value of a property, click the Apply bar at the bottom of the
Properties pane to make the change take effect.

An individual message component can be removed from the workspace or deleted

from the shared configuration. For example, to remove an element from the

Chapter 8. Working with MRM messages in the Control Center 171

Editing message sets and components
workspace, right-click the element in the Messages Pane and select Remove. To
delete a component, right-click it and select Delete. If the parent is not a compound
type, the component and its parent do not have to be checked out for you to
remove or delete the component. If the parent of the component is a compound
type, you must check out the parent and the component to perform these actions.

You can only edit a component’s properties or rename it if the component itself,
and any related component, is checked out.

Table 83 summarizes the available edit actions and shows for each action:
v Which component needs to be checked out.
v What happens when you make the change.
Table 83. Editing relationships and properties: check-out requirements
If you want to: You must check out: Then:
Edit the basic The component you You can edit the component and check it back in
properties of a want to edit
component
Edit the connection The compound type You can edit the connection tab then check the parent back in.
tab of a child element that is the parent of
the element
Edit the CWF of a The compound type You can edit the CWF tab then check the parent back in.
child element that is the parent of
the element
Edit the C language The component you You can edit all three tabs. The name is C-validated or COBOL
tab, COBOL language want to edit validated by the Control Center; you cannot click Apply if they are
tab, or Description tab invalid. If they are valid, you can check the component back in.
of a component
Edit an element The associated You can edit the message then check it back in.
qualifier assignment message
Delete an element Nothing If nobody has the element value checked out, the element value is
value from the deleted from the shared repository. If the element value has been
Element Values folder used to form a value constraint elsewhere in your message set,
highlighting the value constraint causes error message BIP0404E to
be displayed. Right-click the value constraint and select the only
option, Remove. If the element value is checked out, an error
message is displayed and you are not allowed to delete the element
value.
Remove an element Check-out status is The element value is removed from the workspace and there is no
value from the not significant change in the shared repository. The element value can be added to
Element Values folder. the workspace again.
Delete a compound Nothing If any user has an element or a message of this type checked out,
type from the Types or if any user has this type checked out an error message is
folder displayed and you are not allowed to delete. Otherwise, the type is
deleted and all elements of this type are also deleted throughout
the message set.
Remove a compound Check-out status is The type and its children are removed from the workspace under
type from the Types not significant the Types folder. Nothing else is affected. The compound type can
folder be added to the workspace again.
Remove a simple type Nothing The type is removed from the workspace under the Types folder.
from the Types folder Nothing else is affected. The simple type can be added to the
workspace again.

172 WebSphere MQ Integrator Working with Messages

 Editing message sets and components
Table 83. Editing relationships and properties: check-out requirements (continued)
If you want to: You must check out: Then:
Remove a child The type from which The child is deleted from the type. When you check the type in, it
simple element from a you will remove the is updated in the shared repository, but the child element continues
type in the Types element to exist. Other types that contain the element as a child are not
folder affected.
Delete a child simple Nothing If nobody has the child simple element checked out and if nobody
element from a type has any type or element qualifier that is a parent of the simple
in the Types folder element checked out, the element is deleted from the shared
repository and all the types that previously used it as a child are
updated. Otherwise, an error message is issued and you are not
allowed to perform the delete.
Delete a child Nothing If nobody has the child compound element checked out and if
compound element nobody has any type or element qualifier that is a parent of the
from a type in the compound element checked out, the element is deleted from the
Types folder shared repository and all the types that previously used it as a
child are updated. Otherwise, an error message is issued and you
are not allowed to perform the delete.
Remove a child The type from which The child is deleted from the type and, on check in, the type is
compound element you will remove the updated in the shared repository but the child element continues to
from a type in the element exist. Other types that contain the element as a child are unaffected.
Types folder
Delete a simple Nothing If nobody has the element checked out, and if nobody has any type
element from the or element qualifier that is a parent of the element checked out, the
Elements folder element is deleted from the shared repository and all the types that
previously used it as a child are updated. Otherwise, an error
message is issued and you are not allowed to perform the delete.
Remove a simple Check-out status is The element is removed from the workspace under the Elements
element from the not significant folder. Nothing else is affected. The element can be added to the
Elements folder workspace again.
Delete a top-level Nothing If nobody has the element checked out, and if nobody has any type
compound element in or element qualifier that is a parent of the element checked out, the
the Elements folder element is deleted from the shared repository, and all the types that
used the element as a child are updated. Otherwise, an error
message is issued and you are not allowed to perform the delete.
Remove a top-level Check-out status is The element and its children are removed from the workspace
compound element in not significant. under the Elements folder. Nothing else is affected. The compound
the Elements folder element can be added to the workspace again.
In the Elements folder, Nothing If nobody has the child element checked out; and if nobody has any
alter a compound type or element qualifier that is a parent of the element checked
element by deleting a out; and if nobody has the type of the compound element checked
child simple element out; the element is deleted from the shared repository, and all the
types that previously used the element as a child are updated.
Otherwise, an error message is issued and you are not allowed to
perform the delete.
In the Elements folder, The type associated The child is deleted from the type, and when you check the type
alter a compound with the compound back in, it is updated in the shared repository but the child element
element by removing element continues to exist. Other types that contain the element as a child
a child simple element are not affected.

Chapter 8. Working with MRM messages in the Control Center 173

Editing message sets and components
Table 83. Editing relationships and properties: check-out requirements (continued)
If you want to: You must check out: Then:
In the Elements folder, Nothing If nobody has the child element checked out; and if nobody has any
alter a compound type or element qualifier, of which the compound element is a
element by deleting a child, checked out; and if nobody has the type of the parent
child compound compound element checked out; then the element is deleted from
element the shared repository and all the types that used the element as a
child are updated. Otherwise, an error message is issued and you
are not allowed to perform the delete.
In the Elements folder, The type associated The child compound element is removed from the workspace.
alter a compound with the parent Nothing else is affected. The compound element can be added to
element by removing compound element the workspace again.
a child compound
element
Delete a message in Nothing If nobody has the message checked out, and if nobody has any
the Messages folder category of which the message is a child checked out, the message
is deleted from the shared repository, Otherwise, an error message
is issued and you are not allowed to perform the delete.
Remove a message Check-out status is The message and its children are removed from the workspace
from the Messages not significant under the Messages folder. Nothing else is affected. The message
folder can be added to the workspace again.
Alter a message by Nothing If nobody has the child element checked out, and if nobody has the
deleting a simple type of the message checked out, and if nobody has any type, of
child element in the which the element is a child, checked out, then the element is
Messages folder deleted from the shared repository and all the types that used the
element as a child are updated. Otherwise, an error message is
issued and you are not allowed to perform the delete.
Alter a message by The type associated The child is deleted from the type, and on check in the type is
removing a child with the message that updated in the shared repository, but the child element continues to
simple element in the contains the element exist and other types that contain the element as a child are not
Messages folder affected.
Alter a message by Nothing If nobody has the child element checked out; and if nobody has any
deleting a child type or element qualifier that is a parent of the child compound
compound element in element checked out; and if nobody has the type of the message
the Messages folder. checked out; then the element is deleted from the shared repository
and all the types that used the element as a child are updated.
Otherwise, an error message is issued and you are not allowed to
perform the delete.
Alter a message by The type associated The child compound element is removed from the workspace.
removing a child with the message that Nothing else is affected. The child compound element can be added
compound element in contains the element to the workspace again.
the Messages folder

Changing the state of a message set

When a message set is under development, its state can be frozen, unfrozen, and
finalized. You might want to do this to protect the message set against further
change, temporarily (by freezing) or permanently (by finalizing).

To change the state of a message set:

1. In the Message Sets pane, right-click the message set whose state you want to
change.
2. Select the state you want. For example, to freeze a message set, click Freeze.

174 WebSphere MQ Integrator Working with Messages

 Changing the state of a message set
There are some restrictions you must be aware of:
v When you import a message set, it is initially in the frozen state. You can
unfreeze it if you want to make changes after import.
v When you freeze a message set, the freeze timestamp property of the message
set is set to the current date and time.
v If you unfreeze a message set, the message set must be checked out to you. The
freeze timestamp property of the message set is reset to blank.
v When you finalize a message set, the Finalized field in the properties of the
message set is set to True and the freeze timestamp property is set. Finalize
cannot be reversed. When a message set is finalized, it cannot be changed or
updated, although it can be deleted.
v You cannot freeze or finalize a message set if any of the elements it contains is
checked out.

Using copy and paste

You can use standard copy and paste techniques in the Control Center to reuse
components within a message set, and between message sets within your
workspace. For example, you might copy an element from one compound type to
another within the same message set. Or you might copy a compound type from
one message set to another.

If you copy from one message set to another, you must ensure that the two
message sets have identical names for their wire format tabs (if present), and that
both have the same language bindings.

Adding message sets and message set components to the

workspace
You can add any message set or message set component that is defined in the
message repository to your workspace. The message repository includes all objects
defined by current users of the Control Center, and all objects imported into the
message repository through the use of the mqsiimpexpmsgset command. See the
WebSphere MQ Integrator Administration Guide for more details.

To add a message set from the message repository to your workspace:

1. In the Message Sets pane, right-click the Message Sets root.
2. Select Add to Workspace—> Message Set.
The Add an existing Message Set dialog is displayed, showing all message sets
that you can add to your workspace (and that aren’t already in the workspace).
3. Select one or more message sets from this list and click Finish. The selected
messages are added to the Messages folder of the appropriate message set in
the Message Sets pane.

The message sets you selected to add are displayed in the Message Sets view. All
of the components of the message set (messages, elements, and so on) are now
available to your workspace, but are not automatically added. This is because
message sets can be very complex, and it is likely that you do not need to view or
access many of the subcomponents. If you add large numbers of components to
the workspace, this can cause slow response times and out-of-memory problems.

You can add just those components that you want to work with, or view, by
selecting the appropriate folder and adding the components when and as you need
them.

Chapter 8. Working with MRM messages in the Control Center 175

Adding message sets to the workspace
For example, to add an element to your workspace:
1. Right-click the Element folder of the message set to which you want to make
the element available, and select Add to Workspace —> Element.
The Add an existing Element dialog is displayed, showing all elements that
you can add, that is, all the elements that are defined in the message set.
2. Select one or more elements from the list and click Finish. The selected
elements are added to the Elements folder of the appropriate message set in the
Message Sets pane.

You can add categories, transactions, element qualifiers, messages, types, and
element values to your workspace in the same way.

Importing message set definitions

You can import existing message definitions into message sets within the Control
Center:
v “Importing C and COBOL data structures”
v “Importing a DTD” on page 177

Importing C and COBOL data structures

You can import message definitions that exist as C or COBOL datastructures. These
must be imported into an existing message set, therefore you must create a new
message set if you do not want to import into a message set that contains other
messages. You must also add a C or COBOL language binding (or both) to the
message set before you import. See “Adding a language binding” on page 162 for
more information about adding language bindings.

To import a message definition:

1. In the Message Sets pane of the Message Sets view, right-click the message set
into which you want to import the definition and select Import to Message Set
—> C or Import to Message Set —> COBOL. The action is also available if you
select Message Sets from the task bar and select Import to Message Set —> C or
Import to Message Set —> COBOL.
The C Language Importer dialog or COBOL Language Importer dialog is
displayed.
2. Type the fully qualified name of the source file you are importing in the Import
Source File field, or use the Browse button to search for and select the file that
you want to import. If you want only to generate a report at this time, select
the Report only check box. Click OK.

The import function parses the source code files, isolates the data structure
definitions, and creates logical definitions that correspond to those data structures.
It also sets the appropriate wire format (CWF) properties to define the mapping
between the logical definitions and the physical message format, as defined by the
C or COBOL data structures.

A compound type is created for each data structure, and elements are created for
each field within the data structure. For more detailed information about the way
in which C and COBOL data structures are interpreted by the MRM language
importers, and a summary of the restrictions on the contents that you can
successfully import, see Chapter 9, “C and COBOL default mappings” on page 183.

176 WebSphere MQ Integrator Working with Messages

 Importing C and COBOL structures
A report is generated by the import function that describes all the definitions that
have been created. It includes information about errors or conflicts within the
definitions. You can elect to produce this report without committing any changes
to the message set. You are recommended to do this and check the report before
running the complete import process.

When the import process is complete, you must create a message for each
compound type that defines a complete message (described in “Create the
message” on page 168): all other components are created automatically. However,
you are recommended to review your message definition, and edit it if necessary,
to ensure that it meets your needs.

| If you attempt to import a C header file that contains an erroneous C structure

| syntax, the structure does not import correctly and you must review the error
| information in the report. However, this failure causes all future imports of C
| header files to fail, even if these contain valid syntax. You must stop and restart
| the Configuration Manager before you can import further C header files.

Importing a DTD
You can import a DTD into the Control Center. This can be a DTD that you have
generated from this or another message repository (a procedure described in
“Generating MRM message set definitions in XML DTDs” on page 181), or a DTD
from another source. The DTD must be syntactically valid XML.

To import a DTD:
1. Select a message set into which you want to import the DTD. This can be a
new message set that you have created for this purpose, or an existing one to
which you want to add the DTD contents.
2. Select Import to Message Set—>DTD. The XML Import dialog is displayed.
3. Enter the fully qualified filename of the DTD that you want to import. If you
prefer, you can click Browse to locate the file on the Selector dialog. Select the
file that you want to import in the left pane, and click the >> button to add it
to the right pane. You can only select a single file.
4. Click OK. The fully qualified filename is displayed.
5. Click Next >>. The DTD importer parses the input file. If it encounters a
syntactical error, it displays an error message dialog and terminates the import
operation. Click OK when you have reviewed the message. You can click
Back to return to the previous display to select a new file to import, or to
correct the contents of the file.
6. If the file you have selected is parsed correctly, the importer displays the list
of elements contained in the DTD in the left pane on the XML Import dialog.
7. All the elements listed in the left pane are imported as elements in the
message set. If you want any of the listed elements to be imported as
messages, select the element and click the >> button to add it to the list in the
right pane. You can use the << button to move elements from the right pane
to the left pane.
8. You can click Back at any time to return to the previous display. You can click
Cancel to terminate the operation.
9. When you have the correct elements in each list, click Finish.
10. When the import has completed, click OK to return to the Message Sets view.

When you view the message set after import, the components that you selected as
elements have been created as elements, and the components that you selected as

Chapter 8. Working with MRM messages in the Control Center 177

Importing a DTD
messages have been created as messages. Each component is marked as new. The
definitions that have been created for these components exist only in your local
repository. If you want to keep these definitions, you must store them in the
message repository using Check In.

Generating information from message sets

You can generate several resources from the definitions of message sets in the
message repository. Using the options available Message Sets view, you can
generate:
v “Generating documentation”
v “Generating language bindings” on page 179
v “Generating run time dictionaries” on page 180
v “Generating MRM message set definitions in XML DTDs” on page 181

Generating documentation
You can generate documentation in HTML format from the message set definitions
maintained in the message repository. Using the options available from the
Message Sets view, you can generate:
v A message book, which contains an entry for each message in a message set or
specified category, showing its hierarchical structure.
v A glossary, which contains descriptions of all elements in a message set or
specified category, ordered alphabetically by name.

Generating a message book

To generate a message book:
1. In the Message Sets pane of the Message Sets view, right-click the folder of the
message set or message category for which you want to generate
documentation.
2. Select Generate —> Documentation —> Message Book....
The Message Definition Book dialog is displayed.
3. In the Message Definition Book dialog, type the fully qualified name of the
generated documentation file in the Generated Files Server Location field. This
file must be created on the system on which the Configuration Manager is
running, not on the local system.
If you want to freeze the message set at this time, select the Freeze Message
Set check box. (If the message set is already finalized, you cannot select this
check box.)
You can generate documentation based on categories or messages. The
categories or messages (depending on which you select) defined in this
message set are listed in the Categories or Messages field. You can select a
subset of these for inclusion in the message book. Alternatively, to include them
all, select the Select All check box.
You must select at least one category or one message for successful generation
of documentation. If there is no category listed, you must create one.
4. Click Start.

The message book is generated and written to the specified location: the file
MRM-MAIN.HTML is created, along with a subdirectory named Private. This
subdirectory contains a large number of files, for example, image files and indexes.

178 WebSphere MQ Integrator Working with Messages

 Generating a message book
The description of each element within each compound type included in the
message book indicates whether the element is mandatory or optional. There are
four possible settings:
1. The element can be Optional.
This value is set if the element is optional within its type.
2. The element can be Mandatory if parent present.
This value is set if the element is mandatory within its type.
3. The element can be Always Mandatory.
This is set if the element is associated with a context tag and that context tag is
mandatory within the message for which the documentation has been created.
This setting overrides the values Optional and Mandatory if parent present.
If the element is associated with a context tag and that context tag is optional
within the message, the current setting of Optional or Mandatory if parent
present is not overridden.
4. The element can be Implied Mandatory.
This value is set if one of its descendants has been given the value Always
Mandatory. This value will override the value set for the element in isolation
unless the element itself has the Always Mandatory value.

Repeating elements are indicated by the characters *** after the element name.

Generating a glossary
To generate a glossary:
1. In the Message Sets pane of the Message Sets view, right-click the folder of the
message set or message category for which you want to generate
documentation.
2. Select Generate —> Documentation —> Glossary... from the action list of the
message set.
The Glossary dialog is displayed.
This dialog is identical to the Message Definition Book dialog, except that
only categories are available.
3. Complete the dialog and click Start.

The Glossary is generated and written to the specified location: the file
MAINGLOS.HTML is created, along with a subdirectory named Private. This
subdirectory contains a large number of files, for example, HTML files.

Generating language bindings

You can generate C or COBOL language bindings from message definitions you
have created using the Control Center. To do so, you must have added the
appropriate language binding layer to your message set, and there must be at least
one category defined in your message set.

To generate language bindings:

1. In the Message Sets pane of the Message Sets view, right-click the folder of the
message set for which you want to generate language bindings. Select Generate
—> Language Bindings —> C... or Generate —> Language Bindings —> COBOL....
The language extractor dialog is displayed.
2. In the language extractor dialog, enter the fully qualified name of the directory
of the generated file in the Generated Files Server Location field. If you want to

Chapter 8. Working with MRM messages in the Control Center 179

Generating language bindings
freeze the message set at this time, select the Freeze Message Set check box. (If
the message set is already finalized, you cannot select this check box.)
The categories defined in this message set are listed in the Categories field.
If you are generating C language bindings, you can select a subset of these for
inclusion in the language bindings. You must select at least one category for
successful generation of C language bindings. If no category is listed in this
dialog, you must create one in the message set and re-invoke the generate
action. Select the Select All check box to select all categories.
If you are generating COBOL language bindings, this acts on all categories. You
cannot select individual categories.
3. Click Start.
The requested language bindings are generated and written to the specified
location.

Individual COBOL data structure files are created from the message set. These files
are created with unique filenames, which are always the characters CS followed by
five numbers. The file type is CPY. For example, CS00005.CPY. A mapping file,
CSMAP.TXT, is also generated. This contains the names of the files generated, and
the associated structure names.

The language bindings files that are generated by this process do not map directly
to the content of the source message set and represent only an approximation of
the message structure. You are recommended to use the generated files for
documentation purposes only.

Generating run time dictionaries

You can generate a run time dictionary from a message set. The run time
dictionary represents the definition of the message set in a format that is suitable
for use with applications that use the Common Messaging Interface (CMI).

To generate a run time dictionary:

1. In the Message Sets pane of the Message Sets view, right-click the folder of the
message set for which you want to generate the run time dictionary. Select
Generate —> Runtime Dictionary....
The Generate Runtime Dictionary dialog is displayed.
2. Enter the name of the run time dictionary in the Generated Runtime Dictionary
Server Filename field. This must be an absolute file path on the Configuration
Manager’s system.
3. Select the Freeze Message Set check box if you want to freeze this message set
when you generate the run time dictionary. You might want to select this if you
want to ensure that further changes are not made to the message set that
would affect the validity of your CMI application logic.
4. Click Finish.

The run time dictionary for this message set is generated in the specified location.

The following files are also generated and are written to the directory
install_dir\log:
v rtderror.log. This file contains status messages about the generation of the run
time dictionary.
v rtd.trc. This file shows what has been extracted from the message repository
database for the run time dictionary file.
v rtd.txt. This formatted file shows the contents of the run time dictionary file.

180 WebSphere MQ Integrator Working with Messages

 Generating run time dictionaries
The dictionary contents are composed of the message set’s associated resources
(message schemata and wire formats) expressed in PDF (Portable Data Format, not
Portable Document Format associated with Adobe Acrobat). The PDF content is
enveloped in XML.

An example of the generated file is shown in Figure 28 (the PDF data has been
truncated for simplicity):

<CMIResourceDeploymentTool>
<Deploy>
<MessageSet projectID="DIDA22006S001">
<MessageSetName>XYZ Corp business messages</MessageSetName>
<MessageSetLevel>1</MessageSetLevel>
<DefaultWireFormat>CWF</DefaultWireFormat>
<LogicalFormat encoding="PDF.hex"> 50df50df000002e80002000004e4000200000000000000010...
</LogicalFormat>
<WireFormat formatID="PDF"/>
<WireFormat formatID="CWF" encoding="PDF.hex"> 50df50df000002000002000004e4000200001...
</WireFormat>
<WireFormat formatID="CWF_hp_variant" encoding="PDF.hex"> 50df50df000002000002000004...
</WireFormat>
<WireFormat formatID="CWF_390_variant" encoding="PDF.hex"> 50df50df00000200000200000...
</WireFormat>
</MessageSet>
</Deploy>
</CMIResourceDeploymentTool>

Figure 28. Generated run time dictionary

Generating MRM message set definitions in XML DTDs

If you have defined messages with an XML message format in the message
repository, you can request a Document Type Definition (DTD) to be generated by
the MRM.

To generate a DTD:
1. In the Message Sets pane of the Message Sets view, right-click the folder of the
message set for which you want to generate the DTD. Select Generate —>
DTD....
The Generate DTD dialog is displayed.
2. In the Generate DTD dialog, enter the name of the DTD file in the Generated
DTD Server Filename field. Click Start.

The DTD for this message set is generated as requested and written to the
specified location.

You can import the generated DTD file into another message set, or into another
message repository in a different broker domain. This procedure is described in
“Importing a DTD” on page 177.

Chapter 8. Working with MRM messages in the Control Center 181

Setting up message flows

Setting up message flows to handle these messages

The following sections provide guidelines for setting up message flow nodes when
you are using predefined MRM messages.

For information about manipulating these messages in message flow nodes, see the
WebSphere MQ Integrator ESQL Reference.

Input nodes
If you are using messages in the MRM domain, you can use an MQInput node, an
MQeInput node, or a SCADAInput node to receive messages for processing by the
message flow.

If your incoming messages have an MQRFH or MQRFH2 header, the message

domain, message set, message type, and message format are defined in the mcd
folder of the header. You do not have to customize the input node of your message
flow if you expect all messages to include a header that provides these definitions.
These values are always used in preference to any values set as properties of the
input node.

If your incoming messages do not have an MQRFH or MQRFH2 header, or there

are no values set in the header, you must set up the following properties on the
Default tab of the node properties (these properties are identical for all three input
nodes):
v Set Message Domain to MRM.
v Set the Message Set to the identifier (not the name) of the message set to which
the input message belongs.
v Set the Message Type to the identifier (not the name) of the message that defines
the structure of the input message.
v Set the Message Format to the wire format of the message (for example, CWF).

For more information about configuring these input nodes, see the Control Center
online help.

Output nodes
You can include any of the output nodes in a message flow that processes
messages in the MRM domain. There are no special configuration requirements.

For more information about configuring the output nodes, see the Control Center
online help.

Other nodes
If you have predefined your message to the MRM, you can use any of the supplied
IBM primitive nodes. However, you cannot setup a message flow in which an
MRM message that includes repeating components is routed to one of the three
nodes that process NEONMSG domain messages (the NEONMap,
NEONRulesEvaluation, and NEONTransform nodes). If one of these nodes receives
an MRM message that includes repeating components, it produces unpredictable
results.

For more information about configuring these nodes, see the Control Center online
help.

182 WebSphere MQ Integrator Working with Messages

 Chapter 9. C and COBOL default mappings
This chapter describes the defaults that the C and COBOL importers use when
mapping C datatypes or COBOL datatypes to MRM datatypes. The data designer
defining a message set in the Control Center might want to follow these defaults,
but this decision will depend on the business usage of the data.
v Table 84 on page 184 defines the datatype mappings for C structures imported
into the MRM.
The following datatypes are outside the scope of the C importer:
– Pointers.
– Long double.
– Packed data structure.
v Table 85 on page 185 illustrates datatype mapping for common COBOL data
definitions. Columns 1 to 5 in describe some examples of COBOL data
definitions. Columns 6 to 12 describe the equivalent data mappings used to store
these definitions in the MRM.
The following datatypes are outside the scope of the COBOL importer:
– Binary (10 to 18 digits)
– External floating point
– The DBCS datatype
Notes:
1. Column 5 (Internal representation) assumes an ASCII Big Endian code page.
2. Column 12 (Jst.) indicates the justification of the datatype.
| 3. Level 88 is supported.

© Copyright IBM Corp. 2000, 2002 183

 Table 84. C datatypes and their default settings in the MRM

184
C datatype MRM logical type Physical type Length Sign String justification Repeat
Long Integer Integer 4 Signed
Char String Fixed Length 1
Char[10] String Fixed Length 10 Left justify
Char[10][3] String Fixed Length 3 Left justify 10
Char[10][3][6] String Fixed Length 6 Left justify 30
Int Integer Integer 4 Signed
Int[2] Integer Integer 4 Signed 2
Int[2][3] Integer Integer 4 Signed 6
Unsigned Int Integer Integer 4 Unsigned
Unsigned Short Integer Integer 2 Unsigned
C and COBOL default mappings

Float Float Float 4

Double Float Float 8
Short Integer Integer 2 Signed

WebSphere MQ Integrator Working with Messages

Unsigned char Integer Integer 1
Unsigned char[2] Binary Binary 2
(#define)BOOL int Boolean Boolean
(#define)Boolean Boolean Boolean
 Table 85. COBOL datatypes and their default settings in the MRM
1. COBOL 2. Permitted 3. PICTURE and 4. Value 5. Internal 6. MRM 7. Physical 8. Length in 9. Sign 10. 11. Pad. 12. Jst.
datatype symbols USAGE and optional representation Logical type type bytes Virtual char.
SIGN clause dec.
point
External 9 P S V If > 9 digits: extended =num of digits.
decimal (Zoned float If a decimal If sign is
Decimal) fraction: float separate, add 1
Else: integer
PIC S9999 DISPLAY +1234 31 32 33 34 Integer extended 4 Y 0
decimal including
trailing
-1234 31 32 33 74
1234 31 32 33 34
PIC 9999 DISPLAY 1234 31 32 33 34 integer extended 4 N 0
decimal
PIC 99V99 DISPLAY 1234 31 32 33 34 float extended 4 N 2
decimal
PIC S9999 DISPLAY +1234 31 32 33 34 integer extended 4 Y 0
SIGN LEADING decimal including
leading
-1234 71 32 33 34
PIC S9999 DISPLAY +1234 2B 31 32 33 34 integer extended 5 Y separate 0
SIGN LEADING decimal leading
SEPARATE
-1234 2D 31 32 33 34
PIC S9999 DISPLAY +1234 31 32 33 34 2B integer extended 5 Y separate 0
SIGN TRAILING decimal trailing
SEPARATE
-1234 31 32 33 34 2D
Binary 9 P S V integer integer if <5 decimal
digits, 2 bytes
If 5 thru 9
digits, 4 bytes
PIC S9999 BINARY or +1234 04 D2 integer integer 2 Y
COMP or COMP-4 or
COMP-5
-1234 FB 2E

Chapter 9. C and COBOL default mappings

PIC 9999 BINARY or 1234 04 D2 integer integer 2 N
COMP or COMP-4 or
COMP-5
C and COBOL default mappings

185
 Table 85. COBOL datatypes and their default settings in the MRM (continued)

186
1. COBOL 2. Permitted 3. PICTURE and 4. Value 5. Internal 6. MRM 7. Physical 8. Length in 9. Sign 10. 11. Pad. 12. Jst.
datatype symbols USAGE and optional representation Logical type type bytes Virtual char.
SIGN clause dec.
point
Internal 9 P S V If > 9 digits, Rounded down
Decimal float If a result of (Num
(Packed fraction, float of digits+2)/2
Decimal) Else integer
PIC S9999 +1234 01 23 4C integer packed 3 Y
PACKED-DECIMAL or decimal
COMP-3
-1234 01 23 4D
PIC 9999 1234 01 23 4F integer packed 3 N
PACKED-DECIMAL or decimal
C and COBOL default mappings

COMP-3
Internal
floating point

WebSphere MQ Integrator Working with Messages

no PIC clause COMP-1 +1234 44 9A 40 00 float float 4 Y
-1234 C4 9A 40 00
no PIC clause COMP-2 +1234 40 93 48 00 00 00 float float 8 Y
00 00
-1234 C0 93 48 00 00 00
00 00
Alphabetic A PIC A(3) DISPLAY ABC 41 42 43 string fixed 3 chars space L
length
Alphanumeric X PIC XXXX DISPLAY DEF 44 45 46 20 string fixed 4 chars space default
length L
PIC X(4) JUSTIFIED DEF 20 44 45 46 string fixed 4 chars space R
RIGHT length
JUST RIGHT
Alphanumeric X B 0 9 / PIC BX/9 DISPLAY A/3 20 41 2F 33 string fixed 4 chars space L
edited length
Numeric edited B P V Z 9 0/ length in space default
comma symbol chars=sum of R
period symbol + chars in PIC
- CR DB * $ string
excluding V
PIC 9999 0123 30 31 32 33 string fixed 4 space R
length
 Table 85. COBOL datatypes and their default settings in the MRM (continued)
1. COBOL 2. Permitted 3. PICTURE and 4. Value 5. Internal 6. MRM 7. Physical 8. Length in 9. Sign 10. 11. Pad. 12. Jst.
datatype symbols USAGE and optional representation Logical type type bytes Virtual char.
SIGN clause dec.
point
PIC ZZZ9 123 20 31 32 33
PIC $$Z9 $123 24 31 32 33
$12 20 24 31 32
PIC 999V9 1234 31 32 33 34
PIC ZZZV9 1234 31 32 33 34
PIC $ZZZ,ZZ9V.99 $123,456.78 24 31 32 33 2C 34 string fixed 11 space R
35 36 2E 37 38 length

Chapter 9. C and COBOL default mappings

C and COBOL default mappings

187
C and COBOL default mappings

188 WebSphere MQ Integrator Working with Messages

Part 3. Messages in the XML and JMS domains
Chapter 10. The XML domain . . . . . . . 191
Overview. . . . . . . . . . . . . . . 191
XML Declaration . . . . . . . . . . . . 192
XmlDecl . . . . . . . . . . . . . . 192
Version . . . . . . . . . . . . . . 192
Encoding . . . . . . . . . . . . . . 192
Standalone . . . . . . . . . . . . . 193
XML Declaration example . . . . . . . . 193
The XML message body . . . . . . . . . . 193
Element . . . . . . . . . . . . . . 194
Attribute . . . . . . . . . . . . . . 194
Content . . . . . . . . . . . . . . 194
XML message body example: elements,
attributes, and content . . . . . . . . . 194
CDataSection . . . . . . . . . . . . 195
EntityReferenceStart and EntityReferenceEnd 195
Comment. . . . . . . . . . . . . . 196
ProcessingInstruction . . . . . . . . . . 196
AsisElementContent . . . . . . . . . . 197
Document Type Declaration . . . . . . . . 198
DocTypeDecl . . . . . . . . . . . . 198
IntSubset . . . . . . . . . . . . . 198
PublicId . . . . . . . . . . . . . 198
SystemId . . . . . . . . . . . . . 198
NotationDecl . . . . . . . . . . . . 198
Entities . . . . . . . . . . . . . . 199
EntityDecl . . . . . . . . . . . . 199
ParameterEntityDecl . . . . . . . . . 199
ExternalParameterEntityDecl . . . . . . 199
ExternalEntityDecl. . . . . . . . . . 199
UnparsedEntityDecl . . . . . . . . . 199
EntityDeclValue . . . . . . . . . . 200
ElementDef . . . . . . . . . . . . . 200
AttributeList. . . . . . . . . . . . . 200
AttributeDef. . . . . . . . . . . . . 200
AttributeDefValue . . . . . . . . . . 200
AttributeDefDefaultType . . . . . . . 200
AttributeDefType . . . . . . . . . . 200
DocTypePI . . . . . . . . . . . . . 201
WhiteSpace and DocTypeWhiteSpace . . . . 201
DocTypeComment. . . . . . . . . . . 201
XML DTD example . . . . . . . . . . 202
Setting up message flows to handle these messages 206
Input nodes . . . . . . . . . . . . . 206
Output nodes . . . . . . . . . . . . 206
Other nodes . . . . . . . . . . . . . 206

Chapter 11. The JMS domain . . . . . . . 209

Setting up message flows to handle these messages 209
Input nodes . . . . . . . . . . . . . 209
Output nodes . . . . . . . . . . . . 210
Other nodes . . . . . . . . . . . . . 210

© Copyright IBM Corp. 2000, 2002 189

190 WebSphere MQ Integrator Working with Messages
Chapter 10. The XML domain
This chapter discusses how you can create and work with messages defined to the
XML message domain. It contains:
v “Overview”
v “XML Declaration” on page 192
v “The XML message body” on page 193
v “Document Type Declaration” on page 198
v “Setting up message flows to handle these messages” on page 206

A self-defining message can be handled by every IBM-supplied message processing

node. The whole message can be stored in a database, and headers can be added
to or removed from the message as it passes through the message flow.

The information provided here does not provide a full definition or description of
XML terminology, concepts, and message constructs: it is a summary that
highlights aspects that are important when you use XML messages with
WebSphere MQ Integrator. For further information about XML, see the IBM web
site at:
http://www.ibm.com/developer/xml

You can define XML messages to the MRM domain if you choose. For further
information, see Chapter 3, “The MRM domain” on page 23.

Overview
A self-defining XML message carries the information about its content and
structure within the message in the form of a document that adheres to the XML
specification. Its definition is not held anywhere else. When an XML message is
received by the broker, it is interpreted by the XML parser, and an internal
message tree structure is created according to the XML definitions contained within
that message.

A self-defining message is also known as a generic XML message. It does not have a
recorded format.

The name elements used in this description (for example, XmlDecl) are provided
by WebSphere MQ Integrator for symbolic use within the ESQL, and are referred
to as correlation names. The ESQL defines the processing of message content that
is to be performed by the nodes, such as a filter node, within a message flow. They
are not a part of the XML specification itself. You can find examples of ESQL
syntax in WebSphere MQ Integrator ESQL Reference.

Figure 29 illustrates a simple XML message.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>

<!DOCTYPE s1 PUBLIC "http://www.ibm.com/example.dtd" "example.dtd">
<s1>.........</s1>

Figure 29. Example XML message document

© Copyright IBM Corp. 2000, 2002 191

 XML domain
The corresponding syntax element tree (top level elements only) is shown in
Figure 30.

XmlDec1 WhiteSpace DocTypeDec1 WhiteSpace Element

Figure 30. Example XML message syntax element tree

The WhiteSpace elements within the tree are there because of the line breaks in the
original XML document, and have no business meaning. WhiteSpace within an
XML element does have business meaning and is represented using the Content
syntax element (described in “Content” on page 194). WhiteSpace and
DocTypeWhiteSpace are described in “WhiteSpace and DocTypeWhiteSpace” on
page 201.

| The correlation names for XML name elements (for example, Element and
| XmlDecl) equate to a constant value of the form 0x01000000. You can see these
| constants used in the output created by the Trace node when a message, or a
| portion of the message, is traced. These constants are defined in Appendix E of the
| WebSphere MQ Integrator Programming Guide.

XML Declaration
The beginning of an XML message can contain what is called an XML declaration.
An example of a declaration is included in Figure 29 on page 191.

The XML Declaration includes the following correlation names:

v “XmlDecl”
v “Version”
v “Standalone” on page 193
v “Encoding”

XmlDecl
This is a name element that corresponds to the XML declaration itself. The
XmlDecl element is a child of the XML parser and is written to a bit stream first.
Although the XMLDecl element is a named element, its name has no relevance.

The remaining correlation names identify children of XmlDecl.

Version
The version element is a value element and stores the data corresponding to the
version string in the actual declaration. It is always a child of the XmlDecl element.
For example, for the declaration shown above the version element would contain
the string value ″1.0″.

Encoding
The encoding element is a value element and is always a child of the XmlDecl
element. The value of the encoding element is a string that corresponds to the
value of the encoding string in the declaration. In the example shown above the
encoding element would have a value of “UTF-8”.

You cannot specify MQSeries encodings in this element.

192 WebSphere MQ Integrator Working with Messages

 XML Declaration
Standalone
The standalone element defines the existence of an externally defined DTD. It is a
value element and stores the data corresponding to the value of the standalone
string in the declaration. It is always a child of the XmlDecl element. The values
for the standalone element must be the string “yes” or “no”.

“no” indicates that this XML document is not standalone and depends on an
externally defined DTD. “yes” indicates the XML document is self-contained.
However, the current release of WebSphere MQ Integrator does not resolve
externally defined DTDs. Therefore the setting of standalone is irrelevant and is
ignored.

XML Declaration example

Figure 31 and Figure 32 provide an example of the XML Declaration in an XML
document and tree structure form.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

Figure 31. Example XMLDecl document

XmlDec1

Version Encoding Standalone

value=”1.0” value=”UTF-8” value=”yes”

Figure 32. Example XMLDecl tree structure

The XML message body

Every XML message must have a body. The body comprises a top level XML
element that contains all of the message data. The body contains complex XML
markup, which translates to many syntax element types in the parsed tree. Each
syntax element type is introduced here, with a series of example XML fragments.

The following common element types are discussed:

v “Element” on page 194
v “Attribute” on page 194
v “Content” on page 194

More complex XML messages might use some of the following syntax element
types:
v “CDataSection” on page 195
v “EntityReferenceStart and EntityReferenceEnd” on page 195
v “Comment” on page 196
v “ProcessingInstruction” on page 196
v “AsisElementContent” on page 197

Chapter 10. The XML domain 193

XML message body
Element
This syntax element is the default name element supported by the XML parser, and
is one of the most common elements. The name of the syntax element corresponds
to the name of the XML element in the message. This element can have many
children, including Attributes, Elements, and Content.

“tag” is also supported for backward compatibility.

Attribute
This syntax element is the default name-value element supported by the XML
parser. It is used to represent the attributes associated with its parent Element. The
name and value of the syntax element correspond to the name and value of the
attribute being represented. Attribute elements have no children, and must always
be children of an Element.

When Attributes are written to a message, occurrences of ampersand (&), less than
(<), greater than (>), double quote (“), and apostrophe (’) within the attribute value
are replaced by the predefined XML entities &amp;, &lt;, &gt;, &quot;, and &apos;.

“attr” is also supported for backward compatibility.

Content
This syntax element is the default value element supported by the XML parser. It
is used to represent character data (including white space) that is part of the
Element content. There might be many Content elements as children of a single
Element, in which case they are separated by other syntax element types such as
nested Elements or Attributes.

When Content is written to a message, occurrences of ampersand (&), less than (<),
greater than (>), double quote (“), and apostrophe (’) are replaced by the
predefined XML entities &amp;, &lt;, &gt;, &quot;, and &apos;.

“pcdata” is also supported for backward compatibility.

XML message body example: elements, attributes, and

content
Figure 33 and Figure 34 on page 195 provide an example of the XML message body
in an XML document and tree structure form.

<Person age="32" height="172cm">

<Name>Cormac Keogh</Name>
</Person>

Figure 33. Example XML message body document

194 WebSphere MQ Integrator Working with Messages

 XML message body

Element
- name=”person”

Attribute Attribute Content Element Content

- name=”age” - name=”height” - value=”\n” - name=”Name” - value=”\n”
- value=”32” - value=”172cm”

Content
- value=”Cormac Keogh”

Figure 34. Example XML message body tree structure

CDataSection
CData sections in the XML message are represented by the CDataSection value
element. The content of the CDataSection element is the value of the CDataSection
element without the <![CDATA[ that marks the beginning, and without the ]]> that
marks the end of the Cdata section.

For example, the following Cdata section:

<![CDATA[<greeting>Hello, world!</greeting>]]>

is represented by a CDataSection element with a string value of:

"<greeting>Hello, world!</greeting>"

Unlike Content, occurrences of <, >, &, “, and ’ are not translated to their escape
sequences when the CDataSection is written out to a serialized message.

EntityReferenceStart and EntityReferenceEnd

When an entity reference is encountered in the XML message both the expanded
form and the original entity name are stored in the syntax element tree. The name
of the entity is stored as the value of both the EntityReferenceStart and
EntityReferenceEnd syntax elements, and any syntax elements between contain the
entity expansion.

Figure 35 and Figure 36 on page 196 provide an example of the XML entity
references in an XML document and tree structure form.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<!DOCTYPE example [ <!ENTITY entityName "eValue"> ]>
<example>Test: &entityName;</example>

Figure 35. Example XML Entity reference document

Chapter 10. The XML domain 195

XML message body

Element
- name=”example”

Content EntityReferenceStart Content EntityReferenceEnd

- value=”Test: ” - value=”entityName” - value=”eValue” - name=”entityName”

Figure 36. Example XML Entity reference tree structure

The XML Declaration and the Document Type Declaration are not shown here.
Refer to “XML Declaration” on page 192 and “Document Type Declaration” on
page 198 for details of those sections of the syntax element tree.

Comment
When an XML comment is encountered outside of the Document Type Declaration,
it is represented by the Comment value syntax element. The value of the element
is the comment text from the XML message.

Figure 37 and Figure 38 provide an example of the XML comment in an XML

document and tree structure form.

<example><!-- This is a comment --></example>

Figure 37. Example XML comment document

Element
- name=”example”

Comment
- value=” This is a comment ”

Figure 38. Example XML comment tree structure

ProcessingInstruction
When an XML processing instruction is encountered outside of the Document Type
Declaration, it is represented by the ProcessingInstruction name-value syntax
element. The name of the syntax element is the processing instruction target name,
and the value of the syntax element is the character data of the processing
instruction. The value of the syntax element must not be empty. The name cannot
be ”XML“, or any uppercase or lowercase variation of ”XML“.

Figure 39 and Figure 40 on page 197 provide an example of the XML message body
in an XML document and tree structure form.

<example><?target This is a PI.?></example>

Figure 39. Example XML processing instruction document

196 WebSphere MQ Integrator Working with Messages

 XML message body

Element
- name=”example”

ProcessingInstruction
- name=”target
- value=”This is a PI.”

Figure 40. Example XML processing instruction tree structure

AsisElementContent
This syntax element is a special value element. It is used to precisely control the
XML generated in an output message without the safeguards of the normal
Element, Attribute, and Content syntax elements. If you use AsisElementContent, it
is your responsibility to ensure that the output message is well formed XML.

You might choose to use this syntax element, for example, if you want to suppress
the normal behavior in which occurrences of ampersand (&), less than (<), greater
than (>), double quote (“), and apostrophe (’) are replaced by the predefined XML
entities &amp;, &lt;, &gt;, &quot;, and &apos;.

The following example illustrates the use of AsisElementContent. The statement:

Set OutputRoot.XML.(XML.Element)Message.(XML.Content) = ’<rawMarkup>’;

generates the following XML in an output message:

<Message>&lt;rawMarkup&gt;</Message>

However, the statement:

Set OutputRoot.XML.(XML.Element)Message.(XML.AsisElementContent) = ’<rawMarkup>’;

generates the following output message:

<Message><rawMarkup></Message>

This shows that the value of an AsisElementContent syntax element is not

modified before is it written to the output message.

Chapter 10. The XML domain 197

XML DTD

Document Type Declaration

The document type declaration (DTD) of an XML message is represented by a
syntax element of type DocTypeDecl and its children and descendants. These
comprise the DOCTYPE construct.

Only internal DTD subsets are represented in the syntax element tree. External
DTD subsets (identified by the SystemID or PublicId elements described below)
can be referenced in the message but those referenced are not resolved by the
broker.

The following correlation names are defined by WebSphere MQ Integrator:

v “DocTypeDecl”
v “NotationDecl”
v “Entities” on page 199
v “ElementDef” on page 200
v “AttributeList” on page 200
v “AttributeDef” on page 200
v “DocTypePI” on page 201
v “WhiteSpace and DocTypeWhiteSpace” on page 201
v “DocTypeComment” on page 201

Following these descriptions, there is an example of an XML DTD, in “XML DTD

example” on page 202.

DocTypeDecl
The DocTypeDecl is a named element and is a child of the XML parser. It is
written to the bit stream before the element that represents the body of the
document during serialization. The following can be specified within this element:
v “IntSubset”
v “PublicId”
v “SystemId”

IntSubset
IntSubset is a named element that groups all of those elements that represent the
DTD constructs contained in the internal subset of the message. Although the
IntSubset element is a named element its name is not relevant.

PublicId
PublicId represents a general public identifier construct found in an XML message.
It can be a part of a DocTypeDecl or a NotationDecl element. The value of the
PublicId is typically a URL.

SystemId
SystemId is a value element and is used to represent a general system identifier
construct found in an XML message. It can be a part of a DocTypeDecl or a
NotationDecl element. The value of the SystemId is a URI, and is typically a URL
or the name of a file on the current system. A system identifier of the form SYSTEM
“Note.dtd” has a string value of “Note.dtd”.

NotationDecl
The NotationDecl element represents a notation declaration in an XML message. It
is a name element whose name corresponds to the name given with the notation
declaration. It must have a SystemId as a child, and it can optionally have a child
element of type PublicId.

198 WebSphere MQ Integrator Working with Messages

 XML DTD
Entities
Entities in the DTD are represented by one of six named element types described
below.
v “EntityDecl”
v “ParameterEntityDecl”
v “ExternalParameterEntityDecl”
v “ExternalEntityDecl”
v “UnparsedEntityDecl”
v “EntityDeclValue” on page 200

EntityDecl
The EntityDecl element represents a general entity and is declared in the internal
subset of the DTD. It is a named element and has a single child element which is
of type EntityDeclValue.

An entity declaration of the form:

<!ENTITY bookTitle “User Guide”>

has an EntityDecl element of name “bookTitle”, and a child element of type

EntityDeclValue with a string value of “User Guide”.

ParameterEntityDecl
The ParameterEntityDecl represents a parameter entity definition in the internal
subset of the DTD. It is a named element and has a single child element that is of
type EntityDeclValue. For parameter entities the name of the entity does not
include the percent sign %. In XML a parameter entity declaration takes the form:
<!ENTITY % inline "#PCDATA | emphasis | link">

ExternalParameterEntityDecl
The ExternalParameterEntityDecl represents a parameter entity definition where
the entity definition is contained externally to the current message. It is a named
element and has a child of type SystemId. It can also have a child of type PublicId.
The name of the entity does not include the percent sign %. In XML an external
parameter entity declaration takes the form:
<!ENTITY % bookDef SYSTEM "BOOKDEF.DTD">

This is represented by an ExternalParameterEntityDecl element of name “bookDef”

with a single child of type SystemId with a string value of “BOOKDEF.DTD”.

ExternalEntityDecl
The ExternalEntityDecl element represents a general entity where the entity
definition is contained externally to the current message. It is a named element and
has a child of type SystemId. It can also have a child of type PublicId.

An external entity declaration of the form:

<!ENTITY bookAppendix SYSTEM “appendix.txt”>

has an EntityDecl element of name “bookAppendix” and a child element of type

SystemId with a string value of “appendix.txt”.

UnparsedEntityDecl
An unparsed entity is an external entity whose external reference is not parsed by
an XML processor.

The UnparsedEntityDecl is named element. It has a child of type SystemId and

optionally a child of type PublicId. The presence of NDATA after the SystemId in

Chapter 10. The XML domain 199

XML DTD
the entity declaration indicates that this entity is not parsed by the XML processor.
After NDATA is the name of a corresponding notation declaration. In XML an
unparsed entity declaration takes the form:
<!ENTITY pic SYSTEM "scheme.gif" NDATA gif>
v NotationReference
The NotationReference value element represents a reference to a notation
declaration from within an UnparsedEntityDecl element. It is always a child of
an UnparsedEntityDecl element.

EntityDeclValue
This value element represents the value of an EntityDecl, or a ParameterEntityDecl
defined internally in the DOCTYPE construct. It is always a child of an element of
one of those types, and is a value element. For the following entity:
<!ENTITY bookTitle "User Guide">

the EntityDeclValue element has the string value “User Guide”.

ElementDef
The ElementDef name-value element represents the <!ELEMENT construct in a DTD.
The name of the element that is defined corresponds to the name member of the
syntax element. The value member corresponds to the element definition.

AttributeList
The AttributeList name element represents the <!ATTLIST construct in a DTD. The
name of the AttributeList element corresponds to the name of the element for
which the list of attributes is being defined.

AttributeDef
The AttributeDef name element describes the definition of an attribute within a
<!ATTLIST construct. It is always a child of the AttributeList element. The name of
the syntax element is the name of the attribute being defined. It can have three
children:
v “AttributeDefValue”
v “AttributeDefDefaultType”
v “AttributeDefType”

AttributeDefValue
For attributes of type CDATA (see AttributeDefType below), or defined by an
enumerated list, the AttributeDefValue gives the default value of the attribute.

AttributeDefDefaultType
The AttributeDefDefaultType syntax element is a value element which represents
the attribute default as defined under the attribute definition. The value can be one
of the following strings:
v #REQUIRED
v #IMPLIED
v #FIXED

AttributeDefType
The AttributeDefType syntax element is a name-value element whose name
corresponds to the attribute type found in the attribute definition. Possible values
for the name are:
v CDATA
v ID
v IDREF

200 WebSphere MQ Integrator Working with Messages

 XML DTD
v IDREFS
v ENTITY
v ENTITIES
v NMTOKEN
v NMTOKENS
v NOTATION

If there is an enumeration present for the attribute definition, the entire

enumeration string is held as a string in the value member of the name-value
syntax element. In this case, the name member of the name-value syntax element is
empty. The value string starts with an open parenthesis “(” and ends with a close
parenthesis “)”. Each entry in the enumeration string is separated by a “|”
character. If the Attribute value is not defined by an enumerated list, the value
member of the syntax element is empty.

DocTypePI
The DocTypePI element represents a processing instruction found within the DTD.
The ProcessingInstruction element represents a processing instruction found in the
XML message body.

This element is a name-value element. The name of the element is used to store the
processing instruction target name, and the value contains the character data of the
processing instruction. The value of the element can be empty. The name cannot be
the string “XML” or any uppercase or lowercase variation of “XML”.

WhiteSpace and DocTypeWhiteSpace

The DocTypeWhiteSpace element represents white space that is found inside the
DTD that is not represented by any other element. The WhiteSpace element
represents any white space characters that are found outside the message body and
DTD that are not represented by any other element. Both are value elements.

For example, white space within the body of the message is reported as element
content using the Content element type, but white space characters found between
the XML declaration and the beginning of the message body are represented by the
WhiteSpace element.
<?xml version=“1.0”?> <BODY>....</BODY>

The characters between “1.0”?>“ and <BODY> are represented by the WhiteSpace
element. White space characters found within a DocType between two definitions
are represented by the DocTypeWhiteSpace element.
<!ENTITY % bookDef SYSTEM "BOOKDEF.DTD"> <!ENTITY bookTitle "User Guide">

The characters between DTD”> and <!ENTITY are represented by the

DocTypeWhiteSpace element.

DocTypeComment
Comments in the XML DTD are represented by the DocTypeComment element. It
is a value element for which the value string contains the comment text.

Chapter 10. The XML domain 201

XML DTD example
XML DTD example
Figure 41 and Figure 42 provide an example of the XML DTD in an XML document
and tree structure form.

<!DOCTYPE test PUBLIC “//this/is/a/URI/test” “test.dtd” [

<!NOTATION TeX PUBLIC “//this/is/a/URI/TexID” “//TexID”>
<!ENTITY ent1 “this is an entity”>
<!ENTITY % ent2 “#PCDATA | subel2”>
<!ENTITY % extent1 PUBLIC “//this/is/a/URI/extent1” “more.txt”>
<!ENTITY extent2 PUBLIC “//this/is/a/URI/extent2” “more.txt”>
<!ENTITY unpsd PUBLIC “//this/is/a/URI/me.gif” “me.gif” NDATA TeX> <?test Do this?>
<!--this is a comment-->
<!ELEMENT subel2 (#PCDATA)>
<!ELEMENT subel1 (subel2 | el4)+>
<!ELEMENT el1 (#PCDATA)>
<!ELEMENT el2 (#PCDATA | subel2)*>
<!ELEMENT el3 (#PCDATA | subel2)*>
<!ELEMENT el4 (#PCDATA)>
<!ELEMENT el5 (#PCDATA | subel1)*>
<!ELEMENT el6 (#PCDATA)>
<!ATTLIST subel1
size (big | small) “big”
shape (round | square) #REQUIRED>
<!ATTLIST el5
el5satt CDATA #IMPLIED>
]>

Figure 41. Example XML DTD document

When a message is parsed by the generic XML parser, the relevant part of the
message tree would look like this (assuming there are no carriage returns or white
space between tags):

XML

DocTypeDec1
- name=”test”

SystemId PublicId IntSubset

- value=”test.dtd” - value=”//this/is/a/URI/test”

Figure 42. Example XML DTD tree structure

The IntSubset structure contains the following structures at the next level of
nesting: the tree structure for each of these is shown in Figure 43 on page 203.

202 WebSphere MQ Integrator Working with Messages

 XML DTD example

NotationDecl
- name=”teX”

SystemId PublicId
- value=”//TexID” - value=”//this/is/a/URI/TexID”

EntityDecl
- name=”ent1”

EntityDeclValue
- value=”this is a entity”

ParameterEntityDecl
- name=”ent2”

EntityDeclValue
- value=”#PCDATA | subel2”

ExternalParameterEntityDecl
- name=”extent1”

SystemId PublicId
- value=”more.txt” - value=”//this/is/a/URI/extent2”

Figure 43. Example XML IntSubset tree structures (Part 1 of 3)

Chapter 10. The XML domain 203

XML DTD example

ExternalEntityDecl
- name=”extent2”

SystemId PublicId
- value=”more.txt” - value=”//this/is/a/URI/extent2”

UnparsedEntityDecl
- name=”unpsd”

SystemId PublicId NotationReference

- value=”me.gif” - value=”//this/is/a/URI/me.gif” - value=”TeX”

DocTypeWhiteSpace
- value=” ”

DocTypePI
- name=”test”
- value=”Do this”

DocTypeComment
- value=”this is a comment”

ElementDef
- name=”subel2”
- value=”(#PCDATA)”

ElementDef
- name=”subel1”
- value=”Subel2 | el4”

ElementDef
- name=”el1”
- value=”(#PCDATA)”

ElementDef
- name=”el2”
- value=”(#PCDATA | Subel2)*”

ElementDef
- name=”el3”
- value=”(#PCDATA | Subel2)*”

Figure 44. Example XML IntSubset tree structures (Part 2 of 3)

204 WebSphere MQ Integrator Working with Messages

 XML DTD example

ElementDef
- name=”el4”
- value=”(#PCDATA)”

ElementDef
- name=”el5”
- value=”(#PCDATA | Subel1)*”

ElementDef
- name=”el6”
- value=”(#PCDATA)”

AttributeList
- name=”Subel1”

AttributeDef AttributeDef
- name=”size” - name=”shape”

AttributeDefType AttributeDefValue
- value=”(big | small)” - value=”big”

AttributeDefDefaultType AttributeDefType
- value=”REQUIRED” - value=”(round | square)”

AttributeList
- name=”el5”

AttributeDef
- name=”el5satt”

AttributeDefType AttributeDefDefaultType
- name=”CDATA” - value=”IMPLIED”

Figure 45. Example XML IntSubset tree structures (Part 3 of 3)

Chapter 10. The XML domain 205

Setting up message flows

Setting up message flows to handle these messages

The following sections provide guidelines for setting up input and output nodes.
There are no other specific requirements for generic XML messages.

For information about manipulating these messages in message processing nodes,

see the WebSphere MQ Integrator ESQL Reference.

Input nodes
If you are using messages in the XML domain, you can use any of the three
supplied input nodes (MQInput, MQeInput, or SCADAInput) to receive messages
for processing by the message flow. You can also provide your own plug-in input
node. For more information about supplied and plug-in input nodes, see “Using
the supplied input nodes and parsers” on page 8 and “Using plug-in nodes and
parsers” on page 10.

If your incoming messages have an MQRFH or MQRFH2 header, the message

domain is defined in the mcd folder of the header. If you are using a supplied input
node, you do not have to customize it if you expect all messages to include a
header that provides these definitions. These values are always used in preference
to any values set as properties of the input node.

If your incoming messages do not have an MQRFH or MQRFH2 header, or there

are no values set in the header, you must set up the following properties on the
Default tab of the node properties (these properties are identical for all three input
nodes):
v Set Message Domain to XML.
v Leave Message Set, Message Type, and Message Format blank.

If you are using a plug-in input node, you must refer to the properties and
behavior of that node to determine how it must be customized to handle these
messages.

For more information about configuring these input nodes, see the Control Center
online help.

Output nodes
You can include any of the output nodes in a message flow that processes
messages in the XML domain. There are no special configuration requirements.

For more information about configuring the output nodes, see the Control Center
online help.

Other nodes
If you are using generic XML messages, you cannot use the following supplied
IBM primitive nodes, which require predefined messages to enable drag and drop
operations:
v DataDelete
v DataInsert
v DataUpdate
v Extract
v Warehouse

206 WebSphere MQ Integrator Working with Messages

 Setting up message flows
You cannot use the following nodes, which depend on an MRM definition that
includes message set, type, and format identifiers:
v Check
v ResetContentDescriptor

You can, however, achieve the function that these nodes provide by coding the
appropriate ESQL in a Compute or Database node. See the WebSphere MQ
Integrator ESQL Reference book for further guidance.

For more information about configuring these nodes, see the Control Center online
help.

Chapter 10. The XML domain 207

208 WebSphere MQ Integrator Working with Messages
Chapter 11. The JMS domain
This chapter provides additional specific information for the JMS message domain.
Two JMS message types, JMSMap and JMSStream, are supported by WebSphere
MQ Integrator. These message types map naturally to the XML domain, and are
therefore supported in an identical fashion to XML messages.

You can define JMS messages to the MRM domain if you choose. For further
information, see Chapter 3, “The MRM domain” on page 23.

Setting up message flows to handle these messages

The following sections provide guidelines for setting up input and output nodes.
There are no other specific requirements for JMS messages.

For information about manipulating these messages in message processing nodes,

see the WebSphere MQ Integrator ESQL Reference.

Input nodes
If you are using messages in the JMS domain, you can use any of the three
supplied input nodes (MQInput, MQeInput, or SCADAInput) to receive messages
for processing by the message flow. You can also provide your own plug-in input
node. For more information about supplied and plug-in input nodes, see “Using
the supplied input nodes and parsers” on page 8 and “Using plug-in nodes and
parsers” on page 10.

If your incoming messages have an MQRFH or MQRFH2 header, the message

domain is defined in the mcd folder of the header. If you are using a supplied input
node, you do not have to customize it if you expect all messages to include a
header that provides these definitions. These values are always used in preference
to any values set as properties of the input node.

If your incoming messages do not have an MQRFH or MQRFH2 header, or there

are no values set in the header, you must set up the following properties on the
Default tab of the node properties (these properties are identical for all three input
nodes):
v Set Message Domain to either JMSMap or JMSStream.
v Leave Message Set, Message Type, and Message Format blank.

If you are using a plug-in input node, you must refer to the properties and
behavior of that node to determine how it must be customized to handle these
messages.

For more information about configuring these input nodes, see the Control Center
online help.

© Copyright IBM Corp. 2000, 2002 209

JMS domain
Output nodes
You can include any of the output nodes in a message flow that processes
messages in the JMS domain. There are no special configuration requirements.

For more information about configuring the output nodes, see the Control Center
online help.

Other nodes
If you are using JMS messages, you cannot use the following supplied IBM
primitive nodes, which require predefined messages to enable drag and drop
operations:
v DataDelete
v DataInsert
v DataUpdate
v Extract
v Warehouse

You cannot use the following nodes, which depend on an MRM definition that
includes message set, type, and format identifiers:
v Check
v ResetContentDescriptor

You can, however, achieve the function that these nodes provide by coding the
appropriate ESQL in a Compute or Database node. See the WebSphere MQ
Integrator ESQL Reference book for further guidance.

For more information about configuring these nodes, see the Control Center online
help.

210 WebSphere MQ Integrator Working with Messages

Part 4. Messages in the New Era of Networks domains
Chapter 12. The New Era of Networks domains 213
The NEONMSG domain. . . . . . . . . . 214
The NEONMSG message body parser . . . . 214
Transforming from XML and MRM to
NEONMSG . . . . . . . . . . . . 215
Setting up message flow nodes to handle
NEONMSG messages . . . . . . . . . 216
Input nodes . . . . . . . . . . . . 216
NEONTransform node . . . . . . . . 217
The NEONMap node. . . . . . . . . 218
The NEONRulesEvaluation node . . . . . 219
Creating a NEONMSG domain message in a
Compute node . . . . . . . . . . . 223
Output nodes . . . . . . . . . . . 223
Other nodes . . . . . . . . . . . . 224
The NEON domain . . . . . . . . . . . 224
The NEON message body parser . . . . . . 224
Setting up message flow nodes to handle NEON
messages . . . . . . . . . . . . . . 225
Input nodes . . . . . . . . . . . . 225
NeonFormatter . . . . . . . . . . . 226
NeonRules . . . . . . . . . . . . 226
Output nodes . . . . . . . . . . . 226
Other nodes . . . . . . . . . . . . 226
Control Center support for New Era of Networks
messages . . . . . . . . . . . . . . . 227

© Copyright IBM Corp. 2000, 2002 211

212 WebSphere MQ Integrator Working with Messages
Chapter 12. The New Era of Networks domains
WebSphere MQ Integrator supports two domains for New Era of Networks
messages, NEONMSG and NEON. Parsers are provided to interpret these
messages on receipt by a message flow.

The two domains are supported by message processing nodes (NEONMap,

NEONRulesEvaluation, and NEONTransform for NEONMSG domain, and
NeonFormatter and NeonRules for the NEON domain). The nodes that process
messages in the NEONMSG domain provide more comprehensive processing, and
you are recommended to use this domain for all messages that you define as New
Era of Networks messages.

You must use the New Era of Networks graphical user interfaces to define the
messages to both domains, and to define the processing rules that are used by the
New Era of Networks nodes. The interfaces provided are the New Era of
Networks Formatter and the New Era of Networks Rules. These are accessible
from the Control Center, which also provides some support for these message
formats. For further details, see “Control Center support for New Era of Networks
messages” on page 227.

The message processing model in WebSphere MQ Integrator has three stages: the
incoming message is parsed, it is processed, and it is reserialized into an output
format. The processing stage takes place on a logical message model: a tree
structure that holds the data content of the message in a way that is independent
of the wire format.

The NEON parser cannot reserialize an output message: a message in the NEON
domain is simply reformatted from one wire format to another. The NEONMSG
parser can translate wire format messages in its domain into WebSphere MQ
Integrator message trees on input, and regenerate the message as a New Era of
Networks format on output. However, it can only reserialize messages defined as
outputs in the New Era of Networks Rules and Formats database, or messages
defined as input formats in the New Era of Networks Rules and Formats database,
that have not been modified by the message flow.

For further information about working with these messages, refer to the New Era of
Networks Rules and Formatter Support for WebSphere MQ Integrator User’s Guide.

For information about creating and accessing the New Era of Networks database,
in which these rules and formats are maintained, see the WebSphere MQ Integrator
Administration Guide.

This chapter discusses the two domains and the setup required for message flows
that process these messages:
v “The NEONMSG domain” on page 214
v “The NEON domain” on page 224

© Copyright IBM Corp. 2000, 2002 213

NEONMSG domain

The NEONMSG domain

The NEONMSG domain is the preferred message domain for messages that you
have defined to the New Era of Networks database. Messages in the NEONMSG
domain are parsed by the NEONMSG parser, which translates wire format
messages in its domain into WebSphere MQ Integrator message trees on input, and
regenerates the message on output.

This parser handles messages that can be processed in the NEONMap,

NEONRulesEvaluation, and NEONTransform nodes.

A NEONMSG message can also be handled by all other IBM-supplied message

processing nodes, with the exception of the NeonFormatter and NeonRules nodes
(which handle only messages in the NEON domain). The whole message can be
stored in a database, and headers can be added to or removed from the message as
it passes through the message flow. The message contents can be manipulated by
the Compute, Filter, Database, DataDelete, DataInsert, DataUpdate, and Warehouse
nodes.

The NEONMSG message body parser

The NEONMSG parser can only parse messages that are defined as input formats
in the New Era of Networks database. It uses the Message Type property (specified
in the MQRFH or MQRFH2 header in the message, or as a property on the input
node that receives this message) to identify the input format in the database. If an
input format with the name specified in the Message Type property does not exist,
an exception is thrown by the node that attempts to access the message body.

The structure of the message tree generated by the NEONMSG parser is

two-dimensional. The top level format name is omitted from the tree, because this
information is contained in the message properties. Each component input format
below the top level is added as a vertical layer to the tree. Fields of a flat input
format are added as children of the owning format. For example, a format defined
to the New Era of Networks Formatter user interface as follows:

[-]...> CompoundIn1
|
[-]...> FlatIn1
| |
| |...> Field1
|
[-]...> FlatIn2
|
|...> Field2

Figure 46. Sample New Era of Networks input message

Results in the generation of the following message tree:

(0x1000000)NEONMSG = (
(0x1000002)FlatIn1 = (
(0x3000001)Field1 = ’some data’
)
(0x1000002)FlatIn2 = (
(0x3000001)Field2 = ’some more data’
)
)

214 WebSphere MQ Integrator Working with Messages

 NEONMSG parser
The NEONMSG parser creates vertical levels in the message tree to represent the
component formats of a “compound format” message. New Era of Networks
formats are divided into flat formats that contain only data fields, and compound
formats (a term specific to New Era of Networks) that contain both flat formats
and other compound formats. The data content of the fields depends on the values
present in the incoming message.

The resulting message tree is like that shown in Figure 1 on page 13. The name of
the top-level format is omitted from the message tree because this information is
contained in the message properties. Each component input format becomes a
vertical level in the tree. Fields of a flat format become children of the format that
owns them.

For information about using ESQL to access New Era of Networks messages in
message processing nodes, see the WebSphere MQ Integrator ESQL Reference book.

Transforming from XML and MRM to NEONMSG

You can use the facilities provided by the message processing nodes and the
brokers to transform an input MRM or XML message to an output NEONMSG
message. However, you must be aware that the NEONMSG parser does not
recognize repeating fields in these messages: if the input message includes
repeating fields the output message generated will not accurately reflect the input.
v If the input message is an XML message, you can manually edit the message to
insert the attribute NNSY-XML-repeating="true" to each repeating field. For
example, an input message might contain:
<PurchaseOrder>
<CustomerName>IBM</CustomerName>
<OrderDetail> <PartNum>1234-L</PartNum>
<PartDesc>Large Widget</PartDesc>
</OrderDetail>
<OrderDetail>
<PartNum>1234-M</PartNum>
<PartDesc>Medium Widget</PartDesc>
</OrderDetail>
<OrderDetail>
<PartNum>1234-S</PartNum>
<PartDesc>Small Widget</PartDesc>
</OrderDetail>
</PurchaseOrder>

You must manually edit this to contain:

<PurchaseOrder>
<CustomerName>IBM</CustomerName>
<OrderDetail NNSY-XML-repeating="true">
<PartNum>1234-L</PartNum>
<PartDesc>Large Widget</PartDesc>
</OrderDetail>
<OrderDetail NNSY-XML-repeating="true">
<PartNum>1234-M</PartNum>
<PartDesc>Medium Widget</PartDesc>
</OrderDetail>
<OrderDetail NNSY-XML-repeating="true">
<PartNum>1234-S</PartNum>
<PartDesc>Small Widget</PartDesc>
</OrderDetail>
</PurchaseOrder>
v If the input message is MRM, the message cannot be manipulated and any
repeating fields will be lost in this transformation.

Chapter 12. The New Era of Networks domains 215

 Setting up message flows for NEONMSG messages
Setting up message flow nodes to handle NEONMSG
messages
The following sections describe how you can set up nodes within a message flow
that processes messages in the NEONMSG domain.

For information about manipulating these messages in message processing nodes,

see the WebSphere MQ Integrator ESQL Reference.

Input nodes
If you are using messages in the NEONMSG domain, you can use an MQInput
node, an MQeInput node, or a SCADAInput node to receive messages for
processing by the message flow. You can also provide you own plug-in input node.
For more information about supplied and plug-in input nodes, see “Using the
supplied input nodes and parsers” on page 8 and “Using plug-in nodes and
parsers” on page 10.

| If your incoming messages have an MQRFH or MQRFH2 header, the message

| domain, message set, message type, and message format are retrieved from the mcd
| folder of the header. However, the presence of an MQRFH header causes the
| NEON parser to be used, therefore you must customize the input node of your
| message flow to specify the NEONMSG domain. Other properties can be retrieved
| from the header. You therefore do not need to customize other properties of the
| input node if you expect all messages to include a header that provides these
| definitions. The header information is always used in preference to any values set
| as properties of the input node.

If your incoming messages do not have an MQRFH or MQRFH2 header, or there

are no values set in the header, you must set up the following properties on the
Default tab of the node properties (these properties are identical for all three input
nodes):
v Set Message Domain to NEONMSG.
v Set Message Set to the name of the New Era of Networks Formatter Application
Group that defines the rules by which this message must be processed. This field
is only used by the NEONRulesEvaluation node. If your message flow does not
contain an instance of this node, you can leave this field blank.
v Set Message Type to the defined input format.
v Leave Message Format blank. (This value is required for other message domains
only.)

| You can specify a field from the MQMD to determine the Message Set and Message
| Type, if appropriate. You can select one of:
| v $MQMD.Format
| v $MQMD.PutAplName
| v $MQMD.ApplIdentityData

| This behavior is consistent with the way in which the MQSeries Integrator Version
| 1 products set the default message set and message type. (If your New Era of
| Networks database is Oracle, you must ensure that these fields, if used, do not
| contain leading blanks.)

| If your incoming messages include NULL characters, these are not handled
| correctly by the NEONMSG parser. The NULL character is interpreted as a field
| terminator. You must modify these messages to use the data type Not Applicable
| to ensure that NULLs are handled and preserved in the data.

216 WebSphere MQ Integrator Working with Messages

 Setting up message flows for NEONMSG messages
For more information about configuring these input nodes, see the Control Center
online help.

NEONTransform node
The NEONTransform node transforms a message from a known input format to a
specified output format using map objects that you must define using the New Era
of Networks Formatter user interface. These objects provide a way of explicitly
mapping input message fields to output message fields.

A message in the NEONMSG domain can be put into a message flow in a

particular input wire format, and a NEONTransform node can be used to convert
the input message into a generic format, specifying as part of this operation the
ultimate wire format in which the message should be output from the message
flow (not just in which the message should be output from the node itself).

When the message is reserialized at a ResetContentDescriptor node attached to a

NEONTransform node or at an MQOutput node, the NEONMSG parser
automatically performs the necessary transform operation to convert the message
into the specified output wire format. (The NEONMap node also provides this
function.)

After mapping from input to output format, the NEONTransform node performs
the output operations specified for each field in the target format (also defined
using the New Era of Networks Formatter user interface). This might include
changing the data in some way. For example, if a field in an output format had an
upper casing output operation specified, the incoming data some data would be
turned by the NEONTransform node into SOME DATA when it was mapped to that
output format.

The output operations might also result in the adding of tags and delimiters to the
message data. For example, a field tagged by F: and delimited by a semicolon
character ; would appear in the output message as F:data;.

Both the input and output formats must be defined in the New Era of Networks
database. You can set properties in the NEONTransform node properties dialog to
influence the processing done by this node.

If you want to convert a NEONMSG message to another message domain (for

example, BLOB), you must use a ResetContentDescriptor node attached to the
appropriate output terminal of the NEONTransform node.

For more information about configuring the NEONTransform node, see the Control
Center online help.

Map Name and Map Version: You can identify the name and version of the map
that is to be used by the node in the Map Name and Map Version properties on the
Basic tab of the NEONTransform node properties. (Map Version is not operational
in the current release.)

See the New Era of Networks Rules and Formatter Support for WebSphere MQ Integrator
User’s Guide for more details of these values.

Output Domain: The Output Domain of a message can be set to either NEONMSG
(the default) or XML. A message with an Output Domain of NEONMSG is output
as a normal NEONMSG domain message. Any subsequent modification or
re-parsing of this message is done by the NEONMSG domain parser.

Chapter 12. The New Era of Networks domains 217

NEONTransform node
If a message is output with an Output Domain of XML, the message tree structure
generated by the NEONMSG parser is used to create an XML message. For
example, a message in the ‘CompoundIn1’ format (shown in Figure 46 on
page 214), would, if output in the XML domain from a NEONTransform node,
consist of the following XML:
<CompoundOut1>
<FlatOut1>
<Field1>some data</Field1>
</FlatOut1>
<FlatOut2>
<Field2>some more data</Field2>
</FlatOut2>
</CompoundOut1>

The outermost XML element consists of the outermost format name. The other
XML elements reflect the structure of the CompoundOut1 output format.

Output Message Type and Output Message Set: By default, the Message Type of
a message output from the NEONTransform node is set to the value of the Target
Format attribute in the message definition. If the Output Message Type property is
explicitly set to a different value, it sets up a delayed transform that is applied to
the message upon reserialization.

Therefore if a NEONTransform node transforms a message from input format

WireIn1 to output format ContentModel1, setting the Output Message Type
attribute to WireOut1, on reserialization (at a ResetContentDescriptor or an output
node), the message is transformed a second time, into the WireOut1 output format.

A message in the NEONMSG domain can be input to a message flow in a

particular input wire format; a NEONTransform or NEONMap node converts this
into a generic format, specifying as part of this operation the ultimate Output
Message Type (output wire format) in which the message should be discharged
from the message flow. When the message is reserialized in anticipation of this
discharge (or due to the intervention of a ResetContentDescriptor node), the
NEONMSG parser automatically performs the necessary transform operation to
convert the message into the specified output wire format. Of course, it is still
possible to use the NEONMap and NEONTransform nodes as simple two-stage
reformat operations if required.

The Output Message Type and Output Message Set properties have no meaning
within the XML domain and therefore, although the Output Message Type and
Output Message Set standard properties are set in the output message as specified,
these values do not affect the subsequent processing of the XML message in any
way. If you set the Output Message Set property when the Output Domain is
NEONMSG, the application group (as defined in the New Era of Networks Rules
user interface) is changed to the group to which the message belongs.

The NEONMap node

The NEONMap node maps message data from the fields of the input format to the
fields of the specified target format according to either the default mapping
(defined for that target format) or the specified Map Name and Map Version.

This node differs from the NEONTransform in that it performs only the mapping
stage of a reformat and does not perform data transformation in the form of
output operations. Because of this, the output message from this node might not be

218 WebSphere MQ Integrator Working with Messages

 NEONMap node
suitable for putting to an output queue. Therefore this node must be followed in
the message flow (at any point before the output node) by a NEONTransform to
apply output format processing.

Refer to “NEONTransform node” on page 217 for properties that you can configure
for this node.

For more information about configuring the NEONMap node, see the Control
Center online help.

The NEONRulesEvaluation node

The NEONRulesEvaluation node processes messages according to the rules
specified in the New Era of Networks database for the current message format.

The Map and Transform actions defined in the rules process a message in an
identical way to the NEONMap and NEONTransform nodes respectively. Because
the NEONRulesEvaluation node processes a message tree (rather than the bit
stream processed by a NeonRules node), multiple Maps or Transforms can be
executed within a single subscription.

To illustrate the differences between the NeonRules and NEONRulesEvaluation

nodes’ behavior in this circumstance, consider the following three formats:
v Input1: flat input format with a single, semicolon delimited field, Field1.
v Output1: flat output format with a single field, also named Field1. The output
control for this field upper cases the field data and suffixes a semicolon to the
end. The mapping for this format is such that Field1 in the output format maps
its data from Field1 in the input format.
v Output2: flat output format with a single field, Field2. The output control for
this field suffixes a semicolon to the end. The mapping for this format is such
that Field2 in the output format maps its data from Field1 in the input format.

Given an input message of format Input1 with the bit stream body some data;, the
effect of applying two Reformat actions in the NeonRules node can be compared
against the effect of applying two Transform actions in the NEONRulesEvaluation
node:
Table 86. Comparison of the functions of the NEONRulesEvaluation node and NeonRules
node
NEONRulesEvaluation node NeonRules node
Transform Reformat
Target Format = Output1 INPUT_FORMAT = Input1
TARGET_FORMAT = Output1
PutQueue PutQueue
When serialized, the output wire When serialized, the output wire
format message body consists of: format message body consists of:
SOME DATA; SOME DATA;
Transform Reformat
Target Format = Output2 INPUT_FORMAT = Input1
TARGET_FORMAT = Output2

Chapter 12. The New Era of Networks domains 219

NEONRulesEvaluation node
Table 86. Comparison of the functions of the NEONRulesEvaluation node and NeonRules
node (continued)
PutQueue PutQueue
When serialized, the output wire When serialized, the output wire
format message body consists of: format message body consists of:
SOME DATA;; SOME DATA;

Note: two semicolons. Note: one semicolon.

The Transform action has no equivalent of the Reformat’s INPUT_FORMAT option.

This is because the Transform action in the NEONRulesEvaluation node takes a
message tree as input and produces a message tree as output, while the Reformat
action in the NeonRules node takes a bit stream as input and produces a bit stream
as output.

The Reformat action has to perform three steps: it must parse the incoming bit
stream, map the resulting input fields to the output format fields (applying any
output operations), and reserialize the output format fields into a new bit stream.
Because the Transform action works directly with message trees, it has no need to
perform the first and third of these steps, and therefore does not need to be told
the format of the input message.

Table 87 and Table 88 on page 221 show the result of each of the above actions:
Table 87. Behavior of the NeonRules node reformat action
Action Behavior
INPUT_FORMAT = Input1 v The incoming message bit stream, some
TARGET_FORMAT = Output1 data; is parsed as input format Input1,
generating the field Field1 with data some
data.
v Field1 from the input format is mapped
to Field2 in the output format Output1.
v Output1 is reserialized, with output
operations applied to produce the bit
stream
SOME DATA;

PutQueue The message is propagated to the putqueue

terminal. It is already serialized so no
further reserialization takes place when it
reaches the output node.

220 WebSphere MQ Integrator Working with Messages

 NEONRulesEvaluation node
Table 87. Behavior of the NeonRules node reformat action (continued)
Reformat v Following the previous reformat, the
INPUT_FORMAT = Input1 message bit stream now consists of
TARGET_FORMAT = Output2 SOME DATA;

This is a valid bit stream for input format

Input1, so it is successfully parsed,
generating the field Field1 with data SOME
DATA
v Field1 from the input format is mapped
to Field3 in the output format Output2.
v Output2 is reserialized, with output
operations applied to produce the bit
stream
SOME DATA;

PutQueue The message is propagated to the putqueue

terminal. It is already serialized so no
further reserialization will take place when it
reaches the output node.

Table 88. Behavior of the NEONRulesEvaluation node transform action

Action Behavior
Transform The incoming message tree (generated by
Target Format = Output1 the NEONMSG parser) consists of:
(0x1000000)NEONMSG = (
(0x3000001)Field1 = ’some data’ )

This is transformed to:

(0x1000000)NEONMSG = (
(0x3000001)Field1 = ’SOME DATA;’ )
PutQueue Output1 is propagated to the putqueue
terminal with the above message tree. When
it reaches the output node the NEONMSG
parser reserializes it into:
SOME DATA;
Transform The incoming message tree (as generated by
Target Format = Output2 the previous Transform action) consists of:
(0x1000000)NEONMSG = (
(0x3000001)Field1 = ’SOME DATA;’ )

This is transformed to:

(0x1000000)NEONMSG = (
(0x3000001)Field2 = ’SOME DATA;;’ )

The output control associated with Field2

causes a semicolon to be added to the data
from the input field Field1. Field1 contained
the data
SOME DATA;

therefore adding an extra semicolon results

in SOME DATA;;.

Chapter 12. The New Era of Networks domains 221

NEONRulesEvaluation node
Table 88. Behavior of the NEONRulesEvaluation node transform action (continued)
PutQueue Output2 is propagated to the putqueue
terminal with the above message tree. When
it reaches the output node the NEONMSG
parser reserializes it into SOME DATA;;.

Single NEONRulesEvaluation Transform actions function identically to single

NeonRules Reformat actions. However, multiple Transform actions within a single
subscription might function differently to multiple Reformat actions within a single
subscription. This means that the behavior of subscriptions executed by the
NEONRulesEvaluation node differs from that in the NeonRules node. You can
avoid this by placing each Transform action in a separate subscription and
attaching the resulting multiple subscriptions to a single rule. This avoids any
problems caused by performing multiple Transforms in a single subscription, while
the overall effect of that rule on the message remains unchanged.

For more information about configuring the NEONRulesEvaluation node, see the
Control Center online help.

Propagate, Put Queue, and Route actions: The Propagate, Put Queue, and Route
actions all result in a message being propagated to the appropriate output terminal
of the NEONRulesEvaluation node. Therefore they all support the Message
Domain, Message Set, and Message Type options. These actions also support the
Output CCSID and Output Encoding attributes, which set the CCSID and
Encoding of the body of the outgoing message to the specified values.

Propagate

This action causes a message to be output from the NEONRulesEvaluation node

through the propagate terminal. This has no attributes in addition to those
described above.

Put Queue

The Put Queue action causes a message to be output from the

NEONRulesEvaluation node through the putqueue terminal. Before it is output,
the DestinationList within the LocalEnvironment tree is updated to reflect the
values of the Target Queue and Target Queue Manager attributes. If the message
output from the putqueue terminal subsequently reaches an MQOutput node that
is configured with a Destination Mode of Destination List, it is placed on the
MQSeries queue specified in the Target Queue attribute, belonging to the MQSeries
queue manager specified in the Target Queue Manager attribute.

The Put Queue action has the following additional attributes:

v MQS Format. Sets the Format field of the MQSeries header immediately
preceding the output message body to the specified value.
v MQS Propagate. If this is set to NO_PROPAGATE, any MQRFH or MQRFH2
header on the input message is not copied to the output message. This is the
default. If it is set to PROPAGATE, any MQRFH or MQRFH2 header is copied to
the output message.
v MQS Persist. This can be set to PERSIST or NO_PERSIST. It sets the Persistence
of the output message (as defined in its standard properties folder) to TRUE or
FALSE respectively. If no value is specified for this attribute the output message
retains the persistence of the input message.

222 WebSphere MQ Integrator Working with Messages

 NEONRulesEvaluation node
v MQS Expiry. If this is set to PROPAGATE, the expiry time of an input message
is copied across to the output message. This is the default. If MQS Expiry is set
to NO_PROPAGATE, the expiry time of the output message is set to Unlimited
(it never expires).
| You can also set numeric values (these are not valid for the NeonRules node):
– The value -1 disables expiry.
– A positive integer (for example, 3) sets the expiry to this value in seconds.

Route

The Route action causes a message to be output from the route terminal of the
NEONRulesEvaluation node. Before it is output, the DestinationList is updated to
reflect the value of the LabelName property. If the message output from the route
terminal subsequently reaches a RouteToLabel node, it might be routed to the
Label node with the name specified in the Label Name attribute, depending on
whether any other Label values have been appended to the DestinationList of the
message, and on the configuration of the RouteToLabel node.

Creating a NEONMSG domain message in a Compute node

You can use the Compute node to create a NEONMSG domain message: however,
you cannot create a NEON domain message in this way. The requirements for
creating a NEONMSG domain message are the same as those for creating any
other domain message: the message body tree must be created and populated, and
the message properties set to reflect the message attributes.

Because the NEONMSG domain parser only reserializes output format message
trees, or input format messages that have a valid bit stream associated with them,
it is only possible to create NEONMSG messages which are defined as output
formats in the New Era of Networks database: input format messages cannot be
created.

When a NEONMSG message is created in this way, the output controls associated
with the format of the created message (as defined by the New Era of Networks
Formatter) are not applied to the message data until it is reserialized. Thus if
Field1 had an associated output control to upper case the contents of the field,
querying the contents of Field1 as it passed through the message flow would show
the value ‘some data’. However, when the message was reserialized and placed on
an output queue, the contents of the field would be ‘SOME DATA’.

For more information about configuring the Compute node, see the Control Center
online help. For an example of creating a NEONMSG in the Compute node, see
the WebSphere MQ Integrator ESQL Reference.

Output nodes
You can include any of the output nodes in a message flow that processes
messages in the NEON domain. There are no special configuration requirements.

For more information about configuring the output nodes, see the Control Center
online help.

Chapter 12. The New Era of Networks domains 223

Creating a NEONMSG in a Compute node
Other nodes
If you are using NEONMSG messages, the following supplied IBM primitive nodes
provide no significant function:
v Check
v DataDelete
v DataInsert
v DataUpdate
v Extract
v Warehouse

You can, however, achieve the function that they provide by coding the
appropriate ESQL in a Compute or Database node. See the WebSphere MQ
Integrator ESQL Reference book for further guidance.

For more information about configuring these nodes, see the Control Center online
help.

The NEON domain

Messages in the NEON domain are parsed by the NEON parser, which translates
wire format messages in its domain into WebSphere MQ Integrator message trees
on input, and regenerates the message on output.

This parser handles messages that can be processed in the NeonFormatter and
NeonRules nodes.

A NEON domain message can also be handled by all other IBM-supplied message
processing nodes, with the exception of the NEONMap, NEONRulesEvaluation,
and NEONTransform nodes (which handle only messages in the NEONMSG
domain). The whole message can be stored in a database, and headers can be
added to or removed from the message as it passes through the message flow.
However, no other nodes can manipulate the message contents.

You are recommended to use the NEONMSG parser, and the NEONMap,
NEONRulesEvaluation, and NEONTransform nodes for all new message flows in
preference to the NEON parser and the NeonFormatter and NeonRules nodes,
because the NEONMSG parser and its nodes provide richer message processing
function.

The NEON message body parser

The NEON parser uses the Message Type property (specified in the MQRFH or
MQRFH2 header in the message, or as a property on the input node that receives
this message) to identify the input format in the database. If an input format with
the name specified in the Message Type property does not exist, an exception is
thrown by the node that attempts to access the message body.

If an MQRFH is included in the message, but the input node has not defined the
message domain, the domain NEON is assumed and no error is generated.

The NEON parser cannot reserialize an output format message, therefore the
NeonFormatter node generates an already-serialized bit stream, rather than a
message tree, as the body of its output message.

224 WebSphere MQ Integrator Working with Messages

 NEON message parser
The NEON parser flattens all the fields in the message to a single vertical level.
The data content of the fields depends on the values present in the incoming
message. An example message received by the parser might be:
[-]...> CompoundIn1
|
[-]...> FlatIn1
| |
| |...> Field1
|
[-]...> FlatIn2
|
|...> Field2

When this message is parsed by the NEON parser, the following is generated:
(0x1000000)NEON = (
(0x3000000)Field1 = ’some data’
(0x3000000)Field2 = ’some more data’
)

For information about using ESQL to access NEON messages in message

processing nodes, see the WebSphere MQ Integrator ESQL Reference book.

Setting up message flow nodes to handle NEON messages

The following sections describe how you must set up nodes within a message flow
that processes messages in the NEON domain.

For information about manipulating these messages in message processing nodes,

see the WebSphere MQ Integrator ESQL Reference.

Input nodes
If you are using messages in the NEON domain, you can use an MQInput node,
an MQeInput node, or a SCADAInput node to receive messages for processing by
the message flow. You can also provide you own plug-in input node. For more
information about supplied and plug-in input nodes, see “Using the supplied
input nodes and parsers” on page 8 and “Using plug-in nodes and parsers” on
page 10.

| If your incoming messages have an MQRFH or MQRFH2 header, the message

| domain, message set, message type, and message format are defined in the mcd
| folder of the header. The presence of an MQRFH header causes the NEON parser
| to be used. You do not have to customize the input node of your message flow if
| you expect all messages to include a header that provides the definitions of the
| other properties. The header information is always used in preference to any
| values set as properties of the input node.

If your incoming messages do not have an MQRFH or MQRFH2 header, or there

are no values set in the header, you must set up the following properties on the
Default tab of the node properties (these properties are identical for all three input
nodes):
v Set Message Domain to NEON.
v Set Message Set to the name of the NEON Application Group to which this
message belongs.
v Set Message Type to the defined input format.
v Leave Message Format blank.

Chapter 12. The New Era of Networks domains 225

 Setting up message flows for NEON messages
| You can specify a field from the MQMD to determine the Message Set and Message
| Type, if appropriate. You can select one of:
| v $MQMD.Format
| v $MQMD.PutAplName
| v $MQMD.ApplIdentityData

| This behavior is consistent with the way in which the MQSeries Integrator Version
| 1 products set the default message set and message type. (If your New Era of
| Networks database is Oracle, you must ensure that these fields, if used, do not
| contain leading blanks.)

| If your incoming messages include NULL characters, these are handled correctly
| by the NEON parser.

For more information about configuring these input nodes, see the Control Center
online help.

NeonFormatter
The NeonFormatter node provides message processing function that is a subset of
that provided by the NEONMap and NEONTransform nodes. It has the following
properties:
v Target Format. This determines the format of the output message. The output
format must be defined in the New Era of Networks database.
v Output format properties. These can be set in the same way as the equivalent
NEONTransform node properties:
– “Output Domain” on page 217
– “Output Message Type and Output Message Set” on page 218

For more information about configuring the NeonFormatter node, see the Control
Center online help.

NeonRules
The NeonRules node provides message processing function that is a subset of that
provided by the NEONRulesEvaluation node. The two nodes are compared in
“The NEONRulesEvaluation node” on page 219. In particular, note that the option
of specifying a numeric value for the MQS Expiry attribute for the the PutQueue
and Propagate actions is not supported.

For more information about configuring the NeonRules node, see the Control
Center online help.

Output nodes
You can include any of the output nodes in a message flow that processes
messages in the NEON domain. There are no special configuration requirements.

Other nodes
If you are using messages defined to the NEON domain, the following supplied
IBM primitive nodes provide no significant function:
v Check
v DataDelete
v DataInsert
v DataUpdate
v Extract
v Warehouse

226 WebSphere MQ Integrator Working with Messages

 NeonRules node
You can, however, achieve the function that they provide by coding the
appropriate ESQL in a Compute or Database node. See the WebSphere MQ
Integrator ESQL Reference book for further guidance.

For more information about configuring these nodes, see the Control Center online
help.

Control Center support for New Era of Networks messages

The Control Center supports messages defined to the two New Era of Networks
domains in the following ways:
v It provides access to the New Era of Networks user interfaces from the Nnsy
menu item in the task bar in the Message Sets view. You can invoke:
– The New Era of Networks Formatter interface. This interface allows you to
create, modify, and delete messages in the NEONMSG and NEON domains.
– The New Era of Networks Rules interface. This interface allows you to create,
modify, and delete processing rules. The rules are used by the New Era of
Networks message processing nodes to determine the processing that is
carried out on the message.
– The Visual Tester. This interface lets you test formats and rules after you have
defined them using the New Era of Networks Formatter and New Era of
Networks Rules interfaces. For example, you can test the parsing,
transformation, and evaluation of messages from and to files, queues, and the
display.
v It displays messages defined to the New Era of Networks database in the
Message Sets view.
To display New Era of Networks messages, you must:
1. Start the New Era of Networks Formatter GUI from the Control Center
Message Sets view (the NNSY item in the taskbar).
2. Create a ‘format collection’ in the New Era of Networks Formatter GUI.
3. Add to the collection those message formats that you want to view in the
Control Center.
4. Add the New Era of Networks message set to your workspace (right-click
Message Sets and select Add to Workspace–>Message Set and select the
message set NNSYMessageSet from the list displayed).
5. Expand the message set and add the messages you want to view to this
message set.

Chapter 12. The New Era of Networks domains 227

Control Center support for New Era of Networks messages

228 WebSphere MQ Integrator Working with Messages

Part 5. Messages in the BLOB domain
Chapter 13. The BLOB domain . . . . . . . 231
Setting up message flows to handle these messages 231
Input nodes . . . . . . . . . . . . . 231
Output nodes . . . . . . . . . . . . 232

© Copyright IBM Corp. 2000, 2002 229

230 WebSphere MQ Integrator Working with Messages
Chapter 13. The BLOB domain
Messages in the BLOB domain can be processed in the following ways:
v The message content can be referenced if the location (offset) of particular
information in the message is known. Offset values can be specified in ESQL
statements within message processing nodes in a message flow to manipulate
the information.
v The message can be stored in an external database, in whole or in part (where
the part is identified by the offset of the data to be stored).

The BLOB message body parser does not create a tree structure in the same way
that other message body parsers do. It has a root element “BLOB”, that has a child
element, also called “BLOB”, that contains the data.

For example, InputBody.BLOB.BLOB[10] identifies the tenth byte of the message

body. substring(InputBody.BLOB.BLOB from 10 for 10) references 10 bytes of the
messages data starting at offset 10.

For more information and examples of how you can use ESQL to manipulate the
content of BLOB messages, see the WebSphere MQ Integrator ESQL Reference book.

Setting up message flows to handle these messages

The following sections provide guidelines for setting up input and output nodes.
There are no other specific requirements for BLOB messages.

For information about manipulating these messages in message processing nodes,

see the WebSphere MQ Integrator ESQL Reference.

Input nodes
If you are using messages in the BLOB domain, you can use any of the three
supplied input nodes (MQInput, MQeInput, or SCADAInput) to receive messages
for processing by the message flow. You can also provide your own plug-in input
node. For more information about supplied and plug-in input nodes, see “Using
the supplied input nodes and parsers” on page 8 and “Using plug-in nodes and
parsers” on page 10.

If your incoming messages have an MQRFH or MQRFH2 header, the message

domain can be defined in the mcd folder of the header. If you are using a supplied
input node, you do not have to customize it if you expect all messages to include a
header that provides these definitions. These values are always used in preference
to any values set as properties of the input node.

If your incoming messages do not have an MQRFH or MQRFH2 header, or there

are no values set in the header, you can set up the following properties on the
Default tab of the node properties (these properties are identical for all three
supplied input nodes):
v Set Message Domain to BLOB.
v Leave Message Set, Message Type, and Message Format blank.

© Copyright IBM Corp. 2000, 2002 231

The BLOB domain
If you do not set these properties, and there are no values in the header (or no
header), BLOB is assumed.

If you are using a plug-in input node, you must refer to the properties and
behavior of that node to determine how it must be customized to handle these
messages.

A message is assumed to be a BLOB message if the input node cannot otherwise

identify it (for example, if there is no MQRFH or MQRFH2 header with the
message, and the input node default domain property is not set).

For more information about configuring these input nodes, see the Control Center
online help.

Output nodes
You can include any of the output nodes in a message flow that processes
messages in the BLOB domain. There are no special configuration requirements.

For more information about configuring the output nodes, see the Control Center
online help.

232 WebSphere MQ Integrator Working with Messages

Part 6. Appendixes

© Copyright IBM Corp. 2000, 2002 233

234 WebSphere MQ Integrator Working with Messages
Appendix A. Element definitions for message parsers
The following sections discuss datatypes for the MQSeries headers, and define the
element names, types, and attributes for each of the supported headers.

The following parsers are described:

v “Data types of fields and elements” on page 236
v “The MQCFH parser” on page 238
v “The MQCIH parser” on page 239
v “The MQDLH parser” on page 240
v “The MQIIH parser” on page 241
v “The MQMD parser” on page 242
v “The MQMDE parser” on page 244
v “The MQRFH parser” on page 245
v “The MQRFH2 parser” on page 246
v “The MQRMH parser” on page 247
v “The MQSAPH parser” on page 248
v “The MQWIH parser” on page 249
v “The SMQ_BMH parser” on page 250

For each parser, the following terms are defined:

v Root element name. This is the name of the syntax element created by the parser
at the root of its own part of the tree.
v Class name. This is the name by which the parser defines itself to WebSphere
MQ Integrator.

© Copyright IBM Corp. 2000, 2002 235

Data types of fields and elements

Data types of fields and elements

The fields contained within MQSeries headers are of a particular data type, and
you must be aware of this to be able to reference the fields correctly when you
manipulate the messages and their headers using ESQL in the message processing
nodes.

Data types of the fields in MQSeries headers

Parsers are supplied for the MQSeries headers listed in “MQSeries header parsers”
on page 8. The mapping of the MQSeries data types to the data types used in
WebSphere MQ Integrator is shown in Table 89.
Table 89. Data types for fields in MQSeries headers
Data type of the field Represented as
MQLONG INTEGER
MQCHAR, MQCHAR4 CHARACTER
MQBYTE, MQBYTEn BLOB

Data types for elements in the Properties folder

A parser is supplied for the Properties folder. The fields and data type of each field
are shown in Table 90.
Table 90. Data types for elements in the Properties folder
Data type of the element Represented as
MessageSet CHARACTER
MessageType CHARACTER
MessageFormat CHARACTER
Encoding INTEGER
CodedCharSetId INTEGER
Transactional BOOLEAN
Persistence BOOLEAN
CreationTime TIMESTAMP
ExpirationTime TIMESTAMP
Priority INTEGER
ReplyIdentifier CHARACTER
ReplyProtocol CHARACTER
Topic (this field contains a list) CHARACTER

Data types for elements in the DestinationData folder

The fields and data type of each field are shown in Table 91.

The Control Center online help has information about setting the MQOutput node
properties that correspond to the values set in the fields listed here.
Table 91. Data types for elements in the DestinationData folder
Data type of the element Represented as
queueManagerName CHARACTER

236 WebSphere MQ Integrator Working with Messages

 Data types of fields and elements
Table 91. Data types for elements in the DestinationData folder (continued)
Data type of the element Represented as
queueName CHARACTER
transactionMode CHARACTER
persistenceMode CHARACTER
newMsgId CHARACTER
newCorrelId CHARACTER
segmentationAllowed CHARACTER
alternateUserAuthority CHARACTER
request CHARACTER
replytoqueuemanagername CHARACTER
replytoqueue CHARACTER

Data types for elements in an MRM message

Elements in a message defined to the MRM have the data types shown in Table 92.
Table 92. Data types for elements in an MRM message
Data type of the element Represented as
BINARY BLOB
BOOLEAN BOOLEAN
DATETIME DATE (if MRM fields are date only)
TIME (if MRM fields are time only)
TIMESTAMP (if MRM fields are both)
DECIMAL DECIMAL
FLOAT FLOAT
INTEGER INTEGER
STRING CHARACTER

Data types for an unstructured (BLOB) message

An unstructured message has the data types shown in Table 93.
Table 93. Data types for elements in an unstructured (BLOB) message
Data type of the element Represented as
BLOB BLOB
UnknownParserName CHARACTER

The UnknownParserName field, if present, contains the class name of the parser
that would have been chosen in preference to the BLOB parser. This information is
used by the header integrity routine (described in “Maintaining header integrity”
on page 9) to ensure that the semantic meaning of the message is preserved.

Appendix A. Element definitions for message parsers 237

MQCFH parser

The MQCFH parser

The Root name for this parser is “MQPCF”. The class name is “MQPCF”.

Table 94 lists the elements native to the MQCFH header.

Table 94. MQCFH parser element names, types, and attributes
Element Name Element Data Type Element Attributes
Type INTEGER Name Value
StrucLength INTEGER Name Value
Version INTEGER Name Value
Command INTEGER Name Value
MsgSeqNumber INTEGER Name Value
Control INTEGER Name Value
CompCode INTEGER Name Value
Reason INTEGER Name Value
ParameterCount INTEGER Name Value

For further information about this header and its contents, see the MQSeries
Programmable System Management book.

238 WebSphere MQ Integrator Working with Messages

 MQCIH parser

The MQCIH parser

The Root name for this parser is “MQCIH”. The class name is “MQCICS”.

Table 95 lists the elements native to the MQCIH header.

Table 95. MQCIH parser element names, types, and attributes
Element Name Element Data Type Element Attributes
Format CHARACTER Name Value
Version INTEGER Name Value
Encoding INTEGER Name Value
CodedCharSetId INTEGER Name Value
Flags INTEGER Name Value
ReturnCode INTEGER Name Value
CompCode INTEGER Name Value
Reason INTEGER Name Value
UOWControl INTEGER Name Value
GetWaitInterval INTEGER Name Value
LinkType INTEGER Name Value
OutputDataLength INTEGER Name Value
FacilityKeepTime INTEGER Name Value
ADSDescriptor INTEGER Name Value
ConversationalTask INTEGER Name Value
TaskEndStatus INTEGER Name Value
Facility BLOB Name Value
Function CHARACTER Name Value
AbendCode CHARACTER Name Value
Authenticator CHARACTER Name Value
Reserved1 CHARACTER Name Value
ReplyToFormat CHARACTER Name Value
RemoteSysId CHARACTER Name Value
RemoteTransId CHARACTER Name Value
TransactionId CHARACTER Name Value
FacilityLike CHARACTER Name Value
AttentionId CHARACTER Name Value
StartCode CHARACTER Name Value
CancelCode CHARACTER Name Value
NextTransactionId CHARACTER Name Value
Reserved2 CHARACTER Name Value
Reserved3 CHARACTER Name Value
CursorPosition INTEGER Name Value
ErrorOffset INTEGER Name Value
InputItem INTEGER Name Value
Reserved4 INTEGER Name Value

Appendix A. Element definitions for message parsers 239

MQDLH parser

The MQDLH parser

The Root name for this parser is “MQDLH”. The class name is “MQDEAD”.

Table 96 lists the elements native to the MQDLH header.

Table 96. MQDLH parser element names, types, and attributes
Element Name Element Data Type Element Attributes
Format CHARACTER Name Value
Version INTEGER Name Value
Encoding INTEGER Name Value
CodedCharSetId INTEGER Name Value
Reason INTEGER Name Value
DestQName CHARACTER Name Value
DestQMgrName CHARACTER Name Value
PutApplType INTEGER Name Value
PutApplName CHARACTER Name Value
PutDate TIMESTAMP/CHARACTER Name Value
PutTime TIMESTAMP/CHARACTER Name Value

240 WebSphere MQ Integrator Working with Messages

 MQIIH parser

The MQIIH parser

The Root name for this parser is “MQIIH”. The class name is “MQIMS”.

Table 97 lists the elements native to the MQIIH header.

Table 97. MQIIH parser element names, types, and attributes
Element Name Element Data Type Element Attributes
Format CHARACTER Name Value
Version INTEGER Name Value
Encoding INTEGER Name Value
CodedCharSetId INTEGER Name Value
Flags INTEGER Name Value
LTermOverride CHARACTER Name Value
MFSMapName CHARACTER Name Value
ReplyToFormat CHARACTER Name Value
Authenticator CHARACTER Name Value
TranInstanceId BLOB Name Value
TranState CHARACTER Name Value
CommitMode CHARACTER Name Value
SecurityScope CHARACTER Name Value
Reserved CHARACTER Name Value

Appendix A. Element definitions for message parsers 241

MQMD parser

The MQMD parser

The Root name for this parser is “MQMD”. The class name is “MQHMD”.

Table 98 lists the orphan elements adopted by the MQMD header.

Table 98. MQMD parser orphan element names, types, and attributes
Element Name Element Data Type Element Attributes
SourceQueue CHARACTER Name Value
Transactional CHARACTER Name Value

Table 99 lists the elements native to the MQMD header.

Table 99. MQMD parser native element names, types, and attributes
Element Name Element Data Type Element Attributes
Format CHARACTER Name Value
Version INTEGER Name Value
Report INTEGER Name Value
MsgType INTEGER Name Value
Expiry INTEGER/TIMESTAMP Name Value
Feedback INTEGER Name Value
Encoding INTEGER Name Value
CodedCharSetId INTEGER Name Value
Priority INTEGER Name Value
Persistence INTEGER Name Value
MsgId BLOB Name Value
CorrelId BLOB Name Value
BackoutCount INTEGER Name Value
ReplyToQ CHARACTER Name Value
ReplyToQMgr CHARACTER Name Value
UserIdentifier CHARACTER Name Value
AccountingToken BLOB Name Value
ApplIdentityData CHARACTER Name Value
PutApplType INTEGER Name Value
PutApplName CHARACTER Name Value
PutDate TIMESTAMP/CHARACTER Name Value
PutTime TIMESTAMP/CHARACTER Name Value
ApplOriginData CHARACTER Name Value
GroupId BLOB Name Value
MsgSeqNumber INTEGER Name Value
Offset INTEGER Name Value
MsgFlags INTEGER Name Value
OriginalLength INTEGER Name Value

242 WebSphere MQ Integrator Working with Messages

 MQMD parser
The Expiry field in the MQMD is a special case. If the Expiry field is set to -1
(unlimited), it is converted to an INTEGER. If the Expiry field is not set to -1 , it is
converted to a TIMESTAMP.

Appendix A. Element definitions for message parsers 243

MQMDE parser

The MQMDE parser

The Root name for this parser is “MQMDE”. The class name is “MQHMDE”.

Table 100 lists the elements native to the MQMDE header.

Table 100. MQMDE parser element names, types, and attributes
Element Name Element Data Type Element Attributes
Format CHARACTER Name Value
Version INTEGER Name Value
Encoding INTEGER Name Value
CodedCharSetId INTEGER Name Value
Flags INTEGER Name Value
GroupId BLOB Name Value
MsgSeqNumber INTEGER Name Value
Offset INTEGER Name Value
MsgFlags INTEGER Name Value
OriginalLength INTEGER Name Value

244 WebSphere MQ Integrator Working with Messages

 MQRFH parser

The MQRFH parser

The Root name for this parser is “MQRFH”. The class name is “MQHRF”.

Table 101 lists the elements native to the MQRFH header.

Table 101. MQRFH parser element names, types, and attributes
Element Name Element Data Type Element Attributes
Format CHARACTER Name Value
Version INTEGER Name Value
Encoding INTEGER Name Value
CodedCharSetId INTEGER Name Value
Flags INTEGER Name Value

Other name value elements might be present that contain information as parsed
from or destined for the option buffer. See the Rules and Format header
documentation for specific names and values.

Appendix A. Element definitions for message parsers 245

MQRFH2 parser

The MQRFH2 parser

The Root name for this parser is “MQRFH2”. The class name is “MQHRF2”.

Table 102 lists the elements native to the MQRFH2 header.

Table 102. MQRFH2 parser element names, types, and attributes
Element Name Element Data Type Element Attributes
Format CHARACTER Name Value
Version INTEGER Name Value
Encoding INTEGER Name Value
CodedCharSetId INTEGER Name Value
Flags INTEGER Name Value
NameValueCCSID INTEGER Name Value

Other name and child name value elements might be present that contain
information as parsed from or destined for the option buffer. See the WebSphere
MQ Integrator Programming Guide for further information about this header.

246 WebSphere MQ Integrator Working with Messages

 MQRMH parser

The MQRMH parser

The Root name for this parser is “MQRMH”. The class name is “MQHREF”.

Table 103 lists the elements native to the MQRMH header.

Table 103. MQRMH parser element names, types, and attributes
Element Name Element Data Type Element Attributes
Format CHARACTER Name Value
Version INTEGER Name Value
Encoding INTEGER Name Value
CodedCharSetId INTEGER Name Value
Flags INTEGER Name Value
ObjectType CHARACTER Name Value
ObjectInstanceId BLOB Name Value
1
SrcEnv CHARACTER Name Value
2
SrcName CHARACTER Name Value
3
DestEnv CHARACTER Name Value
4
DestName CHARACTER Name Value
DataLogicalLength INTEGER Name Value
DataLogicalOffset INTEGER Name Value
DataLogicalOffset2 INTEGER Name Value
Notes:
1. This field represents both SrcEnvLength and Offset
2. This field represents both SrcNameLength and Offset
3. This field represents both DestEnvLength and Offset
4. This field represents both DestNameLength and Offset

Appendix A. Element definitions for message parsers 247

MQSAPH parser

The MQSAPH parser

The Root name for this parser is “MQSAPH”. The class name is “MQHSAP”.

Table 104 lists the elements native to the MQSAPH header.

Table 104. MQSAPH parser element names, types, and attributes
Element Name Element Data Type Element Attributes
Format CHARACTER Name Value
Version INTEGER Name Value
Encoding INTEGER Name Value
CodedCharSetId INTEGER Name Value
Flags INTEGER Name Value
Client CHARACTER Name Value
Language CHARACTER Name Value
HostName CHARACTER Name Value
UserId CHARACTER Name Value
Password CHARACTER Name Value
SystemNumber CHARACTER Name Value
Reserved BLOB Name Value

248 WebSphere MQ Integrator Working with Messages

 MQWIH parser

The MQWIH parser

The Root name for this parser is “MQWIH”. The class name is “MQHWIH”.

Table 105 lists the elements native to the MQWIH header.

Table 105. MQWIH parser element names, types, and attributes
Element Name Element Data Type Element Attributes
Format CHARACTER Name Value
Version INTEGER Name Value
Encoding INTEGER Name Value
CodedCharSetId INTEGER Name Value
Flags INTEGER Name Value
ServiceName CHARACTER Name Value
ServiceStep CHARACTER Name Value
MsgToken BLOB Name Value
Reserved CHARACTER Name Value

Appendix A. Element definitions for message parsers 249

SMQ_BMH parser

The SMQ_BMH parser

The Root name for this parser is “SMQ_BMH”. The class name is “SMQBAD”.

Table 106 lists the elements native to the SMQ_BMH header.

Table 106. SMQ_BMH parser element names, types, and attributes
Element Name Element Data Type Element Attributes
Format CHARACTER Name Value
Version INTEGER Name Value
Encoding INTEGER Name Value
CodedCharSetId INTEGER Name Value
ErrorType INTEGER Name Value
Reason INTEGER Name Value
PutApplType INTEGER Name Value
PutApplName CHARACTER Name Value
PutDate TIMESTAMP/CHARACTER Name Value
PutTime TIMESTAMP/CHARACTER Name Value

250 WebSphere MQ Integrator Working with Messages

|

| Appendix B. TDS Mnemonics

| The Tagged Delimited String Wire Format (TDS) layer uses mnemonics for a
| number of properties for a message set, compound type, or both. These are listed
| in Table 107.
| Table 107. TDS mnemonics and associated properties
| Mnemonic string Meaning Default value Associated property
| <EDIFACT_CS> Component data separator in : Message set and type,
| EDIFACT Delimiter
| <EDIFACT_DS> Data element separator in + Message set and type,
| EDIFACT Delimiter
| <EDIFACT_TAGDATA_SEP> Tag data separator in EDIFACT + Message set and type, Tag
| Data Separator
| This is overridden with the
| same value as that which
| overrides <EDIFACT_DS>
| <EDIFACT_DEC_NOTATION> Decimal notation in EDIFACT . Message set, Decimal Point
| <EDIFACT_ESC_CHAR> Escape character in EDIFACT ? Message set, Escape Character
| <EDIFACT_GROUP_TERM> Tag terminator in EDIFACT ‘ Message set, Tag Terminator
| <X12_GROUP_TERM> Tag terminator in X12 ! Message set level, Tag
| Terminator
| <X12_DS> Data element separator for X12 * Message set and type,
| Delimiter
| <X12_CS> Component data element : Message set and type,
| separator for X12 Delimiter
| <LT> Represents the less than <
| character, which is a reserved
| character
| <GT> Represents the greater than >
| character, which is a reserved
| character
| <CR> Represents the carriage return %X0D
| character
| <LF> Represents the line feed character %X0A
|

| Mnemonics are also supported for the following control characters:

|| <ACK> <BEL> <BS> <CAN> <CR> <DC1> <DC2> <DC3>
| <DC4> <DLE> <EM> <ENQ> <EOT> <ESC> <ETB> <ETX>
| <FF> <FS> <GS> <GT> <HT> <LF> <LT> <NAK>
| <NUL> <RS> <SI> <SO> <SOH> <SP> <STX> <SUB>
| <SYN> <US> <VT>
|
| You can enter a mnemonic in the form <U+xxxx> where xxxx are hexadecimal
| numbers up to a value of FFFF. These numbers represent a Unicode character, not a
| character in your local code page or the code page in which message data is
| formatted. None of the characters in this structure are case sensitive. Do not
| enclose spaces inside the angle brackets.

© Copyright IBM Corp. 2000, 2002 251

252 WebSphere MQ Integrator Working with Messages
|

| Appendix C. DATETIME formats

| When you create a DATETIME element in the MRM, you must specify a format
| string in the element’s Format String property for each physical format layer (CWF,
| TDS, XML). You can use the symbols defined in this appendix to control the
| format in which the DATETIME appears in the message data.

| You can only use DATETIME for Gregorian calendar dates.

| DATETIME information can appear in a message as:

| v String data. This includes TDS, XML, and all CWF physical formats except those
| mentioned below. This is described further in “DATETIME as STRING data”.
| v Binary data. This is for the CWF Binary physical format. See “DATETIME as
| CWF BINARY data” on page 256 for more information.
| v An offset from an epoch in seconds or milliseconds. This is used if you have set
| the CWF Physical Type property to Time Seconds or Time Milliseconds
| respectively. See “DATETIME as CWF encoded values” on page 256 for details of
| this option.

| The defaults that are set for each message set property that relates to DATETIME,
| for each physical representation (CWF, TDS, XML), are defined in “Message set
| defaults” on page 257.
|
| DATETIME as STRING data
| If the DATETIME element is CWF Packed Decimal, you can only use the symbols
| that are presented as numbers. For all other Physical Type options, you can use all
| symbols.

| You can specify the DATETIME format using a string of pattern letters. The count
| of pattern letters determines the format. Table 108 defines the letters that are
| reserved as pattern letters.
| Table 108. DATETIME formatting symbols
| Symbol Meaning Presentation Example
| y year Number 1996¹
| Y year: use with week in year only Number 1996¹²
| M month in year Text and Number July and 07
| d day in year Number 10
| h hour in am or pm (1–12) Number 12
| H hour in day (0–24) Number 0
| k hour in day (1–24) Number 24
| K hour in am or pm (0–11) Number 0
| m minute in hour Number 30
| s second in minute Number 55
| S millisecond Number 978
| E day in week Text Tuesday

© Copyright IBM Corp. 2000, 2002 253

 DATETIME as STRING data
| Table 108. DATETIME formatting symbols (continued)
| Symbol Meaning Presentation Example
| e day in week (1–7 Number 2
| D day in year Number 189
| F day of week in month Number 2 (2nd Wed in
| July)³
| w week in year Number 27²
| W week in month Number 2⁴
| a am or pm marker Text pm
| Z time zone Text +05:30⁵
| ’ escape for text ’User text’
| ″ single quote ’o″’clock’
| T Parse as Time (ISO8601) (note 6)
| | Parse as Date/Time (ISO8601) (note 6)
|

| The following describe the presentation:

| v Text. If you specify four or more of the symbols, the full form is presented. If
| you specify less than four, the short or abbreviated form, if it exists, is presented.
| For example, EEEE produces Monday, EEE produces Mon.
| v Number. Repeat the symbol to specify the minimum number of digits that you
| want. Shorter numbers are padded with zeros to this length. For example, if you
| specify m, the number 6 is presented. If you specify mm, the number 06 is
| presented. A year is a special case, see note 1 in Table 108 on page 253.
| v Text and number. If you specify three or more symbols, text is displayed. If you
| specify less, the number is presented. For example, if you specify M, it produces
| 1. If you specify MM, it produces 01. If you specify MMM, it produces Jan. If you
| specify MMMM, it produces January.
| Any characters in the pattern that are not in the ranges of [’a’..’z’] and [’A’..’Z’]
| are treated as quoted text. For example, characters like colon (:), comma (,),
| period (.), the number sign (hash or pound, #), the at sign (@) and space appear
| in the resulting time text even if they are not enclosed within single quotes.

| The following points explain the notes in Table 108 on page 253:
| 1. Year is handled as a special case:
| v On output, if the count of y is 2, the year is truncated to 2 digits. For
| example, if yyyy produces 1997, yy produces 97.
| v On input, for 2 digit years the CWF message set property of Century Window
| is used to determine the century. For example, if Century Window is set to 53,
| year 97 is 1997, year 52 is 2052, and year 52 is 1953.
| 2. The first day of a year does not usually fall on a week boundary, therefore
| dates expressed using week in year might refer to dates in neighboring years.
| For example, day 1 of week 1 in 2002 (2002 01 Monday) using format string
| YYYY ww EEEE is in fact 31st December 2001. If you use Y, if the day of week (E)
| and week in year (w) are adjusted if necessary to indicate that the date falls in
| the previous year. If you use the y symbol, the adjustment is not done and
| unpredictable results could occur for dates around year end.
| For example, if the string 2002 01 Monday is formatted:
| v day 1 of week 1 in 2002 using format string YYYY ww EEEE is correctly
| interpreted as 31st December 2001

254 WebSphere MQ Integrator Working with Messages

 DATETIME as STRING data
| v day 1 of week 1 in 2002 using format string yyyy ww EEEE is incorrectly
| interpreted as 30th December 2002

| Y should only be used in conjunction with w. If you specify Y without w, the

| year is ignored. For example, if you specify YYYY–mm–dd to format 1996–03–01
| the result is 2002–03–01 because the year input is ignored and the current year
| is assumed.
| 3. The 11th July 2001 is the second Wednesday in July and can be expressed as
| 2001 July Wednesday 2 using format string yyyy MMMM EEEE F. This is not the
| same as Wednesday in week 2 of July 2001, which is 4th July 2001.
| 4. The first and last week in a month might include days from neighboring
| months. For example, Tuesday 31st July 2001 could be expressed as Tuesday in
| week one of August 2001, which is 2001 08 1 Tuesday using format string yyyy
| MM W EEEE.
| 5. You can only express a time zone as an offset in hours and minutes from GMT
| ( ±hh:mm ). The number of Z formatting symbols affects the output:
| v –Z (short form) produces –5
| v –ZZ (medium form) produces –05
| v –ZZZ (long form) produces –05:00
| 6. You can use the formatting symbol vertical bar (|) to match any ISO8601
| datetime strings. Examples of these are shown in Figure 47.
| On input to a message flow, a format string of | allows any ISO8601 compliant
| datetime to be parsed. On output from a message flow, the datetime is always
| expressed in the fullest form yyyy–MM–ddTHH:mm:ss.S.
| If you use the T formatting symbol, format strings can be constructed to match
| ISO8601 datetimes where T precedes the time portion if a datetime entity.
| Figure 47 provides some examples of ISO8601 datetime formats.
|
| Year
| yyyy
| Year and month
| yyyy–MM
| Complete date
| yyyy–MM–dd
| Complete date plus hours and minutes
| yyyy–MM–ddTHH:mm
| Complete date plus hours, minutes, and seconds
| yyyy–MM–ddTHH:mm:ss
| Complete date plus hours, minutes, seconds, and a decimal fraction of a second
| yyyy–MM–ddTHH:mm:ss.S

|
| Figure 47. ISO8601 datetime examples
|
| Here are several examples of DATETIME formats:
| Table 109. DATETIME formatting examples
| Format pattern Result
| ″yyyy.MM.dd’at’HH:mm:ss ZZZ″ 1996.07.10 at 15:08:56 –05:00
| EEE, MMM d, ″yy″ Wed, July 10, ’96
| ″h:mm a″ 8:08 PM
| ″hh ’o’’clock’ a, ZZZZ″ 09 o’clock AM, +09:00
| ″K:mm a, ZZZ″ 9:34 AM, –5:00
| ″yyyy.MMMMM.dd hh:mm aaa″ 1996.July.10 12:08 PM
|

Appendix C. DATETIME formats 255

 DATETIME as STRING data
| You can create formatting strings that produce unpredictable results, so you must
| use these symbols with care. For example, if you specify dMyyyy, it is impossible to
| distinguish between day, month, and year. dMyyyy tells the broker that a minimum
| of one character represents the day, a minimum of one character represents the
| month, and four characters represent the year. Therefore 3111999 could be
| interpreted as 3/11/1999 and 31/1/1999.
|
| DATETIME as CWF BINARY data
| The count of pattern letters determines the number of bytes used to represent a
| value.
| Table 110. DATETIME symbols for CWF binary data
| Symbol Meaning Example
| y year 1996
| M month in year 7
| d day in month 10
| H hour in day (0–23) 13
| m minute in hour 30
| s second in minute 55
| S millisecond 978
| X Ignore on input
| Pad with zeros on output
|

| The following example shows the C language structure tm with an integer of four
| bytes:
| struct tm
| { int tm_sec; /* seconds after the minute - [0,59]*/
| { int tm_min; /* minutes after the hour - [0,59]*/
| { int tm_hour; /* hours since midnight - [0,23]*/
| { int tm_mday; /* day of the month - [1,31]*/
| { int tm_mon; /* months since January - [0,11]*/
| { int tm_year; /* years since 1900 */
| { int tm_wday; /* days since Sunday - [0,6]*/
| { int tm_yday; /* days since January 1 - [0,365]*/
| { int tm_isdst; /* daylight savings time flag */
| };

| You can format this structure by specifying the string

| ″ssssmmmmHHHddddMMMM+1yyyy+1900XXXXXXXXXXXX″. The number of pattern letters
| determines the number of bytes. There are 36 A-Z characters specified in this
| pattern, which match the 36 byte structure tm. A field followed by a plus sign (+)
| has the succeeding numeric characters added to it. Therefore MMMM+1 adds one to
| the month, yyyy+1900 adds 1900 to the year. X expects one byte of input, but
| ignores its value. On output, it outputs the byte as 0.
|
| DATETIME as CWF encoded values
| You can represent a DATETIME element with the following physical types:
| v TimeSeconds. This is a 4 byte integer that represents the number of seconds since
| the epoch.
| v TimeMilliSeconds. This is an 8 byte integer that represents the number of
| milliseconds since the epoch.

256 WebSphere MQ Integrator Working with Messages

 DATETIME as CWF encoded values
| These types provide a way for c time_t and Java Date time representations to be
| parsed.

| The epoch (time 0) is specified by the format string. This has the default value of
| 1970-01-01T00:00 +00:00. You can specify other epoch strings, which must
| conform to the format pattern ″yyyy-MM-dd’T’HH:mm ZZZ″.
|
| DATETIME component defaults
| Default values are assumed if any part of a DATETIME element is not present on
| input. For example, the formatting string yyyy–MM’T’HH:mm does not contain any
| information about day in month (d), seconds (s), or milliseconds (S).Table 111
| shows the defaults for all DATETIME components
| Table 111. DATETIME component defaults
| Component Default value
| Year Current year
| Month First month of year
| Day First day of month
| Hour First hour of day
| Minute Minute 0 of hour
| Second Second 0 of minute
| Millisecond Millisecond 0 of second
|
|
| Message set defaults
| Table 112 shows the default DATETIME formatting symbols for the different
| physical message representations.
| Table 112. Message set defaults for DATETIME
| Message set property CWF default TDS default XML default
| Default DateTime Format yyyy-MM- yyyy-MM- yyyy-MM-
| dd’T’HH:mm:ssZZZ dd’T’HH:mm:ssZZZ dd’T’HH:mm:ssZZZ
| Default Time Zone ID +00:00 +00:00 +00:00
| Century Window 53 20 20
| First Week of Year 4 4 4
| First Day of Week Monday Monday Monday
|

| You can update these default values for CWF, but not for TDS or XML. These
| defaults are set for all values of the Physical Type property. If you change the CWF
| Physical Type to Binary, Packed Decimal, TimeSeconds, or TimeMilliseconds, you
| must update the Default DateTime Format property manually to ensure consistent
| results.

| For more information about these message set properties, see “Message set
| properties for CWF” on page 83 (CWF), “Message set properties” on page 136
| (TDS), or “Message set properties for XML” on page 112 (XML).

Appendix C. DATETIME formats 257

Message set defaults

258 WebSphere MQ Integrator Working with Messages

|

| Appendix D. Default TDS message set properties

| Table 113, Table 114, Table 115 on page 260, and Table 116 on page 260 define the
| defaults for the message set properties for the TDS layer for each of the industry
| standard messages that you can define. For more information about the TDS layer,
| and the industry standards supported, see Chapter 7, “Working with Tagged
| Delimited String messages” on page 131.
| Table 113. Default message set property values for TDS (part 1 of 2)
| Property Messaging standard = ACORD Messaging standard = EDIFACT
| AL3
| TDS Wire Format Identifier ACORD_AL3 EDIFACT
| Default CCSID 367 367
| Trim Fix Len String No Trim Trim Both
| Group Indicator Empty Empty
| Group Terminator Empty <EDIFACT_GROUP_TERM>
| Tag Data Separator Empty <EDIFACT_TAGDATA_SEP>
| Tag Length Empty Empty
| Delimiter Empty <EDIFACT_CS>
| Decimal Point . <EDIFACT_DEC_NOTATION>
| Escape Character Empty <EDIFACT_ESC_CHAR>
| Reserved Chars Empty <EDIFACT_ESC_CHAR>
| <EDIFACT_TAGDATA_SEP>
| <EDIFACT_GROUP_TERM>
| <EDIFACT__CS>
| Output Compression Technique SimpleALCharCompression n/a
| Input Compression Technique SimpleALCharCompression n/a
| Boolean True Representation Y 1
| Boolean False Representation N 0
| Boolean Null Representation N 0
|
| Table 114. Default message set property values for TDS (part 2 of 2)
| Property Messaging standard = Messaging standard = Messaging standard = X12
| SWIFT UNKNOWN
| TDS Wire Format Identifier SWIFT TDS X12
| Default CCSID 37 376 367
| Trim Fix Len String Trim Both No Trim Trim Both
| Group Indicator <CR><LF>: Empty Empty
| Group Terminator <CR><LF>– Empty <X12_GROUP_TERM>
| Tag Data Separator : Empty Empty
| Tag Length Empty Empty Empty
| Delimiter <CR><LF>: Empty <X12_CS>
| Decimal Point , . .

© Copyright IBM Corp. 2000, 2002 259

 Default TDS message set properties
| Table 114. Default message set property values for TDS (part 2 of 2) (continued)
| Property Messaging standard = Messaging standard = Messaging standard = X12
| SWIFT UNKNOWN
| Escape Character Empty Empty None
| Reserved Chars Empty Empty Empty
| Output Compression n/a None n/a
| Technique
| Input Compression n/a None n/a
| Technique
| Boolean True Representation 1 1 1
| Boolean False Representation 0 0 0
| Boolean Null Representation 0 0 0
|
| Table 115. Default type property values for TDS (part 1 of 2)
| Property Messaging standard = ACORD AL3 Messaging standard = EDIFACT
| Group Indicator Empty Empty
| Group Terminator Empty <EDIFACT_GROUP_TERM>
| Tag Data Separator Empty <EDIFACT_DATA_SEP>
| Tag Length Empty Empty
| Data Element Separation Fixed Length AL3 All Elements Delimited
| Delimiter not applicable <EDIFACT_CS>
|
| Table 116. Default type property values for TDS (part 2 of 2)
| Property Messaging standard = SWIFT Messaging standard = Messaging standard = X12
| UNKNOWN
| Group Indicator <CR><LF>: Empty Empty
| Group Terminator <CR><LF>– Empty <X12_GROUP_TERM>
| Tag Data Separator : Empty Empty
| Tag Length Empty Empty Empty
| Data Element Tagged Delimited Fixed Length All Elements Delimited
| Separation
| Delimiter <CR><LF>: Empty <X12_CS>

260 WebSphere MQ Integrator Working with Messages

|

| Appendix E. TDS error report

| The following extract from an error log illustrates what you might see if you try to
| deploy a message set that has a TDS wire format layer that includes an error. In
| this case, the cause of the problem is that the element Town does not have a tag
| defined.
| TDS Extractor Trace File
| ========================
|
| Beginning Extract..
|
| Extracting Identification Info
| Extracting Project Info
| Extracting Messages
| Extracting Elements
| Extracting Compound Types
| Extracting Type Members
| Extracting Type Members
| Extracting Type Members
| Extracting Type Members
| Extracting Type Members
| Beginning Indexing..
|
| Creating Member IDs to Tags Index Table.
|
| Beginning Validation..
|
| Validating Project
| Validating Types
| ERROR: TDSValidator::ValidateTypeMemberSimpleElement:
| Simple elements in a type with Data Element Separation attribute = Tagged Delimited
| must have the following attribute set:
| Element Level - Tag
| (Element ID: Town)
| (Type ID: AddressType)
| Return Code: -80
|
| Validating Messages
|
| Trace Info
| ===========
| EXCEPTION: TDSValidator::Validate:
| TDS Validation failed.
| 1 errors
| 0 warnings
| Return Code: -1

© Copyright IBM Corp. 2000, 2002 261

262 WebSphere MQ Integrator Working with Messages
|

| Appendix F. PDF error codes

| The MRM uses the PDF wire format for internal messages. You might therefore see
| PDF error codes quoted in error messages and log information.
| Table 117. PDF error codes for MRM
| Category of error Code Meaning
| Operational 1 Not initialized
| 2 Invalid operation
| 3 NULL pointer
| Parse/write 4 Read error
| 5 Write error
| 6 Message parsing error
| 7 ICU error
| Memory 8 Insufficient memory
| 9 Overflow
| Unknwon 10 Definition not found
| 11 Invalid field type
| 12 Invalid node class
| 13 Invalid bit stream
| 14 System error

© Copyright IBM Corp. 2000, 2002 263

264 WebSphere MQ Integrator Working with Messages
Appendix G. Notices
This information was developed for products and services offered in the United
States. IBM may not offer the products, services, or features discussed in this
information in other countries. Consult your local IBM representative for
information on the products and services currently available in your area. Any
reference to an IBM product, program, or service is not intended to state or imply
that only that IBM product, program, or service may be used. Any functionally
equivalent product, program, or service that does not infringe any IBM intellectual
property right may be used instead. However, it is the user’s responsibility to
evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter
described in this information. The furnishing of this information does not give you
any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, Japan

The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or
implied warranties in certain transactions, therefore this statement may not apply
to you.

This information could include technical inaccuracies or typographical errors.

Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the information. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
information at any time without notice.

Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.

© Copyright IBM Corp. 2000, 2002 265

Notices
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:
IBM United Kingdom Laboratories,
Mail Point 151,
Hursley Park,
Winchester,
Hampshire,
England
SO21 2JN.

Such information may be available, subject to appropriate terms and conditions,

including in some cases, payment of a fee.

The licensed program described in this information and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Programming License Agreement, or any equivalent agreement
between us.

Information concerning non-IBM products was obtained from the suppliers of

those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.

266 WebSphere MQ Integrator Working with Messages

 Notices

Trademarks
The following terms are trademarks of International Business Machines
Corporation in the United States, other countries, or both:

AIX DB2 DB2 Universal Database

Everyplace IBM IBMLink
MQSeries OS/390 SupportPac
WebSphere z/OS

Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States, other countries, or both.

UNIX is a registered trademark in the United States and other countries licensed
exclusively through The Open Group.

Other company, product, and service names may be trademarks or service marks
of others.

Appendix G. Notices 267

268 WebSphere MQ Integrator Working with Messages
Glossary of terms and abbreviations
This glossary defines WebSphere MQ Integrator check in. The Control Center action that stores a new
terms and abbreviations used in this book. If you or updated resource in the configuration or message
do not find the term you are looking for, see the repository.
index or the IBM Dictionary of Computing, New
check out. The Control Center action that extracts and
York: McGraw-Hill, 1994. locks a resource from the configuration or message
repository for local modification by a user. Resources
This glossary includes terms and definitions from from the two repositories can only be worked on when
the American National Dictionary for Information they are checked out by an authorized user, but can be
Systems, ANSI X3.172-1990, copyright 1990 by the viewed (read only) without being checked out.
American National Standards Institute. Copies
may be ordered from the American National collective. A hyperconnected (totally connected) set of
brokers forming part of a multi-broker network for
Standards Institute, 11 West 42 Street, New York,
publish/subscribe applications.
New York 10036. Definitions are identified by the
symbol (A) after the definition. configuration. In the broker domain, the brokers,
execution groups, message flows and message sets
A assigned to them, topics and access control
specifications.
Access Control List (ACL). The list of principals that
Configuration Manager. A component of WebSphere
have explicit permissions (to publish, to subscribe to,
MQ Integrator that acts as the interface between the
and to request persistent delivery of a publication
configuration repository and an executing set of
message) against a topic in the topic tree. The ACLs
brokers. It provides brokers with their initial
define the implementation of topic-based security.
configuration, and updates them with any subsequent
ACL. Access Control List. changes. It maintains the broker domain configuration.

AMI. Application Messaging Interface. configuration repository. Persistent storage for broker
configuration and topology definition.
Application Messaging Interface (AMI). The
programming interface provided by MQSeries that connector. See message processing node connector.
defines a high level interface to message queuing
content-based filter. An expression that is applied to
services. See also MQI and JMS.
the content of a message to determine how the message
is to be processed.
B
context tag. See element qualifier.
BLOB. Binary Large OBject. A block of bytes of data
Control Center. The graphical interface that provides
(for example, the body of a message) that has no
facilities for defining, configuring, deploying, and
discernible meaning, but is treated as one solid entity
monitoring resources of the WebSphere MQ Integrator
that cannot be interpreted.
network.
broker. See message broker.

broker domain. A collection of brokers that share a

D
common configuration, together with the single
datagram. The simplest form of message that
Configuration Manager that controls them.
MQSeries supports. Also known as send-and-forget. This
type of message does not require a reply. Compare with
C request/reply.

callback function. See implementation function. debugger. A facility on the Message Flows view in the
Control Center that enables message flows to be
category. An optional grouping of messages that are debugged.
related in some way. For example, messages that relate
to a particular application. deploy. Make operational the configuration and
topology of the broker domain.

© Copyright IBM Corp. 2000, 2002 269

Glossary
destination list. See local environment. length of a string element might be defined in one
message set but used in several message sets.
distribution list. A list of MQSeries queues to which a
message can be put using a single statement. External Security Manager. A program that provides
security management for users and resources on z/OS.
Document Type Definition (DTD). The rules that
specify the structure for a particular class of SGML or
XML documents. The DTD defines the structure with F
elements, attributes, and notations, and it establishes
constraints for how each element, attribute, and field reference. A sequence of period-separated values
notation can be used within the particular class of that identify a specific field (which might be a
documents. A DTD is analogous to a database schema structure) within a message tree. An example of a field
in that the DTD completely describes the structure for a reference might be something like
particular markup language. Body.Invoice.InvoiceNo.

DTD. Document Type Definition. filter. An expression that is applied to the content of a
message to determine how the message is to be
processed.
E
format. A format defines the internal structure of a
e-business. A term describing the commercial use of message, in terms of the fields and order of those
the Internet and World Wide Web to conduct business fields. A format can be self-defining, in which case the
(short for electronic-business). message is interpreted dynamically when read.

element. A unit of data within a message that has

business meaning, for example, street name G
element qualifier. A tag that is applied to an element graphical user interface (GUI). An interface to a
within a message to enable that element to be treated software product that is graphical rather than textual. It
differently in different contexts. For example, an refers to window-based operational characteristics.
element could be mandatory in one context and
optional in another.
I
environment. User-defined variable information
associated with a message while it is being processed IBM Developer Kit. IBM Developer Kit for the Java
by a message flow. This information can be created and Platform, a software package that can be used to write,
used by nodes within the message flow. compile, debug, and run Java applets and applications.

ESM. External Security Manager. IBM Runtime Environment. IBM Runtime

Environment for the Java Platform. A subset of the IBM
ESQL. Extended SQL. Developer Kit for the Java Platform, that contains the
core executables and files that constitute the standard
exception list. A list of exceptions that have been Java platform. The IBM Runtime Environment includes
generated during the processing of a message, with the Java Virtual Machine, core classes and supporting
supporting information. files.

execution group. A named grouping of message flows implementation function. Function written by a
that have been assigned to a broker. The broker is third-party developer for a plug-in node or parser. Also
guaranteed to enforce some degree of isolation between known as a callback function.
message flows in distinct execution groups by ensuring
that they execute in separate address spaces, or as input node. A message flow node that represents a
unique processes. source of messages for the message flow.

Extended SQL. A specialized set of SQL functions and installation mode. The installation mode can be Full,
statements based on regular SQL, extended with Custom, or Broker only. The mode defines the
functions and statements unique to WebSphere MQ components of the product installed by the installation
Integrator. process on Windows NT systems.

Extensible Markup Language (XML). A W3C

standard for the representation of data.

external reference. A reference within a message set to

a component that has been defined outside the current
message set. For example, an integer that defines the

270 WebSphere MQ Integrator Working with Messages

 Glossary

J message dictionary. A repository for (predefined)

message type specifications.
Java Database Connectivity (JDBC™). An application message domain. The value that determines how the
programming interface that has the same characteristics message is interpreted (parsed). The following domains
as ODBC but is specifically designed for use by Java are recognized:
database applications. v MRM, which identifies messages defined using the
Control Center.
Java Message Service (JMS). An application
v NEONMSG and NEON, which identify messages
programming interface that provides Java language
created using the New Era of Networks user
functions for handling messages.
interfaces.
JDBC. Java Database Connectivity. v XML, JMSMap, and JMSStream, which identify
messages that are self-defining.
JMS. Java Message Service. See also AMI and MQI. v BLOB, which identifies messages that are undefined.
You can also create your own message domains: if you
L do so, you must supply your own message parser.

local environment. Information associated with a message flow. A directed graph that represents the set
message while it is being processed by a message flow. of activities performed on a message or event as it
This information includes: passes through a broker. A message flow consists of a
v User-defined variable information that can be created set of message processing nodes and message
and used by nodes within the message flow. processing node connectors.
v A user-defined list of internal and external
message flow component. See message flow.
destinations to which a message is sent. These can be
nodes within a message flow (for example, when message parser. A program that interprets the bit
using the RouteToLabel and Label nodes) or stream of an incoming message and creates an internal
MQSeries queues (when the list is examined by an representation of the message in a tree structure, and
MQOutput node to determine the final target for the that regenerates a bit stream for an outgoing message
message). from the internal representation.
v A list of destinations to which a message has been
sent. This list is created by an output node only if it message processing node. A node in the message
is connected to another node in the message flow. flow, representing a well defined processing stage. A
message processing node can be one of several
Also known as destination list in previous MQSeries primitive types or can represent a subflow.
Integrator releases. Destination list is valid and can be
used for compatibility. message processing node connector. An entity that
connects the output terminal of one message processing
local error log. A generic term that refers to the logs node to the input terminal of another. A message
to which WebSphere MQ Integrator writes records on processing node connector represents the flow of
the local system. control and data between two message flow nodes.
v On UNIX systems, this is the syslog.
v On Windows NT, this is the Event Viewer message queue interface (MQI). The programming
(Application View). interface provided by MQSeries queue managers. The
v On z/OS systems, this is the operator console. programming interface allows application programs to
access message queuing services. See also AMI and
Entries written to this log include records that provide JMS.
information about events that are not errors, but that
occur normally during operation, for example, message repository. A database holding message
successful deployment of a configuration. template definitions.

Also known as system log. message repository manager (MRM). A component of

the Configuration Manager that handles message
definition and control. A message defined to the MRM
M has a message domain set to MRM.

message broker. A set of execution processes hosting message set. A grouping of related messages.
one or more message flows.
message template. A named and managed entity that
messages. Entities exchanged between a broker and its represents the format of a particular message. Message
clients. templates represent a business asset of an organization.

Glossary of terms and abbreviations 271

Glossary
message type. The logical structure of the data within point-to-point. Style of messaging application in
a message. For example, the number and location of which the sending application knows the destination of
character strings. the message. Compare with publish/subscribe.

metadata. Data that describes the characteristic of POSIX. Portable Operating System Interface For
stored data. Computer Environments. An IEEE standard for
computer operating systems (for example, AIX and
MQI. Message queue interface. Solaris).

MQIsdp. WebSphere MQ Integrator SCADA device predefined message. A message with a structure that
protocol. A lightweight publish/subscribe protocol is defined before the message is created or referenced.
flowing over TCP/IP. Compare with self-defining message.

MQRFH. An architected message header that is used primitive. A message processing node that is supplied
to provide metadata for the processing of a message. with the product.
This header is supported by MQSeries
Publish/Subscribe. principal. An individual user ID (for example, a log-in
ID) or a group. A group can contain individual user
MQRFH2. An extended version of MQRFH, providing IDs and other groups, to the level of nesting supported
enhanced function in message processing. by the underlying facility.

MQSeries Everyplace™. A generally available property. One of a set of characteristics that define the
MQSeries product that provides proven MQSeries values and behaviors of objects in the Control Center.
reliability and security in a mobile environment. For example, message processing nodes and deployed
message flows have properties.
MRM. Message Repository Manager.
publication node. An end point of a specific path
multilevel wildcard. A wildcard that can be specified through a message flow to which a client application
in subscriptions to match any number of levels in a subscribes. A publication node has an property,
topic. subscription point. If this is not specified, the
publication node represents the default subscription
N point for the message flow.

node. See message processing node. publish/subscribe. Style of messaging application in

which the providers of information (publishers) are
decoupled from the consumers of that information
O (subscribers) using a broker. Compare with
point-to-point. See also topic.
ODBC. Open Database Connectivity.
publisher. An application that makes information
Open Database Connectivity. A standard application about a specified topic available to a broker in a
programming interface (API) for accessing data in both publish/subscribe system.
relational and non-relational database management
systems. Using this API, database applications can
access data stored in database management systems on Q
a variety of computers even if each database
management system uses a different data storage queue. An MQSeries object. Message queuing
format and programming interface. ODBC is based on applications can put messages on, and get messages
the call level interface (CLI) specification of the from, a queue. A queue is owned and maintained by a
X/Open SQL Access Group. queue manager. Local queues can contain a list of
messages waiting to be processed. Queues of other
output node. A message processing node that types cannot contain messages: they point to other
represents a point at which messages flow out of the queues, or can be used as models for dynamic queues.
message flow.
queue manager. A system program that provides
queuing services to applications. It provides an
P application programming interface (the MQI) so that
programs can access messages on the queues that the
plug-in. An extension to the broker, written by a queue manager owns.
third-party developer, to provide a new message
processing node or message parser in addition to those
supplied with the product. See also implementation
function and utility function.

272 WebSphere MQ Integrator Working with Messages

 Glossary

R subscription. Information held by a broker that

records the details of a subscriber application, including
the identity of the queue on which that subscriber
retained publication. A published message that is
wants to receive relevant publications.
kept at the broker for propagation to clients that
subscribe at some point in the future. subscription filter. A predicate that specifies a subset
of messages to be delivered to a particular subscriber.
request/reply. Type of messaging application in which
a request message is used to request a reply from subscription point. A property of a publication node
another application. Compare with datagram. that differentiates it from other publication nodes on
the same message flow and therefore represents a
rule. A rule is a definition of a process, or set of
specific path through the message flow. An unnamed
processes, applied to a message on receipt by the
publication node (that is, one without a specific
broker. Rules are defined on a message format basis, so
subscription point) is known as the default publication
any message of a particular format will be subjected to
node.
the same set of rules.
Supervisory, Control, And Data Acquisition. A broad
S term, used to describe any form of remote telemetry
system used for gathering data from remote sensor
SCADA. Supervisory, Control, And Data Acquisition. devices (for example, flow rate meters on an oil
pipeline) and for the near real time control of remote
self-defining message. A message that defines its equipment (for example, pipeline valves).
structure within its content. For example, a message
coded in XML is self-defining. Compare with pre-defined system log. See local error log.
message.

send and forget. See datagram.

T
setup type. The definition of the type of installation terminal. The point at which one node in a message
requested on Windows NT systems. This can be one of flow is connected to another node. Terminals enable
Full, Broker only, or Custom. you to control the route that a message takes,
depending whether the operation performed by a node
shared. All configuration data that is shared by users on that message is successful.
of the Control Center. This data is not operational until
it has been deployed. topic. A character string that describes the nature of
the data that is being published in a publish/subscribe
signature. The definition of the external characteristics system.
of a message processing node.
topic based subscription. A subscription specified by
single-level wildcard. A wildcard that can be a subscribing application that includes a topic for
specified in subscriptions to match a single level in a filtering of publications.
topic.
topic security. The use of ACLs applied to one or
SQL. Structured Query Language. more topics to control subscriber access to published
messages.
stream. A method of topic partitioning used by
MQSeries Publish/Subscribe applications. topology. In the broker domain, the brokers,
collectives, and connections between them.
Structured Query Language. A programming
language that is used to define and manipulate data in transform. A defined way in which a message of one
a relational database. The language used by WebSphere format is converted into one or more messages of
MQ Integrator, ESQL, is based on SQL, and has many another format.
similar constructs.

subflow. A sequence of message processing nodes that U

can be included within a message flow. A subflow does
not have to include an input node or an output node, Uniform Resource Identifier. The generic set of all
but can do so if required. names and addresses that refer to World Wide Web
resources.
subscriber. An application that requests information
about a specified topic from a publish/subscribe Uniform Resource Locator. A specific form of URI
broker. that identifies the address of an item on the World
Wide Web. It includes the protocol followed by the
fully qualified domain name (sometimes called the host

Glossary of terms and abbreviations 273

Glossary
name) and the request. The Web server typically maps
the request portion of the URL to a path and file name.
Also known as Universal Resource Locator.

URI. Uniform Resource Identifier

URL. Uniform Resource Locator

User Name Server. The WebSphere MQ Integrator

component that interfaces with operating system
facilities to determine valid users and groups.

utility function. Function provided by WebSphere MQ

Integrator for the benefit of third-party developers
writing plug-in nodes or parsers.

W
warehouse. A persistent, historical datastore for events
(or messages). The Warehouse node within a message
flow supports the recording of information in a
database for subsequent retrieval and processing by
other applications.

wildcard. A character that can be specified in

subscriptions to match a range of topics. See also
multilevel wildcard and single-level wildcard.

wire format. This describes the physical representation

of a message within the bit-stream.

W3C. World Wide Web Consortium. An international

industry consortium set up to develop common
protocols to promote evolution and interoperability of
the World Wide Web.

X
XML. Extensible Markup Language.

274 WebSphere MQ Integrator Working with Messages

Bibliography
This section describes the documentation
available for all current WebSphere MQ Integrator
WebSphere MQ Integrator
products. Version 2.1 platform-specific
publications
WebSphere MQ Integrator Each WebSphere MQ Integrator product is
Version 2.1 cross-platform documented in at least one platform-specific
publications publication, in addition to the family books.
WebSphere MQ Integrator for AIX Version 2.1
The WebSphere MQ Integrator cross-platform
publications are: WebSphere MQ Integrator for AIX
Installation Guide, GC34-5841
v WebSphere MQ Integrator Introduction and
Planning, GC34-5599 WebSphere MQ Integrator for HP-UX Version
v WebSphere MQ Integrator Using the Control 2.1
Center, SC34-5602 WebSphere MQ Integrator for HP-UX
v WebSphere MQ Integrator Messages, GC34-5601 Installation Guide, GC34-5907
v WebSphere MQ Integrator Programming Guide, WebSphere MQ Integrator for Sun Solaris
SC34-5603 Version 2.1
v WebSphere MQ Integrator Administration Guide, WebSphere MQ Integrator for Sun Solaris
SC34-5792 Installation Guide, GC34-5842
v WebSphere MQ Integrator ESQL Reference, WebSphere MQ Integrator for Windows NT and
SC34-5923 Windows 2000 Version 2.1
v WebSphere MQ Integrator Problem Determination WebSphere MQ Integrator for Windows
Guide, GC34-5920 NT and Windows 2000 Installation
v WebSphere MQ Integrator Working with Messages, Guide, GC34-5600
SC34-6039
WebSphere MQ Integrator for z/OS Version 2.1
These books are all available in hardcopy. WebSphere MQ Integrator for z/OS
Customization and Administration Guide,
You can order publications from the IBMLink™ SC34-5919
Web site at: WebSphere MQ Integrator for z/OS
http://www.ibm.com/ibmlink Program Directory, GI10-2536

In the United States, you can also order MQSeries Everyplace

publications by dialing 1-800-879-2755.
publications
In Canada, you can order publications by dialing If you intend to connect MQSeries Everyplace
1-800-IBM-4YOU (1-800-426-4968). applications to message flows that include the
MQSeries Everyplace message flow nodes, you
For further information about ordering will find the following publications useful:
publications contact your IBM authorized dealer
v MQSeries Everyplace for Multiplatforms Version
or marketing representative.
1.2 Introduction, GC34-5843
v MQSeries Everyplace for Multiplatforms Version
1.2 Programming Guide, SC34-5845
v MQSeries Everyplace for Multiplatforms Version
1.2 Programming Reference, SC34-5846
v MQSeries Everyplace for Multiplatforms Version
1.2 Native Client Information, SC34-5880

© Copyright IBM Corp. 2000, 2002 275

 Bibliography
You can find these books on the MQSeries Web softcopy publications provided on the CD for
site (see “MQSeries information available on the Windows NT components.
Internet” on page 277). Translated versions of
these books are also available in some languages | The searchable PDF package comprises a set of
from the same Web site. | panels, books, and index files that are linked
| together to provide a stand-alone method of
| searching the WebSphere MQ Integrator library. It
New Era of Networks Rules and | contains the following usability enhancements:
Formatter Support for | v One searchable index per book
WebSphere MQ Integrator | v One searchable index file for the entire
publications | WebSphere MQ Integrator library
| v Logical page numbering of PDF files to match
The following publications are supplied on the | printed books
product CD in PDF format, and are installed with
the Documentation component. They are also | v Full cross-referencing within books that allows
available in hardcopy. | you to jump to other parts of the same
| document
v New Era of Networks Rules and Formatter Support
for WebSphere MQ Integrator User’s Guide, | v Hyperlinked URLs to enable transparent
SC34-6084 | integration with the Web
v New Era of Networks Rules and Formatter Support | v An expandable list of PDF Bookmarks that
for WebSphere MQ Integrator System Management | allows you to jump directly to a specific section
Guide, SC34-6083 | within a book
v New Era of Networks Rules and Formatter Support | v Thumbnail images of all pages in the book to
for WebSphere MQ Integrator Rules Programming | allow you to scan for diagrams, tables, and so
Reference, SC34-6085 | on
v New Era of Networks Rules and Formatter Support You can install the searchable PDF package as
for WebSphere MQ Integrator Formatter follows:
Programming Reference, SC34-6086
v On AIX, invoke install —d and select the
v New Era of Networks Rules and Formatter Support documentation fileset. After installation, run the
for WebSphere MQ Integrator Application command mqsidocs. This launches Acrobat
Development Guide, SC34-6082 Reader and opens the PDF package.
These books are provided in US English only. v On HP-UX, invoke swinstall —d and select
WMQI-DOCS from the menu. After installation,
run the command mqsidocs. This launches
Softcopy books Acrobat Reader and opens the PDF package.
All the WebSphere MQ Integrator books are v On Solaris, invoke pkgadd —d and select
available in softcopy formats. wmqi-docs from the menu. After installation,
run the command mqsidocs. This launches
Portable Document Format (PDF) Acrobat Reader and opens the PDF package.
| The WebSphere MQ Integrator library is supplied v On Windows NT, select the Online
| in a searchable PDF package in US English only Documentation component on a custom
| on the product CD. (This package excludes the installation, or do a full installation. After
| WebSphere MQ Integrator for z/OS Program installation, select Start—>Programs—>IBM
| Directory.) The searchable PDF package is also WebSphere MQ Integrator 2.1—>Documentation.
| supplied in the DOC directory on the product | Translated books for national language versions of
| Supplemental CD. The contents of the DOC | this product are provided as stand-alone PDFs
| directory can be viewed without installing the | with the US English PDF package and
| product. | stand-alone PDFs of US English books (for
| WebSphere MQ Integrator and New Era of
Softcopy publications are not provided for the | Networks Rules and Formatter Support for
z/OS operating system. If you have WebSphere | WebSphere MQ Integrator) on a documentation
MQ Integrator for z/OS Version 2.1, refer to the | CD (order number SK3T–6922), which you can

276 WebSphere MQ Integrator Working with Messages

 Bibliography
| order following general availability. (Not every v Download an MQSeries SupportPac.
| book is available in every supported language.) | v Access Redbooks.

| PDF files can be viewed and printed using the

| Adobe Acrobat Reader. To take advantage of the
| usability enhancements provided in the
| searchable library, you will need Adobe Acrobat
| Reader with Search Version 4.05 on Windows NT,
| or Adobe Acrobat Reader with Search Version 4.5
| on UNIX systems. You are not recommended to
| use this package with Adobe Acrobat Reader with
| Search Version 3.xx.

If you need to obtain the Adobe Acrobat Reader,

or would like up-to-date information about the
platforms on which the Acrobat Reader is
supported, visit the Adobe Systems Inc. web site
at:
http://www.adobe.com/

| If you want to generate your own searchable

| index files for this collection of PDF files, you will
| need Adobe Acrobat Catalog 4 (part of Adobe
| Acrobat Version 4). If you want to make your
| own softcopy annotations in the files, you will
| need the full version of Adobe Acrobat Version 4
| (formerly Adobe Acrobat Exchange Version 3.01).

If you cut and paste examples of commands from

PDF files to a command line for execution, you
must check that the content is correct before you
press Enter. Some characters might be corrupted
by local system and font settings.

PDF versions of all current WebSphere MQ

Integrator books are also available from the
MQSeries product family Web site at:
http://www.ibm.com/software/mqseries/

MQSeries information available

on the Internet
The MQSeries product family Web site is at:
http://www.ibm.com/software/mqseries/

By following links from this Web site you can:

v Obtain latest information about the MQSeries
product family.
v Access the MQSeries books in HTML and PDF
formats.
v Obtain information about complementary
offerings by following these links:
– IBM Business Partners
– Partner Offerings (within Related links)

Bibliography 277
MQSeries on the Internet

278 WebSphere MQ Integrator Working with Messages

Index
A checking in
all (save to shared) 170
constraint (continued)
defining with element value 59
about this book xi all in workspace 170 message set 28
ACORD AL3 150 confirmation 170 validation 28
adding list 170 Control Center
CWF format layer 161 message objects 169 New Era of Networks message
TDS format layer 161 message sets 169 support 227
XML format layer 161 checking out copy message set 175
adding to the workspace list 170 correlation names
category 175 message sets 170 XML message 192
compound type 175 CMI creating
element 175 see Common Message Interface 31 compound type using the
element qualifier 175 COBOL copybook, generating from MRM SmartGuide 168
element value 175 message set 31 message sets 159
message 175 COBOL default mappings 185 message using the SmartGuide 168
message set 175 COBOL language binding layer 164 MRM message 165
transaction 175 category copy book name 164 Custom Wire Format layer 83
COBOL language name 164, 165 CWF
main copy book name 164 data conversion 106
B message copy book name 164 element values, defaults 109
base type, MRM 49 structure copy book name 165 message set properties 83
BINARY element properties, TDS 143 transaction copy book name 164 multipart message 106
BLOB message domain 231 COBOL language bindings, null handling 106
BLOB message, data type of generating 179 relationship with logical model 107
elements 237 code page 251 rules 107
BOOLEAN element properties, TDS 143 code page conversion 106, 162 rules for base type 108
broker validation 28, 42, 52, 64, 111, 122, coded character set 84, 93, 96, 99, 122, rules for Type Composition 107
124, 125 136 rules for Type Content 108
Common Messaging Interface 31 setting properties 83
complementary offerings type member properties
C IBM Business Partners 277
Partner Offerings 277
for BINARY 86
for BOOLEAN 88
C default mappings 183 component properties for compound type 105
C header file, generating from MRM edit 172 for DATETIME 89
message set 31 compound type for DECIMAL 93
C language binding layer adding to the workspace 175 for FLOAT 96
C language name 163, 164 characteristics 49 for INTEGER 99
category header file name 163 creating using the SmartGuide 168 for STRING 102
file name 164 defining 50 video customer example 109
include in main header 163 permitted options for nesting with CWF wire format
main header file name 163 TDS 147 support in MRM 4
orphan header file name 163 properties 50 use in MRM 29
transaction header file name 163 property panes 50 CWF wire layer
C language bindings, generating 179 unresolved choice handling 73, 108 adding 161
cardinality, MRM 28 compound type definition
caret character, in MRM element using the SmartGuide 168
identifiers 41
category
compound type member property
Max Occurs 54
D
adding to the workspace 175 data conversion 5, 9, 66, 106, 122, 146
Min Occurs 54
characteristics 55 data structures, importing (C and
Repeat 54
defining 56 COBOL) 30
compound type properties
message category 55 data types
XML wire format 123
properties 56 elements in DestinationData
compound type property
property panes 55 folder 236
Identifier 50
transaction category 55 elements in MRM message 237
Name 50
category property elements in Properties folder 236
Suspended from Use 50
Identifier 56 elements in unstructured (BLOB)
Type 51
Name 56 message 237
Type Composition 51
Suspended from Use 56 fields in MQSeries headers 236
Type Content 51
changes for this edition of elements 236
constraint
SC34-6039–01 xv of fields 236
defining with element qualifier 56
changing the state of a message set 174

© Copyright IBM Corp. 2000, 2002 279

DATETIME element property ESQL (continued)
component defaults 257 Encoding 116 MRM (continued)
format for ISO8601 255 Encoding Null 143 referencing elements 71
formatting symbols 253 Encoding Null Value 143 referencing simple types 72
Gregorian calendar 253 Format 142 testing for null 74
message set defaults 257 Identifier 46 unresolved choice 73
DATETIME element properties, TDS 143 Interpret Element Value 142 examples
DECIMAL element properties, TDS 143 Justification 142 DATETIME formatting 255
default mappings Length 141 C program 256
C 183 Length Value Of 141 ISO8601 DATETIME formatting 255
COBOL 185 Name 46 exception list tree
defining a compound type using the Negative Sign 143 ConversionException 17
SmartGuide 168 Padding Character 142 DatabaseException 17
defining a message using the Positive Sign 143 ParserException 17
SmartGuide 168 Precision 142 RecoverableException 17
DestinationData folder Sign Orientation 143 root 16
data type of elements 236 Suspended from Use 46 UserException 17
DOCTYPE Text Tag 141 exception, status of message tree 11
XML wire format 114 Type 46 exporting
documentation Virtual Decimal Point 142 MRM message set 31
generating from MRM message XML name 116
set 31, 178 element qualifier
domain, definition 3
DTD
adding to the workspace 175
characteristics 56
F
fields, data types 236
generating from MRM message defining 57
FLOAT element properties, TDS 143
set 31, 181 properties 57
format for ISO8601
importing 30 property panes 57
DATETIME 255
DTD importer element qualifier member
MRM 30 properties 58
XML wire format 122 element qualifier property
Element name 57 G
Identifier 57 generating
E Name 57
Suspended from Use 57
C header file 31
COBOL copybook 31
EDIFACT 151
element value documentation 31, 178
edit
adding to the workspace 175 DTD 31, 181
component properties 172
characteristics 59 glossary 179
message set properties 171
defining 60 language bindings 179
element
properties 60 message book 178
adding to the workspace 175
property panes 60 run time dictionary 31, 180
characteristics 45
element value member generators for MRM 31
data types 236
properties 61 glossary, generating 179
defining 46
element value member property Gregorian calendar 253
omission in TDS 148
Role 61
properties 46
element value property
property panes 45
reorder 171
Identifier 60
Name 60
H
truncation in TDS 148 header, data type of fields 236
Suspended from Use 60
element member
Type 60
properties 46
Value 61
element member properties
XML wire format 117
encoding 9, 84, 93, 96, 99, 102, 106, 116, I
118, 192 IBM Business Partners 277
element member property
environment tree 14 identifier
Max Occurs 46
error example, TDS 261 prefixed 40
Member Encoding 118
ESQL importers
Member Format 118
MRM MRM 30, 31
Member ID Attribute Name 117
explicit null handling 75 importing
Member ID Attribute Value 118
implicit null handling 75 C header 176
Member Render 117
manipulating message content 70 C structures 30
Member Value Attribute Name 118
multiple elements 71 COBOL copy book 176
Member XML Name 117
null elements in input COBOL structures 30
Min Occurs 46
message 74 DTD 30, 177
Repeat 46
null elements in output message definition 176
element of data, definition 3
message 74 MRM message set 31
element properties
null handling, base types 75 industry standard
TDS 141
referencing base types 72 ACORD AL3 150
XML wire format 116
referencing compound types 73 EDIFACT 151

280 WebSphere MQ Integrator Working with Messages

industry standard (continued) message (continued) message set
SWIFT 153 name-value element 13 adding to the workspace 175
TDS defaults 259 predefined MRM 23 C Language tab 163
TDS support 150 predefined NEON 214, 224 changing the state 174
X12 153 properties 48 characteristics 41
information on the Internet property panes 47 checking in 169
complementary offerings 277 self-defining 191 checking out 170
MQSeries family libraries 277 SWIFT 153 COBOL Language tab 164
MQSeries products 277 value element 13 constraints 28
MQSeries SupportPacs 277 video customer example creating 159
inline DTD, XML wire format 114 CWF 109 CWF layer 160
input node model 78 DATETIME defaults 257
identifying MRM message 27 TDS 154 defining 43
plug-in 10 XML 126 definition 3
INTEGER element properties, TDS 143 X12 153 editing properties 171
message book, generating 178 exporting 31
message definition generating C header file 31
J identifying the logical model 165
importing 176
generating COBOL copybook 31
generating documentation 31
JMS message
using the SmartGuide 168 generating DTD 31
domain 209
message domain generating run time dictionary 31
message processing nodes
BLOB 231 identifier 160
input nodes 209
identifying for MRM message 27 identifying for MRM message 27
other nodes 210
JMS 209 importing 31
output nodes 210
MRM 23 language binding 160
NEON 213, 224 Level 77
NEONMSG 213, 214 level, using an existing name 161
L plug-in parser 10 name 159
language bindings, generating 179 XML 191 parser optimization 159
legacy format message message format physical representation 29
exporting 30 identifying for MRM message 27 properties 43
importing 30 message format, definition 3 property panes 42
local environment tree message header parsers 8 reorder elements 171
Destination 15 maintaining header integrity 9 Run Time tab 159
MQ 15 message header, data type of fields 236 share with other users 161
MQDestinationList 15 message model state 76
root 14 video customer example 78 Finalized 77
RouterList 15 message parser Frozen 76
Variables 15 MQCFH 238 Locked 76
WrittenDestination 16 MQCIH 239 Normal 76
logical model MQDLH 240 TDS wire format layer 160
relationship with CWF 107 MQIIH 241 using copy and paste 175
relationship with TDS 149 MQMD 242 using with CMI 31
relationship with XML wire MQMDE 244 version 77
format 123 MQRFH 245 version, using an existing name 161
MQRFH2 246 wire format
MQRMH 247 CWF 29
M MQSAPH 248
MQWIH 249
PDF 29
TDS 29
member of relationship
SMQ_BMH 250 XML 29
MRM object 62
message properties wire format layer 160
message
TDS 138 XML wire format layer 160
ACORD AL3 150
XML wire format layer 115 message set properties
adding to the workspace 175
message property CWF 83
basic concepts 3
DOCTYPE public id 115 TDS 136
characteristics 47
DOCTYPE system id 115 TDS defaults 259
creating 165
DOCTYPE text 115 XML wire format layer 112
creating using the SmartGuide 168
Identifier 48 message set property
data type of elements (MRM) 237
Message Key 138 Base message set 44
data type of elements
Mode 48 Boolean False 85
(unstructured) 237
Name 48 Boolean False Representation 138
defining 48
Render 115 Boolean Null 85
definition 3
Root tag name 115 Boolean Null Representation 138
EDIFACT 151
Suspended from Use 48 Boolean True 85
elements that define destination 16
Type 48 Boolean True Representation 138
generic XML 191
XML name 115 Boolean True Value 113
multipart 38
Byte Alignment 85
name element 13

Index 281
message set property (continued) message type (continued) MRM domain (continued)
Byte Alignment Pad 85 predefined 4 designing new messages 32
Byte Order 84 self-defining 4 element 45
Century Window 85 supported 4 element qualifier 56
Custom Wire Format Identifier 84 undefined (BLOB) 4 element value 59
Decimal Point 137 messages, defining in MRM 159 ESQL 69
Default CCSID 84, 136 messaging standard example logical message model 66
Default DateTime Format 85 tagged/delimited identifier 39
Default null permitted 43 ACORD AL3 32 identifying message in input node 27
Default Time Zone ID 85 EDIFACT 32 identifying message in MQRFH2 27
Default wire format 43 SWIFT 32 identifying message to broker 27
Delimiter 137 UNKNOWN 32 implications for different wire
DOCTYPE Public ID 112 X12 32 formats 63
DOCTYPE System ID 112 mnemonic, TDS input node properties 70
DOCTYPE Text 113 name 135 logical message model 25, 27
Enable versioning support 113 symbols 251 logical message representation 25
Encoding Null Non-Num 114 Unicode character 135 managing message sets 76
Encoding Null Non-Num Val 114 MQCFH, parser 238 member of relationship 62
Encoding Null Num 114 MQCIH, parser 239 message 47
Encoding Null Num Val 114 MQDLH, parser 240 message dictionary 24
Escape Character 137 MQFMT_IMS_VAR_STRING, message example 26
Finalized 43 restrictions 9 message model objects 39
First Day of Week 86 MQIIH, parser 241 message set 41
First Week of Year 85 MQMD, parser 242 message set assignment 24
Float Format 84 MQMDE, parser 244 message tree 24
Freeze timestamp 43 MQRFH, parser 245 modeler 24
Group Indicator 137 MQRFH2 MQRFH2 properties 70
Group Terminator 137 identifying MRM message 27 name 39
Identifier 43 MQRFH2, parser 246 naming conventions 33
Input Compression Technique 138 MQRMH, parser 247 null handling 64
Level 43 MQSAPH, parser 248 null handling, base types 66
Message Type Prefix 44 MQSeries Everyplace publications 275 object relationships 62
Messaging Standard 136 MQSeries header parsers 8 organizing messages 33
Name 43 MQSeries header, data type of fields 236 parser 24
Output Compression Technique 138 MQWIH, parser 249 physical message representation 25
Packed Decimal Byte Order 84 MRM physical representation
Reserved Chars 137 creating a complex message 38 CWF 32
Root tag name 113 creating a logical message model 37 TDS 32
run time parser 42 creating a multipart message 38 XWF 32
Standalone document 112 creating a simple message 38 planning a message model 32
Suppress DOCTYPE 112 defining if nulls are permitted 64 predefined message 63
Suppress XML declaration 112 definition 23 reference relationship 62
Tag Data Separator 137 logical message model 35 referencing base types with ESQL 72
Tag Length 137 logical model referencing choice compound type
TDS Wire Format Identifier 136 compound type 27 with ESQL 73
Trim Fix Len String 137 element 28 referencing compound types with
XML Wire Format Identifier 112 message 27 ESQL 73
message set state, MRM 76, 174 message set 27 referencing elements with ESQL 71
message set version, MRM 77, 161 simple type 27 referencing embedded messages with
message structure the message set in the Control ESQL 73
environment tree 14 Center 36 referencing simple types with
exception list tree 16 utilities 30 ESQL 72
local environment tree 14 MRM domain reusing existing messages 32
message tree 12 accessing base types from message reusing types and elements 37
tree format 11 flow 69 self-defining message 63
message tree accessing compound types from setting the value of null 65
access by message flow nodes 11 message flow 69 sparse message 64
copying input data to output data 11 accessing element from message transaction 58
correlation names 12 flow 68 type 49
exception handling 11, 16 accessing simple types from message writing output message 24
headers 12 flow 69 MRM element
properties 12 base type 49 duplicate 52, 54
root 12 broker’s view of the logical message identifier 40
structure 11 model 66 mandatory 28
message type category 55 optional 28
definition 3 data conversion 66 repeating 28, 46, 52, 54, 168
identifying for MRM message 27 defining language bindings 33 restrictions 45, 56, 59

282 WebSphere MQ Integrator Working with Messages

MRM identifier 40
MRM in the Control Center
N physical message representation
(continued)
description pane 36 NEON domain 224 TDS 131
general pane 36 NEON message XML 111
message set pane 36 message processing nodes plug-in
properties pane 36 other nodes 226 input node 10
MRM message NeonFormatter node 226 parser 10
adding language bindings 162 NEONMap node 218 Portable Document Format (PDF) 276
configuring language bindings NEONMSG domain 214 predefined message
C 163 NEONMSG message MRM domain 23
COBOL 164 message processing nodes NEON domain 224
data type of elements 237 other nodes 224 NEONMSG domain 214
exporting legacy format 30 transforming to XML or MRM 215 support in MRM 63
exporting message sets 31 NeonRules node 226 prefixed identifier, MRM elements 40
importing DTD 30 NEONRulesEvaluation node 219 Propagate 222
importing legacy format 30 Propagate 222 properties
importing message sets 31 Propagate, Put Queue, and Route CWF 83
message flow nodes 182 actions 222 TDS 135
input nodes 182 Put Queue 222 XML wire format 112
other nodes 182 Route 223 Properties folder, data type of
output nodes 182 NEONTransform node 217 elements 236
NEONMSG nodes and repeating Map Name and Map Version 217 properties parser 10
components 182 Output Domain 217 properties, MRM
TDS Output Message Type and Output category 56
industry standard defaults 259 Message Set 218 compound type 50
mnemonics 251 New Era of Networks message element 46
sample error 261 Formatter interface 227 element qualifier 57
wire formats Rules interface 227 element value 60
CWF 83 support in the Control Center 227 general 36
TDS 131 Visual Tester 227 message 48
XML 111, 123 New Era of Networks message message set 43
MRM message domain 23 domains 213 transaction 59
MRM message set New Era of Networks Rules and publications
exporting 31 Formatter Support publications 276 MQSeries Everyplace 275
importing 31 null handling WebSphere MQ Integrator 275
MRM name 39 CWF 106 Put Queue 222
MRM object MRM 64
category 55 options for XML wire format 120
TDS 144
element 45
element qualifier 56 XML wire format 119 R
Redbooks 277
element value 59
reference relationship
identifier 40
implications for different wire O MRM object 62
rendering options
formats 63 optional elements, MRM 28 XML wire format
member of relationship 62 OS/390 xii XMLAttribute 119
message 47
XMLElement 119
message set 41
XMLElementAttrId 119
name 39
null handling 64
P XMLElementAttrIdVal 119
padding characters, MRM 162 XMLElementAttrVal 119
null handling, base types 66
parser rendering options, XML in MRM 118,
reference relationship 62
NEON message body 224 119
relationships wiht other objects 62
NEONMSG message body 214 reorder elements in compound
setting null with ESQL 74
plug-in 10 types 171
setting the value of null 65
parser, message headers 8 reorder message set components 171
testing for null with ESQL 74
parser, MQSeries headers 8 restrictions, MRM element 45, 56, 59
transaction 58
parser, properties 10 Route 223
type 49
parsers rules
uniqueness of identifier 40
maintaining header integrity 9 CWF 107
using ESQL to access 69
Partner Offerings 277 Data Element Separation, TDS 146
MRM padding characters 162
paste message set 175 general, TDS 147
multipart message
PDF (Portable Document Format) 276 general, XML wire format 122
CWF 106
PDF wire format TDS 146
MRM 38
error codes 263 XML 122
TDS 145
support in MRM 4 run time dictionary, generating 31, 180
XML wire format 121
use in MRM 29
physical message representation
CWF 83

Index 283
S TDS (continued)
null handling 144
Type Content
Closed 52, 53, 124
self-defining element, MRM 111 omission 148 Open 52, 53, 124
self-defining message, MRM 63 permitted options for nested Open Defined 53, 124
self-defining messages 191 compound types 147 Opendefined 52
simple type, characteristics 49 permitted values for type permitted values for TDS 149
SmartGuide composition 149 type member properties, TDS 141
create a compound type 168 permitted values for type type member property
creating a message 168 content 149 BINARY
SMQ_BMH, parser 250 relationship with logical model 149 Byte Alignment 87
softcopy books 276 Reserved Characters 135 Length Count 86
sparse message rules 146 Length Type 86
support in MRM 64 setting properties 135 Length Units 86
states of message set 76 STRING element properties 143 Length Value Of 86
STRING element properties, TDS 143 SWIFT 153 Physical Type 86
SupportPac 277 tag 131 Repeat Count 87
SWIFT 153 tag data separator 131 Repeat Count Type 87
symbols truncation 148 Repeat Count Value Of 87
DATETIME formatting type member properties 141 Skip Count 87
CWF BINARY 256 type properties 138 BOOLEAN
CWF TimeMilliseconds 256 type properties, defaults 260 Byte Alignment 88
CWF Timeseconds 256 using mnemonics 135 Physical Type 88
STRING 253 video customer example 154 Repeat Count 88
X12 153 Repeat Count Type 88
TDS delimiter value Repeat Count Value Of 88
T Delimiter 134 Skip Count 88
Tagged/Delimited String Wire Format Group Indicator 134 compound element
layer 131 Group Terminator 134 Byte Alignment 105
TDS Repeating Element Delimiter 134 Length Count 105
ACORD AL3 150 Tag Data Separator 134 Length Units 105
BINARY element properties 143 TDS wire format Repeat Count 105
BOOLEAN element properties 143 adding 161 Repeat Count Type 105
combination of element type and data conversion 146 Repeat Count Value Of 105
property 144 support in MRM 4 Skip Count 105
data element separation use in MRM 29 DATETIME
All Elements Delimited 133 terms used in this book xii Byte Alignment 90
definition 132 transaction Encoding Null 92
Fixed Length 134 adding to the workspace 175 Encoding Null Value 92
Fixed Length AL3 134 characteristics 58 Format String 91
Tagged Delimited 133 defining 59 Length Count 89
Tagged Fixed Length 133 properties 59 Length Type 89
Undefined 134 property panes 58 Length Units 90
Variable Elements Delimited 133 transaction property Length Value Of 89
Data Element Separation rules 146 Identifier 59 Padding Character 91
DATETIME element properties 143 Name 59 Physical Type 89
DECIMAL element properties 143 Suspended from Use 59 Repeat Count 91
Decimal Point 135 tree Repeat Count Type 91
delimiter 131 child 12 Repeat Count Value Of 91
delimiter values 134 environment 14 Sign Orientation 90
EDIFACT 151 exception list 16 Signed 90
element properties 141 local environment 14 Skip Count 91
Escape Character 135 message 12 String Justification 90
examples of using special parent 12 DECIMAL
characters 135 sibling 12 Byte Alignment 94
FLOAT element properties 143 type Encoding Null 95
general rules 147 characteristics 49 Encoding Null Value 95
group indicator 131 properties 50 Length Count 93
group terminator 131 property panes 50 Length Units 93
identifying embedded message 145 Type Composition Padding Character 94
identifying multipart message 145 Choice 52, 108 Physical Type 93
industry standards 150 Empty 52, 108, 124 Repeat Count 94
INTEGER element properties 143 Message 52, 108 Repeat Count Type 94
message properties 138 Ordered Set 52, 108 Repeat Count Value Of 95
message set properties 136 permitted values for TDS 149 Sign Orientation 93
message set properties, defaults 259 Sequence 52, 107, 124 Signed 93
mnemonics 135 Simple Unordered Set 52, 108, 124 Skip Count 94
multipart message 145 Unordered Set 52, 108 String Justification 94

284 WebSphere MQ Integrator Working with Messages

type member property (continued) utilities XLM wire format
DECIMAL (continued) generators 31 combinations of Type Composition
Virtual Decimal Point 94 importers 30, 31 and Type Content 124
FLOAT MRM 30 XML message 191
Byte Alignment 97 AttributeDef
Encoding Null 98 AttributeDefDefaultType 200
Encoding Null Value 98
Length Count 96
V AttributeDefType 200
AttributeDefValue 200
validation
Length Units 96 correlation names 192
broker 28, 42, 52, 64, 111, 122, 124,
Padding Character 97 DocTypeDecl
125
Physical Type 96 IntSubset 198
constraints 28
Repeat Count 98 PublicId 198
versions of message sets 77
Repeat Count Type 98 SystemId 198
video customer example
Repeat Count Value Of 98 Document Type Declaration 198
Control Center
Sign Orientation 97, 99 DTD 198
adding elements to compound
Signed 96 AttributeDef 200
type 168
Skip Count 97 AttributeList 200
defining compound elements 167
String Justification 97 DocTypeComment 201
defining compound types 167
Virtual Decimal Point 98 DocTypeDecl 198
defining message 168
INTEGER DocTypePI 201
defining simple elements 166
Byte Alignment 100 DocTypeWhiteSpace 201
elements 165
Encoding Null 101 ElementDef 200
CWF
Encoding Null Value 101 Entities 199
element member properties 109
Length Count 99 example 202
message set properties 109
Length Units 99 NotationDecl 198
message model 78
Padding Character 100 WhiteSpace 201
compound types 79
Physical Type 99 Entities
element member properties 81
Repeat Count 100 EntityDecl 199
element properties 80
Repeat Count Type 100 EntityDeclValue 200
message properties 79
Repeat Count Value Of 100 ExternalEntityDecl 199
message set properties 78
Signed 99 ExtrenalParameterEntityDecl 199
message tree 82
Skip Count 100 ParameterEntityDecl 199
simple elements 79
String Justification 100 UnparsedEntityDecl 199
type properties 80
Repeating Element Delimiter 141 example document 191
TDS 154
STRING example tree structure 192
element properties 155
Byte Alignment 103 message body 193
message properties 155
Encoding Null 104 Attribute 194
message set properties 154
Encoding Null Value 104 CData 195
type member properties 155
Length Count 102 Comment 196
type properties 155
Length Type 102 Content 194
XML 126
Length Units 103 Element 194
element properties 127
Length Value Of 102 EntityReferenceEnd 195
message properties 127
Padding Character 104 EntityReferenceStart 195
message set properties 126
Physical Type 102 ProcessingInstruction 196
rendering options 128
Repeat Count 104 message processing nodes
type member properties 128
Repeat Count Type 104 input nodes 206
Repeat Count Value Of 104 other nodes 206
Skip Count 103 output nodes 206
String Justification 103 W XML declaration 192
type member, properties 54 WebSphere MQ Integrator on the XMLDecl 192
type properties Internet 277 Encoding 192
TDS 138 WebSphere MQ Integrator example 193
TDS defaults 260 publications 275 Standalone 193
type property national language 276 Version 192
Data Element Separation 140 platform–specific 275 XML message domain 191
Delimiter 140 Windows 2000 xii XML wire format
Group Indicator 138 Windows NT xii adding 161
Group Terminator 139 wire format, MRM compound type properties 123, 125
Tag Data Separator 139 CWF 83 Connection pane and DTD
Tag Length 139 TDS 131 attributes 125
XML 111 Connection pane and DTD
elements 125
U data conversion 122
UNIX xii X DOCTYPE Text 114
DTD importer 122
unstructured message, data type of X12 153
element member properties 117
elements 237
element properties 116

Index 285
XML wire format (continued)
encoding null
NULLAttribute 120
NULLElement 120
NULLEmpty 120
NULLValAttr 120
NULLValue 120
general rules 122
identifying multipart message in input
message 121
identifying multipart message in input
node 121
identifying multipart message in
MQRFH2 121
inline DTD 114
message properties 115
message set properties 112
MRM support for self-defining
elements 111
multipart message 121
null handling 119
null value options 120
relationship with logical model 123
rendering for output messages 119
rendering options 118, 119
rules 122
setting properties 112
storing a null value 120
support in MRM 4
use in MRM 29
use of Message Type Prefix 121
video customer example 126

Z
z/OS xii

286 WebSphere MQ Integrator Working with Messages

Sending your comments to IBM
If you especially like or dislike anything about this book, please use one of the
methods listed below to send your comments to IBM.

Feel free to comment on what you regard as specific errors or omissions, and on
the accuracy, organization, subject matter, or completeness of this book.

Please limit your comments to the information in this book and the way in which
the information is presented.

To make comments about the functions of IBM products or systems, talk to your
IBM representative or to your IBM authorized remarketer.

When you send comments to IBM, you grant IBM a nonexclusive right to use or
distribute your comments in any way it believes appropriate, without incurring
any obligation to you.

You can send your comments to IBM in any of the following ways:
v By mail, to this address:
User Technologies Department (MP095)
IBM United Kingdom Laboratories
Hursley Park
WINCHESTER,
Hampshire
SO21 2JN
United Kingdom
v By fax:
– From outside the U.K., after your international access code use
44–1962–842327
– From within the U.K., use 01962–842327
v Electronically, use the appropriate network ID:
– IBM Mail Exchange: GBIBM2Q9 at IBMMAIL
– IBMLink: HURSLEY(IDRCF)
– Internet: [email protected]

Whichever method you use, ensure that you include:

v The publication title and order number
v The topic to which your comment applies
v Your name and address/telephone number/fax number/network ID.

© Copyright IBM Corp. 2000, 2002 287

288 WebSphere MQ Integrator Working with Messages



Printed in U.S.A.

SC34-6039-01
Spine information:

 WebSphere MQ Integrator WebSphere MQ Integrator Working with Messages Version 2.1