Code Matching


Code Matching provides a way to ensure that the scanned barcode data matches against expected data included in the print job. This prevents e.g. an existing barcode on a product to be mistaken for a successfully applied label.

Example scenario: Applying label X on a product with an existing barcode Y.

If Code Matching would have not been used, the existing barcode Y of the same type would have been mistaken as a successful application of label X.

Expected data can be included in print jobs using the special variable "_code_matching". This works for JSON-RPC and ZPL.

See also

Code Matching in the JSON-RPC API documentation for details on pattern matching and matching policy.

Error Classes

Barcode errors have been categorized in three different classes:


One or more barcode not readable because:

  • Label does not stick to the product.
  • Broken printhead dots.
  • Layout errors.
  • Media errors.

Unexpected barcodes read because of:

  • A stray label is visible by the scanner.
  • Barcodes already present on the product.

Unexpected barcodes read because of:

  • Synchronization error (the host and the printer are mismatched – possibly due to differing views on the job queue state).
  • Product conveying issues (products unexpectedly appearing or missing) before printing and applying.

Validation Techniques

Using a scanner it is possible to validate the existance of barcodes in different ways:

Require n barcodes
The basic way to use a scanner is to require a number of readable barcodes on each scan. This is only effective against ERR_TOO_FEW which is implied in all cases below.
Require no_read - Not implemented
A scanner can also give feedback whether any readable barcodes exist prior to label application.
Internal Matching
The printer matches the scanner against a stored expected data set.
External Code Matching - Not implemented
The expected data set is sent in a host-controlled scanning command. This way the marker doesn’t need to hold any state, and any synchronization errors are catched as well. Requires the most integration work in the host system.

The table describes which combination of errors (ERR_TOO_FEW and Require n barcodes is implied in all cases) can be detected using different validation strategies.

  • The first two columns denotes which error classes that are expected to be present.
  • The next three columns describes which validation techniques that are used.
  • Finally the Detection column sums up whether the combination of employed validation techniques will reliably detect the present error classes.
ERR TOO MANY ERR SYNC Require no_read Internal Matching External Matching Detection
OK – Scanner detects non-readable barcodes.
Yes UNRELIABLE – if scanner cannot distinguish between a stray label/barcode and the printed label.
Yes Yes Fair – Code Matching increases probability to find stray labels, but will only work for unique labels.
Yes Yes OK – Requiring no_read before applying prevents stray labels or present barcordes to be mixed up with the last printed label.
Yes Yes/– Yes/– UNRELIABLE – Synchronization errors risk to pass undetected.
Yes Yes/– Yes OK – external Code Matching finds synchronization errors.
Yes Yes Yes Possibly UNRELIABLE – if scanner cannot distinguish between stray label and the printed label.
Yes Yes Yes Yes OK – Requiring no read before applying prevents stray labels or present barcodes to be mixed up with the last printed label. Combined with external Code Matching this is the safest option.


Failed Application With Scanner

With a scanner, an unreadable barcode or non-existent label will be detected.

UNDETECTED: Failed Application With Scanner and Stray Label

Even with a scanner, a stray label, or old barcodes on the product itself could potentially be mistakenly taken for a successful labeling.

Failed Application With Code Matching and Stray Label

Using Code Matching we can decrease the probablity that a stray label would be mistaken for the real label.

In summary, internal Code Matching helps with errors that happens external to the printer sequence. E.g. labels being mechanically dropped, or scanner potentially scanning other labels.

UNDETECTED: Printer Synchronization Error With Code Matching

If the host system and printer fails to synchronize their world views on the expected product to print and apply due to e.g. queuing issues, there is a risk that internal Code Matching does not detect any errors.

Printer Synchronization Error With External Code Matching

By letting the host request the scanning with an explicit match data set, any synchronization errors can be detected. This requires a higher level of integration but would give the most robust solution to any interference during the print and apply sequence.

Revision History

Revision 2021-01-05

  • Updated transport of expected data in ZPL files.

Revision 2021-01-31

  • Minor changes to UI element naming and examples.

Revision 2021-01-22

  • Changed pattern matching syntax from regular expressions to Unix shell style matching using easier to understand * and ? wildcards.

Revision 2021-01-21

  • Changed name from Match Count to Matching Policy.
  • Changed name from Match Method to Matching Method.
  • Updated pattern matching examples using valid regular expression syntax.