Hilfsprogramm p2fCombine.exe

Anforderung

Beim Einsatz von print2forms kommt immer wieder einmal die Anforderung, Dokumente aus mehreren Quellen aufzusammeln und zu einem Dokument zusammenzufügen. Das ist beispielsweise dann der Fall, wenn von externen Dienstleistern oder von Lieferanten Dokumente angeliefert werden, die in eigene Prozesse eingebunden werden sollen. Aber auch zu verschiedenen Zeiten auf verschiedenen Rechnern entstandene Dokumente sollen manchmal gemeinsam verarbeitet werden.

Dabei besteht das 'Zusammenfügen' eben in besonderen Fällen aus deutlich mehr, als nur die zu druckenden Dateien nacheinander auszudrucken. Meist müssen die Dokumente noch mit print2forms nachbearbeitet werden, um etwa besondere Papierquellen (z.B. für Etiketten) auszuwählen oder die Dokumente zusammenzuheften.

Das Zusammenfügen von PCL-Dateien erfordert als erstes, dass eventuell vorhandene PJL-Sequenzen entfernt werden müssen, weil sonst gegenüber print2forms oder dem Drucker selbst nicht ein Druckauftrag entsteht. Anschliessend müssen die verbliebenen PCL-Sequenzen mit neuen PJL-Sequenzen zu einem (oder mehreren) neuen Druckaufträgen zusammengefügt werden.

Eine weitere Anforderung ist die, PCL-Dateien von externen Dienstleistern oder Lieferanten mit print2forms drucken zu müssen, ohne dass die angelieferten Dateien PJL-Sequenzen zur Auswahl von Druckereinstellungen und zur Auswahl des notwendigen Prozesses beinhalten. Auch dann müssen nachträglich PJL-Sequenzen in den Druckauftrag eingefügt werden.

Realisierung

Bei solchen Anforderungen kommt eigentlich immer ein print2forms-Gateway, das print2forms-LPD-Gateway oder der print2forms-Monitor zum Einsatz, welche im Idealfall alle Einzelaufträge empfangen, und dann prüfen, ob die Bedingungen für die Erstellung des Gesamtdokuments (alle Teildokumente vorhanden) erfüllt sind. Diese Prüfung ist sehr anwendungsspezifisch und erfolgt daher immer innerhalb eines Skriptes, welches durch das Gateway gestartet wird, sobald ein Dokument bearbeitet worden ist.

Hat das Skript ermittelt, um welche Art Datei es sich handelt, und entschieden, wie diese zu bearbeiten ist, kann das Programm p2fCombine aufgerufen werden, um die notwendigen Änderungen und Ergänzungen am Druckauftrag vorzunehmen. p2fCombine kann zum einen so eingesetzt werden, dass es wieder eine Druckdatei erzeugt, die dann in geeigneter Weise vom Skript weiterbearbeitet wird, oder p2fCombine übermittelt das Ergebnis seiner Bearbeitung via TCP/IP an ein print2forms-Client/Gateway, an den print2forms-Router oder direkt an einen Drucker.

p2fCombine benötigt bei seinem Aufruf eine ganze Reihe von Parametern. Zum einen natürlich Angaben darüber, wo das Ergebnis der Bearbeitung abgeliefert werden soll, und zum anderen Angaben darüber, was mit der Druckdatei überhaupt passieren soll.

Wird p2fCombine ohne Parameter über die Kommandozeile aufgerufen, gibt es folgende kurze Beschreibung aus:

p2fCombine V4.2  (c) 2018 by SPE Systemhaus GmbH

Description:
 Combines multiple pcl-files to one large pcl-file.
 PJL- and PCL-sequences can be inserted between files.
 Intended for use with print2forms gateways only.

Program parameters are:
 -k<key>    license key (mandatory)
 -f<name>   File with instructions (mandatory)
 -i<ip>     Target IP address of printer (default 'localhost')
 -p<port>   Target port number of printer (default 9500)
 -o<name>   Output file name
 -l<name>   Log file name

