How to create, print PDF417 in Eclipse BIRT reports?

Here we will learn how to generate, print, customize PDF417 barcodes within Eclipse BIRT (Business Intelligence and Reporting Tools) reports. PDF417 is a two dimensional stacked linear barcode symbology used extensively in transport, identification cards, inventory management, and other applications where high data density and error correction are required. The name "PDF" stands for Portable Data File. The PDF417 symbology was invented by Dr. Ynjiun P. Wang at Symbol Technologies in 1991.


The BarcodeLib BIRT PDF417 Generator is an Eclipse BIRT Custom Extended Report Item built on the BarcodeLib Java Barcode Generator library. It enables you to generate high quality PDF417 barcode images directly in BIRT reports without writing Java code. All PDF417 property settings 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. It generates high quality PDF417 barcode images in PNG format by default, with support for other raster formats as well.

The BarcodeLib BIRT Barcode PDF417 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 PDF417 component specifically targets the PDF417 symbology, which is widely used in logistics, government identification, and supply chain management due to its ability to encode large amounts of data (up to about 1.1 kilobytes in byte compaction mode) and its robust error correction.

Valid data scope for PDF417 encoding:

• All 128 ASCII characters (including A - Z, a - z, 0 - 9, punctuation, and control characters).
• Extended ASCII characters (values 128 - 255) in accordance with ISO 8859-1 (Latin 1). These are referred to as extended ASCII and include accented letters and special symbols.

This section provides a step by step guide to generating and printing PDF417 barcodes in a BIRT report.

1. Create a new empty report in your BIRT report barcoding project
2. Open the Palette view and add the barcode report item
3. Edit the barcode parameters
   Right click the barcode item you have added and select Properties from the context menu. This opens the General tab, where you will find all barcode properties.
   • For static text data, enclose the value in double quotation marks (e.g., "12345").
   • For data set expressions, do not use quotes; instead, enter an expression such as row["CUSTOMERNUMBER"].
4. Change the barcode type to PDF 417
   In the General tab, locate the Barcode Type property. Change it from the default (e.g., Code 128) to PDF-417 (or PDF417 depending on the plugin version).
5. Preview the report
   Click the Preview button (or View Report) on the toolbar. A PDF 417 barcode image should be printed on your BIRT report.

PDF417 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.

PDF417 can encode multiple character sets, which you configure indirectly through the Data Mode property and the Process Tilde property:

• Full ASCII (all 128 characters) : This is supported in both Text and Byte compaction modes. It works for most standard text data (e.g., URLs, plain text IDs) in BIRT reports.
• Extended ASCII (ISO 8859-1 values 128 - 255) : Supports special characters such as accented letters, currency symbols, and punctuation marks. These are common in international BIRT reports and support locale/internationalization requirements.
• Up to 811,800 different character sets or data interpretations : Configurable via binary data mode. Use the Process Tilde property with the ~7dddddd escape sequence.
• Various function codewords : Used for control purposes, such as reader programming (~rp) and macro markers (~m5, ~m6). These are configured through the Data property using tilde escapes.

PDF417 supports three compact encoding modes. You can let the library auto select the best mode, or you can manually set it using the Data Mode property in the Report Item Property view:

• Auto Mode : The PDF417 library automatically selects the most efficient encoding mode based on the input data. This is the recommended setting for most BIRT reports, especially those with mixed data types.
• Text Compaction Mode : Permits all printable ASCII characters (values 32 - 126 inclusive, in accordance with ISO/IEC 646 (IRV)) and selected control characters. Ideal for plain text data in BIRT reports.
• Byte Compaction Mode : Permits all 256 possible 8 bit byte values. This includes all ASCII characters (values 0 - 127) and supports international character sets, binary data, and Unicode text. Required when EncodeUnicodeText is set to true or when non printable characters are present.
• Numeric Compaction Mode : Permits efficient encoding of numeric data strings. Optimized for numeric IDs, transaction numbers, or other numeric data common in enterprise BIRT reports.

