CIB job technischer Leitfaden (DE)
9. CIB job Properties
Property „ConfigFilename“
Property „ModuleVersion“
Property „LicenseCompany“
Property „LicenseKey“
Property „InputData“
Property „InputDataLength4“
Property „InputMemoryAddress“
Property „MemoryOutputCallback“
Property „MemoryOutputUserdata“
Property „OutputMode“
Property „InputFilename“
Property „OutputFilename“
Property „OutputUrl“
Property „UseInMemoryProcessing“
Property „WorkSpace“
Property „InputData“
Property „InputEncoding“
Property „OutputEncoding“
Property „InputCharset“
Property „OutputCharset“
Property „ContentType“
Property „RemovePath“
Property „CreatePath“
Property „DirectoryPermissions“
Property „OutputContentType“
Property „MaxJobExecutionTime“
Property „WriteDate“
Property „WriteProducer“
Property „WriteTIMING“
Property „LicenseFile“
Allgemein
Die sogenannten „Properties“ oder Eigenschaften bilden ein wesentliches Kriterium vor dem Aufruf der eigentlich auszuführenden Methode. Alle unten im Klartext genannten Optionsnamen sind in den einzelnen Headerdateien der Komponenten auch als define deklariert und auch über diese defines in Ihrem Sourcecode ansprechbar. Die verschiedenen Ausgabemodule besitzen weitere spezielle Properties, die dort in den einzelnen Unterkapiteln beschrieben sind.
Alle CIB job Properties, auch die Zahlenwerte sind vom Typ Stringproperty. Siehe auch Abschnitt Aufrufschnittstelle.
Es ist zu unterscheiden zwischen Properties, die über die Aufrufschnittstelle CibJobSetProperty() gesetzt werden und Properties, die bei Schritten in der Auftragsdatei angegeben werden. Die Properties sind entsprechend gekennzeichnet mit „(Aufruf)“ und/oder „(Schritt)“.
Aufrufproperties können auch im <default>-Element des Auftrags oder der Konfigurationsdatei angegeben werden.
Ist eine Property wie z.B. WorkSpace mehrmals gesetzt, so gilt folgende Reihenfolge:
Die niedrigste Priorität hat die Angabe in der Konfigurationsdatei, eine höhere Priorität hat die Angabe im Abschnitt default, die höchste Priorität hat die Angabe im Schritt des Auftrags.
Zu beachten ist, dass die Schreibweise der Propertynamen berücksichtigt wird.
Property „ConfigFilename"
Angabe des Dateinamens für die Konfigurationsdatei.
Die Property kann nur über die Aufrufschnittstelle CibJobSetProperty() gesetzt werden.
Es handelt sich hierbei um eine Zeichenkette, die den Dateinamen und –pfad enthält. Wenn der Pfad oder die Datei nicht existieren, wird kein Fehler gemeldet, aber ein Eintrag im Trace erzeugt und es wird die Standardkonfiguration benutzt.
Die Property hat Vorrang vor der Umgebungsvariable CIB_JOBCONFIGFILENAME. Ist die Property gesetzt, wird die Umgebungsvariable ignoriert.
Der Standardwert wenn die Property und die Umgebungsvariable nicht gesetzt sind oder leer sind lautet ./jobconfig.xml. Das bedeutet die Datei jobconfig.xml muss einfach ins Arbeitsverzeichnis des aufrufenden Prozesses kopiert werden.
Property „ModuleVersion"
Liefert die Version des vorliegenden CIB job Moduls als String.
Es handelt sich hierbei um eine Ausgabeproperty. Die Property kann nur über die Aufrufschnittstelle CibJobGetProperty() gelesen werden.
Property „LicenseCompany"
Angabe des Lizenznehmers.
Die Property kann über die Aufrufschnittstelle CibJobSetProperty() gesetzt werden und kann in den Job-Defaults oder in der Konfigurationsdatei angegeben werden.
Es handelt sich hierbei um eine Zeichenkette, die den Namen des Lizenznehmers enthält.
Die Property muss vor dem Aufruf von Execute gesetzt sein.
Property „LicenseKey"
Angabe des Lizenzschlüssels.
Die Property kann über die Aufrufschnittstelle CibJobSetProperty() gesetzt werden und kann in den Job-Defaults oder in der Konfigurationsdatei angegeben werden.
Es handelt sich hierbei um eine Zeichenkette, die den Lizenzschlüssel enthält.
Die Property muss vor dem Aufruf von Execute gesetzt sein.
Property „InputData"
Die Property kann sowohl über die Aufrufschnittstelle CibJobSetProperty() gesetzt werden, als auch bei einem Schritt in der Auftragsdatei angegeben werden. Für die Verwendung der Property bei einem Schritt siehe Abschnitt Property „InputData“.
Übergabe der Auftragsdatei als Zeichenkette.
Die Länge der Zeichenkette müssen sie mit der Property „InputDataLength4“ setzen.
Die Property muss vor dem Aufruf von Execute gesetzt sein.
Property „InputDataLength4"
Setzt die Länge der Zeichenkette von der Property „InputData“.
Die Property kann nur über die Aufrufschnittstelle CibJobSetProperty() gesetzt werden.
Die Property muss vor dem Aufruf von Execute gesetzt sein.
Property „InputMemoryAddress"
Übergabe der Auftragsdatei im Hauptspeicher.
Die Property kann nur über die Aufrufschnittstelle CibJobSetProperty() gesetzt werden.
Diese Property enthält eine Folge aus Speicheradressen von lesbaren Speicherblocks und deren Länge. Die Speicheradressen und die Längen werden dezimal angegeben. Es wird abwechselnd eine Adresse und eine Länge angegeben, die Zahlenwerte sind durch Strichpunkte getrennt.
Diese Speicherblocks müssen – wenn zusammengesetzt – die Auftragsdatei enthalten.
Die Property muss vor dem Aufruf der Execute-Funktion gesetzt sein. Ist die Property „InputData“ ebenfalls gesetzt, hat „InputMemoryAddress“ Vorrang.
Property „MemoryOutputCallback"
Übergabe der Callbackadresse, um die erzeugte Auftragsergebnisdatei entgegenzunehmen.
Die Property kann nur über die Aufrufschnittstelle CibJobSetProperty() gesetzt werden.
Nullterminierte Zeichenkette, die den dezimalen Wert der Adresse einer ausführbaren Funktion enthält.
Die Funktion muss folgende Signatur besitzen (C-Syntax):
COMOD_BOOL COMOD_API *MemoryOutputCallbackType(const char* a_Output, size_t a_Length, void*a_pUserdata, int a_Error);
|
Typ: |
Variable: |
Bedeutung: |
|
const char * |
a_Output |
Adresse des aktuellen Ergebnisspeicherblocks |
|
Size_t |
a_Length |
Länge des aktuellen Ergebnisspeicherblocks |
|
Void * |
a_pUserdata |
Inhalt der Property MemoryUserData |
|
Int |
a_Error |
Aktueller Fehlercode |
Die Funktion wird während der Laufzeit von CIBjobExecute mehrmals aufgerufen.
Beim ersten Aufruf wird lediglich eine Zeichenkette übergeben, die den MIME-Type der in den nachfolgenden Aufrufen gelieferten Auftragsergebnisdatei enthält. Dieser erste Ergebnisspeicherblock ist also nicht Teil der Auftragsergebnisdatei.
Beim letzten Aufruf haben die Adresse des aktuellen Ergebnisspeicherblocks und die Länge beide den Wert 0. Nach dem Ende dieses Aufrufs sind die bei den vorhergehenden Aufrufen gelieferten Adressen ungültig. Der Aufrufer muss die Daten also spätestens bei diesem Aufruf kopieren.
Die Property muss vor dem Aufruf der Execute-Funktion gesetzt sein. Wenn diese Property gesetzt ist, wird die Property „OutputFilename“ ignoriert.
Die Funktion kann FALSE zurückgeben, um die Verarbeitung durch CIB job abzubrechen.
Property „MemoryOutputUserdata"
Übergabe eines beliebigen Zeigers, der bei jedem Aufruf des „MemoryOutputCallback“ der Callbackfunktion im Parameter Userdata zur Verfügung gestellt wird.
Die Property kann nur über die Aufrufschnittstelle CibJobSetProperty() gesetzt werden.
Nullterminierte Zeichenkette, die den dezimalen Wert der Adresse enthält.
Die Property muss nicht gesetzt werden, muss dann aber vor dem Aufruf der Execute-Funktion gesetzt sein.
Property „OutputMode"
Steuerung des Ausgabemodus.
Die Property kann über die Aufrufschnittstelle CibJobSetProperty() gesetzt werden, als auch in den Job-Defaults angegeben werden.
Nullterminierte Zeichenkette mit den erlaubten Werten „Direct“ und „Xml“.
Nur im Fall „Direct“ wird bei erfolgreicher Ausführung des Auftrags das erste Ergebnisdokument des ersten Jobs als direkte Auftragsergebnisdatei zurückgeliefert.
Im Fall „Xml“ oder wenn bei der Ausführung ein Fehler aufgetreten ist, wird eine Auftragsergebnisdatei im XML-Format entsprechend dem Abschnitt Auftragsergebnisspezifikation zurückgegeben.
Die Property muss nicht gesetzt werden, muss dann aber vor dem Aufruf der Execute-Funktion gesetzt sein.
Der Defaultwert der Property ist „Xml“.
Property „InputFilename"
Übergabe des Dateinamens der Auftragsdatei, wenn diese im Dateisystem vorliegt.
Die Property kann sowohl über die Aufrufschnittstelle CibJobSetProperty() gesetzt werden, als auch bei einem Schritt mit den Kommandos „load“ oder „delete“ in der Auftragsdatei angegeben werden.
Nullterminierte Zeichenkette, die den Dateinamen und –pfad enthält.
Diese Property kann an zwei unterschiedlichen Stellen auftreten: Wird sie über die native Aufrufschnittstelle gesetzt, heißt das, dass die Auftragsdatei aus dem Dateisystem einzulesen ist.
Ist sie dagegen bei einem Schritt mit dem Kommando „load“ gesetzt, wird dadurch die angegebene Datei aus dem Dateisystem gelesen und als Schrittergebnis in den Speicher geladen.
Die Property muss vor dem Aufruf der Execute-Funktion gesetzt sein. Diese Property wird dann ignoriert, wenn eine der Properties „InputData“ oder „InputMemoryAddress“ gesetzt ist. Ist die Property allerdings bei einem Schritt mit dem Kommando „load“ angegeben, so wird sie dort immer ausgewertet.
Property „OutputFilename"
Übergabe des Dateinamens der Auftragsergebnisdatei, wenn diese im Dateisystem vorliegt.
Die Property kann sowohl über die Aufrufschnittstelle CibJobSetProperty() gesetzt werden, als auch bei einem Schritt mit dem Kommando „save“ in der Auftragsdatei angegeben werden und bei den Job-Defaults.
Nullterminierte Zeichenkette, die den Dateinamen und –pfad enthält.
Diese Property kann an zwei unterschiedlichen Stellen auftreten: Wird sie über die native Aufrufschnittstelle gesetzt, heißt das, dass die Auftragsergebnisdatei oder die direkte Auftragsergebnisdatei in das Dateisystem geschrieben wird.
Ist sie dagegen bei einem Schritt mit dem Kommando „save“ gesetzt, wird das Ergebnisdokument des Schritts (nicht die Auftragsergebnisdatei) in das Dateisystem geschrieben. Das Schrittergebnis eines solchen Schritts ist der Dateiname, außer die Property „OutputUrl“ ist ebenfalls gesetzt.
Die Property muss vor dem Aufruf der Execute-Funktion gesetzt sein. Diese Property wird dann ignoriert, wenn die Property „MemoryOutputCallback“ gesetzt ist. Ist die Property allerdings bei einem Schritt mit dem Kommando „save“ angegeben, so wird sie dort immer ausgewertet.
Property „OutputUrl"
Rückgabe des Pfades zu einem Ergebnisdokument (nur bei einem Schritt mit dem Kommando „save“).
Die Property kann nur bei einem Schritt mit dem Kommando „save“ in der Auftragsdatei angegeben werden.
Nullterminierte Zeichenkette, die die Url enthält. Diese Url wird aus Sicht des Clients auf ein im Dateisystem des Servers vorliegendes Ergebnisdokument verweisen. Damit das funktioniert, muss beim gleichen Schritt die Property „OutputFilename“ einen dazu passenden Pfad und Dateinamen enthalten.
Das bedeutet, dass die Auftragsergebnisdatei im XML-Format gesendet wird, aber das Ergebnisdokument mit dem Kommando „save“ von CIB job ins Dateisystem geschrieben wird.
Der Outputmode kann nicht „Direct“ sein.
Property „UseInMemoryProcessing"
Steuert die Verwendung des Memoryinterfaces
Die Property kann über die Aufrufschnittstelle CibJobSetProperty() gesetzt werden, als auch in den Job-Defaults angegeben werden.
Boolsche Property mit erlaubten Werten „true“, „false“, „1“ und „0“ (case-insensitive). DefaultWert „true“.
Im Fall „true“ werden Ergebnisse einzelner Steps im Speicher vorgehalten bzw. auch an den nachfolgenden Schritt weitergegeben.
Im Fall „false“ wird ausschließlich auf Datenträgerebene gearbeitet. Einzelne Steps erfordern eine explizite Angabe der Properties „InputFilename“ und „OutputFilename“. Es werden keine Stepresults im Speicher vorgehalten.
Die Steps „Save“, „Load“, „Identitiy“, „Delete“ und „Mem“ sind im Fall „false“ deaktiviert.
Property „WorkSpace"
Definition eines Basisverzeichnisses für alle Dateinamensangaben.
Die Property kann sowohl über die Aufrufschnittstelle CibJobSetProperty() gesetzt werden, als auch bei einem Schritt mit dem Kommando „load“ oder „save“ in der Auftragsdatei angegeben werden, sowie bei den Job-Defaults.
Nullterminierte Zeichenkette, die einen Pfad enthält. Der Pfad kann absolut angegeben werden oder relativ zum Arbeitsverzeichnis des aufrufenden Prozesses.
Alle anderen Dateiangaben in den Properties „InputFilename“ und „OutputFilename“ und nur diese werden relativ zum Workspace betrachtet.
Die Property kann über die Aufrufschnittstelle , in der Konfigurationsdatei, im Auftrag oder bei den Schritten mit dem Kommando „load“ oder „save“ angegeben werden. Im letzteren Fall gelten sie nur für die dort angegebenen Werte der Properties „InputFilename“ und „OutputFilename“.
Property „InputData"
Übergabe von Eingabedaten für Schritte eingebettet in der Auftragsdatei.
Die Property kann nur bei einem Schritt mit dem Kommando „mem“ in der Auftragsdatei angegeben werden.
Diese Property wird mit einer XML-kompatiblen Zeichenkette gefüllt. Diese ist in der Regel die Base64-encodede Darstellung einer Datei. Diese kann zusätzlich komprimiert oder verschlüsselt sein. Siehe Properties „InputEncoding“ und „InputCharset“.
Property „InputEncoding"
Angabe, wie die in der Property „InputData“ übergebenen Daten zu dekomprimieren bzw. zu dekodieren sind.
Die Property kann nur bei einem Schritt mit dem Kommando „mem“ in der Auftragsdatei angegeben werden.
Diese Property wird mit einer kommagetrennten Folge von Encoding-Bezeichnern gefüllt. Die Reihenfolge der Encodings ist die, wie sie auf die Daten angewendet wurde, um den Inhalt der „InputData“ Property zu erhalten. CIB job wendet sie also von hinten nach vorne an, um den dekodierten Inhalt zu ermitteln.
Folgende Encodings werden unterstützt:
Zip, Base64
Base64
Weitere Encodings auf Anfrage.
Property „OutputEncoding"
Angabe, welche Encodings auf das Schrittergebnis anzuwenden sind.
Die Property kann nur bei einem Schritt mit dem Kommando „mem“ in der Auftragsdatei angegeben werden.
Diese Property wird mit einer kommagetrennten Folge von Encoding-Bezeichnern gefüllt. Die Reihenfolge der Encodings ist die, wie sie von CIB job auf die Daten angewendet werden sollen, nachdem eine etwaige Charset-Umwandlung stattgefunden hat. Siehe Property „InputCharset“.
Folgende Encodings werden unterstützt:
Zip, Base64
Base64
Weitere Encodings auf Anfrage.
Property „InputCharset"
Angabe des Charsets der Eingabe.
Die Property kann nur bei einem Schritt mit dem Kommando „mem“ in der Auftragsdatei angegeben werden.
Diese Property enthält einen Charset-Bezeichner. Es ist dies das Charset der dekodierten Daten, also nach Anwendung der Property „InputEncoding“. Siehe auch Property „InputData“.
Nur wenn beide Charset-Properties gesetzt sind, wird eine Charset-Umwandlung vom „InputCharset“ ins „OutputCharset“ vorgenommen.
Folgende Charsets werden unterstützt:
CodePageAnsi
CodePageMac
CodePagePc
CodePagePca
CodePagePdf
CodePage1256Arabic
CodePageUnicode
CodePageUtf8
Folgende Charsets werden ebenfalls unterstützt, konnten jedoch noch nicht sprachlich überprüft werden:
CodePage932ShiftJIS
CodePage949Hangul
CodePage936GB2312
CodePage950ChineseBIG5
CodePage1255Hebrew
CodePage1253Greek
CodePage1254Turkish
CodePage1258Vietnamese
CodePage874Thai
CodePage1250EastEurope
CodePage1251Cyrillic
CodePage1257Baltic
Property „OutputCharset"
Angabe des gewünschten Ziel-Charsets.
Die Property kann nur bei einem Schritt mit dem Kommando „mem“ in der Auftragsdatei angegeben werden.
Beschreibung siehe Property „InputCharset“.
Property „ContentType"
Angabe, was die Schritteingabe bzw. -ausgabe eigentlich darstellt (MIME-Type).
Die Property kann nur bei einem Schritt mit dem Kommando „mem“ oder „load“ in der Auftragsdatei angegeben werden.
Diese Property wird mit einer http-kompatiblen Zeichenkette gefüllt, die den MIME-Type der Daten angibt, zum Beispiel text/plain.
Property „RemovePath"
(ab Version 1.4.20)
Ermöglicht das zusätzliche Entfernen von Verzeichnissen.
Der Defaultwert für diese Property lautet FALSE
Die Property kann nur bei einem Schritt mit dem Kommando „delete“ in der Auftragsdatei angegeben werden.
Die Property wird mit einem boolschen Wert gefüllt, wahlweise als Zeichenkette oder als Ganzzahl.
Es wird versucht den in „InputFilename“ gesetzten Pfad, d.h. Datei mit Verzeichnis, zu löschen. Sollte es nicht möglich sein die Datei zu löschen, so gibt das Programm einen Fehler zurück.
Falls sich die Datei entfernen lässt, das Löschen von Verzeichnissen aber nicht möglich sein sollte, dann wird kein Fehler gesetzt. In diesem Fall wird eine Warnung ins logfile geschrieben.
Verzeichnisse, die in der Property „WorkSpace“ gesetzt werden, werden nicht beachtet.
Es gilt die üblichen Konventionen beim Entfernen von Dateien und Verzeichnissen zu beachten, wie z.B Zugriffsbeschränkungen, etc.
Property „CreatePath"
(ab Version 1.4.20)
Ermöglicht das zusätzliche Anlegen von Verzeichnissen.
Der Defaultwert für diese Property lautet FALSE
Die Property kann nur bei einem Schritt mit dem Kommando „save“ in der Auftragsdatei angegeben werden.
Die Property wird mit einem boolschen Wert gefüllt, wahlweise als Zeichenkette oder als Ganzzahl.
Es wird versucht den in „OutputFilename“ gesetzten Pfad, d.h. Datei mit Verzeichnis, zu erstellen.. Sollte es nicht möglich sein die Datei zu erstellen, so gibt das Programm einen Fehler zurück.
Unter unixoiden Betriebssystemen besteht die optionale Property „DirectoryPermissions“. (Beschreibung siehe unten).
Es gilt die üblichen Konventionen beim Erstellen von Dateien und Verzeichnissen zu beachten, wie z.B. Zugriffsbeschränkungen, etc.
Property „DirectoryPermissions"
(ab Version 1.4.20)
Angabe der gewünschten Zugriffsbeschränkungen.
Der Defaultwert für diese Property lautet ‚0777’
Die Property kann nur bei einem Schritt mit dem Kommando „save“ in der Auftragsdatei angegeben werden.
Die Property wird mit einer 4-stelligen Ganzzahl gefüllt. Sie setzt die Zugriffsbeschränkungen für mit „CreatePath“ im Kommanso „save“ erstellte Verzeichnisse auf unixoiden Betriebssystemen.
Wichtig: Die im Zielsystem gesetzte Einstellung der Systemproperty „umask“ wird auf den gesetzten Wert angewendet.
Property „OutputContentType"
(ab Version 1.4.20)
Diese Property liefert im Fall einer Ausgabe in Datei „OutputFilename“ den Mimetype des Ergebnisses.
Dies wird benötigt, wenn CIB job von einer Anwendung aufgerufen wird, z.B. Jcomod, die den Typ des erzeugten Auftrags-Ergebnisses nicht kennt.
Zu den möglichen Inhalten dieser Property siehe Kapitel „MIME-Type“.
Property „MaxJobExecutionTime"
(ab Version 1.6.2)
Mit dieser Property „MaxJobExecutionTime“ kann eine maximale Laufzeit für einen Auftrag vorgegeben werden. Die Property kann an CIB job (CibJobSetProperty), in der jobconfig.xml oder den Job-Defaults angegeben werden.
Benötigt die Ausführung des Auftrags länger als diese Zeit, wird der Auftrag abgebrochen und der Fehler 414 geliefert.
Es wird eine Fehlerantwort erstellt, mit JobResultCode 414, und einem StepResultCode 412 oder 413.
Property „WriteDate"
Durch diese Property kann man festlegen, ob im Response das Bearbeitungsdatum zurückgeliefert werden soll.
Boolsche Property mit erlaubten Werten „true“, „false“, „1“ und „0“ (case-insensitive). DefaultWert „true“ (Die Property wird im Response geliefert).
Property „WriteProducer"
Durch diese Property kann man festlegen, ob im Response der Aufrufer zurückgeliefert werden soll.
Boolsche Property mit erlaubten Werten „true“, „false“, „1“ und „0“ (case-insensitive). DefaultWert „true“ (Die Property wird im Response geliefert).
Property „WriteTIMING"
Durch diese Property kann man festlegen, ob im Response die Dauer der Auftragsverarbeitung zurückgeliefert werden soll.
Boolsche Property mit erlaubten Werten „true“, „false“, „1“ und „0“ (case-insensitive). DefaultWert „true“ (Die Property wird im Response geliefert).
Property „LicenseFile"
(ab Version 3.5.0)
Durch die Property „LicenseFile“ können Lizenzinformationen im JSON-Format hinterlegt werden. Dadurch müssen die Lizenzinformationen nicht durch das Property-Paar „LicenseKey“ und „LicenseCompany“ angegeben werden, welche weiterhin als Alternative zur Verfügung stehen.
Die Lizenzinformationen können entweder direkt angegeben oder durch eine entsprechende Datei hinterlegt werden:
Beispiel mit Datei:
<property name="LicenseFile">myLicense.txt</property>
Beispiel Inhalt direkt im JSON-Format:
<property name="LicenseFile">{"Company": "Gesellschaft-Name",
"Key": "xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx ",
"OperatingSystem": "Windows", "Products": [ { "Name": "CIB job" } ] } </property>