General return codes:
    0 - Success
   -1 - Failed
   -2 - Unknown program option
   -3 - Program option expected
 -100 - No network support
 -101 - Can't resolve DNS name of printer
 -102 - Can't connect to printer
 -103 - Can't access data base
 -104 - Can't access output file
 -105 - No permission to run

Return codes related to instruction file:
 -201 - Unable to open file
 -202 - Unsupported command found
 -203 - Unable to open included file
 -204 - Command too long
 -205 - Parameter string to long
 -206 - UEL command with parameter
 -207 - PCL command without parameter
 -208 - INC command without parameter
 -209 - PAG command with parameter
 -210 - LIN command with parameter
 -211 - PAS command without parameter
 -212 - DEL command without parameter
 -213 - OVL command path to file too long
 -214 - OVL command too many overlays
 -215 - OVL command can't open file
 -216 - SUP command too many suppressions
 -217 - SUP command not three characters
 -218 - CHG command sequence too long 
 -219 - CHG command too many exchanges 
 -220 - OVL command can't decode y position
 -221 - OVL command can't decode x position
 -222 - OVL command can't decode page number
 -223 - REC command wrong or missing identifier
 -224 - RCL command wrong or missing identifier
 -225 - RCL command wrong or missing page range
 -226 - UEL command invalid within a recording
 -227 - PJL command invalid within a recording
 
Examples:
 p2fCombine -fInst.txt -i10.1.17.7 -p9200
 p2fCombine -fInst.txt -iwww.spe-gmbh.de -p9200
 p2fCombine -fInst.txt -oOutput.pcl

print2forms (R)  is a registered trademark
                 of SPE Systemhaus GmbH

Damit p2fCombine weiss, wie der Ausgabedatenstrom zu erstellen ist, muss beim Aufruf des Programms mit dem Parameter '-f' der Name einer Datei mit entsprechenden Instruktionen für p2fCombine mit übergeben werden.

Der unbedingt erforderliche Parameter '-k' zeigt schon an, dass für die Nutzung des Programm p2fCombine ein besonderer Eintrag in der Lizenz für das print2forms-Gateway benötigt wird. Dieser Lizenzschlüssel muss vom Gateway beim Aufruf des Skriptes immer mitgegeben werden.

Die print2forms-Gateways stellen zu diesem Zweck einen verschlüsselten Wert zur Verfügung, der mit dem Platzhalter '%K' in der Kommandozeile des Gateways an p2fCombine selbst oder ein Skript, das seinerseits p2fCombine aufruft, übergeben wird. Eine typische Kommandozeile für ein Gateway sähe etwa so aus:

"%1\p2fCombine.exe" -k%K "-f%1\Instruction.txt" -i10.1.17.27 -p9500 "-l%1\Gateway.log"

Dabei wurde angenommen, dass p2fCombine selbst und die Datei 'Instruction.txt' im Skriptverzeichnis des Gateways stehen.

Instruktionsdatei

Die Instruktionsdatei ist eine reine Textdatei, die mit jedem einfachen Editor oder via Skript erstellt werden kann. Sie enhält pro Zeile eines von mehreren Kommandos, die zum Erzeugen eines Ausgabedatenstroms eingesetzt werden können. Die Instruktionsdatei wird beginnend mit der ersten Zeile zeilenweise abgearbeitet. Ist die letzte Zeile bearbeitet, wird der Ausgabedatenstrom geschlossen und an das beim Programmaufruf angegebene Ziel übertragen.

Parameter für einzelne Kommandos werden nach einem Gleichheitszeichen als einfache Zeichenfolge angegeben. Mit dem Ende der Zeile ist auch die Parameterzeichenfolge abgeschlossen. Leerzeichen vor und nach dem Kommando sind ohne Bedeutung. Leerzeichen nach dem Gleichheitszeichen werden ebenfalls ignoriert. Die Parameterzeichenfolge beginnt mit dem ersten Zeichen nach dem Gleichheitszeichen, welches kein Leerzeichen ist.

