Appendix B. Input format (ECI and Structural Append)

Data matrix encoder accepts three parameters - the data encoded, the target size, and the line feed string. The target size is an integer representing one of 30 choices that a data matrix symbol can have, plus value 0 for automatic size selection. The line feed string is used to separate lines so you can parse the result into an array of strings, with each representing a barcode row.

The data encoded is a single-byte ASCIIZ string. The control character NULL (the first one in the ASCII table) is not allowed in an ASCIIZ string, because this peculiar character is reserved as the indicator of end of string (EOS) in C language. If you want to encode this character, you need to use the escaped format.

Escaping means using an alternative form (usually a combination of several readable characters) to enter the character instead. It is necessary since some characters are not normally acceptable due to the limitations imposed by the programs or transport protocols, such as control characters (ASCII value 0 - 31).

There are several advanced data matrix features which require special input. Because all character values, from 0 to 256 can be encoded into a data matrix symbol, the only way to enter them into the input parameter is through the escaped form. These features include Macro 5 and 6, ECI and Structural Append.


If you are not encoding control characters, or not using any of the advanced features, you can skip this chapter all together.

B.1. Tilde codes

Tilde codes always start with the ASCII character tilde ~ (character value 126). The corresponding key on a standard PC keyboard sits at the top left corner, just under ESC key.

Although many vendors support it, the tilde codes are not public standards. We have not seen any endorsement by standards organizations. It does not appear in the data matrix standard either.


When nnn corresponds to a numeric value between 0 and 255, the tilde code sequence represents a character with value equal to nnn. For example, ~d032 represents a space character.


Represents a tilde (~) character.


Represents a FNC1 character. The tilde escape sequence can appear anywhere in the input.


Indicates that a structural append control block follows. See structural append topic for details.


Represents a symbol character which means that message followed is used for reader programming. This escape sequence must appear at the beginning of the input.


Represents a symbol character which encodes Macro 5 abbreviation. Must appear at the beginning of the message.


Represents a symbol character which encodes Macro 6 abbreviation. Must appear at the beginning of the input.


Indicates the start of an ECI block. This escape sequence must be followed by exact 6 digits, which corresponds to the ECI value.


Represents a character value from 0 to 26. Replace the X like in the following example: ~@=means character ASCII 0, ~A means character ASCII 1, ~B means character 2, ~C means character ASCII 3 and so on. The most used symbols are ~I for a tab and ~M which represents a carriage return.

B.2. Macro 5 and 6

Data matrix provides a way of abbreviating two industry specific header and trailer in one symbol character. This feature aims to reduce the overall symbol size. They must appear at the beginning of the input. You can use tilde codes ~5 and ~6 to enter them.

Table B.1. Macro 5 and 6

Tilde SequenceNameInterpretation
~505 Macro[)>[RS]05[GS][RS][EOT]
~606 Macro[)>[RS]06[GS][RS][EOT]

B.3. Extended Channel Interpretation (ECI)

ECI allows data streams with different interpretations to be encoded in one symbol. Without ECI the default interpretation is ISO8859-1, the Latin alphabet used in western Europe. Started from version 3.30, the ECI is supported on DataMatrix Fontware.

An ECI value can be any number between 0 and 999999. The tilde code ~7nnnnnn is used to enter the ECI value. The tilde code sequence can appear at any places of the input, but there must be exact 6 digits following ~7. For example, to start ECI interpretation 10, enter ~7000010.

B.4. Structural Append (SA)

The structural append feature allows up to 16 symbols in a structure. A capable reader can either buffer the contents of each symbol until all symbols are read, or deliver the data chunk by chunk.

To encode structural append, you must provide three settings for each symbol:

  • Symbol Sequence Indicator (SI). The sequence indicator is 1-based index which identify the position of this particular symbol in the group. Can be any number between 1 and 16.

  • Total number of symbols (TS). This value indicates the number of total symbols. Can be any number between 1 and 16. The value should be consistent among all symbols in the group.

  • File Identification Number(FID). Identify the symbol group. This number must remain the same among all the symbols in the group.

The tilde codes sequence is expressed in the following format:


For example, tilde code sequence ~2[1][126][6] indicates that the current symbol belongs to a group with file identification number as 126, and there are 6 symbols in total in this group.

The ~2 tilde code sequence must appear at the end of the input. All three fields are required and must be enclosed with square brackets ([ and ]) and must follow the tilde code ~2.

B.4.1. File ID (FID)

The File ID is a number remaining constant among all symbols in a group. It uniquely identifies the symbol group. The value for this field should be between 1 and 64516.

B.4.2. Sequence Indicator (SI)

Sequence indicator is a 1-based index number of the current symbol. In a group with total 10 symbols, the first symbol has the SI as 1 and the last has the SI as 10.

B.4.3.  Total Number of Symbols

The Total number of symbols indicates how many symbols in the group.