Note
Manually selecting an incompatible encoding mode (e.g., Numeric Compaction Mode for Unicode text) will cause encoding errors. Always use Auto Mode if you are unsure about the data type, or verify the data set field's data type before selecting a mode.

The maximum data length of a PDF417 barcode depends on its encoding mode and the error correction level (ECL). The following limits apply to the lowest error correction level (ECL 0), which provides the highest data capacity:

• Text Compaction Mode: Up to 1,850 characters.
• Byte Compaction Mode: Up to 1,108 characters (ideal for extended ASCII or binary data in BIRT reports).
• Numeric Compaction Mode: Up to 2,710 digits (most efficient for numeric data).

Note: Higher error correction levels reduce these capacities because more codewords are reserved for error correction.

This section walks you through encoding various text data types in PDF417 barcodes within BIRT reports, including printable ASCII text, non printable ASCII text, Unicode text, binary data.

PDF417 supports all 95 printable ASCII characters (values 32–126) with a simple configuration.

• Use data binding to map the Data property to a data set field containing printable ASCII text (e.g., "PRODUCT_NAME").

Non Printable ASCII Text

Non printable ASCII characters (e.g., Carriage Return [CR], Line Feed [LF], Tab) cannot be directly input into a Java string or a BIRT data set.

1. Set the Process Tilde property to true. This enables the PDF417 generator to interpret the tilde (~) as an escape character for non printable characters.
2. Set the Data Mode property to BYTE (required for encoding non printable characters because they fall outside the printable range).
3. Replace each non printable character with ~ followed by its three digit ASCII value. For example:
   • Carriage Return (CR, ASCII 13) > ~013
   • Line Feed (LF, ASCII 10) > ~010
   • Tab (ASCII 9) > ~009
4. Set the Data property using a BIRT expression that includes the escaped non printable characters. For example: "Data~013PDF417" encodes the string "Data", then a carriage return, then "PDF417".

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

PDF417 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.

• Set the EncodeUnicodeText property to true. This tells the PDF417 generator to use UTF-8 encoding for the input data.
• Set the Data Mode property to BYTE (required for Unicode encoding).
• Use data binding to map the Data property to a data set field that contains Unicode text (e.g., "CUSTOMER_NAME" with Chinese characters).
• Test the report in the BIRT Web Viewer to confirm the Unicode text is encoded correctly. Scan the PDF417 to verify the text appears as expected.

Customize the size and dimensions of your PDF417 barcodes in BIRT reports using the Report Item Property view. You can adjust module size, number of rows and columns, quiet zones, unit of measure, and image resolution to ensure scannability and proper fit within your report layout.

The following PDF417 dimension settings are configurable in the Report Item Property view:

• UOM (Unit of Measure) : Select the unit for size settings (PIXEL, CM, or INCH). This ensures consistency with the report's Master Page settings.
• X (Module Width) : The width of each PDF417 module. The minimum module width is defined by your application's specifications. Smaller modules create smaller barcodes but may be harder to scan, especially in printed BIRT reports.
• XtoYRatio : The ratio of module width (X) to module height. The default value is 0.3333333f (1:3). You can change this if needed, but deviating from the standard ratio may affect scannability.
• Row Count : The number of rows in the PDF417 barcode, ranging from 3 to 90. Increasing the row count makes the barcode taller.
• Column Count : The number of data columns per row, ranging from 1 to 30. Increasing the column count makes the barcode wider and increases data capacity.
• Quiet Zones : Set LeftMargin, RightMargin, TopMargin, and BottomMargin to define the empty space around the PDF417. The minimum quiet zone width is 2X (twice the module width), as per PDF417 standards. Insufficient quiet zones are a common cause of scanning failures.
• Resolution : Set the Resolution property (e.g., 96 DPI for screen, 300 DPI for printing) to control the image quality. Higher resolution is recommended for printed BIRT reports to ensure sharp modules.
• Image Format : Set the output image format (e.g., PNG, JPEG, BMP, SVG) to meet your BIRT output format requirements (e.g., PDF, HTML, Excel). PNG is recommended for barcodes due to its lossless compression.