Leerzeilen zur optischen Strukturierung innerhalb der Instruktionsdatei sind zulässig. Ist das erste nicht leere Zeichen innerhalb einer Zeile ein '#', wird diese Zeile als Kommentarzeile angesehen.

Kommando Beschreibung
CHG CHANGE: Definiert eine Liste von auszutauschenden PCL-Sequenzen. Die zu ersetzende sowie die ersetzende PCL-Sequenz werden durch Leerzeichen getrennt angegeben. Wird das Kommando ohne Parameter aufgerufen, wird die Liste gelöscht und somit keine Ersetzungen vorgenommen. Details zu diesem Kommando finden sich weiter unten.
DEL DELETE: Löscht eine oder mehrere Dateien. Der komplette Pfad der zu löschenden Datei oder Dateien (mit Wildcards) muss als Parameter übergeben werden. Beispiel: 'DEL = C:\print2forms\*.PCL'. Wird als Parameter eine einzelne Ziffer übergeben, wird die entsprechende Aufzeichnung gelöscht.
INC INCLUDE: Öffnet eine Datei mit PJL/PCL-Daten, entfernt die PJL-Sequenzen und fügt die übrig bleibenden PCL-Sequenzen in den Ausgabedatenstrom ein. Der komplette Pfad der einzufügenden Datei muss als Parameter übergeben werden. Beispiel: 'INC = C:\print2forms\Datei 1.PCL'
LIN LINEFEED: Fügt einen Zeilenvorschub (Carriage Return, Linefeed '<0D><0A>') in den Ausgabedatenstrom ein. Das Kommando bedarf keines Parameters. Beispiel: 'LIN'
OVL OVERLAY: Definiert eine Liste von PCL-Dateien oder Texten, die als Overlays für die einzelnen Seiten eines Druckauftrags verwendet werden sollen. Wird das Kommando ohne Parameter aufgerufen, wird die Liste gelöscht und somit keine Overlays eingedruckt. Details zu diesem Kommando finden sich weiter unten.
PAG PAGE: Fügt einen Seitenvorschub (Formfeed '<0C>') in den Ausgabedatenstrom ein. Das Kommando bedarf keines Parameters. Beispiel: 'PAG'
PAS PASSTHROUGH: Öffnet eine Datei mit beliebigem Inhalt und fügt sie unverändert in den Ausgabedatenstrom ein. Der komplette Pfad der einzufügenden Datei muss als Parameter übergeben werden. Beispiel: 'PAS = C:\print2forms\Datei 2.BIN'
PCL Fügt eine PCL-Sequenz in den Ausgabedatenstrom ein. Die PCL-Sequenz wird einfach ohne das Escape-Zeichen selbst angegeben. Beispiel: 'PCL = &l26A'.
PJL Fügt eine PJL-Sequenz in den Ausgabedatenstrom ein. Die PJL-Sequenz wird einfach ohne das führende '@PJL' angegeben. Ohne Parameter erzeugt das Kommando ein leeres PJL-Kommando. Beispiel: 'PJL = ENTER LANGUAGE = PCL'.
RCL RECALL: Fügt den Inhalt einer Aufzeichnung in den aktuellen Druckdatenstrom ein. Als erster Parameter wird mit einer Ziffer '0' bis '9' die Aufzeichnung ausgewählt. Anschliessend wird eine Liste von Seitenbereichen angegeben, die die jeweils spezifizierten Seiten aus der Aufzeichnung abruft. Details zu diesem Kommando finden sich weiter unten.
REC RECORD: Startet die Aufzeichnung nachfolgender Kommandos in einen Zwischenpuffer. Es können insgesamt zehn Puffer verwendet werden, die mit den Ziffern '0' bis #9' gekennzeichnet werden. Details zu diesem Kommando finden sich weiter unten.
STP STOP: Beendet eine aktuell aktive Aufzeichnung. Das Kommando benötigt keinerlei Parameter.
SUP SUPRESS: Definiert eine Liste von zu unterdrückenden PCL-Sequenzen. Die PCL-Sequenz wird durch das Gruppenzeichen, das Parameterzeichen und das Terminierungszeichen definiert. Wird das Kommando ohne Parameter aufgerufen, wird die Liste gelöscht und somit keine Sequenzen unterdrückt. Details zu diesem Kommando finden sich weiter unten.
UEL Fügt ein UEL (Universal Exit Language '<esc>%-12345X') in den Ausgabedatenstrom ein. Das Kommando bedarf keines Parameters. Beispiel: 'UEL'.


