VW SoftwareSoftware für Windows, seit 2005

Etikettendruck API: Barcode-Etiketten per XML drucken

Unsere auf Barcodes spezialisierte Etiketten-Software Barcode Forge gibt es als Standard und als Developer Edition. Letztere erweitert die Software um die Möglichkeit (API), Barcode-Etiketten aus anderen Applikationen heraus zu drucken. Zur Nutzung sind Programmierkenntnisse erforderlich.

Barcode-Etiketten per XML drucken – das Prinzip

Die aufrufende Applikation schreibt die zu druckenden Daten in eine XML-Datei und übergibt deren Pfad als Parameter an die API. Als weiterer Parameter wird das vorgefertigte Etikettenlayout in Form einer Barcode Forge-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 sollen dabei jeweils 3 Etiketten gedruckt werden.
<?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>

Erläuterung 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 Etiketten, 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.

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. Mehr zur Druckerkonfiguration lesen sie bitte im entsprechenden Kapitel.)

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.

Allgemeine Hinweise zu XML-Dateien

Zum Erzeugen von XML-Dateien ist eine XML-API nicht erforderlich. Mit den jeweiligen Bordmitteln zum Schreiben "normaler" Textdateien ist dies zuweilen sogar schneller und übersichtlicher umzusetzen.

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.). Selbstredend sollte die XML-Datei stets unter der Verwendung des in ihr selbst deklarierten Zeichensatzes erzeugt werden.

Innerhalb der für den Etikettendruck bestimmten Daten sind die Zeichen < > & " ' durch entsprechende Entities zu ersetzen (&lt; &gt; &amp; &quot; &apos;). Der Text Hufen & Hörner sollte etwa wie folgt in die XML-Datei geschrieben werden:
<cell>Hufen &amp; Hörner</cell>

Nach dem Drucken – 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 entsprechend 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 zulässigen Bereichs
202 – Vertikale Startposition außerhalb des zulässigen Bereichs
203 – Druckdienst (mit dem übergebenen Namen) nicht gefunden
301 – (Unbekannter) Fehler beim Drucken

Standardmäßig zeigt Barcode Forge 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"