Das folgende Beispiel befindet sich im Unterverzeichnis Lueckentext. Es verwendet ein Anschreiben, das als RTF vorliegt. Dieses enthält Variablen, die aus einer Datenquelle gefüllt werden sollen. Dabei handelt es sich um eine CSV-Datei mit den Daten des Empfängers. Das Ergebnis des Mischlaufs ist eine Zahlungserinnerung, die die Kundendaten aus der CSV-Datei enthält.

Aufruf der CIB merge Hilfe
Einfachste Form eines Mischlaufs (IOD)
Aufruf einzelner Parameter über die Kommandozeile
Aufruf einzelner Parameter über JAVA
Aufruf einzelner Parameter über C++
Aufruf der Parameterdatei über Kommandozeile
Aufruf der Parameterdatei über JAVA
Optimierung von Rohtexten vor Auslieferung

---

Aufruf der CIB merge Hilfe

Die CIB merge Hilfe kann unter Windows nicht auf der Konsole ausgegeben werden, da es sich um eine Fensteranwendung handelt, um einen Fortschrittsdialog während des Mischlaufs anzeigen zu können (siehe Parameter --dialog). Um einen Überblick über alle möglichen Aufrufparameter zu erhalten, kann die Hilfe in einer Datei ausgegeben werden. Dazu ist folgender Aufruf in der Kommandozeile einzugeben, oder die Batch-Datei hilfe.bat auszuführen.

cibmrg32 --logfile=!hilfe.txt --help

Die Hilfe wird in die Datei hilfe.txt umgeleitet und ist wie folgt aufgebaut:

Benutzung von CIB merge:

>CIBMRG32 <Parameter1> <P2> ...

Jeder Parameter sollte mit einem Startzeichen aus "-/" beginnen.

 

Die ersten Parameter ohne Startzeichen bekommen sonst der Reihe nach die Parameterzeichen aus "IODH" zugewiesen.

Nach Auswertung aller Parameter wird automatisch "/@" ausgeführt.

 

Parameter            : Wirkung

Q<Arbeitsverzeichnis>: setzt Arbeitsverzeichnis (muss zwingend am Anfang sein!)

A<Templateverzeichnis>: setzt Templateverzeichnis

I<Eingabe>           : setzt RTF Eingabequelle

?                    : Hilfeseite anzeigen

weitere Parameter

Einfachste Form eines Mischlaufs (IOD)

Die einfachste Form eines Mischlaufs besteht darin, eine Eingabedatei mit Daten zu füllen und das Ergebnis in eine Ausgabedatei zu schreiben. Das kann über die einzelnen Parameter --inputfile (I), --outputfile (O) und --datafile (D) angegeben werden. Im Folgenden wird beschrieben, wie diese Parameter über die Kommandozeile angegeben werden können. Außerdem werden Varianten zur Ansteuerung aus JAVA und C++ vorgestellt.

Aufruf einzelner Parameter über die Kommandozeile

Um eine Eingabedatei mit Daten zu mischen und in eine Ausgabedatei zu schreiben, reicht ein einfacher Aufruf in der Kommandozeile. Mit Hilfe des Aufrufparameters --inputfile wird die Datei angegeben, die dem Mischlauf als Eingabedatei dient. Der Parameter --datafile gibt den Namen der Datenquelle an und --outputfile legt die Ausgabedatei fest.

Folgender Aufruf versorgt somit die Eingabedatei Anschreiben_in.rtf mit den Daten aus Adresse.csv (die sich im gleichen Verzeichnis befindet) und schreibt das Ergebnis in die Ausgabedatei Anschreiben_out.rtf, wobei eine evtl. bereits vorhandene Datei überschrieben wird.

cibmrg32.exe --inputfile=Anschreiben_in.rtf
--outputfile=!Anschreiben_out.rtf --datafile=Adresse.csv 

Wird die Reihenfolge IODH (inputfile, outputfile, datafile, headerfile) eingehalten, kann auf die Angabe der Parameter verzichtet werden. Folgender Aufruf führt dann zum gleichen Ergebnis (Anschreiben.bat):

cibmrg32.exe Anschreiben_in.rtf !Anschreiben_out.rtf Adresse.csv

