Output
BarcodeReaderCLI generates output data written to the specified output file or to the console. Console output can be redirected to a file or piped to another application.
- Console output is generated if -output=console OR no -output option is set
- Console output is sent to stdout. All errors, diagnostics, versions, and help information are sent to stderr.
- The -format option defines the format of the console output. The default is json.
- If -format=text, then the -output-text option must be set
- If the -output option is not set, and the last values of the -format, -fields, and -output-text options are applied to the console output.
- The format of the output file is defined by the output file name extension.
- JSON for a file with .json extension
- CSV for a file with .csv extension
- BIN for a file with .bin extension
- Text for a file with any other extension. The -output-text option must be set.
- If JSON, CSV, or TEXT file already exists, the output action depends on the value of -if-exists option.
- overwrite replaces the existing file
- append adds the new data to the existing file.
- unique adds a unique index to the filename preceding the extension, i.e., the modified filename becomes basename.NNNN.ext Where NNNN is a unique file index.
- error generates a runtime error
- Multiple output files can be specified, each requiring a separate -output option value. Options -fields, -output-text, -if-exists , if set, should precede the -output option for their value to be applied to that output file. Different options can be specified before each -output options to create multiple, different outputs from the same session.
- Content of JSON, and CSV outputs is defined by the -fields option
- CSV Format: Double quotes ("") enclose:
- Barcode text values
- Filenames containing spaces or commas
- The content of Text outputs is defined by -output-text option
- Text values are stored as UTF-8 to represent non-English values accurately. If the barcode contains binary data, its text value is modified per JSON and CSV format requirements.
- If the output is appended to an existing file:
- JSON format adds the object to "sessions":[] array
- CSV format: append new rows. The existing header row is not updated.
- Text format: append new text
- The output file contains a single barcode value as a byte array.
- If the image contains multiple barcodes, a unique name is created to hold the output of each barcode. For example: some-folder/some-prefix.{filename}.p{page}.i{ind}.t{type}.bin
- BIN output is not available for console output
- A BIN output file can not be appended
Text format output is based on the macro expansion. By default, the output is initiated when a new barcode is read. An event identifier must precede macro reference to trigger processing on a new event. Available event identifiers are:
Event identifier | Event | Macros available for expansion |
[onSesion] | After session started | Environment variables macros Command-line macros Session macros |
[onSource] | Source processing is completed | all of the above + Source macros |
[onFile] | Image file processing is completed | all of the above + File macros |
[onPage] | Page processing is completed | all of the above + Page macros |
[onBarcode] | Barcode is read | all of the above + Barcode macros |
[onDrvLic] | Barcode with driver's license data is read | all of the above + Driver license macros |
Text outside of the macro reference is copied to the output as is. Example 1 - Output each barcode text value on a separate line
Example 2 - Complete text output with events processing:
All output formats are created using UTF-8 encoding to accurately represent non-English file names and barcode text values. Localized language text can be encoded in the barcode in several ways:
Type | Generation process | auto-detection |
UTF8 | Text is encoded as UTF-8 before barcode generation | yes |
ECI | Barcode generator uses Extended Channel Interpretation | yes |
Generator | The Barcode generator encodes text according to barcode type specification, e.g., KANJI for QR code. | yes |
CodePage | Text encoded using language-specific code page before barcode generation. | no |
The barcode recognition engine automatically detects and outputs the UTF-8 barcode values for UTF8, ECI, and Generator types.
To convert CodePage text to UTF-8 text set -encoding option before source
Using incorrect -encoding for codePage type barcodes results in an incorrect output text value.
BarcodeReaderCLI uses iconv library to perform conversion from all popular languages to UTF-8. A list of typically supported encodings is shown here. Some of the encoding names are just aliases for the same encoding.