Barcode-Etiketten API – Labeldruck für Ihre Applikation

“Barcode Forge” gibt es als Standard und als Developer Edition. Letztere erweitert die Software um die Möglichkeit (API), Barcode-Etiketten aus der eigenen Applikation heraus zu drucken (z.B. Warenwirtschaftssystem, ERP, Lagerverwaltung etc.).

Die Etiketten-API – Alles auf einen Blick

Die eigene Applikation schreibt die zu druckenden Daten in eine XML-Datei und übergibt den Dateipfad an die API. Als erster Parameter wird ein im GUI-Modus von “Barcode Forge” angefertigtes Etikettenlayout (Projektdatei) übergeben:

bcf.exe "C:\Etiketten\Layout.bcfp" "C:\TEMP\Druckauftrag.xml"

Nachfolgend das Beispiel einer XML-Druckauftragsdatei, welche 2 Datensätze mit jeweils 3 Feldern zum Drucken übergibt. Pro Datensatz soll die API dabei jeweils 3 Etikettenkopien drucken.

Version: 6.8
Sprachen: DE / EN
Größe: 30 MB
Windows 11, 10, 8, 7

30-Tage-Demo: DOWNLOAD Alternative Quelle:
heise.de/...

Software-Lizenz BESTELLEN
Auslese bekannter Unternehmen, die unsere Barcode Software einsetzen: REFERENZEN

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

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

    <printservice name="default"/>

    <fieldmap>

        <field>ArtikelNr</field>

        <field>Bezeichnung</field>

        <field>Gewicht</field>

    </fieldmap>

    <data>

        <row>

            <cell>123</cell>

            <cell>Apfel</cell>

            <cell>200</cell>

        </row>

        <row>

            <cell>456</cell>

            <cell>Orange</cell>

            <cell>180</cell>

        </row>

    </data>

</printjob>

Referenz der Elemente und Attribute

1. Druckauftrag: Die zum Wurzelelement printjob gehörenden und allesamt optionalen Attribute enthalten Parameter für den aktuellen Druckauftrag. labelsperrow definiert die Anzahl Etikettenkopien, die pro Datensatz gedruckt werden sollen. Default-Wert ist 1. printdirection bestimmt die Druckrichtung, falls der Druck auf Etikettenbögen erfolgt. Mögliche Werte sind "horizontal" (default) und "vertical". startpositionx und startpositiony legen die Position des ersten zu bedruckenden Etiketts auf dem Etikettenbogen fest, beginnend jeweils mit 1. Nicht im obigen Beispiel abgebildet: Mit designno kann festgelegt werden, welcher der drei Etikettenentwürfe (römisch I, II, III in der GUI) verwendet werden soll. Mögliche Werte sind entsprechend 1 (default), 2 oder 3.

2. Druckdienst: Das printservice-Element spezifiziert den zu verwendenden Druckdienst und ist genauso wie alle anhängenden Attribute des Elements (aktuell gibt es davon nur eines, nämlich name) optional. Zur Ansteuerung eines bestimmten Druckers muss das name-Attribut dessen Namen enthalten (Groß-/Kleinschreibung ist zu berücksichtigen). Der Standard-Drucker lässt sich mit "default" und "" (Leerstring) auswählen. (Hinweis: "Standard-Drucker" meint hier ausnahmsweise nicht den Druckdienst, welcher im Betriebssystem als Standard definiert ist, sondern denjenigen, den Sie im GUI-Modus von Barcode Forge selbst als den zu verwendenden Drucker auswählen.)

3. Feldzuordnungen: Im fieldmap-Element (optional) werden Zuordnungen von Feldnamen eines Barcode Forge-Projektes zu Spaltennummern der Datensätze innerhalb der aktuellen XML-Druckauftragsdatei hergestellt. So wird z.B. im ersten field-Subelement das Feld innerhalb des Barcode Forge-Projektes referenziert, in welches jeweils der erste Wert eines Datensatzes eingepflegt wird, usw. Wird das fieldmap-Element ausgelassen, so gilt die gemeinsame Position als Verknüpfung.