Aufruf einzelner Parameter über JAVA

Statt die Parameter über die Kommandozeile zu setzen, kann die Ansteuerung auch über JAVA erfolgen. Das gleiche Ergebnis wird mit folgendem JAVA-Code (MergeEinzelneParameter.java) erzielt:

Auszug aus MergeEinzelneParameter.java:

…
JCibMergeJob t_Job = new JCibMergeJob();
t_Job.initialize();
if (!t_Job.isInitialized())
{
      // Fehler beim Initialisieren
      System.err.println("Fehler beim
Initialisieren");
      System.exit(1);
}
try
{
      // Beteiligte Dateien für den
Mischlauf
 t_Job.setProperty(ICibMergeJob.PROPERTY_INPUTFILE,
"Anschreiben_in.rtf");
 t_Job.setProperty(ICibMergeJob.PROPERTY_OUTPUTFILE,
"Anschreiben_out.rtf");
 t_Job.setProperty(ICibMergeJob.PROPERTY_DATAFILE,
"Adresse.csv");
      //Job ausführen
      t_Job.execute();
      //Fehlerbehandlung
      int t_Error =
((Integer)t_Job.getProperty(IComodJob.PROPERTY_ERROR)).intValue();
      if (t_Error != 0)
      {
      // Fehler beim Ausführen des Jobs
      String t_Errortext =
(String)t_Job.getProperty(IComodJob.PROPERTY_ERRORTEXT);
      System.err.println("Fehler beim
Ausführen: "+t_Error+" "+t_Errortext);
      }
}
finally
{
      t_Job.terminate();
}
…

Hier wird die Jobklasse zum Ansteuern des CIB merge aus Java verwendet. Mit dem JCibMergeJob kann ein Mischauftrag aus Java heraus an den CIB merge übergeben werden. Die Jobklasse sammelt zunächst die Parameter, die mit setProperty gesetzt werden. Mit execute() wird CIB merge dann aufgerufen.

Aufruf einzelner Parameter über C++

Ist eine Ansteuerung über C++ gewünscht, ist cibmerge(int argc, char *argv[]) zu verwenden. Auf diese Weise können die gewünschten Parameter gesetzt werden. Das Verzeichnis C:\\comod\\, das die CIB Module enthält, muss entsprechend angepasst werden. Für die Initialisierung von CIB merge wird dieses Verzeichnis benötigt.

Auszug aus MergeEinzelneParameter.cpp:

…
extern "C" const char *cibmerge_errormessage;

static char *test_arguments[]={"MergeEinzelneParameter",
"--inputfile=Anschreiben_in.rtf", "--outputfile=!Anschreiben_out.rtf",
"--datafile=Adresse.csv", 0};

int main(const unsigned int number_of_arguments, char *argument_vector[])
{
 if(!cibmerge_initialize("C:\\comod\\", 0))
            cout << cibmerge_errormessage << endl;

      int iReturn=0;
      iReturn = cibmerge(sizeof(test_arguments)/sizeof(*test_arguments) - 1, test_arguments);
      cout << "MergeEinzelneParameter Returnwert cibmerge: " << iReturn << endl;

      if(!cibmerge_terminate())
            cout << cibmerge_errormessage << endl;
      return 0;
}

• Protokollierung und Verwendung eines anderen Trennzeichens in der Datenquelle

Im Folgenden sollen mögliche auftretende Fehler in einer Logdatei protokolliert werden und in dieser Datei auch eigene Meldungen, sowie Informationen zur verwendeten Programmversion ausgegeben werden. Außerdem ist die Datenquelle so aufgebaut, dass statt des Zeichens „;“ ein Komma als Trennzeichen in der CSV-Datei dient.

Um dies zu realisieren, müssen zusätzliche Aufrufparameter beim Mischlauf berücksichtigt werden. Ein Aufruf über die Kommandozeile wird dadurch leicht unübersichtlich. In diesem Fall ist es ratsam, die Parameter in eine Parameterdatei auszulagern. Diese Parameterdatei kann dann über die Kommandozeile aufgerufen werden. Die Varianten, wie die Parameterdatei über JAVA und C++ ausgeführt werden kann, werden im Folgenden ebenfalls erläutert.

Aufruf der Parameterdatei über Kommandozeile

Die Parameter, die für diesen Mischlauf benötigt werden befinden sich alle in der Datei Komma_par.par. Wird CIB merge über die Kommandozeile aufgerufen, wird die Parameterdatei mit Hilfe des Aufrufparameters --parameterfile angegeben ( Komma.bat):

cibmrg32.exe --parameterfile=Komma_par.par

Alle Zeilen, die in der Parameterdatei nicht mit „--„ oder „-„ beginnen, sind Kommentare (auch mit Leerzeichen eingerückte Parameter sind Kommentare).

Inhalt der Parameterdatei Komma_par.par:

Fehler sollen protokolliert werden

--logfile=!Komma_log.log
--version

Beteiligte Dateien für den Mischlauf

--inputfile=Anschreiben_in.rtf
--outputfile=!Komma_out.rtf
--datafile=Adresse_Komma.csv

Hier gilt das Komma als Trennzeichen in der CSV

--delimiter=,
-mDer Mischvorgang verwendet folgende Ein- und Ausgabedateien:
-m@

• Erläuterungen

Neben den bereits beschriebenen Aufrufparametern --help, --inputfile, --datafile und --outputfile, enthält die Parameterdatei weitere Aufrufparameter, die beim Mischlauf berücksichtigt werden.

Der Parameter --logfile erzeugt eine Datei, in die alle während des Mischlaufs auftretenden Fehler geschrieben werden. Die Logdatei wird ohne Pfadangabe in das aktuelle Arbeitsverzeichnis generiert.

Um die Fehlerprotokolldatei übersichtlicher zu gestalten, können mit Hilfe des Parameters -m benutzerdefinierte Meldungen erzeugt werden. In diesem Beispiel enthält die Logdatei Komma_log.log nach dem Mischlauf neben Fehlern und Meldungen noch eine Ausgabe der verwendeten CIB merge Version (Parameter --version).

Nach dem Mischlauf steht somit auch folgender Text in der Logdatei:

CIB merge 3.9.171
CIB software GmbH 1991-2009

Diese Software ist urheberrechtlich sowie nach internationalen Vertraegen

geschuetzt. Unberechtigte Vervielfaeltigung und Verbreitung, unabhaengig
auf welche Art oder Weise oder mit welchen Mitteln, elektronisch oder
mechanisch und unabhaengig zu welchem Zweck,
ob ganz oder auszugsweise, kann schwere zivil- und strafrechtliche Konsequenzen
nach sich ziehen und wird unter Ausschoepfung der Rechtsmittel geahndet.

Der Mischvorgang verwendet folgende Ein- und Ausgabedateien:
Eingabedatei:    Anschreiben_in.rtf
Steuerdatei:     Adresse_Komma.csv
Steuersatzdatei:
Ausgabedatei:    Komma_out.rtf
Meldungsdatei:   Komma_log.log
…

Als Trennzeichen in der CSV-Datei wird mit Hilfe des Parameters --delimiter das Komma-Zeichen definiert. Die CSV-Datei Adresse_Komma.csv sieht also folgendermaßen aus:

Vorname,Name,Strasse,PLZ,Ort,Geschlecht,KundenNr,AuftragsNr,Betrag
Max,Müller,Teststraße 3,99999,Testort,M,0987392,232222-4,123118

Aufruf der Parameterdatei über JAVA

Statt das Parameterfile über die Kommandozeile zu setzen, kann die Ansteuerung auch über JAVA erfolgen. Das gleiche Ergebnis wird mit folgendem JAVA-Code (MergeParameterfile.java) erzielt:

Auszug aus MergeParameterfile.java:

…
JCibMergeJob t_Job = new JCibMergeJob();
t_Job.initialize();
if (!t_Job.isInitialized())
{
      // Fehler beim Initialisieren
      System.err.println("Fehler beim
Initialisieren");
      System.exit(1);
}
try
{
      // Parameterdatei für den Mischlauf
 t_Job.setProperty(ICibMergeJob.PROPERTY_PARAMETERFILE,
"Komma_par.par");
      //Job ausführen
      t_Job.execute();
      //Fehlerbehandlung
      int t_Error =
((Integer)t_Job.getProperty(IComodJob.PROPERTY_ERROR)).intValue();
      if (t_Error != 0)
      {
      // Fehler beim Ausführen des Jobs
      String t_Errortext =
(String)t_Job.getProperty(IComodJob.PROPERTY_ERRORTEXT);
      System.err.println("Fehler beim
Ausführen: "+t_Error+" "+t_Errortext);
      }
}
finally
{
      t_Job.terminate();
}
…

Aufruf der Parameterdatei über C++

Erfolgt die Ansteuerung über C++, kann mit Hilfe von CibMergePFile die entsprechende Parameterdatei ausgeführt werden. Das Verzeichnis C:\\comod\\, in dem die CIB Module liegen, muss entsprechend angepasst werden, da es für die Initialisierung von CIB merge benötigt wird.

Auszug aus MergeParameterfile.cpp:

…
extern "C" const char *cibmerge_errormessage;

int main(const unsigned int number_of_arguments, char *argument_vector[])
{
 if(!cibmerge_initialize("C:\\comod\\", 0))
            cout << cibmerge_errormessage << endl;

      int iReturn=0;
      iReturn = CibMergePFile("Komma_par.par");
      cout << "Returnwert CibMergePFile: " << iReturn << endl;

      if(!cibmerge_terminate())
            cout << cibmerge_errormessage << endl;
      return 0;
}

• Default-Verhalten für undefinierte/leere Variablen festlegen

Jetzt soll im Ergebnis-RTF ein definierter Default-Wert ausgegeben werden, wenn eine Variable nicht durch die Datenversorgung gefüllt werden kann oder diese leer ist. Dazu wird in der RTF-Datei Default_in.rtf einer Variablen namens „Default.“ mithilfe des SET-Feldbefehls der Wert „<unbekannter Wert>“ in roter Schrift zugewiesen.

{ SET Default. „<unbekannter Wert>“ }

Alle leeren oder undefinierten Variablen sollen diesen Wert erhalten. Die CSV-Datei Adresse_Default.csv ist so abgeändert, dass es keinen Wert für die Variable Ort gibt. Um dieses Verhalten zu unterstützen, ist das Setzen weiterer Parameter notwendig.

Folgender Aufruf startet den Mischlauf mit gewünschten Default-Verhalten (Default.bat):

cibmrg32.exe --parameterfile=Default_par.par

Auszug aus der Parameterdatei Default_par.par:

…
Beteiligte Dateien für den Mischlauf

--inputfile=Default_in.rtf
--outputfile=!Default_out.rtf
--datafile=Adresse_Default.csv

Default-Verhalten festlegen

--default-mode=all
--default-prefix=Default.
…

• Erläuterungen

Der Parameter --default-mode legt fest, in welchen Fällen das Default-Verhalten, also das Einsetzen eines Ersatzwertes, eingeschaltet werden soll. In diesem Fall, soll ein Default-Wert eingesetzt werden, wenn eine Variable nicht durch die Datenversorgung gefüllt werden kann, weil sie nicht definiert ist, oder weil sie leer ist. Wenn das Verhalten nur für undefinierte Variablen gelten soll, muss an dieser Stelle der default-mode auf „undefined“ (statt „all“) gesetzt werden.

Das Präfix, das unbekannten/leeren Variablen vorangestellt wird, wird mit dem Parameter --default-prefix definiert. Hier ist es das Präfix „Default.“. Für die Variable Ort wurde kein Wert in der Datenquelle gefunden, also wird überprüft, ob ein Wert für Default.Ort definiert ist. Da dies auch nicht der Fall ist, wird der Wert eingesetzt, der für „Default.“ gesetzt wurde, nämlich „<unbekannter Wert>“. Das Ergebnis ist in der Datei Default_out.rtf zu finden.

• Eingabe- und Ausgabesprache für Zahlenformat/Datumsformat festlegen

Das RTF Language_in.rtf enthält nun einen Zahlenformatschalter zur Formatierung des Rechnungsbetrags. Der Betrag soll jetzt mit Tausender-Trennzeichen und 2 Nachkommastellen angezeigt werden. Das Anschreiben ist auf Englisch verfasst. Demnach wird in diesem Fall die Angabe des Zahlenformats im englischen Format gemacht. Die Ausgabe der Zahlen soll ebenfalls im englischen Zahlenformat erfolgen. Im RTF steht also folgender Ausdruck:

{ REF Betrag \# #,####0.00€}

Um eine korrekte Darstellung im Ergebnis-Dokument zu erreichen, muss über die Parameter angegeben werden, dass es sich bei der Eingabe um eine englische Zahlenformatierung handelt (und nicht, wie standardmäßig angenommen, um eine deutsche). Um diese Formatierung auch im Ausgabedokument beizubehalten, muss dies ebenfalls über einen zusätzlichen Parameter gesteuert werden

Folgender Aufruf startet den Mischlauf zur Erzeugung der englischsprachigen Zahlungserinnerung (Language.bat):

cibmrg32.exe --parameterfile=Language_par.par

Auszug aus der Parameterdatei Language_par.par:

…
Beteiligte Dateien für den Mischlauf

--inputfile=Language_in.rtf
--outputfile=!Language_out.rtf
--datafile=Adresse.csv

Eingabeformat für Zahlen ist auf englisch

--input-language=english

Ausgabeformat für Zahlen und Datum ist auf englisch

--output-language=english
…

• Erläuterungen

Der Aufrufparameter --input-language=english gibt an, dass die Zahlenformat-Angabe im RTF auf Englisch erfolgt. Um im Ergebnis eine korrekte Darstellung zu erreichen, muss diese Information angegeben werden, da sonst automatisch davon ausgegangen wird, dass es sich um eine deutsche Formatierung handelt, was unter Umständen zu unerwünschten Ergebnissen führen kann.

Um die Zahlen und Datumsangaben im Ergebnisdokument ebenfalls auf Englisch zu erhalten, wird der Aufrufparameter --output-language gesetzt.

Das Feld { DATE \@ "dddd, d.MM.jjjj" } erscheint im Ergebnisdokument z.B. als „Friday, 23.10.2009“. (deutsch: Freitag, 23.10.2009)

Das Feld {REF Betrag \# #,####0.00 } wird bei einem Betrag von 123118 zu „123,118.00“ formatiert. (deutsch: 123.118,00)

Optimierung von Rohtexten vor Auslieferung

Im Folgenden soll demonstriert werden, wie RTF-Bausteine optimiert und deren Dateigröße verringert werden kann. Vor allem in großen Projekten spielt das eine Rolle. Exemplarisch wird die Optimierung an der RTF-Datei Optimierung_in.rtf gezeigt. Diese enthält einige \* MERGEFORMAT Schalter, die MS Word beim Einfügen oder Umformatieren von REF-Feldern teilweise einfügt. Diese Schalter sollen aus dem RTF entfernt werden. Weitere Möglichkeiten, eine Beschleunigung der Verarbeitung in CIB merge und CIB format zu erreichen, besteht darin, Short-Tokens zu verwenden. Die Verwendung von Short-Tokens bietet zusätzlich einen Schutz vor Manipulation, da die Datei nur noch mit CIB-Modulen weiterverarbeitet werden kann. Werden die Dateien zwischen unterschiedlichen Maschinen ausgetauscht kann eine Übertragung beschleunigt werden, indem die Datei vorher komprimiert wird. All diese Schritte sollten durchgeführt werden, ohne dass Feldinhalte eingemischt werden. Welche Kombination von Optimierungen sinnvoll ist, hängt vom jeweiligen Umfeld und Einsatzgebiet ab. Um die Auswirkungen der verschiedenen Parameter zu testen, können die jeweiligen Parameter einkommentiert werden („#“ in der jeweiligen Zeile entfernen).

Folgender Aufruf optimiert die Eingabedatei (Optimierung.bat):

cibmrg32.exe --parameterfile=Optimierung_par.par

 

Inhalt der Parameterdatei Optimierung_par.par:

Fehler sollen protokolliert werden

--logfile=!Optimierung_log.log

Eingabe-Datei

--inputfile=Optimierung_in.rtf

Ausgabe explizit in eigenes Verzeichnis

--outputfile=!Optimierung_out.rtf

Schalter Mergeformat entfernen

--optimize

Short-Tokens verwenden

#--short-tokens

Komprimieren

#--compress=9

Keine Inhalte einmischen

--filter=f

• Erläuterungen

Der Parameter --optimize entfernt alle MERGEFORMAT-Schalter im RTF. Dadruch wird die Datei ein wenig kleiner und ist zudem besser lesbar.

Der Parameter --short-tokens erzeugt eine Ausgabedatei mit verkürzten CIBrtf-Tokens (CIBRtf). Durch die verkürzten RTF-Befehle in der Ausgabe erhält man eine gegenüber dem RTF verkleinerte Ergebnisdatei. Dies führt zu einer beschleunigten Verarbeitung in CIB merge und CIB format. Außerdem kann die Datei anschließend nur noch mit CIB-Modulen weiterverarbeitet werden.

Der Parameter --compress erzeugt eine komprimierte Ausgabedatei. Hier wurde die höchste Komprimierungsstufe 9 gewählt. Durch die Komprimierung wird die Dateigröße wesentlich verringert. Zusätzlich --short-tokens zu verwenden, würde keinen weiteren spürbaren Größenvorteil bringen.

Mit dem Parameter --filter werden die Feldinhalte nicht ausgewertet. Die Belegung „f“ (fast) verhindert dabei auch, dass die Feldinhalte geparst und übersetzt werden.

Eine weitere Möglichkeit, nicht benötigte Felder aus dem RTF herauszufiltern, besteht darin, den Parameter --field-results zu verwenden, der alle Field-Results entfernt, die in CIB format keine Rolle spielen. Diese Field-Results kommen vor allem dann im RTF vor, wenn mit {INCLUDETEXT} andere Bausteine angezogen werden. Deshalb wird der Parameter im Anwendungsbeispiel Bausteine vorgestellt.

• Weitere Möglichkeiten für zusätzliche Aufrufparameter

Nun soll eine Nachbearbeitung im CIB dialog über Schalter im RTF gesteuert werden. Die Ausgabe soll verschlüsselt erzeugt werden. Die Daten werden von der Anwendung nun in der Codepage PCA erstellt. Im RTF soll nicht für jedes Feld der „\* CHARFORMAT“-Schalter manuell gesetzt werden müssen.

Die Parameterdatei Zusatz_par.par enthält die notwendigen zusätzlichen Parameter, um diesen Sachverhalt zu unterstützen (Zusatz.bat):

cibmrg32.exe --parameterfile=Zusatz_par.par

Beteiligte Dateien für den Mischlauf

--inputfile=Zusatz_in.rtf
--outputfile=!Zusatz_out.rtf
--datafile=Adresse_pca.csv

Zusatzschalter für HTML-Ausgabe verstehen

--html-switches

Feldformatierung trotz Schalter übernehmen

--charformat=plain-values-only

CSV mit PCA-Zeichensatz unterstützen

--codepage=pca

Ausgabe verschlüsseln

--encrypt

• Erläuterungen

Im RTF-Baustein Zusatz_in.rtf sind Felder mit Zusatzschaltern definiert, die bei einer Umwandlung nach HTML eine Rolle spielen. In diesem Beispiel handelt es sich um einzeilige Textfelder, die über CIB dialog ausgefüllt werden können ({ REF Vorname\* <cib-formfield type="text" info="Vorname" testvalue="Max" /> }). Um diese Zusatzschalter zu verstehen, muss der Parameter --html-switches gesetzt werden.

Der Parameter --charformat=plain-values-only bewirkt, dass die Felder, die mit einem solchen Zusatzschalter ausgestattet sind, dennoch die Formatierung des Feldes erhalten. In diesem Fall sind die Felder Vorname und Name fett formatiert. Diese werden nach dem Mischlauf auch fett ausgegeben, obwohl sie Zusatzschalter enthalten.

Die verwendete CSV-Datei (Adresse_pca.csv) benutzt den PCA-Zeichensatz. Um die Daten korrekt darzustellen (beispielsweise Umlaute), muss der Parameter --codepage=pca gesetzt werden.

Durch den Parameter --encrypt ist die Ausgabedatei Zusatz_out.rtf verschlüsselt. Eine Weiterverarbeitung mit CIB-Modulen ist weiterhin möglich.