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.
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:
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:
Version: 6.9
Languages: EN, DE
Size: 30 MB
Windows 11, 10, 8, 7
30-Day Trial: DOWNLOAD Alternative Source:
heise.de/...
Software License ORDER
Selection of well-known companies that use our barcode software: REFERENCES
Languages: EN, DE
Size: 30 MB
Windows 11, 10, 8, 7
30-Day Trial: DOWNLOAD Alternative Source:
heise.de/...
Software License ORDER
Selection of well-known companies that use our barcode software: REFERENCES
<?xml version="1.0" encoding="UTF-8"?>
<printjob labelsperrow="3" printdirection="vertical" startpositionx="2" startpositiony="4">
</printjob>
<printjob labelsperrow="3" printdirection="vertical" startpositionx="2" startpositiony="4">
<printservice name="default"/>
<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 printservice element specifies the print service to be used and is optional, as are all of the element's appended attributes (currently there is only one of them, namely name). To target a specific printer, the name attribute must contain its name (case sensitive). The default printer can be selected using "default" or an empty string (""). (Note: "Default printer" here exceptionally does not mean the print service that is defined as default in the operating system, but the one that you select yourself in the GUI mode of “Barcode Forge” as the printer to be 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;
}
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. Typically, 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
301 – Printing error
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
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 optional parameter:
bcf.exe -showerrors=no "C:\Labels\Layout.bcfp" "C:\TEMP\PrintJob.xml"