Eine typische Instruktionsdatei, die zwei Dateien zu einem Druckdatenstrom zusammenfasst und ein paar Parameter für print2forms via PJL setzt, könnte demnach wie folgt aussehen:

UEL
 
# PJL-Header für weitere Verarbeitung durch print2forms
PJL
PJL = SET COMPUTER = "S65E393C"
PJL = SET MODEL = "P2FDEMO"
PJL = SET USER = "print2forms"
PJL = SET FORM = "RECHNUNG"
PJL = ENTER LANGUAGE = PCL
 
# DIN-A4, Portrait, 6 Zeilen pro Zoll, kein oberer Rand, Rand nicht überspringen
PCL = E
PCL = &l26ao6deL
 
INC = D:\Dokumente\print2forms\Druckdaten_1.pcl
INC = D:\Dokumente\print2forms\Druckdaten_2.pcl
 
UEL


Overlays

Der Mechanismus zum Einbinden von sogenannten Overlays kommt dann zur Anwendung, wenn es gilt, aus mehreren PCL-Dateien eine einzige Druckseite zusammenzustellen. Typische Anwendungen sind zum Beispiel das Einbinden eines extern bezogenenen Retourenetiketts auf Lieferpapieren.

Je Druckseite kann ein Overlay zugemischt werden. Das geschieht unmittelbar vor dem Formfeed, der die Druckseite terminiert. Mit dem Kommando 'OVL' wird eine Liste aufgebaut. Das Kommando erhält als ersten Parameter die Seite des Druckauftrags, auf der das Overlay eingefügt werden soll. Um das Overlay an einer bestimmten Position auf dieser Druckseite einzufügen, wird im 'OVL'-Kommando als nächste Parameter eine horizontale und vertikale Position für das Overlay angegeben. Die Einheiten für die Positionskoordinaten sind Decipoints (1/720„) und der Wert muss immer ganzzahlig sein. Die Koordinaten sind relativ zum Nullpunkt der logischen Seite und können auch negativ sein.

Als letzter Parameter wird entweder der Name einer Datei mit PCL-Daten oder, in einfachen Hochkommata eingeschlossen, ein zu druckender Text angegeben. Im Falle eines Dateinamens wird die Datei geöffnet und ihr Inhalt ausgegeben. Dabei werden aber einige PCL-Sequenzen, die einen Seitenvorschub auslösen können (z.B. Wechsel des Papiereinzugs oder Papierformats) unterdrückt. Eventuell vorhandene PJL-Sequenzen werden ebenfalls unterdrückt.

Im Falle der Angabe eines Textes als Parameter wird dieser einfach in den Druckdatenstrom übernommen. Der Text darf keine Steuerzeichen enthalten. Der Einsatzzweck eines solchen Textes ist darauf beschränkt, in einem dann nachfolgend aufgerufenen print2forms-Prozess ausgefiltert zu werden und lediglich den weiteren Ablauf zu steuern.

Die Liste der Overlays wird nur beim nächsten 'INC'-Kommandos angewendet. Nach der Ausführung des 'INC'-Kommandos ist die Liste der Overlays wieder leer und muss gegebenenfalls für das nächste 'INC'-Kommando neu aufgebaut werden.

