---
title: Output
slug: output
docTags: 
createdAt: 2023-03-08T17:46:24.000Z
---

## Output Destinations

### Console 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 <font color="#eb144c">`-output=console`</font> OR no <font color="#eb144c">`-output`</font> option is set
- Console output is sent to <font color="#eb144c">`stdout`</font>. All errors, diagnostics, versions, and help information are sent to <font color="#eb144c">`stderr`</font>.
- The <font color="#eb144c">`-format`</font> option defines the format of the console output. The default is `json`.
- If <font color="#eb144c">`-format=text`</font>, then the <font color="#eb144c">`-output-text`</font> option must be set
- If the <font color="#eb144c">`-output`</font> option is not set, and the last values of the <font color="#eb144c">`-format`</font>, <font color="#eb144c">`-fields`</font>, and <font color="#eb144c">`-output-text`</font> options are applied to the console output.

### Output files

- 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 <font color="#eb144c">`-output-text`</font> option must be set.
- If `JSON`, `CSV`, or `TEXT` file already exists, the output action depends on the value of <font color="#eb144c">`-if-exists`</font> 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 <font color="#eb144c">`-output`</font> option value.
  Options <font color="#eb144c">`-fields`</font>, <font color="#eb144c">`-output-text`</font>, <font color="#eb144c">`-if-exists`</font> , if set, should precede the <font color="#eb144c">`-output`</font> option for their value to be applied to that output file.
  Different options can be specified before each <font color="#eb144c">`-output`</font> options to create multiple, different outputs from the same session.

## Output Formats

### Output content (JSON, CSV, TEXT)

- Content of `JSON`, and `CSV` outputs is defined by the <font color="#eb144c">`-fields`</font> option
- `CSV` Format: Double quotes (<font color="#eb144c">`""`</font>) enclose:
  - Barcode text values
  - Filenames containing spaces or commas
- The content of `Text` outputs is defined by <font color="#eb144c">`-output-text`</font> 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

### BIN output

- 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: <font color="#eb144c">*some-folder*/some-*prefix*.{filename}.p{page}.i{ind}.t{type}.bin</font>
- `BIN` output is not available for console output
- A `BIN` output file can not be appended

### TEXT output

Text format output is based on the [macro](docId\:LCj_sxpqwHwUR1q-9vvGz) 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**                                                    |
| ------------------------------------------ | ------------------------------------------------ | ------------------------------------------------------------------------------------- |
| <font color="#eb144c">`[onSesion]`</font>  | After session started                            | Environment variables macros<br />Command-line macros<br />Session macros<br /><br /> |
| <font color="#eb144c">`[onSource]`</font>  | Source processing is completed<br />             | all of the above +<br />Source macros                                                 |
| <font color="#eb144c">`[onFile]`</font>    | Image file processing is completed               | all of the above +<br />File macros                                                   |
| <font color="#eb144c">`[onPage]`</font>    | Page processing is completed<br />               | all of the above +<br />Page macros                                                   |
| <font color="#eb144c">`[onBarcode]`</font> | Barcode is read<br />                            | all of the above +<br />Barcode macros                                                |
| <font color="#eb144c">`[onDrvLic]`</font>  | Barcode with driver's license data is read<br /> | all of the above +<br />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

:::BlockQuote
\{text}\{nl}
:::

Example 2 - Complete text output with events processing:

:::BlockQuote
**\[onSession]**\{tab}SESSION:  application: \{app.filename}\{tab} \{app.version}
\{tab} date/time: \{start.date} \{start.time}**&#xA;\[onSource]**\{tab|#x2}SOURCE:  type: \{type}  path: \{path}
\{tab|#x2} files: \{files}  bc.count: \{bc.count}**&#xA;\[onFile]**\{tab|#x3}FILE path: \{path}
\{tab|#x3} pages: \{pages}  format: \{format}  size: \{size}  bc.count: \{bc.count}**&#xA;\[onPage]**\{tab|#x4}PAGE\:path: \{path}  page: \{page}
\{tab|#x4} width: \{width}  height: \{height}  bpp: \{bpp}  hdpi: \{hdpi}  vdpi: \{vdpi}
\{tab|#x4} compr: \{compr}  bc.count: \{bc.count}**&#xA;\[onBarcode]**\{tab|#x5}BARCODE:  type: \{type}  length: \{length}  
\{tab|#x5} rectangle: \{rectangle.left}:\{rectangle.top}-\{rectangle.right}:\{rectangle.bottom}
\{tab|#x5} rotation: \{rotation}  path: \{path}  page: \{page}
\{tab|#x5} skew: \{skew}  mode: \{mod}  encoding: \{encoding}
\{tab|#x5} text: \{text}
\{tab|#x5} data: \{data}**&#xA;\[onDrvLic]**\{tab|#x6} DRIVER LICENSE:
\{tab|#x6} NAME: \{last}   \{middle}   \{first}
\{tab|#x6} DATA: \{dob}  EYES: \{eyes} HAIR: \{hair}  SEX: \{sex} HEIGHT: \{height} WEIGHT: \{weight}&#x20;
\{tab|#x6} ADDRESS: \{street}  \{city}  \{state}  \{postal}
\{tab|#x6} LICENSE: \{id}  ISSUED: \{issued}  EXPIRES: \{expires}
:::

##  Non-English barcode text&#x20;

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** |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| <font color="#eb144c">`UTF8`</font>      | Text is encoded as UTF-8 before barcode generation                                                                                                          | yes                |
| <font color="#eb144c">`ECI`</font>       | Barcode generator uses  [Extended Channel Interpretation](https://en.wikipedia.org/wiki/Extended_Channel_Interpretation)                                    | yes                |
| <font color="#eb144c">`Generator`</font> | The Barcode generator encodes text according to barcode type specification, e.g., [KANJI](https://en.wikipedia.org/wiki/QR_code) for QR code.               | yes                |
| <font color="#eb144c">`CodePage`</font>  | Text encoded using language-specific [code page](https://www.inliteresearch.com/help/BarcodeReaderCLI/barcodereadercli_help.htm) before barcode generation. | no                 |



The barcode recognition engine automatically detects and outputs the **UTF-8** barcode values for <font color="#eb144c">`UTF8`</font>, <font color="#eb144c">`ECI`</font>, and <font color="#eb144c">`Generator`</font> types.

To convert <font color="#eb144c">`CodePage`</font>  text to UTF-8 text set <font color="#eb144c">`-encoding`</font> option before <font color="#eb144c">`source`</font>  &#x20;

:::hint{type="danger"}
Using incorrect <font color="#eb144c">`-encoding`</font> for <font color="#eb144c">codePage</font> type barcodes results in an incorrect output text value.
:::

BarcodeReaderCLI uses [iconv](https://en.wikipedia.org/wiki/Iconv) library to perform conversion from all popular languages to UTF-8. A list of typically supported encodings is shown [here](https://www.inliteresearch.com/help/BarcodeReaderCLI/output/encodings.txt). Some of the encoding names are just aliases for the same encoding.