4. Daten: Das data-Element enthält schließlich die "eigentlichen" Daten für den Etikettendruck in Form von keinem, einem oder mehreren row-Subelementen, welche ihrerseits aus keinem, einem oder mehreren cell-Subelementen bestehen können. Nicht im obigen Beispiel abgebildet: Ein row-Element kann zusätzlich das optionale Attribut labels besitzen. Damit lässt sich die zu druckende Menge Etiketten für den jeweiligen Datensatz individuell definieren. Fehlt das Attribut, dann bestimmt das unter (1) beschriebene labelsperrow-Attribut die Menge.

Zu beachten beim Erzeugen der XML-Datei

1. Innerhalb der für den Etikettendruck bestimmten (Nutz-)Daten müssen die Zeichen < > & " ' durch entsprechende HTML4-Entities ersetzt werden: < > & " ' (Diese Ersetzung gewährleistet, dass das XML wohlgeformt bleibt und potenzielle Parsing-Fehler vermieden werden.)

Beispiel einer Methode in Java, welche dies bewerkstelligt:

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

static String escapeHtml4(String s) {
for (int i=4; i>=0; i--) // Reihenfolge wichtig! '&' sollten als erste ersetzt werden
s = s.replace(HTML4_ESC_CHARS[i], HTML4_ESC_ENTITIES[i]);
return s;
}

2. Anstelle von UTF-8 wie im obigen Beispiel (siehe erste Zeile) können auch andere gängige Zeichensätze verwendet werden (ISO-8859-x, Cp1252, UTF-16 usw.). Die XML-Datei sollte allemal stets unter der Verwendung des in ihr selbst deklarierten Zeichensatzes erzeugt werden.

Status-/Fehlerbehandlung

Nach dem Druckvorgang liefert die API einen sogenannten Exit Code zurück – in der Programmierung von Batch-Dateien auch als ERRORLEVEL bekannt. Der Exit Code ist im Allgemeinen eine Ganzzahl, welche Auskunft darüber gibt, auf welche Weise und mit welchem Ergebnis ein Programm beendet wurde. Programmiersprachen, welche in der Lage sind, (externe) Prozesse zu starten, stellen idR. auch Funktionen bzw. Methoden zum Abfragen des Exit Code nach Beendigung eines Prozesses zur Verfügung. Ein aufrufendes Programm kann sich dieser Funktionen bedienen, um auf mögliche Zustände und Fehler zu reagieren.

Exit Codes:

0 – Druckvorgang erfolgreich ausgeführt und beendet
101 – Projektdatei nicht gefunden
102 – XML-Druckauftragsdatei nicht gefunden
103 – I/O-Fehler beim Laden der Projektdatei / Korrupte Projektdatei
104 – I/O-Fehler beim Laden der XML-Druckauftragsdatei
105 – Korrupte XML-Druckauftragsdatei / kein wohlgeformtes XML
201 – Horizontale Startposition außerhalb des möglichen Bereichs
202 – Vertikale Startposition außerhalb des möglichen Bereichs
203 – Druckdienst (mit dem übergebenen Namen) nicht gefunden
301 – Fehler beim Drucken

Standardmäßig zeigt die API bei Auftreten von Fehlern zusätzlich einen Fehlerdialog an. Soll die Fehlerbehandlung vollständig an die aufrufende Anwendung übertragen werden, so kann das Anzeigen von Fehlerdialogen mit Hilfe des optionalen Parameters -showerrors=no unterbunden werden:

bcf.exe -showerrors=no "C:\Etiketten\Layout.bcfp" "C:\TEMP\Druckauftrag.xml"

Fragen?

Bitte zögern Sie nicht uns zu kontaktieren, sollten Sie Fragen technischer oder sonstiger Art haben.