Das folgende Beispiel druckt ein Retourenetikett auf der zweiten Seite des Druckauftrags ein. Das Etikett wird dabei um einen Zoll nach rechts verschoben.

OVL
OVL = 1 720 0 D:\Dokumente\print2forms\Etikett.pcl
INC = D:\Dokumente\print2forms\Druckdaten_1.pcl
# Liste der Overlays ist jetzt leer, nachfolgendes INC ohne Overlays
INC = D:\Dokumente\print2forms\Druckdaten_2.pcl


Unterdrückungen

Um bestimmte PCL-Sequenzen aus einem Druckdatenstrom zu entfernen, kann eine Liste von PCL-Sequenzen definiert werden. Die zu unterdrückende PCL-Sequenz wird durch das Gruppenzeichen, das Parameterzeichen und das Terminierungszeichen angegeben. Der konkrete Parameterwert ist ohne Bedeutung und wird ignoriert.

Typische Anwendungsfälle sind zum Beispiel das Entfernen von Schachtsequenzen beim Zusammensetzen mehrerer Dateien.

Wird das Kommando 'SUP' ohne Parameter angegeben, wird die Liste gelöscht.

Die Liste der Unterdrückungen wird nur bei nachfolgenden 'INC'-Kommandos ausgwertet. Die Ausführung des 'INC'-Kommandos lässt dabei die Liste intakt - es können also mehrere 'INC'-Kommandos mit der gleichen Liste ausgeführt werden, ohne die Liste neu aufzubauen.

Das nachfolgende Beispiel entfernt aus der ersten Folgedatei die PCL-Sequenzen zur Auswahl des Einzugsschachts, zur Auswahl des Papierformats und zur Anwahl des Papiertyps. Dabei ist zu erkennen, dass es auch möglich ist, Sequenzen mit nachfolgenden Binärdaten zu unterdrücken.

INC = D:\Dokumente\print2forms\Druckdaten_1.pcl
#     Unterdrücke Schachtauswahl, Papiergrösse und Papiertyp
SUP
SUP = &lH
SUP = &lA
SUP = &nW
INC = D:\Dokumente\print2forms\Druckdaten_2.pcl
#     Ab hier keine Unterdrückungen mehr
SUP
INC = D:\Dokumente\print2forms\Druckdaten_3.pcl


Ersetzungen

Um bestimmte PCL-Sequenzen auszutauschen, kann mit dem Kommando 'CHG' eine Liste von Ersetzungen definiert werden. Die zu ersetzende sowie die ersetzende PCL-Sequenz werden durch Leerzeichen getrennt angegeben. Dabei ist die zu ersetzende PCL-Sequenz immer so anzugeben, wie sie im Druckdatenstrom auftaucht. Das bedeutet vor allem auch, dass bei der Verkettung von Sequenzen die gesamte Sequenz angegeben werden muss.

Wird das Kommando 'CHG' ohne Parameter angegeben, wird die Liste gelöscht.

Die Liste der Ersetzungen wird nur bei nachfolgenden 'INC'-Kommandos ausgwertet. Die Ausführung des 'INC'-Kommandos lässt dabei die Liste intakt - es können also mehrere 'INC'-Kommandos mit der gleichen Liste ausgeführt werden, ohne die Liste neu aufzubauen.

Typische Anwendungsfälle sind zum Beispiel die Modifikation des Papiereinzugs.

Im nachfolgenden Beispiel wird die Auswahl des Einzugsfachs 1 gegen das Fach 2 angefordert. Einmal als einzelne PCL-Sequenz und einmal verkettet mit der Auswahl des Papierformats, weil das in den Druckdaten genau so vorkommt.

#     Schachtauswahl Fach 1 gegen Fach 2 ersetzen
CHG
CHG = &l1H    &l4H
CHG = &l26a1H &l26a4H
INC = D:\Dokumente\print2forms\Druckdaten.pcl


Aufzeichnungen

