How to create, print Data Matrix 2d barcode in Eclipse BIRT reports?

Here we will learn how to generate and print Data Matrix barcodes within Eclipse BIRT (Business Intelligence and Reporting Tools) reports. Data Matrix is a two dimensional matrix barcode composed of black and white modules arranged in a square or rectangular pattern. It can encode text or raw data ranging from a few bytes up to approximately two kilobytes, depending on the symbol dimensions. Error correction codes are embedded into the symbol, which allows the barcode to remain readable even when partially damaged. A single Data Matrix symbol can store up to 2,335 alphanumeric characters.


The BarcodeLib BIRT Data Matrix Generator is an Eclipse BIRT Custom Extended Report Item built on top of the BarcodeLib Java Barcode Generator library. It enables you to generate high quality Data Matrix barcode images directly in BIRT reports without writing Java code. All Data Matrix properties are configured exclusively in the Report Item Property view of your Report Design file (.rptdesign). The plugin is distributed as a single JAR file, requires no registration key or activation code, and is easy to redistribute.

The BarcodeLib BIRT Barcode Data Matrix Generator is an Eclipse BIRT Custom Extended Report Item that allows you to easily generate and print high quality linear (1D) and two dimensional (2D) barcodes in your BIRT reports. The Data Matrix component specifically targets the Data Matrix symbology, which is widely used in manufacturing, logistics, healthcare, and retail for labeling small items due to its high data density and error correction capabilities.


Valid data scope for Data Matrix encoding:

• All 128 ASCII characters (values 0 - 127) according to the US national version of ISO/IEC 646.
• Extended ASCII characters (values 128 - 255) in accordance with ISO 8859-1 (Latin 1). These are referred to as extended ASCII.

Here we will show how to create and print Data Matrix 2D barcodes in BIRT.

1. Create a new empty report
2. Add the barcode item from Palette view to the report
3. Configure Data Matrix barcode parameters
   • For static text data, enclose the value in double quotation marks, for example: "12345".
   • For data set expressions, do not use quotes; instead, enter an expression such as row["CUSTOMERNUMBER"].
4. Change the barcode type to Data Matrix
   In the General tab, locate the Barcode Type property. Change it from the default (e.g., Code 128) to Data Matrix.
5. Preview the report
   Click the Preview button (or View Report). A Data Matrix barcode image should be printed on your BIRT report.

Data Matrix supports various character sets, data lengths, and encoding modes. All these settings are configured in the Report Item Property view of the barcode report item, ensuring alignment with BIRT best practices.

Data Matrix can encode multiple character sets, which you configure indirectly through the Data Mode property:

• Full ASCII (0 - 127) : Use DataMatrixDataMode.ASCII (value 1). This is the default encoding mode and works for most standard text data (e.g., URLs, plain text IDs) in BIRT reports.
• Extended ASCII (128 - 255) : Also supported via ASCII mode. Includes accented letters, currency symbols, and punctuation marks common in international BIRT reports.
• International characters (Arabic, Cyrillic, Greek, etc.) : These can be encoded through binary encoding.

The maximum data length of a Data Matrix barcode depends on the encoding mode and the symbol size (Format Mode). The largest symbol (144×144) with low error correction can store:

• Numeric data: Up to 3,116 digits.
• Alphanumeric data: Up to 2,335 characters.
• Byte data (8 bit) : Up to 1,555 characters.

If your data exceeds the maximum length for the selected Format Mode, the library may automatically upgrade to a larger symbol (if AutoResize is enabled). However, if the data exceeds the largest possible symbol, an encoding error will occur.

Data Matrix uses six primary encoding modes. The generator can auto select the most efficient mode, or you can manually set it using the Data Mode property in the Report Item Property view:

• Auto (0) : Recommended for most BIRT reports. The library evaluates the input data and selects the best mode (ASCII, C40, Text, X12, Edifact, or Base256) to minimize barcode size.
• ASCII (1) : Encodes digits and standard ASCII characters (0 - 127). Suitable for text with mixed case and punctuation.
• C40 (2) : Optimized for uppercase alphanumeric data. Encodes two characters per byte.
• Text (3) : Optimized for lowercase alphanumeric data. Similar to C40 but with a lowercase preference.
• X12 (4) : Encodes ANSI X12 electronic data interchange characters. Used in B2B reporting.
• Edifact (5) : Encodes ASCII values 32 - 94 for EDIFACT data. Common in logistics and trade reports.
• Base256 (6) : Encodes 8 bit values (0 - 255). Required for binary data, non printable characters, and Unicode text when EncodeUnicodeText is used.

