Barcode Label API – Label Printing for Your Application

"Barcode Forge" is available in two editions: Standard and Developer. The latter enhances the software with an API that allows you to print barcode labels directly from your own application, such as ERP, CRM, inventory management systems, warehouse management and more.

The Label API – Integrating Your Application

To print labels, your application writes the necessary data into an XML file and then passes the file path to the API. The first parameter is the label layout (project file) created in the GUI mode of "Barcode Forge", as shown in this example:

bcf.exe "C:\Labels\Layout.bcfp" "C:\TEMP\PrintJob.xml"

Here's an example of an XML print job file that contains 2 datasets, each with 3 fields for printing. Three label copies are to be printed for each dataset:

<?xml version="1.0" encoding="UTF-8"?>

<printjob labelsperrow="3" printdirection="vertical" startpositionx="2" startpositiony="4">

    <printservice name="default" tray="1"/>

    <fieldmap>

        <field>ItemNo</field>

        <field>Description</field>

        <field>Weight</field>

    </fieldmap>

    <data>

        <row>

            <cell>123</cell>

            <cell>Apple</cell>

            <cell>200</cell>

        </row>

        <row>

            <cell>456</cell>

            <cell>Orange</cell>

            <cell>180</cell>

        </row>

    </data>

</printjob>

Element and Attribute Reference

1. Print Job: The attributes associated with the root element printjob are all optional and serve as parameters for the current print job. labelsperrow defines the number of label copies to be printed per dataset, with a default value of 1. printdirection determines the printing orientation, in case printing is done on label sheets. Possible values include "horizontal" (default) and "vertical". startpositionx and startpositiony establish the position of the first label to be printed on the label sheet, starting with 1 for each. Unpictured in the above example: designno allows selection of one of three label designs (Roman numerals I, II, III in the GUI), with possible values of 1 (default), 2 or 3.

2. Print Service: The optional printservice element specifies the print service to be used. The name attribute specifies the name of the printer (case-sensitive). The printer selected in GUI mode can be addressed using "default", "" or by omitting the attribute. The tray attribute can be used to select a paper tray. The integer IDs of the printer's paper trays are displayed in GUI mode. If the attribute is omitted, the paper tray selected in GUI mode is used.

3. Field Mappings: Within the optional fieldmap element, associations are established between field names of a "Barcode Forge" project and column numbers within the datasets of the current XML print job file. For example, in the first field sub-element, the field within the "Barcode Forge" project is referenced where the first value of a dataset is inserted, and so on. If the fieldmap element is omitted, a shared position is considered as the linkage.

4. Data: Finally, the data element contains the "actual" data for label printing in the form of zero, one or multiple row sub-elements, each of which can consist of zero, one or multiple cell sub-elements. Unpictured in the above example: A row element can also have the optional labels attribute. This attribute allows the quantity of label copies to be printed for each dataset to be defined individually. If the attribute is missing, then the quantity is determined by the labelsperrow attribute described in (1).

Considerations when creating the XML file

1. HTML4 Entities: Within the data intended for label printing, characters < > & " ' must be replaced with the corresponding HTML4 entities: < > & " ' (This replacement ensures that the XML remains well-formed and avoids potential parsing errors.)

Example of a Java method that accomplishes this:

static String[] HTML4_ESC_CHARS = { "<", ">", "\"", "'", "&" };
static String[] HTML4_ESC_ENTITIES = { "<", ">", """, "'", "&" };

static String escapeHtml4(String s) {
for (int i=4; i>=0; i--) // Order matters! '&' should be replaced first
s = s.replace(HTML4_ESC_CHARS[i], HTML4_ESC_ENTITIES[i]);
return s;
}

2. Character Encoding: Instead of UTF-8 as shown in the example above (see the first line), other common character encodings can also be used (ISO-8859-x, Cp1252, UTF-16 etc.). However, the XML file should always be generated using the character encoding declared within the file itself.

Status and Error Handling

After the printing process, the API returns an Exit Code, also referred to as ERRORLEVEL in batch file programming. The Exit Code is an integer that provides information about how a program terminated and the result of that termination. Programming languages capable of launching (external) processes usually provide functions or methods for querying the Exit Code upon process completion. A calling program can utilize these functions to respond to potential states and errors.

Exit Codes:

0 – Printing process successfully executed and completed
101 – Project file not found
102 – XML print job file not found
103 – I/O error while loading the project file / Corrupt project file
104 – I/O error while loading the XML print job file
105 – Corrupt XML print job file / Not well-formed XML
201 – Horizontal start position out of range
202 – Vertical start position out of range
203 – Print service (with the provided name) not found
204 – Paper tray (with the provided ID) not found
301 – Printing error

By default, the API displays an error dialog when errors occur. If you want to fully delegate error handling to the calling application, you can suppress the display of error dialogs using the following parameter:

bcf.exe -showerrors=no "C:\Labels\Layout.bcfp" "C:\TEMP\PrintJob.xml"

Need Assistance or Have Questions?

If you have any technical or other inquiries, please don't hesitate to contact us.