Note
The minimum quiet zone width is 2X. 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.

Take advantage of advanced PDF417 features in BIRT reports, including error correction levels (ECL), compact (truncated) PDF417, and Macro PDF417. All these options are configured in the Report Item Property view.

Each PDF417 symbol contains error correction codewords that provide both error detection and correction capabilities. The error correction level is selectable in the Report Item Property view via the ECL property (labeled as PDF 417 Error Correction Level). Higher levels provide greater resilience against symbol damage but reduce the available space for user data.

The following are the error correction levels and their corresponding number of error correction codewords:

• ECL 0: 2 error correction codewords (lowest error correction, maximum data capacity)
• ECL 1: 4 error correction codewords
• ECL 2: 8 error correction codewords (default)
• ECL 3: 16 error correction codewords
• ECL 4: 32 error correction codewords
• ECL 5: 64 error correction codewords
• ECL 6: 128 error correction codewords
• ECL 7: 256 error correction codewords
• ECL 8: 512 error correction codewords (highest error correction, minimum data capacity)

Note
For BIRT reports that will be printed on labels that may be scratched or smudged (e.g., shipping labels), consider using ECL 3 or higher. For reports that are only viewed on screens (e.g., dashboards), ECL 0 or 1 may be sufficient.

Compact PDF417 (also called Truncated PDF417) is used when space is a primary concern and symbol damage is unlikely. It removes the right hand row indicator and the stop pattern, resulting in a narrower barcode. However, this makes the symbol less resilient to damage because the row indicators help scanners synchronize.

• Set the Truncated property to true in the PDF417 section.
• Preview the report to verify the compact symbol.

Note
Compact PDF417 is less resilient to damage than standard PDF417. Only use it in controlled environments where the barcode is unlikely to be scratched or smudged (e.g., digital BIRT reports viewed on screens or labels that are handled carefully).

Macro PDF417 provides a mechanism for splitting large data into blocks and representing it in multiple PDF417 symbols. This is similar to the Structured Append feature in QR Code and Data Matrix 2D barcodes. Each Macro PDF417 symbol contains additional control information (file ID, segment index, total segment count) that enables the original data to be properly reconstructed regardless of the scanning sequence. Up to 99,999 individual PDF417 symbols can be used for Macro PDF417 encoding.

• Select the barcode report item and open the Report Item Property view.
• Enable the MacroPDF417 property (or 2D Barcode Structured Append depending on the plugin version) to true.
• Set the MacroSymbolCount property (or Symbol Count) to the total number of PDF417 symbols needed to store the full data. For example, set to 3 if splitting data into 3 barcodes.
• Set the MacroSymbolIndex property (or Symbol Index) to the sequence number of the current PDF417. The index starts at 0 for the first symbol, 1 for the second, and so on.
• Set the MacroFileId property (or File Id) to a unique integer (e.g., 12345). All symbols in the same Macro PDF417 sequence must have the same MacroFileId.
• Use a data set with a Group (a BIRT component that organizes data by a field) to split the data into chunks. Bind each chunk to a separate barcode report item in the Detail Row of a Table to generate multiple PDF417 barcodes.

The BIRT plugin does not automatically split data across multiple symbols. You must pre split the data in your data set (e.g., using a scripted data source or a stored procedure) and then generate one barcode per chunk. Ensure that the SymbolCount and SymbolIndex are set correctly for each chunk.

Note
Macro PDF417 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.

This comprehensive guide has provided a complete, step by step workflow for generating PDF417 barcodes in BIRT reports for Eclipse Java projects. All PDF417 properties are configured in the Report Item Property view of the barcode report item.

Using the BarcodeLib PDF417 BIRT Generator, you can customize PDF417 encoding, size, error correction, and advanced features (truncated mode, Macro PDF417) to meet your BIRT report's specific requirements, whether for transport, identification cards, inventory management, or enterprise reporting.