Note:
Manually selecting an incompatible encoding mode (e.g., ASCII mode for Unicode text) will cause encoding errors. If you are unsure about the data type, always use Auto mode. You can also inspect the data set field's data type in BIRT to make an informed decision.

This section walks you through encoding more complex data types in Data Matrix barcodes within BIRT reports, including ASCII non printable characters, Unicode text, binary data, and GS1 data elements. All steps use the Report Item Property view and BIRT scripting features where appropriate.

Some ASCII characters (e.g., Carriage Return [CR], Line Feed [LF], Tab) are non printable and cannot be directly typed into a BIRT expression or data set. To encode these characters, you need to set the Process Tilde property to true and use the ~ddd escape sequence.

1. In the Report Item Property view, set Process Tilde to true.
2. Set Data Mode to Base256 (value 6). This is required because non printable characters require 8 bit encoding.
3. In the Data property, enter an expression that includes the tilde escape sequences. For example, to encode the string "Data" followed by a carriage return and then "Matrix", use: "Data~013Matrix". Here, ~013 represents the carriage return (ASCII 13).
4. For multiple non printable characters, chain the sequences: "Line1~013~010Line2" (CR+LF).

Note
Forgetting to set processTilde to true will cause the tilde characters to be treated as literal tildes, resulting in an invalid Data Matrix that cannot be scanned correctly. Also, ensure that you use exactly three digits for the ASCII value (e.g., ~005 for ENQ, not ~5).

Data Matrix can easily encode Unicode text (e.g., Chinese, Japanese, Arabic) in BIRT reports. The BarcodeLib library provides a dedicated property Encode Unicode Text to simplify this process.

1. In the Report Item Property view, set Encode Unicode Text to true.
2. Set DataMode to Auto or Base256 (the library will handle the conversion).
3. Bind Unicode data from your data set using a standard BIRT expression. For example, if your data set contains a column PRODUCT_NAME with Unicode values, set Data to row["PRODUCT_NAME"].
4. The library automatically converts the unicode text string to a UTF 8 byte sequence and inserts the appropriate '~' markers.
5. Preview the report. The Data Matrix should render the Unicode text correctly.

Customize the size and dimensions of your Data Matrix barcodes in BIRT reports using the Report Item Property view. You can create square or rectangular symbols, adjust module width, set quiet zones, and control the overall image size.

To generate a square Data Matrix where the width equals the height:

• Set the Barcode Width property to your desired pixel size (e.g., 200).
• The height will automatically match the width because Data Matrix symbols are square by default when using square Format Mode values.

Note:
Do not set the width to a value smaller than 100 pixels for typical Data Matrix symbols containing more than a few characters. Very small barcodes may be unreadable by standard scanners. The minimum module width (X) should be at least 2 pixels for screen display and 0.01 inch for printing.

Data Matrix (ECC200) specifies six rectangular symbol sizes. You can generate these in BIRT reports by setting the FormatMode property to one of the following values:

• 8 rows × 18 columns
• 8 rows × 32 columns
• 12 rows × 26 columns
• 12 rows × 36 columns
• 16 rows × 36 columns
• 16 rows × 48 columns

• In the Report Item Property view, set FormatMode to the desired rectangular format (e.g., Format_16X48 for 16 rows and 48 columns).
• Set Barcode Width and Barcode Height to values that maintain the aspect ratio of the selected format. For Format_16X48, the width to height ratio is 48/16 = 3, so BarcodeWidth should be three times BarcodeHeight. For example, width = 300 pixels, height = 100 pixels.
• Adjust margins as needed.

Note:
If the provided Barcode Width and Barcode Height do not match the required ratio, the library may adjust the dimensions to preserve the correct ratio, potentially overriding your values. Always calculate the dimensions from the row/column ratio to avoid surprises.

For precise control over Data Matrix dimensions, use the following advanced properties in the Report Item Property view:

• UOM (Unit of Measure) : Select PIXEL, CM, or INCH to define the unit for all size properties.
• X : Module width. For high density barcodes, a smaller X produces a smaller image but may be harder to scan. A typical value is 4 pixels for web display or 0.01 inch for printing.
• LeftMargin, RightMargin, TopMargin, BottomMargin : Quiet zone margins. The minimum recommended is 1X. For rectangular symbols, the quiet zone is equally important.
• Resolution : Image resolution in DPI. For BIRT reports that will be exported to PDF or printed, set this to 300 DPI. For HTML output, 96 DPI is sufficient.

Note
Quiet zone margins must be at least 1 module width (X). Many scanning failures are caused by margins that are too narrow, especially when the barcode is placed near the edge of a label or report page. In BIRT, you can add an empty space or padding around the barcode image using the layout properties.

