4.3.4.9. MultiRecord
What is an mr file?
An mr file is a multirecord definition file used by the Self-Service MultiRecord wizard to generate the corresponding message definition and also build the corresponding serving xml resource file.
How to build an mr file?
(1) Specify if the message is a delimited or a fixed-length message:
For fixed-length messages, the mr file header looks like this:
<multirecord name="mymultirecord" type="fixed-length" lineDelimited="true" recordDelimiter="\r\n" quoteSymbol-character=""" quoteSymbol-escapeSequence="\"" xmlns="http://xmlns.babelway.com/2007/multi-record">
For delimited messages the mr file header looks like this:
<multirecord name="mymultirecord" type="delimited" fieldDelimiter="," recordDelimiter="\r\n" quoteSymbol-character=""" quoteSymbol-escapeSequence="\"" xmlns="http://xmlns.babelway.com/2007/multi-record">
* recordDelimiter defines the delimiter between each record, it is usually the ending line character represented on windows by \r\n, on Unix/Linux by \n and on Macintosh by \r.
Note: It is recommended when creating Multirecord for the "Message In" to remove the LineDelimited in order to support all EOL "End Of Line" for any of those operating systems.
* lineDelimited specifies if the system uses a record delimiter. If set to false, the record will be based on the sum of the fields length for fixed length or the number of fields for delimited multirecords.
* trim specifies if the white spaces at the beginning and the end of the fields should be removed.
* fieldDelimiter is only used with a delimited message, defines the field delimiter.
* quoteSymbol-character is the character used to quote a field (often ")
* quoteSymbol-escapeSequence is the sequence that displays the quote symbol character in a quoted field (often \")
Tip:
For multirecord as Message In, do not specify recordDelimiter; the system will catch the \r or \n or \r\n. For multirecord as Message Out, DO specify recordDelimiter as being for instance "\r\n"; this will generate windows compliant file and let you change the delimiter from the advanced properties later on.
(2) Write the message records definitions:
You should specify the name for the record and for each of its fields. Each record should have at least one field with a static value which is used to identify the record.
<record name="Record1"> <field name="recordType" value="R1" width="2"/> <field name="field1" width="5"/> <field name="field2" width="3"/> </record>
* the width is only mandatory for fixed-length messages
* value is used to specify a static value of the field that never changes.
By default all first fields with a static value are used to identify a record. But, you can also manually define which fields must be used to identify a record using the identifier parameter.
Note: The identifier is case sensitive, so identifier="true" is not equal to identifier="True".
<record name="Record1">
<field name="recordType" value="R1" width="2" />
<field name="fieldA" width="5"/>
<field name="fieldB" width="3" value="BBB" identifier="true"/>
<field name="fieldC" width="7" />
<field name="fieldD" width="2" value="DD" identifier="true"/>
</record>
In this case, only the third and fifth fields (fieldB & fieldD), with identifier equals to "true", is used to identify the record. The default (without identifier="true") is only using recordType field as the identifier.
Remark:
For fixed-length messages, the fields used to identify a record should have the same position and length in each record. No overlap between identifiers is allowed between records, If there is only one field used to define the records, it should have the same position and can have a different length in each record.
If fixed-length messages have variable length identifiers per record, the only way to define it in the mr files is to first define the smallest common length identifier for all records and then for each record that has a longer identifier, add as many smaller fields as needed to unambiguously identify each record.
Note: if the multi-record file has a leading spaces, it must be taken into account while defining the mr file and make sure that the identifiers are at the same position, so you can remove the leading spaces by using the "Replacement based on regular-expressions" Extra Processing and add the following regex (?m)^[\s]+ to match all the leading spaces and replace them with empty values as shown below:
Regular expression to remove the leading spaces
Note: In Babelway, we're using the standard Java version of REGEX, and it's the same used all over the system.
For example, if we have a message where AAAAA, 111 and 2222 are identifiers as shown below:
AAAAA contentcontent anothercontent 1112222 this and that
The following definition is not valid since the fieldA is bigger than field1 and moreover, fieldA also overlaps with field2 and only the first record will be read:
<record name="Record1">
<field name="fieldA" width="5" value="AAAAA" identifier="true"/>
<field name="fieldB" width="16" />
<field name="fieldC" width="16" />
</record>
It should be replaced by using the "Replacement based on regular-expressions" Extra Processing as indicated before:
<record name="Record1">
<field name="fieldA" width="3" value="AAA" identifier="true"/>
<field name="fieldA" width="2" value="AA" identifier="true"/>
<field name="fieldB" width="16" />
<field name="fieldC" width="16" />
</record>
<record name="Record2">
<field name="field1" width="3" value="111" identifier="true"/>
<field name="field2" width="2" value="22" identifier="true"/>
<field name="field2" width="2" value="22" identifier="true"/>
<field name="field3" width="15" />
</record>
We had to split fieldA in two in order to have one fieldA 3 characters long (the same as field1) and another fieldA with the 2 remaining characters.
Then field2 (length 4) was also bigger than the second fieldA (length 2) so we also need to split it in two field2 of 2-character length.
All corresponding identifiers now have the same length (3 and 2) and there is no overlap between them.
It is also possible to add 4 extra settings (label, description, justify & padCharacters) to each field:
<field name="myField" label="My Field" description="My field description" justify="right" padCharacter="x" width="10"/>
* label and description are used to display the message tree.
* justify can be center, left or right.
* padCharacter is the character used to fill an empty space in the field width.
(3) Define the message structure at the end of the mr file:
<xml>
<group name="Transaction" maxOccurs="unbounded">
<group name="headers">
<record name="header" minOccurs="1" maxOccurs="unbounded"/>
</group>
<record name="record1" maxOccurs="unbounded"/>
<group name="footers">
<record name="footer" />
</group>
</group>
</xml>
*Each element can define the minOccurs and the maxOccurs setting with either 0, a positive number or 'unbounded'.
* Records defined in the records simplesect can only appear once in the message structure.
* Records can be grouped using the group element. The name of the group is mandatory.
* Records in a group should be ordered in the same way they appeared in the message.
Sample of a multirecord fixed-length message:
HH00123 AB HH00045 CDE R1one 100 R1two 101 R1four 103 FF3
Sample of a multirecord definition file:
<?xml version="1.0" encoding="UTF-8"?>
<multirecord name="mymultirecord" type="fixed-length" recordDelimiter="\r\n" quoteSymbol-character=""" quoteSymbol-escapeSequence="\"" xmlns="http://xmlns.babelway.com/2007/multi-record">
<records>
<record name="header">
<field name="recordType" value="HH" width="2"/>
<field name="header1" width="5" justify="right" padCharacter="0" />
<field name="header2" width="4" justify="right" padCharacter=" " />
</record>
<record name="record1">
<field name="recordType" value="R1" width="2"/>
<field name="field1" width="5" label="My field" description="My field Descritpion" />
<field name="field2" width="3"/>
</record>
<record name="footer">
<field name="recordType" value="FF" width="2" />
<field name="footer1" width="1"/>
</record>
</records>
<xml>
<group name="Transaction" maxOccurs="unbounded">
<group name="headers">
<record name="header" minOccurs="1" maxOccurs="unbounded"/>
</group>
<record name="record1" maxOccurs="unbounded"/>
<group name="footers">
<record name="footer" />
</group>
</group>
</xml>
</multirecord>
Note: When updating the MultiRecord structure, you must update it from the "MultiRecord definition" file first (not from the message tree) and then by using the "Rerun creation wizard" button, upload the updated "MultiRecord definition" file from the "Message In" or "Message Out".
The following properties are available: