Skip to content

Console Application User Guide

Jump to bottom
Terry Burton edited this page Oct 4, 2024 · 3 revisions

This guide provides basic instructions for getting started with the demonstration console application that comes with the GS1 Barcode Syntax Engine ("Syntax Engine").

An overview of the features of the application is provided on the project homepage.

Launching the application

Once the application has been downloaded to a location of your choice (or built from source) as described on the project homepage, you can launch it by either double-clicking on the program icon (typical for Windows) or by entering the following at the command prompt (typical for Linux):

cd [location that you placed the binary]
./gs1encoders-linux.bin

Note: The first time that you attempt to run the application your antivirus software may block the attempt because the application or publisher isn't recognised. You should be able to click "more info" (or similar), read the information provided, and you may then decide to "run anyway". If you are in a managed environment and are unable to proceed with running the application then it is likely that a local policy is deliberately blocking all unrecognised applications and you may then need to ask your system administrator to whitelist the application.

Quick start

Upon launch, the application will display the screen shown below:

Main menu

You must select option corresponding to data format that you wish to process or the option that you wish to set. If instead you wish to exit the application then you should choose option 0 (Exit Program).

TIP: To select an option you must type its number and then press the <ENTER> key.

Upon selecting a data format that you wish to process you must enter the data in the required format for the option that you have selected:

  • Plain data: 8, 12, 13 or 14 digits representing a GTIN-8, GTIN-12, GTIN-13 or GTIN-14.
  • Unbracketed AI element string: Use "^" to denote FNC1, for example ^010211234567890098TEST^99ABC123
  • Digital Link URI: Example https://id.gs1.org/01/2112345678900?98=TEST&99=ABC123
  • Bracketed AI element string: Omit any FNC1 characters, for example (01)02112345678900(98)TEST(99)ABC123

After entering the data the input will be validated and transformed into several common GS1 syntaxes:

  • "Barcode message": This is the contents to be included within a GS1 barcode carrier that represents the input, with FNC1 characters expressed as "^".
  • "AI element string": A bracketed rendition of the AI data from the input.
  • "Digital Link URI": The AI data is represented as a Digital Link URI, where this is possible.
  • "HRI": The AI data rendered in the form of "Human Readable Information" (HRI text). In the case that the "Include data titles in HRI" checkbox is ticked this field will show non-standard "mixed-HRI" output that includes Data Titles for each AI element.

Input validation

AI-value pairs will be extracted from element strings and Digital Link URIs and will be validated in the following ways:

  • Invalid syntactic structure for the detected input format: Ensure the input is correctly structured so that the AI-based data can be unambiguously extracted.
  • AI data contents: The contents of the AIs will be validated using the structural rules defined in the GS1 Barcode Syntax Dictionary ("Syntax Dictionary") and any components will be processed by the corresponding Linters.
  • AI associations: Unless the "Validate AI associations" option is set to OFF, the invalid pairings rules and mandatory pairing rules from the Syntax Dictionary will be applied to the input.
  • Repeated AI instances: To ensure that any duplicate instances of an AI have identical values. (To validate multiple data carriers on a trade item their AI element strings can be concatenated so that the overall message will be validated.)

If the data is non-conforming then a descriptive error will be displayed. Note that just because the contents of an AI is accepted does not necessarily indicate that it is meaningful or correct to use within your intended application. Refer to the GS1 General Specifications and applicable application-specific specifications to determine what is the acceptable contents of the barcode.

If your instance of the Syntax Dictionary and the Syntax Engine is out of date with respect to the current specification then it may be necessary to encode an AI that it knows nothing about. The application will prevent you from specifying unknown AIs unless the "Permit unknown AIs" option is set to ON. Bespoke AIs that are incompatible with the GS1 system will still be rejected if they are specified.

The optional feature for accepting unknown AIs is intended to increase the durability of the library in circumstances that necessitate a protracted software update lifecycle. Using this feature increases the risk that bad data is accepted into the barcodes that you generate, so you should always endeavour to keep this application and the library up to date.

Clone this wiki locally