Customize the color scheme and image output format of your Data Matrix barcodes in BIRT reports using the Report Item Property view. These settings ensure that your barcodes are visible and compatible with different BIRT output formats (e.g., PDF, HTML, Excel, Word).

By default, Data Matrix uses a dark module color (black) and a light background color (white). You can customize these colors to align with your BIRT report's branding or to improve contrast on colored backgrounds.

• Fore Color : The color of the modules (bars). Typically black, but can be changed to any color (e.g., dark blue). Ensure sufficient contrast with the background.
• Back Color : The background color of the barcode image. Supports standard colors and also transparent backgrounds.
• Transparent Back Color : Set this property to true to make the background transparent. This is useful if the BIRT report has a custom background color or image defined in the Master Page.

Note
Enable the Transparent Back Color property in the Report Item Property view to make the Data Matrix background transparent. This is useful when the BIRT report has a custom background color or image (added via the Master Page). However, when exporting to PDF, transparency may be rendered as white or black depending on the PDF viewer.

The BIRT Report Engine can render the Data Matrix barcode into the Report Document (.rptdocument) during runtime. You can configure the image format and quality in the Report Item Property view.

Supported formats include:

• PNG (Portable Network Graphics)
  Lossless, good for web and print. Default format.
• JPEG (Joint Photographic Experts Group)
  Lossy compression; suitable for photographs but not ideal for barcodes because compression artifacts may affect scannability. Use PNG or BMP instead.
• BMP (Bitmap)
  Lossless but large file size. Suitable for Windows only deployments.
• SVG (Scalable Vector Graphics)
  Vector format that scales without loss of quality. Ideal for PDF export and high resolution printing.
  
  Note
  SVG vector format is not supported by all BIRT output formats. For example, Microsoft Excel may rasterize SVG or fail to display it. Test the report export to ensure the Data Matrix renders correctly in your target format (e.g., PDF, Word) before deployment.

Take advantage of advanced Data Matrix features in BIRT reports, including Format Mode selection, Structured Append mode, and FNC1 for GS1 compliance. All these options are configured in the Report Item Property view.

The Data Matrix ISO standard (ISO/IEC 16022) specifies 24 square symbol sizes and 6 rectangular symbol sizes for ECC 200. Each symbol size has a specific number of rows and columns, and a corresponding data capacity. You can select the FormatMode property to control the exact symbol size.

• Square formats : Ranging from 10×10 modules (small capacity) up to 144×144 modules (maximum capacity). The naming convention is Format_10X10, Format_12X12, …, Format_144X144.
• Rectangular formats

Note
The automatic upgrade feature is convenient but may change the barcode dimensions unexpectedly. If your BIRT report layout has strict size constraints (e.g., barcode must fit in a fixed size cell), disable AutoResize and ensure your data fits within the selected format.

Structured Append mode allows you to split a large data message into multiple Data Matrix barcodes. The barcodes can be scanned in sequence to reconstruct the full data. This is useful for encoding large documents or datasets in BIRT reports, such as detailed product descriptions, batch information, or long serial numbers.

• StructuredAppend : Set to true to enable this mode.
• SymbolCount : The total number of symbols in the sequence (e.g., 3).
• SymbolIndex : The index of the current symbol, starting from 0 for the first symbol.
• FileId : A unique integer identifier (same for all symbols in the sequence) to group them.

Note
Structured Append is supported by many industrial barcode scanners, but not all consumer grade scanning apps. Verify your target scanning environment before using this feature in production BIRT reports.

When the FNC1 (Function Code 1) character is placed in the first position of a Data Matrix, it signals that the encoded data conforms to the GS1 Application Identifier (AI) standard. This is commonly used in supply chain, retail, and healthcare BIRT reports for encoding product identifiers, expiration dates, batch numbers, and other GS1 data.

• In the Report Item Property view, set the FNC1 Mode property to ENABLE.
• Format the Data property with parentheses around each AI code. For example: "(01)12345678901234(17)250101(10)ABC123".
• The library automatically inserts the FNC1 character at the beginning of the encoded data and removes the parentheses (they are only for human readability).
• Preview the report. The resulting Data Matrix is GS1 compliant.

You now have a complete, step by step guide to generating Data Matrix barcodes in BIRT reports for Eclipse Java projects. All Data Matrix properties are configured in the Report Item Property view of the barcode report item, ensuring consistency and ease of management across your BIRT reports.

Using the BarcodeLib Data Matrix BIRT Generator, you can customize Data Matrix encoding, size, color, and advanced features (Structured Append, FNC1) to meet your BIRT report's specific requirements, whether for supply chain, retail, or enterprise reporting. The plugin is mature, redistributable as a single JAR, and requires no registration key.