ZPL reports

Use this function to describe reports to be printed on ZPL printers.

Presentation

What is a ZPL Printer?

ZPL printers are label printers that use the Zebra Programming Language (ZPL), a command-based language developed by Zebra Technologies. ZPL controls the formatting, layout, and printing of labels at high speed.

These printers are optimized for performance and are ideal for high-volume environments such as:

  • Warehouses

  • Manufacturing facilities

  • Logistics centers

  • Retail operations

Unlike standard printers, ZPL printers process commands directly in their firmware, reducing graphic processing on the computer side and significantly speeding up print times.

ZPL language overview

ZPL uses text-based commands to describe label layout, including:

  • Format commands: Define label size, print speed, darkness, and so on.

  • Field data commands: Insert text, bar codes, or images.

  • Control commands: Start and end of labels, quantity to print, and so on.

This approach minimizes data transfer and maximizes printing speed.

ZPL reports in Sage X3

In Sage X3, ZPL reports are designed to work with ZPL printers. ZPL reports:

  • Are linked via a checkbox and connection link

  • Can share parameters with ZPL printers or Crystal Reports

  • Use a data model and selection criteria to define the data feeding the print flow

  • Are based on a file template (.PAT) that defines the label format

  • Include calculated expressions that can be listed in the record and are subject to conditions

Output behavior

  • If the output destination is Preview, Printer, Message, File, or Archiving, the Crystal Reports report is printed normally.

  • If the output type is ZPL printer, the ZPL report is generated and transmitted directly to the printer’s port.

Performance improvements

Since release 2025.R2/V12.0.38, local variables are used to evaluate the conditions required for generating the report prior to executing the Link instruction. This change significantly improves the performance and accelerates the overall process execution.

ZPL file structure

A ZPL file typically includes:

  • A header:

    Copy 
    ^XA
    ^DFR
    ^XZ

  • A body:

    Copy 
    ^XA
    ^CF0,160
    ^FO220,50^FDSAGE^FS
    ^CFA,30
    ^FO50,300^FDThis line is hardcoded^FS
    ^FO50,340^FVX3E_1^FS
    ^FO50,380^FVX3E_2^FS
    ^FO50,420^FVX3E_3^FS
    ^XZ

  • A footer:

    Copy 
    ^XA
    ^IDFR
    ^XZ

You can create these files using a plain text editor and save them with a .PAT extension. You then need to place them in the server directory: <folder>/PAT/*.PAT.

For more information, refer to the Zebra printing how to guide.

Prerequisites

Refer to the implementation documentation.

Screen management

The screen is defined in 3 sections:

Entry screen

Header

Setup code (CODPAR)

Identifies a ZPL print setup. This code is linked to a report.
Description (INTIT)

Use this field to assign a description to each record.
Active (ENAFLG)

Select this checkbox to activate the current record.

Inactive records retain their content and setup but cannot be used by recalling their code:

  • On other records such as documents and settings
  • On mass processes

The authorizations for a given function can prevent the creation of an active record. In this case, the checkbox is disabled by default. It can only be modified by an authorized user or through a signature workflow.
Template file (PATNAM)

Select the template used to generate the final file for printing.

This field is optional for manual file creation via the ARZ_REPORT action.

When defined, the template is stored in the database and versioned. It is then possible to use a given version number.

You need to create templates in the PAT directory of the current application, using the .PAT extension. A zoom function is available to view template files but you cannot use it to filter them.

To create a new report, the template file must exist. Upon record creation, the system reads the file and stores its characteristics as version 1.

To update a template:

  1. Place the new version in the directory.

  2. Right-click on the template code and select New version.

  3. The new version is stored, the version number is incremented, and it becomes the default. Previous versions remain selectable.

    If the file's creation date matches the previous version, a No new version message displays.

A template file can be one of the following types:

  • Mask: A mask containing variables is predefined and loaded into the print server memory. Data is then sent and merged with the mask to produce labels. You can view the mask description in the Mask tab.
  • Structures: Includes a header, lines, and a footer. You can view each section in its respective tab.
Version (VER)

Select the version of the pattern used during printing.

By default, the latest version is used.

If a setup named version is added to the report setups, its value overrides the default.
Mask issue (ENVMSK)

Select this checkbox to prevent users from sending the mask to the printer.

Mask transmission can be time-consuming, especially with graphical content.

Data section

Data model (MODDON)

Select the data template used to generate the link for reading data to produce the file.

The link is generated in a WMZPL* processing after setup creation or modification.

Use the Validation button to force processing generation.

Expression section

Number (NUM)

This number is used to reference the expression in tags (n=number):

  • X3E_n for parsing type templates

  • ^FNn for mask type templates

The tag is replaced by the evaluated expression value in the output file.

A number can appear multiple times. The condition determines which expression is used.
Condition (CND)

Use this field to manage multiple lines for the same number.

Each calculated field is identified by a number.

The first expression with a satisfied condition is retained.
Expression (EXPLIG)

This expression is valuated during the read loop defined by the data template when generating the print file.
Criteria (CONDIT)

Define the selection criteria for the request.

Multiple lines are linked via a logical AND.

Criteria are passed directly to the database via Link instruction clauses unless the formula contains special functions (for example, Func).

If special functions are used, criteria act as filters during data reading.

Notable function: func ARZIMP.PARAM("name") retrieves report setups and is optimized in the request by being converted to a constant.

You can also define additional selection criteria in the data template.

Specific buttons

Click this button to generate the processing that enables the generation of the flow for transmission to the printer.

Error messages

Other than the generic messages, the following error message can appear when entering data:

No new version

An attempt was made to save a new version of the print template, but the supplied file is older than the previous one.

Tables used

Refer to the implementation documentation.