Das Programm bietet bis zu zehn interne Puffer (in Wirklichkeit Zwischendateien), in denen Druckdaten vorab aufbereitet und aufgezeichnet werden können. Die Motivation für eine solche Aufzeichnung ist, dass so eine Aufzeichnung dann beliebig oft und mit Seitenfiltern abgerufen und in den eigentlichen Druckdatenstrom eingebaut werden kann.

Die zehn Aufzeichnungen werden mit den Ziffern '0' bis '9' identifiziert. Von der Länge her sind sie nur über den zur Verfügung stehenden Festplattenspeicher begrenzt.

Ein Aufzeichnung wird mit dem 'REC'-Kommando gestartet und mit dem 'STP'-Kommando beendet. Abgerufen wird die Aufzeichnung mit dem 'RCL'-Kommando. In einer Aufzeichnung dürfen keine PJL-Sequenzen und keine UEL-Sequenz enthalten sein.

Das 'RCL'-Kommando hat als Parameter die Kennung der abzurufenden Aufzeichnung und eine Liste von Seitenbereichen. Ein Seitenbereich besteht aus einer Startseite, gefolgt von einem Minus-Zeichen, gefolgt von einer Endseite. Dabei muss die Nummer der Endseite grösser oder gleich der der Startseite sein. Je 'RCL'-Kommando können mehrere Seitenbereiche durch Leerzeichen getrennt angegeben werden.

REC = 0
SUP = E
PCL = &l26A
OVL = 1 360 1440 P:\Dokumente\print2forms\Etikett.PCL
INC = P:\Dokumente\print2forms\Rechnung.PCL
STP
#     In umgekehrter Reihenfolge drucken
UEL
PJL = ENTER LANGUAGE = PCL
RCL = 0 3-3 2-2 1-1
UEL
 
DEL = 0


Log-Datei

Mit dem optionalen Parameter '-l' kann p2fCombine aufgefordert werden, eine Art Ablaufverfolgung in eine Log-Datei zu schreiben. Dies ist während der Entwicklung neuer Abläufe oft sehr hilfreich.

Die Log-Datei wird beim erstmaligen Aufruf von p2fCombine erzeugt. Bei allen weiteren Programmaufrufen wird die angefangene Log-Datei fortgeschrieben. Da dabei keinerlei Grössenkontrolle erfolgt, sollte der Parameter '-l' keinesfalls in Produktivumgebungen eingesetzt werden.

Ein typisches Protokoll eines Programmaufrufs mit der oben beispielhaft angegebenen Instruktionsdatei sähe wie folgt aus:

2013-01-14 11.21.10-734:  Program start 'G2KWMG0.XML' 134676739
2013-01-14 11.21.10-734:  Open printer '10.1.17.27:9500' via network
2013-01-14 11.21.10-734:  Processing 'UEL' ''
2013-01-14 11.21.10-734:  Processing 'PJL' ''
2013-01-14 11.21.10-734:  Processing 'PJL' 'SET COMPUTER = "S65E393C"'
2013-01-14 11.21.10-734:  Processing 'PJL' 'SET MODEL = "P2FDEMO"'
2013-01-14 11.21.10-734:  Processing 'PJL' 'SET USER = "print2forms"'
2013-01-14 11.21.10-734:  Processing 'PJL' 'SET FORM = "RECHNUNG"'
2013-01-14 11.21.10-734:  Processing 'PJL' 'ENTER LANGUAGE = PCL'
2013-01-14 11.21.10-734:  Processing 'PCL' 'E'
2013-01-14 11.21.10-734:  Processing 'PCL' '&l26ao6deL'
2013-01-14 11.21.10-734:  Processing 'INC' 'D:\Dokumente\print2forms\Druckdaten_1.PCL'
2013-01-14 11.21.10-752:  Processing 'INC' 'D:\Dokumente\print2forms\Druckdaten_2.PCL'
2013-01-14 11.21.10-765:  Processing 'UEL' ''
2013-01-14 11.21.10-765:  Close printer
2013-01-14 11.21.10-765:  Terminating with code 0



Bemerkungen