CIB merge technischer Leitfaden

1. Einführung

CIB merge ist eine zentrale Komponente aus dem Dokumentbaukasten der CIB office Module. Mit CIB merge bekommt der Anwender ein Werkzeug an die Hand, womit er Dokumentbausteine (=Templates), die auch Feldanweisungen (=Befehle) beinhalten können, interpretieren und mit variablen Daten versorgt zu einem Zieldokument mischen kann. CIB merge unterstützt das RTF-Format von Microsoft als Dokumentenformat. Die variablen Daten können aus einer oder mehreren CSV-Dateien, XML-Dateien oder aus Datenbank(en) eingemischt werden. Es besteht auch die Möglichkeit, eigene UserExit-Funktionen in CIB merge einzuhängen.

Die vorliegende Dokumentation gibt einen schnellen Überblick über die Einsatzmöglichkeiten.

2. Installation

Windows 32/64-Bit

Für die aktive Nutzung des RTF Textinterpreters muss die jeweilige CIB merge Programmversion im Zugriff sein.

Unix allgemein

Es sind aus Gründen mehrerer Libs  Archive mit Installationsanleitung für verschiedende Unix-Derivate verfügbar…

Systeme

CIB merge läuft unter Windows 32- und 64-bit.

CIB merge ist für folgende weitere Plattformen verfügbar:

• Solaris Sparc (32/64)
• Solaris x86 (32/64)
• AIX-ppc (32/64)
• Linux-x86 (32/64)

 Weitere Plattformen auf Anfrage.

Zusatzmodule

Nach dem bewährten Baukastenprinzip der CIB office Module (=CoMod), gibt es rund um CIB merge auch Zusatzkomponenten, die dem Entwickler entweder die technische Integration in seine bevorzugte Architektur erleichtern oder auch den Funktionsumfang des CIB merge Modules sinnvoll ergänzen können.

Alle Zusatzprodukte sind in separaten technischen Leitfaden ausführlich dokumentiert. Diese Informationen können Sie gerne beim CIB Support anfordern.

Mit dem CIB chart Modul gibt es eine optionale Ergänzung für den CIB merge über das es möglich ist, aus der gleichen Datenversorgung auch verschiedenste dynamische Diagramme aus den Daten zu erzeugen und diese als Grafiken im Ergebnisdokument zu hinterlegen.

CIB runshell

Die CIB runshell ist ein Kommandozeilentool über das alle CIB Produkte, die in Form von DLLs oder shared libraries ausgeliefert werden, angesteuert werden können. Mit der CIB runshell ist es insbesondere möglich alle Aufrufparameter ("Properties") zu setzen, die jedes einzelne CIB office Module dem Anwender zur Verfügung stellt.

Mit dem JCoMod Wrapper erhalten Sie eine komplette JAVA/JNI Kapselung, die eine einfache Ansteuerung von CIB merge aus JAVA ermöglicht. Die entsprechenden JAVA/JNI Schnittstellen bedienen auch die CIB runshell, so dass man die CIB Komponenten auch in eigenen Prozessen innerhalb der JAVA VM starten kann.

Falls Sie CIB merge und andere CIB Module in einer .net-Umgebung einsetzen möchten, fragen Sie uns nach den entsprechenden Schnittstellen. Diese stehen für CIB format/output, CIB merge, CIB pdf toolbox, CIB view und CIB job in einem gemeinsamen Assembly zur Verfügung.

Der CIB documentServer dient zur Optimierung des Einsatzes der CIB office Module (CoMod) insbesondere beim Einsatz auf Servern (Dokument und Druckdienste). Mit dem J2EE-Standardpaket des CIB documentServer ist eine schnelle Realisierung - auch komplexer Dokumentanforderungen - im jeweiligen Kundensystem möglich.

Die CIB workbench ist ein Addin für fast alle Versionen von MS-Office. Sie unterstützt insbesondere die Erstellung von Textbausteinen, was das Hinzufügen von Feldbefehlen erheblich erleichtert. Außerdem sind eine Testumgebung und eine Reportingfunktionalität integriert.

Die CIB pdf toolbox ist ein dem CIB merge vergleichbarer Interpreter für PDF-Dateien. Sie bietet vielfache Verarbeitungsmöglichkeiten für PDF und zugelieferte Datenströme. Es bestehen auch Möglichkeiten, in bestehende RTF-Dokumentprojekte zusätzliche PDF-Templates zu einem Zieldokument zu verarbeiten.

3. CIB merge als „Dokumentinterpreter“

CIB merge ist ein universeller Interpreter zur dynamischen Verarbeitung von Dokumenten mit Feldbefehlen, externer Datenversorgung über CSV- oder XML-Dateien, SQL Zugriffen sowie eigenen User Exits.

Es wird RTF als Dokumenteingabeformat unterstützt.

Dem Anwender steht über die Aufrufschnittstelle der gesamte Funktionsumfang des CIB merge zur Verfügung.

3.1. CIB merge

Mit CIB merge ist es möglich:

• Daten aus externen XML und CSV Datenquellen in RTF einzumischen. Dabei werden im RTF Dokument enthaltene Variablenfelder über ihren eindeutigen Namen angesprochen und mit dem angegebenen Inhalt gefüllt. Durch die Möglichkeit der Abarbeitung von Datensätzen wird sowohl die Einzelbrief- als auch die Serienbrieffunktionalität unterstützt.
• Es möglich auch direkte SQL Abfragen aus Dokumenten auszuführen.
• Es ist möglich userseitig aus Dokumente über einen Mischlauf anzusteuern.

3.2. CIB merge&optimize

Die Dokumentbasis (=Templates) wird unter Verwendung von auf dem Markt weitverbreiteten Textsystemen (i.d.R. MS-Office, Open Office) unterschiedlichster Versionen erstellt. Entsprechend sind die einzelnen Bausteine z. T. mit verschiedenen sehr redundanten Informationen angereichert.

CIB merge & optimize ermöglicht es, ohne einen Mischlauf auszuführen, beim Bereitstellen der Bausteine (="Deployen von Templates") in die Anwendungsumgebung, diese entsprechend zu verschlanken, ohne deren Formatierung oder den Inhalt zu ändern.

3.3. CIB merge&crypt

Häufig besteht die Anforderung, die Dokumentbasis (=Templates) geschützt in einer Anwendung zu hinterlegen und ebenso irgendwelche Zwischenergebnisse aus einem Mischlauf gegen "Missbrauch" zu schützen. CIB merge verfügt über entsprechende Aufrufoptionen, die ein Packen und/oder Verschlüsseln ermöglichen.

3.4. CIB merge&analyse

Über eine eigene Umgebung „report & analyse“ bietet CIB die Möglichkeit von Dokumentenprojekten ein eigenes Reporting zu erzeugen. Die CIB merge Komponente leistet in dieser Analyseumgebung wertvolle Dienste, sowohl beim Auswerten der Bausteininhalte des Analyseprojektes als auch beim Erzeugen des eigentlichen Ausgabereports. Beachten Sie hierzu die Detailinformationen aus dem speziellen technischen Leitfaden „CIB report & analyse“.

3.5. Unterstützte Feldbefehle

Allgemein

MS-Office stellt ca. 85 verschiedene Feldbefehle zur Verfügung, die man zur Programmierung von dynamischen Dokumenten benutzen kann. Alle Befehle die nicht unmittelbar mit der Formatierung eines Textes zu tun haben, werden von der CIB merge Komponente bei einem Mischlauf ausgewertet und unterstützt.

Die Interpretation der übrigen Feldbefehle, die für die Layout-/Druckdarstellung wichtig sind (z.B. (Gesamt)Seitennummerierungen, Druckdatum, Signaturfelder u.a.), bleibt der CIB format/output-Komponente vorbehalten. CIB merge reicht diese Feldbefehle ungefiltert in das Ergebnisdokument durch.

Ab CIB merge Version 3.13.7:
Das gleiche Verhalten gilt bei einem Rechenausdruck, der Referenzen auf Tabellenelemente enthält: Der Ausdruck wird ungefiltert an das Ergebnisdokument durchgereicht.
Konkret geht es um diese Referenzen: LEFT/LINKS, RIGHT/RECHTS, ABOVE/ÜBER, BELOW /UNTER.

Übersicht der grundlegenden Feldbefehle

Folgende Feldbefehle eines Dokumentes werden bei einem Mischvorgang direkt durch die CIB merge Komponente interpretiert und dynamisch in die Ausgabedatei umgesetzt (die Feldbefehle sind hier lediglich alphabetisch aufgestellt und nicht mit voller Syntax beschrieben):

Einige dieser Feldbefehle ermöglichen mit Zusatzschaltern eine Erweiterung ihrer Funktionalität.

Beispielsweise können mit Hilfe von Schleifenanweisungen beliebig lange dynamische Tabellen erzeugt werden. Auch das dynamische Einfügen von Textbausteinen ist möglich.

Unterstützte Text-Funktionen

CIB merge unterstützt ab Version 3.12.0 die im Folgenden beschriebenen Text-Funktionen.

Hinweise:

• Die Möglichkeit für eine verkettete (mehrfache) Verarbeitung von Textfunktionen ist hier beschrieben.
• Als Parameter einer Textfunktion können feststehende Texte (Strings) verwendet werden. Der Inhalt eines Strings ist in Anführungszeichen anzugeben. Dabei darf der String selbst keine Anführungszeichen enthalten.

Unterstützte Datums-Funktionen

CIB merge unterstützt ab Version 3.12.12 die im Folgenden beschriebenen Datums-Funktionen.

Die Datumsfunktionen werden analog zu Rechen- oder Textfunktionen in der Form

{ =DATUMSFUNKTION }

Vorraussetzung für diese Funktionen ist, dass das als Eingabe verwendete Datum (bzw. eine Variable „Datum“) einen gültigen Datumswert besitzt und in einem gültigen Datumsformat formatiert ist.

Regeln für die Verarbeitung von Text- und Datumsfunktionen

Innerhalb einer Text- bzw. Datumsfunktion kann der Name einer Variablen aus der Datenversorgung verwendet werden, um den Inhalt dieser Variablen zu verarbeiten.

Beispiel 1:

{ SET myVar "Mein Inhalt aus der Datenversorgung" }

{= LEFT(myVar; 4) }
Ergebnis: Mein

Der Inhalt der Variablen myVar darf beliebige Zeichen enthalten, auch Sonderzeichen wie Anführungszeichen, Semikolon, Komma, Klammern, usw.

Beispiel 2:

Um Sonderzeichen, die sonst durch den RTF-Verarbeitung anderweitig interpretiert würden, korrekt verarbeiten zu können wird folgende Vorgehensweise empfohlen:

{ SET COMMA "," }

{ = SUBSTITUTE("123.45"; "."; COMMA; "1") }

Ergebnis: 123,45

Das Sonderzeichen wird hier per SET-Befehl einer Variablen zugewiesen, die anschließend im SUBSTITUTE-Befehl verwendet werden kann.

Beispiel 3:

{ SET myDatum "15.02.2015" }

Um Text- bzw. Datumsfunktionen verkettet zu verarbeiten, d.h. innerhalb einer Text-/Datumsfunktion mit dem Ergebnis einer anderen Text-/Datumsfunktion weiter zu arbeiten, ist der Umweg über Variablen notwendig.

Beispiel:

{SET a "   abc  "}

{SET b { = TRIM (a)} }

{ = LEFT(b;2)}

3.6. Behandlung von Feldschaltern

Die diversen Feldschalter, die im RTF verwendet werden können und vom CIB merge ausgewertet werden, sind im Detail in den RTF-Schulungsunterlagen erläutert:

 Dynamische Dokumente - Band 1 - Grundlagen.pdf

Sie werden in diesem Leitfaden nur insoweit erwähnt, als sie für die Behandlung einiger Parameter von Bedeutung sind, z.B. \* CHARFORMAT.

3.7. Interessante Zusatzfunktionalitäten

CIB merge bietet in direkter Verbindung mit weiteren CIB Komponenten nützliche Zusatzfunktionalitäten für die dynamische Dokumentgenerierung bzw. für die Auswertung eines solchen Dokumentprojektes.

Dynamische Diagramme mit CIB chart

Oft sind die Tabellen in Rohtexten, die von CIB merge mit aktuellen Daten gefüllt werden, nicht aussagekräftig genug. Eine Ergänzung durch eine optische Geschäftsgrafik, also zum Beispiel um ein Linien- Torten- und Balkendiagramm ist hier wünschenswert. Natürlich müssen diese Grafiken dynamisch erzeugt werden, und zwar ebenfalls aus denselben aktuellen Daten der Anwendung.

CIB chart  ist ein Modul zur Erstellung von dynamischen Geschäftsgrafiken, sowohl für Bildschirmoberfläche als auch zur Integration in Dokumente. Das Produkt CIB chart besteht aus

• dem CIB chart designer der dem Textorganisator die Erstellung der Graphikschablone ermöglicht
• dem CIB chart generator, der zur Laufzeit von CIB merge zur Diagrammerzeugung aus den angelieferten variablen Daten dient.

Der CIB chart designer ist eine eigene Windowsanwendung und dient dem Textorganisator zum Entwerfen einer Grafikvorlage mit Beispieldaten. Die Vorlage ist ein Enhanced Metafile (EMF) mit Erweiterungen in Form von CCR (=CIB chart Resource)Befehlen.

Dieses EMF zeigt die Beispielgrafik auf Basis von Testdaten mit dem vom CIB chart designer entworfenen Layout (Farben, Ausmaße und Beschriftungen). Es lässt sich mit den üblichen Grafiktools anzeigen, wie zum Beispiel die Vorschau im Windows Explorer.

In Microsoft Word lässt sich das EMF wie jede andere Grafikdatei über den Menüpunkt „Einfügen/Grafik/Aus Datei…“ komfortabel einfügen, positionieren und skalieren.

Die CCR Erweiterungen in dieser Grafik geben die im CIB chart designer getroffenen Einstellungen und Daten an CIB merge oder CIB format weiter. Damit kann zum Zeitpunkt der Dokumenterstellung die gewünschte Geschäftsgrafik mit den zu diesem Zeitpunkt verfügbaren Praxisdaten und dem vom Textorganisator vordefinierten Layout erstellt werden.

Dokumentanalysen CIB report&analyse

Viele Anwender erstellen sehr komplexe Dokumentprojekte. Um davon interne Projektreports zu erzeugen, oder auch Schwachstellenanalyse in der Dokumentmodellierung zu betreiben, gibt es die Möglichkeit eines „CIB report&analyse“.

Dieses Reporting Verfahren wird auch in die CIB workbench (AddIn unter MS-Office) integriert. Die Nutzung ist in einem eigenen ausführlichen Leitfaden beschrieben.

4. Datenversorgung

Neben der Interpretation von Feldbefehlen wie Bedingungen, Schleifen, Formeln und Einfügen-Anweisungen ist das Einsetzen von variablen Daten eine zentrale Aufgabe des CIB merge.

Es gibt dazu 4 verschiedene Varianten der Datenversorgung, die auch in gemischter Form zur Anwendung kommen können.

• Die versorgten Daten haben einen Aufbau im CSV Dateiformat (auch Verteilung auf mehrere CSV Dateien möglich)
• Es werden Daten über eine XML Datei versorgt
• Es werden aus einem Dokumentbaustein direkt SQL Abfragen getätigt
• Es werden aus einem Dokumentbaustein direkt UserExits angesteuert

4.1. CSV

Allgemein

Bei den CSV Dateien handelt es sich um eine oder mehrere Text-Dateien, die die Namen der Eingabefelder und die zugehörigen Werte enthalten. Die Abkürzung CSV steht für  "Comma Separated Values".

Die erste Zeile der Steuerdatei beinhaltet den sog. Steuersatz, der aus durch ";" getrennten Feldnamen besteht. Der Steuersatz kann beliebig viele, nur durch den freien Arbeitsspeicher begrenzte Feldnamen enthalten.

Jede weitere Zeile beinhaltet genau einen Datensatz. Ein Datensatz enthält, ebenfalls durch ";" getrennt, in der Reihenfolge der Feldnamen die jeweils einzufügenden Textbausteine bzw. Daten. Die Anzahl der Einträge im Datensatz muss mit der Anzahl der Feldnamen im Steuersatz übereinstimmen.

CIB merge kann eine einzelne CSV-Datei oder Multi-CSV-Dateien verarbeiten.

Verwendung mit CIB merge:

Der Parameter -d<Datensatzquelle> setzt die CSV-Datei für CIB merge, siehe Kapitel Parameter –d.

Hinweise zur Verwendung von Trenn- und Sonderzeichen in der Daten-CSV

Enthält eine einzufügende Textpassage ein Semikolon, ein Tabulatorzeichen oder ein Anführungszeichen, so muss die gesamte Textpassage in Anführungszeichen gesetzt werden. Anführungszeichen in einer Textpassage müssen dann verdoppelt werden. Um beispielsweise den Firmennamen Wäscherei "Weißer Riese" in einem Rohtext einzufügen, muss der Eintrag in der Steuerdatei folgendes Aussehen haben: ;"Wäscherei ""Weißer Riese""";.

CIB merge kann mit dem Parameter -T auch ein anderes Trennzeichen als ";" auf die CSV-Dateien anwenden, siehe Kapitel 6.14 Parameter –T.

Hinweise zu UTF-8 kodierten Daten-CSVs

Damit UTF-8 kodierte Datendateien mit Hilfe des CIB merge korrekt eingemischt werden, sind folgende Schritte notwendig:

1. Die CIB merge par-Datei muss um den folgenden Parameter erweitert werden:
-putf-8
Dieser Parameter sagt aus, dass die Datendateien im UTF-8-Format kodiert sind.

2. Entfernen der "byte order mark" (BOM) aus den Datendateien.
Da für die Verarbeitung der UTF-8 kodierten Datendateien durch CIB merge der unter 1.) beschriebene Parameter verwendet wird, werden alle in der Datendatei enthaltenen Zeichen nach UTF-8-Zeichensatz interpretiert. Dies gilt auch für eine BOM. Damit kommt es zu Fehlermeldungen bei der Verarbeitung. Aus diesem Grund müssen alle BOMs aus den verwendeten Datendateien entfernt werden.

Einzel-CSV-Datei

Beschreibung

Bei der Einzel-CSV-Datei werden den Eingabefeldern direkt ihre Werte zugeordnet. Der Anwender benutzt im Dokumentbaustein direkt den Feldnamen um auf einen Wert zuzugreifen.

Multi-CSV-Datei

Beschreibung:

Mit Hilfe einer Multi-CSV-Datei können mehrere CSV-Dateien verwaltet werden. Sie enthält die Namen aller CSV-Dateien, die im aktuellen Mischlauf geladen werden sollen. Über die Felder in der Kopfzeile der Multi CSV Datei, erhält jede CSV-Datei einen Aliasnamen zugeordnet, über den dann im Dokument auf diese CSV Dateien zugegriffen werden kann.

Verwendung mit CIB merge

Für eine Multi CSV-Datenversorgung muss neben dem Parameter –d mit der Multi CSV Datei auch der Parameter -c gesetzt werden, siehe Kapitel 6.50 Parameter -c.

Vorteile gegenüber XML:

• Einfaches Format
• Einfache 1-n Beziehung
• Kleinere Dateigröße

4.2. XML

Allgemein

CIB merge unterstützt seit der Version 3.9.x auch die Verarbeitung von Daten im XML Format. Es gibt für langjährige CIB merge Nutzer auch eine separate Dokumentation um ein Dokumentenprojekt, das bisher auf CSV Datenversorgung basierte, schrittweise in XML basierte Datenversorgung überzuführen.

XML-Zusatzkomponenten

Eine Unterstützung der XML Datenversorgung erfolgt mit Hilfe von zusätzlichen DLLs, die neben der CIB merge DLL installiert sein müssen. Diese Zusatzkomponenten sind in CIB merge Übergabe-Paketen automatisch enthalten und werden von CIB merge nur im Falle einer vorliegenden XML Versorgung dynamisch angezogen.

XML-Eigenschaften

XML-Dokumente besitzen einen physischen und einen logischen Aufbau.

Der physische Aufbau eines XML-Dokumentes besteht aus

Entitäten. Die erste Entität ist die Hauptdatei des XML-Dokuments. Weitere mögliche Entitäten sind über

Entitätenreferenzen (&name; für das Dokument bzw. %name; für die Dokumenttypdefinition) eingebundene Zeichenketten, eventuell auch ganze Dateien, sowie

Referenzen auf Zeichenentitäten zur Einbindung einzelner Zeichen, die über ihre Nummer referenziert wurden (&#Dezimalzahl;, oder &#xHexadezimalzahl;).

Eine XML-Deklaration wird optional verwendet, um XML-Version, Zeichenkodierung und Verarbeitbarkeit ohne Dokumenttypdefinition zu spezifizieren.

Eine Dokumenttypdefinition wird optional verwendet, um Entitäten sowie den erlaubten logischen Aufbau zu spezifizieren.

Der logische Aufbau eines XML-Dokumentes ist eine Baumstruktur und damit hierarchisch strukturiert. Als Baumknoten gibt es:

Elemente, deren physische Auszeichnung mittels

einem passenden Paar aus Start-Tag (<Tag-Name>) und End-Tag (</Tag-Name>) oder

einem Empty-Element-Tag (<Tag-Name />) erfolgen kann,

Attribute als bei einem Start-Tag oder Empty-Element-Tag geschriebene Schlüsselwort-Werte-Paare (Attribut-Name="Attribut-Wert") für Zusatz-Informationen über Elemente (eine Art Meta-Information),

Verarbeitungsanweisungen (<?Ziel-Name Parameter ?>, engl. Processing Instruction)

Kommentare (<!-- Kommentar-Text -->)

Text, welcher als normaler Text oder in Form eines CDATA-Abschnittes (<![CDATA[ beliebiger Text]]>) auftreten kann.

Ein XML-Dokument muss genau ein Element auf der obersten Ebene enthalten. Unterhalb von diesem Dokumentelement können weitere Elemente verschachtelt werden.

Der Parameter -d<Datensatzquelle> setzt die CSV-Datei für CIB merge, siehe Kapitel 6.11 Parameter –d.

Vorteile gegenüber CSV Nutzung:

• Weniger Dateien
• Arbeitet intern über Knoten
• Mit XPATH können RTF Strukturen vereinfacht werden

4.3. ODBC und SQL

Allgemein

Über die im Programmverzeichnis zusätzlich hinterlegte CIB sql DLL sind SQL Zugriffe direkt aus CIB merge möglich. Das Ergebnis einer Abfrage (eine Tabelle) wird wie eine CSV-Steuerdatei verwendet. Anstatt eine Steuerdatei in der Multisteuerdatei zu bestimmen, wird dort eine Abfrage in SQL gestellt. Es ist auch möglich, bestehenden oder neuen Steuerdatei-Aliasen eine Steuerdatei oder SQL-Abfrage dynamisch zuzuweisen. Die dynamische Aliasbelegung ist auch ohne jegliche Steuerdatei oder Multisteuerdatei erlaubt. Weiterhin ist es möglich von einer Ergebnistabelle einer SQL-Abfrage den Wert der ersten Spalte und ersten Zeile sofort in den Rohtext einsetzen (ohne den Umweg über einen Alias, dem Feld “Nächster” und Variablen).

ODBC Versionen

Die CIB sql Dll verwendet intern die ODBC API Conformance Ebenen Core, Level 1 (z.B.: long data) und Level 2 (z.B.: scrollable Cursor). Die SQL Conformance Ebene Extended SQL Grammar wird für Datumsfelder benötigt. Vgl. hierzu ODBC SDK 2.10 Programmers Reference.

Es ist also darauf zu achten, dass die verwendeten ODBC-Versionen und Treiberversionen die entsprechenden Ebenen unterstützen.

Getestet sind die CIB sql-Funktionalitäten mit der ODBC 3.51 unter Windows NT 4.0. Hierbei kamen die Microsoft Jet Odbc-Treiber für MS Access zum Einsatz, die bei den entprechenden ODBC-Versionen mitgeliefert werden.

SQL

SQL Zugriffe sollen direkt aus CIB merge möglich sein. Das Ergebnis einer Abfrage (eine Tabelle) soll wie eine Steuerdatei verwendet werden. Anstatt eine Steuerdatei in der Multisteuerdatei zu bestimmen, wird eine Abfrage in SQL gestellt. Eine zweite Erweiterung soll dynamisch bestehenden oder neuen Steuerdatei-Aliasen eine Steuerdatei oder SQL-Abfrage zuweisen können. Eine dritte Erweiterung soll von einer Ergebnistabelle einer SQL-Abfrage den Wert der ersten Spalte und ersten Zeile sofort in den Rohtext einsetzen (ohne den Umweg über einen Alias, dem Feld “Nächster” und Variablen). Eine vierte Erweiterung soll die dynamische Aliasbelegung auch ohne Multisteuerdatei und eventuell sogar ohne normale Steuerdatei erlauben.

SQL-Abfragen in der Multisteuerdatei

Der Eintrag eines Feldes in der Multisteuerdatei sieht üblicherweise so aus: “[;]Steuerdatei” oder “Kopfsatzdatei;Datensatzdatei”.  Für SQL-Zugriffe gibt es die Möglichkeit der “SQL:Datenbank;Abfrage”.

Die neue Funktion ist nur mit einer DLL für SQL-Abfragen verfügbar.

Die Abfrage wird an die Datenbank geschickt. Weitere Zugriffe erfolgen mit den bekannten Befehlen für Steuerdateien mit unveränderter Bedeutung. Der einzige Unterschied ist die Datenquelle: Die Tabelle steht nicht in der Steuerdatei als Menge von Datensätzen, sondern in einer Datenbank. (Die Datenbank muss in den Systemeinstellungen für ODBC als Benutzer- oder Systemdatenquelle eingerichtet sein.)

Das folgende Beispiel stellt zwei Steuerdateien mit den Aliasen NormalDat und SqlDat zur Verfügung. Die Steuerdatei SqlDat enthält dabei zwei Spalten aus der Tabelle Tarife. Die Datenbank, die die Tabelle enthält wird über ODBC mit dem Namen ODBC-Tarifdatenbank zur Verfügung gestellt.

Multisteuerdatei:

NormalDat;SqlDat
“normal.csv”; “SQL:ODBC-Tarifdatenbank;SELECT TarifNr, TarifName FROM Tarife ORDER BY TarifNr”

Dynamische Aliasbelegung

Der Befehl “Nächster” liest üblicherweise die nächste Datenzeile oder stellt die Leseposition vor den Anfang der Datenquelle.  Möglich ist aber auch die Neudefinition oder Neuzuweisung eines Alias mit “NÄCHSTER DEF:Alias;Datenquelle”.

Der Alias wird neu bestimmt, wenn er noch nicht existiert.  Falls der Alias bereits belegt ist, wird die damit verbundene Datenquelle geschlossen und der Alias neu belegt.

Die Datenquelle kann eine Steuerdatei oder eine SQL-Abfrage sein. Der Wert hinter dem Semikolon muss also wie ein Eintrag in der Multisteuerdatei aussehen.

Diese Funktion steht auch zur Verfügung, ohne dass in den an Merge übergebenen Parametern jegliche Steuerdatei oder Multisteuerdatei angegeben wurde.

Das Beispiel definiert dynamisch im Rohtext den Alias SqlDyn als die gesamte Tarife-Tabelle. Anschließend werden daraus bestimmte Felder tabellarisch aufgelistet.

Rohtext:

{ NÄCHSTER “DEF:SqlDyn;SQL:ODBC-Tarifdatenbank;SELECT * FROM Tarife ORDER BY TarifNr” }

{ WENN { DATENSATZ ?SqlDyn } = 1 “

{ NÄCHSTER SqlDyn }” \*solange }

SQL-Abfragen im Feld “REF”

Der Befehl “Nächster” liest üblicherweise die nächste Datenzeile oder stellt die Leseposition vor den Anfang der Datenquelle.  Möglich ist aber auch die Neudefinition oder Neuzuweisung eines Alias mit “NÄCHSTER DEF:Alias;Datenquelle”.

Der Alias wird neu bestimmt, wenn er noch nicht existiert.  Falls der Alias bereits belegt ist, wird die damit verbundene Datenquelle geschlossen und der Alias neu belegt.

Die Datenquelle kann eine Steuerdatei oder eine SQL-Abfrage sein. Der Wert hinter dem Semikolon muss also wie ein Eintrag in der Multisteuerdatei aussehen.

Diese Funktion steht auch zur Verfügung, ohne dass in den an Merge übergebenen Parametern jegliche Steuerdatei oder Multisteuerdatei angegeben wurde.

Das Beispiel definiert dynamisch im Rohtext den Alias SqlDyn als die gesamte Tarife-Tabelle. Anschließend werden daraus bestimmte Felder tabellarisch aufgelistet.

Rohtext:

{ NÄCHSTER “DEF:SqlDyn;SQL:ODBC-Tarifdatenbank;SELECT * FROM Tarife ORDER BY TarifNr” }

{ WENN { DATENSATZ ?SqlDyn } = 1 “

{ NÄCHSTER SqlDyn }” \*solange }

5. Technische Schnittstellen

Dieses Kapitel gibt einen kurzen Überblick über die verfügbare API und derer Parameter. Allgemein gilt, dass man über die Funktion cibmerge seine gewünschten Parameter in CIB merge setzt.

5.1. Funktionsprinzip

Die Schnittstellenphilosophie der CIB merge Komponente ist aus historischen Gründen noch abweichend von den anderen CIB Modulen gestaltet. Die Funktion zur Ausführung eines Mischlaufes bekommt noch direkt die Aufrufparameter noch direkt gesetzt.

Sehr wenige der Eigenschaften sind dabei zwingend erforderlich (z.B. Eingabedatei(strom)). Viele Parameter sind optional und ermöglichen dem Anwender eine zielgenaue Bestimmung seines Wunschergebnisses (z.B. Arbeitsverzeichnisse, Optimierung, Verschlüsselung, Defaultwerte,..).

5.2. cibmerge

Syntax:

int WINAPI cibmerge(int argc, char *argv[])

Aufrufparameter:

Die Aufrufparameter sind unter Aufrufparameter im Detail einzeln beschrieben.

Returnwert:

        0  wenn alles erfolgreich ist

     - 1  bei Benutzerabbruch

    > 0  bei Fehlerabbruch

Fehlerbehandlung:

Ein Fehlercode größer 0 bedeutet, dass ein Problem aufgetreten ist und der Mischauftrag nicht ordentlich zu Ende geführt wurde. Ein Fehlercode kleiner 0 bedeutet, dass der Benutzer den Mischauftrag bewusst abgebrochen hat. Zusätzlich kann bei einem CIB merge Lauf eine Fehlerprotokolldatei geschrieben werden, die ausführliche Informationen zu dem aufgetretenen Fehler enthält.

Weitere Informationen zu den Fehlercodes und den Fehlerprotokolldateien finden Sie unter Fehlerbehandlung.

5.3. CibMergeVB

Dieser Funktion werden die einzelnen Parameter in einer langen Zeichenkette (=String) übergeben, wobei für das Trennzeichen ein Blank zu setzen ist, z.B.: „-iInput.rtf –oOutput.rtf -@1“

Syntax:

int WINAPI CibMergeVB(char* strParameters)

Returnwert:

Fehlerbehandlung:

Es ist keine besondere Fehlerbehandlung aktiv.

Fallback

Aufrufkonzepte

5.4. CibMergePFile

Dieser Funktion wird ein Parameter-Filename übergeben, z.B.: D:\Test.par.

Syntax:

int WINAPI CibMergePFile(char* szParamFile)

Returnwert:

Fehlerbehandlung:

Es ist keine besondere Fehlerbehandlung aktiv.

5.5. GetMergeVersion

Die Funktion liefert die aktuelle Versionsnummer der CIB merge DLL zurück. Damit können Sie in Ihrer Applikation sicherstellen, dass eine Mindestversion vorliegt, wenn Sie etwa spezielle Programmeigenschaften benutzen, die erst ab einem bestimmten Release zur Verfügung gestellt wurden.

Syntax:

unsigned
long WINAPI GetMergeVersion()

Returnwert:

Der Returnwert liefert die aktuelle Versionsnummer der CIB merge DLL zurück. Der long-Wert liefert die Information in zwei Bereichen. Die ersten zwei Bytes enthalten den Versionszähler des Hauptreleases. Die Bytes 3 und 4 enthalten den zugehörigen aktuellen Releasezähler. Je nach Programmiersprache sind die Hi- und Lowbereiche entsprechend zu beachten (siehe Codebeispiele unten).

Fehlerbehandlung:

Es ist keine besondere Fehlerbehandlung aktiv.

6. Aufrufparameter im Detail

Im nachfolgenden Kapitel werden alle verfügbaren Aufrufparameter in alphabetischer Reihenfolge beschrieben. Viele der verfügbaren Parameter sind optional möglich und nicht zwingend zu setzen.

Parameter können sowohl als Einzelbuchstaben übergeben werden, wie z.B. -IEingabe.rtf. Es besteht aber ebenso die Möglichkeit ausgeschriebene Parameter zu übergeben, wie z.B. --inputfile=Eingabe.rtf.

Formal kann CIB merge Parameter in der Form (‚-’| ‚/’) ((«Buchstabe» | («Eigenschaft» ‚=’)) «Wert») | «Eigenschaft» aus der Kommandozeile entgegennehmen.

6.1. Allgemeine Hinweise

• Die Groß- und Kleinschreibung der Parameter spielt keine Rolle.
• Alle per Buchstaben versorgten Werte existieren auch als Langversion.
• Als Startzeichen für Parameter, die als Buchstabe übergeben werden, muss „-“ oder „/“ verwendet werden. Für ausgeschriebene Parameter lautet das Startzeichen „--“.
• Die ersten Parameter, die ohne Startzeichen übergeben werden, bekommen der Reihe nach die Parameterzeichen aus "IODH" zugewiesen (Input, Output, Daten).
• Nach Auswertung aller Parameter wird automatisch "/@" ausgeführt.
• «Eigenschaft» darf jedes beliebige Zeichen enthalten außer ‚=‘.
• Die Großschreibung der Eigenschaft spielt keine Rolle.
• Andere Zeichen als a-z, A-Z oder 0-9 werden wie ein ‚-‘ behandelt.
• Die Eingabe von
• (‚-‘ | ‚/‘) «Eigenschaft»
• steht für
• (‚-‘ | ‚/‘) «Eigenschaft» ‚=‘ «Wert»
• mit der leeren Zeichenfolge als Wert.
• Ein „+“ nach einem Dateinamen hängt an die bereits vorhandene Datei an
• ein „!“ nach einem Dateinamen überschreibt eine bereits vorhandene Datei (gilt für Parameter -o Ausgabedatei und Parameter –l Logdatei)

6.2. Hinweis Aufrufbeispiele

Die Parameterbeschreibung enthält jeweils Kurzhinweise zur Nutzung des Parameters aus einer bestimmten Umgebung.

Eine ausführlichere Beschreibung anhand von Anwendungsfällen finden sie im Kapitel „Anwendungsbeispiele“ Ausführliche Codebeispiele, für verschiedene Programmiersprachen, finden Sie im Kapitel „Schneller Einstieg“.

6.3. Übersicht der Abkürzungen für Aufrufparameter

6.4. Parameter --analyse

Der Parameter --analyse spielt nur für das Reportingtool „CIB report&analyse“ eine Rolle. Er bestimmt die statische Feldstruktur.

Syntax

--analyse=<Dateiname>

Beschreibung

Die Struktur, die mithilfe von --analyse bestimmt wird, kann zur weiteren Analyse oder Darstellung dienen. Die Meldung erfolgt in eine gesonderte Datei im Csv-Format. Es werden zunächst nur Ref, Mergerec, Next und Includetext (Ref, Datensatz, Nächster und Einfügentext) Felder bestimmt. Sie haben nur einen Parameter, der auch gemeldet wird. Dieser Parameter ist sinnvoll in dem Zusatzprojekt CIB report&analyse.

Die statische Feldstruktur ist die Reihenfolge der Felder wie aufgeschrieben.

Beispiel für statische Feldstruktur

{If {Mergerec ?Data} <> 0 „{Ref Name}{Next data}” \* Solange} meldet 1. If, 2. Mergerec, 3. Ref und 4. Next

Die dynamische Feldstruktur ist die Reihenfolge der Felder während der Auswertung.

Beispiel für dynamische Feldstruktur

{If {Mergerec ?Data} <> 0 „{Ref Name}{Next data}” \* Solange} meldet 1. If, 2. Mergerec, 3. Ref, 4. Next, 5. Mergerec, 6. Ref, 7. Next, 8. Mergerec, 9. Ref, 10. Next, … und so weiter, bis die Schleife beendet ist.

CSV-Dateien bestehen aus Zeilenschaltungen getrennte Datenzeilen, welche durch Komma, Tabulator oder Semikolon () getrennt sind. Die erste Zeile enthält die Spaltenüberschriften (Feldnamen). Jede Zeile muss die gleiche Anzahl Felder haben. Felder, die Feldtrenner oder Zeilenschaltungen oder Anführungszeichen im Inhalt haben, werden von Anführungszeichen umschlossen. Die inhaltlichen Anführungszeichen werden verdoppelt.

Beispiel: Auszug aus der Parameterdatei:

--logfile=!Felder.csv
-mPfad;Feld;Wert
--logfile=!cibmerge_Bausteine_analyse.log
--source-directory=templates
--outputfile=-
--analyse=+Felder.csv
# für jeden Text
--inputfile=Basisbaustein.rtf
-m@
--filter
--inputfile=Bezug.rtf
-m@
--filter
... für jeden RTF-Baustein...
--inputfile=wurzelbaustein.rtf
-m@
--filter
-mdone 

Dieses Beispiel besteht aus mehreren RTF-Bausteinen. Mit dem Parameter --analyse wird die Ausgabe „Felder.csv“ erzeugt. Diese Datei besitzt folgenden Aufbau:

Pfad;Feld;Wert

Eine genauere Beschreibung der Ausgabe ist im Anwendungsbeispiel Bausteine zu finden.

Hinweis:

Wegen der statischen Feldreihenfolge werden Felder in Schleifen nur einmal ausgegeben. Aus dem gleichen Grund werden Felder sowohl aus dem Dann- und Sonst-Zweig einer Wenn/If-Anweisung ausgegeben. Weil der Filter- und nicht der Mischvorgang die Ausgabe erzeugt, werden keine Felder berechnet und darum auch keine eingebetteten Texte (Includetext/Einfügentext) aufgelöst oder deren Felder ausgegeben.

Macht man eine zusammengehängte Feldanalyse über eine ganze Menge von Texten und Bausteinen, dann erhält man auch den Aufrufbaum mit den eingefügten Bausteinen. Mehrfach auftretende gleiche Felder werden auch mehrfach gemeldet. (Zum Beispiel zweimal {Ref Name})

6.5. Parameter --break

[-b]

Der Parameter --break verschiebt den Zeitpunkt, an dem CIB merge im Fehlerfall einen Mischvorgang abbricht.

Syntax

--break=<Abbruchniveau>
<Abbruchniveau>: all, loop, doc, par, never oder ok

Beschreibung

CIB merge bricht in verschiedenen Situationen mit Fehlermeldungen die Verarbeitung ab. Insbesondere bei Mischvorgängen kommt das zum Beispiel vor, wenn eine Variable eingesetzt wird, die nicht definiert ist.

In manchen Situationen ist es aber erwünscht, dass CIB merge nicht bei jedem Fehler sofort abbricht, sondern mit der Verarbeitung, wenn möglich, fortfährt. Dafür wurde in der Version 3.7.62 der Parameter B für break eingeführt.

Um die Stelle im Rohtext oder Textbaustein zu finden, gibt CIB merge nach der Fehlerursache auch die Folgefehler oder Folgesituationen mit aus. (Das entspricht einer Art "stack unrolling".) Dabei schreibt CIB merge noch die schließenden Klammern des Rohtexts, soweit das die Situation zulässt, damit der Text von anderen Anwendungen geöffnet werden kann.

<Abbruchniveau> bestimmt die Stelle, bis zu der fortgefahren oder ab der abgebrochen wird. Folgende Werte sind möglich:

Beispiele

--break=loop

Falls sich der Mischlauf gerade in einer Schleife befindet, wird diese ab dem Fehler nur noch bis zum Ende durchlaufen, also nicht wiederholt. Direkt anschließend wird der Mischvorgang abgebrochen.

--break=never

CIB merge führt ungeachtet aller auftretenden Fehler den Mischauftrag bis zum Ende durch und gibt den Fehlercode des ersten aufgetretenen Fehlers zurück.

Die Verwendung des Parameters mit diesen beiden Beispielbelegungen wird im Anwendungsbeispiel Bausteine veranschaulicht.

Hinweis

Unabhängig von --break=<Abbruchniveau> werden alle bis zum Ende oder Abbruch des Mischauftrags auftretenden Fehler in der Logdatei mit protokolliert.

6.6. Parameter --charformat

Mit --charformat kann angegeben werden, auf welche Felder, deren Ergebnisse keine eigene Formatierung liefern, CIB merge den Schalter \* CHARFORMAT anwenden soll.

Syntax

--charformat=<Option>
<Option>: off/none, auto/automatic oder plain-values-only

Beschreibung

Durch den Parameter --charformat wird festgelegt, bei welchen Feldern das Zeichenformat verändert werden soll, also bei welchen Feldern die Formatierung auf den Feldinhalt übertragen werden soll.

Durch den Parameter --charformat können die meisten der \* CHARFORMAT -Schalter entfallen, wodurch der Rohtext kürzer und lesbarer wird.

Wird bei einem Feld gezielt der Schalter \* NOCHARFORMAT gesetzt, so kann dadurch die Anwendung des Parameters --charformat auf dieses Feld verhindert werden (ab CIB merge Version 3.9.156).

Nicht formatbehaftet sind Feldinhalte aus CSV-Datei, aus Paramterdatei, Datum Felder mit Schalter sind formatbehaftet.

Für <Option> können folgende Werte gesetzt werden:

Beispiel

--charformat=plain-values-only

 Das Ergebnis von

{REF Vorname \* <cib-formfield type="text" info="Vorname" testvalue="Max" />}

erhält bei gesetztem --charformat=plain-values-only die Formatierung des REF Felds (in diesem Fall wird der Text fett geschrieben), obwohl dieses einen Schalter hat.

Die Verwendung des Parameters wird im Anwendungsbeispiel Lückentext veranschaulicht. 

Hinweis

Es gibt zum einen Feldinhalte mit formatbehafteten Werten und zum anderen Feldinhalte mit nicht formatbehafteten Werten.

Formatbehaftete Werte, die als Ergebnisse von Feldern in die Ausgabe kommen, brauchen den Feld-Schalter \* CHARFORMAT nicht, könnten damit aber gleichartig formatiert werden.

Beispiele für Feldinhalte mit Formatierung sind:
{includetext}, eingefügte RTF-Inhalte, {REF} (wenn die Variable formatbehaftet ist).

In diesen Fällen ist es normalerweise nicht sinnvoll den Parameter --charformat anzuwenden. Falls gewünscht. wird der \* CHARFORMAT - Schalter manuell gesetzt.

Werte, die CIB merge aus Feldern berechnet, können im Eingabetext sichtbar vorkommen, völlig neu entstanden sein oder aus der Steuerdatei stammen.
Beispiele für sichtbare Werte sind IF-Felder, deren Text aus einer der Alternativen genau so kommt, wie es im Feld steht oder mit SET belegte Werte. Sichtbare Werte sind formatbehaftet und nicht vom Parameter betroffen.
Durch Anwendung des Schalters \*NOFORMAT im SET-Befehl kann dieser Wert zum nicht formatbehafteten Wert gemacht werden (ab CIB merge Version 3.9.174).

Nicht formatbehaftete Werte erscheinen standardmäßig in der Standardschriftart (Times Roman, Schriftgröße 10). Sie werden vom Parameter --charformat pauschal formatiert als hätte man jedesmal den Schalter /* CHARFORMAT angegeben.

Beispiele für Feldinhalte ohne Formatierung: {MERGEREC}, {date}, {=…}, Werte aus CSV, {REF} (wenn die Variable nicht formatbehaftet ist),.

In diesen Feldern kann bei gesetztem --charformat auf die \* CHARFORMAT - Schalter verzichtet werden.

Beispiele für erzeugte Werte sind Aktualdat oder die Ausdrucksberechnung mit „=“. Diese Werte sind nicht formatbehaftet und deshalb vom Parameter betroffen, wenn sie in der Ausgabe erscheinen.

Außerdem braucht der Schalter nicht angewendet zu werden, wenn bereits ein anderer Schalter die Formatierung verändert, zum Beispiel \@ „tt.MM.jj“. Hier wird die Formatierung der Maske verwendet und nicht das Zeichenformat. Auch für übergeordnete Felder gilt das. Ein IF-Feld mit \* CHARFORMAT braucht den Inhalt aus dem THEN- oder ELSE-Teil nicht mehr formatiert zu behandeln. Ein in einem der beiden Teile enthaltenes Feld wird sowieso mit dem Zeichenformat formatiert.

6.7. Parameter --chart-…

Allgemein

Die --chart-Parameter ermöglichen das Erzeugen und Einfügen dynamischer Geschäftsgrafiken. CIB merge kann in diesem Fall die Grafikanweisung im Text belassen oder sie durch die aktualisierte Grafik ersetzen. CIB merge aktualisiert (überschreibt) die ursprüngliche Datei automatisch und entfernt die binären Grafikdaten aus dem Ergebnis, wenn die Grafikanweisung erhalten bleibt. Sonst bleibt die Datei unverändert erhalten und nur das Ergebnis wird anstatt der Anweisung in die RTF-Ausgabe eingebettet.

Außerdem besteht auch die Möglichkeit Grafik-Daten aus Nicht-Chart-Grafiken aus einer Datei ins RTF einzubetten. Dabei werden folgende Bildformate unterstützt: BMP bzw. DIB, EMF (Chart- und Nicht-Chart-Grafiken), PNG, JPG und WMF.

Es stehen folgende Parameter zur Verfügung:

Parameter --chart-output-format

CIB merge kann alle im CIB chart designer angebotenen Grafikformate als Ergebnis liefern. Soll die Grafikanweisung im Text belassen werden, kann entweder pauschal für alle Felder “--keep-fields” gesetzt werden oder in ausgewählten Grafikanweisungen der Schalter “\* lassen” eingefügt werden.

Der Parameter --chart-output-format bestimmt das Ausgabeformat der Grafik.

Syntax:

--chart-output-format=<Bildformat>

<Bildformat>: ccr (CIB chart resources), emf (Enhanced Metafile), oder emfccr (Enhanced Metafile erweitert um CIB chart resources (eingebettet))

Parameter --chart-source

Mit --chart-source wird angegeben, ob die Grafik aus den eingebetteten Daten, oder, im Falle einer Einfügengrafik-Anweisung, für den Inhalt der angegebenen Datei oder nie berechnet werden soll. ({\pict} nicht berechnen).

 Syntax:

--chart-source=<Option>
<Option>: 
auto, file/datei, none/ignore/ignorieren/kein/keine oder
document/dokument/embed/embedded/einbetten/eingebettet

Beschreibung

Für die Grafikquelle sind folgende Einstellungen für <Option> möglich:

Parameter --chart-target

Der Parameter --chart-target bestimmt, wohin die Ausgabe der aktualisierten Grafikdaten geschrieben werden soll: in

das Dokument eingebettet oder über den alten Inhalt der angegebenen Datei.

Syntax:

--chart-target=<Option>
<Option>:
auto, file/datei, none/ignore/ignorieren/kein/keine oder
document/dokument/embed/embedded/einbetten/eingebettet 

Beschreibung:

Für das Grafikziel sind folgende Einstellungen für <Option> möglich:

Ist keine Chart-Library verfügbar, werden Chart-Grafiken wie normale Grafiken behandelt.

Durch Setzen des Parameters --chart-target=embed werden, wenn --chart-source nicht „embed“ ist, die Bilddaten von EMF, JPG (JPEG), PNG, WMF und BMP bzw. DIP Grafikdateien in das Ergebnis-RTF eingebettet. Die Art des Dateiformats wird durch den Dateiinhalt, nicht durch den Suffix, bestimmt.

Beispiel:

--chart-source=file
--chart-target=embed

Die Grafikdaten stammen hier aus einer Datei. Alle Grafiken (Chart- und Nicht-Chart-Grafiken) sollen in das Ergebnis-RTF eingebettet werden.

Die Parameter werden im Anwendungsbeispiel Bausteine veranschaulicht.

Eine Übersicht liefert folgende Tabelle:

(1) „Keep“ - Schalter nicht gesetzt

(2) „Keep“ - Schalter gesetzt

(3) Daten konnten nicht aus der Datei gelesen werden

(4) Daten konnten aus der Datei gelesen werden

6.8. Parameter --codepage

[-p]

Der Parameter --codepage steuert den aktuell benutzten Zeichensatz für die Steuerdatei (Zur Steuerdatei siehe Parameter --datafile bzw. --headerfile).  

Syntax

--codepage=<Zeichensatz>
<Zeichensatz>: pca, pc, utf-8 oder ansi

Beschreibung

Wenn der Parameter --codepage nicht angegeben ist und somit kein Zeichensatz für die Steuerdatei definiert ist, gilt als Default die Deklaration in der RTF Eingabedatei (z.B. \rtf1\ansi). Als Zeichensätze sind pca, pc, utf-8 oder ansi zulässig.

Beispiele

--codepage=pca

Hier wird in den CSV-Dateien ein anderer Zeichensatz verwendet (hier pca). Das muss über den Parameter --codepage angegeben werden.

Die Verwendung des Parameters wird im Anwendungsbeispiel Lückentext veranschaulicht.

Hinweis:

Für die RTF-Bausteine wird immer die in der RTF Eingabedatei spezifizierte Codepage benutzt.

Siehe auch die Hinweise zu UTF-8 codierten Datendateien im Kapitel „Hinweise zu UTF-8 kodierten Daten-CSVs“.

6.9. Parameter --colors

Mit dem Parameter --colors können Optimierungen, die für Farbtabellen im Kopf des RTF-Dokuments durchgeführt werden, wahlweise abgeschaltet werden.

Syntax

--colors=<Option>
<Option>: keep, expand, optimize oder minimal

Beschreibung

Jedes RTF-Dokument enthält im Kopf Farbtabellen. Dafür muss CIB merge Zeit für den Abgleich wegen Einfügungen oder zur Optimierung aufwenden. Dieser Abgleich oder diese Optimierungen interessieren aber nicht jeden Anwender. Daher sind sie wahlweise mit dem Parameter --colors abschaltbar.

Mögliche Werte für <Option> sind:

Beispiel

--colors=expand

Neue Farben, die in RTF-Bausteinen verwendet werden, werden in die Farbtabelle aufgenommen und unbenutzte Farben werden nicht entfernt. Somit findet keine Optimierung statt.

Die Verwendung des Parameters wird im Anwendungsbeispiel Bausteine veranschaulicht.

6.10. Parameter --compress

[-z]

Ist der Parameter --compress gesetzt, komprimiert CIB merge die Ausgabe-Datei nach zlib-Verfahren.

Syntax

--compress=<Komprimierungsgrad>
<Komprimierungsgrad>: 1-9

Beschreibung

Wird der Parameter --compress zur Komprimierung eingesetzt, müssen die Prioritäten zwischen der Optimierungszeit und dem Ergebnis für den gewünschten Einsatz abgewägt werden. Mit mehr Zeitaufwand entstehen sehr kleine Ergebnisse, eine möglichst schnelle Komprimierung erreicht dagegen ein durchaus kleines, aber nicht das minimale Ergebnis.

Dem Parameter --compress kann deshalb vom Anwender ein ganzzahliger Wert von 1 bis 9 übergeben werden. Der Defaultwert ist 6.

Beispiele

--compress
CIB merge komprimiert mit dem Default-Komprimierungsgrad 6.
--inputfile=Optimierung_in.rtf
--outputfile=!Optimierung_out.rtf
--compress=9

Die Datei wird so stark wie möglich komprimiert. Daraus ergibt sich eine kleinere Dateigröße, dafür aber eine etwas erhöhte Zeitdauer für diesen Mischvorgang.

Die Verwendung dieses Parameters wird zusammen mit anderen Optimierungs-Parametern im Anwendungsbeispiel Lückentext veranschaulicht.

6.11. Parameter --datafile

[--data/-d]

Mit dem Parameter --datafile wird die Datenquelle angegeben.

Syntax

--datafile=<Dateiname>

Beschreibung

Als Datenquelle kann sowohl eine Datei im CSV- als auch im XML-Format angegeben werden.

Sind die Daten auf mehrere Datendateien verteilt, so ist hier die Multisteuerdatei anzugeben und zusätzlich der Parameter --multidatafile zu setzen.

Beispiele

Single-CSV über Parameterdatei

--datafile=Adresse.csv

Die Daten befinden sich in einer einzigen Datenquelle namens Adresse.csv.

Diese Art der Verwendung des Parameters wird im Anwendungsbeispiel Lückentext veranschaulicht.

Multi-CSV über Parameterdatei

--datafile=multi.csv
--multidatafile

Die Daten sind auf mehrere Datendateien verteilt, die in der Datei multi.csv angegeben werden. Um zu definieren, dass es sich um eine Multi-CSV handelt, muss zusätzlich der Parameter --multidatafile gesetzt werden.

Diese Art der Verwendung des Parameters wird im Anwendungsbeispiel Serienbrief veranschaulicht. 

Ist außerdem der Parameter --target-directory gesetzt, werden die multi.csv und alle weiteren Datendateien in diesem Verzeichnis erwartet:

--target-directory=csv

Im Anwendungsbeispiel Bausteine wird --datafile zusammen mit --target-directory verwendet.

Multi-XML über Parameterdatei

--headerfile=XML:Daten_mitAlias.xml
--datafile=/root/multi
--multidatafile

Der Parameter --datafile gibt hier den XPath zu den Multiknoten an.

Dieser Zusammenhang wird im Anwendungsbeispiel Serienbrief verdeutlicht.

Hinweis:

Die erste Zeile der Datensatzquelle beinhaltet den sog. Steuersatz, der aus durch ";" getrennten Feldnamen besteht. Dieser Steuersatz kann auch in einer getrennten Steuersatzquelle bereitgestelt werden, die mit dem Parameter --headerfile gesetzt wird.

6.12. Parameter --default-mode

[--defaultmodus/--default-modus]

Der Parameter --default-mode stellt einen Mechanismus bereit, um für jede Variable einen Ersatzwert (Default) zu bestimmen, falls die Variable undefiniert bzw. leer ist.

Syntax

--default -mode=<Value>
<Value>: -/off/aus/no/none/kein/keiner/nein, undefiniert/undefined/+, leer/empty oder beides/alles/both/all/voll/full

Beschreibung

Der Parameter --default-mode ist nur in Kombination mit dem Parameter --default-prefix zu verwenden. Dieser definiert den Prefix, der vor einen Variablennamen gestellt wird. Beim Auswerten des REF-Feldes wird festgestellt, ob der Wert ein Kandidat für das Default-Verhalten ist, sonst wird der Wert oder ein Fehler ausgegeben. Das Default-Verhalten tritt bei folgenden Bedingungen ein:

• „Variable ist undefiniert und Verhalten entsprechend gewählt“ oder „Variable ist definiert und leer und Verhalten entsprechend gewählt“. Trifft eine der Bedingungen zu, so setzt sich der Variablenname aus dem Default-Präfix und dem alten Namen zusammen. Ist so ein Default wiederum nicht gesetzt, gibt es noch einen für alle gemeinsam. Erst wenn auch der nicht existiert, wird der übliche Fehler gemeldet, dass eine Variable nicht definiert ist. Es ist möglich zwischen 'kein Default', 'Default für Leer', 'Default für undefiniert' und 'Default für beides' zu wählen. Der Standard ist „kein Default“.

Mögliche Werte für <Value> sind:

Beispiel

--default-mode=all

Es wird nach einem passenden Default-Wert gesucht, wenn eine Variable leer oder undefiniert ist.

Die Verwendung des Parameters wird im Anwendungsbeispiel Lückentext veranschaulicht.

6.13. Parameter --default-prefix

Der Parameter definiert ein Präfix für Variablen, d.h. er stellt dem Variablennamen ein Präfix voran.

Syntax

--default-prefix=<prefix>

Beschreibung:

Mit dem Parameter --default-prefix kann somit einer Variablen ein Ersatzwert (Default) zugewiesen werden. Als gemeinsamer Default gilt die Variable, die genau so heißt wie das Default-Präfix. Die Standardvorbelegung ist „Default.“. Dieser Parameter ist in Kombination mit dem Parameter --default-mode anzugeben.

Beispiel 1

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

Hier wird nach einem Default-Wert gesucht, wenn eine Variable nicht durch die Datenversorgung gefüllt werden kann, weil die Variable nicht existiert oder leer ist. Um den Default-Wert zu ermitteln, wird der Variablen das Präfix „Default.“ vorangestellt.

Die Verwendung des Parameters wird im Anwendungsbeispiel Lückentext veranschaulicht.

Beispiel 2

--default-mode=undefined
--default-prefix=Default.

Variablen-Belegung: A=Anton, B=Berta, C=, Default.B=Bruno, Default.C=Cäsar, Default.D=Dora, Default.=Mama

Der Default-Modus definiert für undefinierte Variablen das Präfix „Default.“. Die Variablen liefern folgende Werte:

REF A liefert Anton

REF B liefert Berta

REF C liefert „“

REF D liefert Dora

REF E liefert Mama, weil Default.E nicht definiert ist. Wäre„Default.“ nicht belegt, gäbe es hier einen Fehler mit der Meldung, dass E nicht belegt ist).

Ist der Default-Modus auf all oder empty gesetzt (--default-mode=all/--default-mode=empty) so liefert die Auswertung für REF C Cäsar.

REF D liefert mit einem Default-Mode off (--default-mode=off) oder empty (--default-mode=empty) einen Fehler.

6.14. Parameter --delimiter

[-t]

Der Parameter --delimiter definiert ein anderes Trennzeichen für die Steuerdateien. Das Standardtrennzeichen für die Steuerdateien ist ";".

Syntax

--delimiter=<Trennzeichen>

Beispiel

--delimiter=,

CIB merge interpretiert jetzt das Komma-Zeichen statt dem Semikolon als Trennzeichen.

Die Verwendung des Parameters wird im Anwendungsbeispiel Lückentext veranschaulicht.

6.15. Parameter --destination-colorschememapping

(ab CIB merge Version 3.12.2)

Über diesen Parameter kann gesteuert werden, ob das \*\colorschememapping in die Ausgabedatei übernommen wird.

Syntax

--destination-colorschememapping=<Option>
<Option>:
keep, remove oder merge

Beschreibung

Als <Option> sind folgende Werte möglich:

6.16. Parameter --destination-datastore

(ab CIB merge Version 3.12.2)

Über diesen Parameter kann gesteuert werden, ob das \*\datastore in die Ausgabedatei übernommen wird.

Syntax

--destination-datastore=<Option>
<Option>: keep, remove oder merge

Beschreibung

Als <Option> sind folgende Werte möglich:

6.17. Parameter --destination-themedata

(ab CIB merge Version 3.12.2)

Über diesen Parameter kann gesteuert werden, ob das \*\themedata in die Ausgabedatei übernommen wird.

Syntax

--destination-themedata=<Option>
<Option>:
keep, remove oder merge

Beschreibung

Als <Option> sind folgende Werte möglich:

6.18. Parameter --dialog

[-x]

Der Parameter --dialog zeigt während des Mischvorganges einen Prozentbalken am Bildschirm an (nichtmodale Dialogmaske). Über diese Maske kann mit Hilfe des Abbrechen-Buttons der Mischlauf gestoppt werden.

In Ausnahmefällen wird die Fortschrittsanzeige vom System nicht im Vordergrund gestartet. Mit dem Schalter top setzt sich die Fortschrittsanzeige beim Start explizit in den Vordergrund.

Syntax

--dialog

Beispiel

--dialog=top

Die Fortschrittsanzeige setzt sich beim Start des Mischvorgangs in den Vordergrund.



Im Anwendungsbeispiel Serienbrief wird die Fortschrittsanzeige verwendet, um eine Endlosschleife abzubrechen.

6.19. Parameter --directory-…

Die directory-Parameter ermöglichen eine dateilose Dateneingabe. Dies geschieht über Einträge (virtuelle Dateien) in virtuellen Verzeichnissen.

Es stehen folgende Parameter zur Verfügung:       

6.20. Parameter --directory-set-inline

Der Parameter --directory-set-inline ermöglicht eine dateilose Dateneingabe mit der Parameterdatei.

Syntax

--directory-set-inline=<virtueller Dateiname>
VAR1;VAR2
VALUE1;VALUE2
VALUE3;VALUE4
…
end-of-file

Beschreibung

Der Parameter --directory-set-inline liest die Zeilen der Parameterdatei bis zur Endezeile (end-of-file). Das heisst, alle Zeilen, die zwischen --directory-set-inline und end-of-file stehen werden als Inhalt von <virtueller Dateiname> interpretiert. Der Inhalt wird im virtuellen Verzeichnis unter <virtueller Dateiname> eingetragen. Existiert bereits ein Inhalt, so wird dieser überschrieben.

Beispiel

Ausschnitt aus einer Parameterdatei mit dateiloser Dateneingabe:

--datafile=daten.csv
--directory-set-inline=daten.csv
Var1;Var2;Var3
Wert1.1;Wert1.2;Wert1.3
Wert2.1;Wert2.2;Wert2.3
end-of-file

Der Parameter --directory-set-inline=daten.csv zeigt die dateilose Dateneingabe an. Die folgenden Zeilen werden eingelesen bis zur Zeile „end-of-file“ und bilden somit den Inhalt der virtuellen Datei mit dem Namen daten.csv.

6.21. Parameter --directory-log

Der Parameter --directory-log schreibt den Inhalt einer virtuellen Datei mit der Beginn- und Endezeile in die Fehlerausgabe.

Die Beginnzeile ist --directory-set-inline.

Die Endezeile ist „end-of-file“.

Syntax

--directory-log=<virtueller Dateiname>

Beispiel

--logfile=!merge.log
--datafile=daten.csv
--directory-set-inline=daten.csv
var1;var2;var3
1.1;1.2;1.3
2.1;2.2;2.3
3.1;3.2;3.3
end-of-file
--inputfile=directory-set-inline.rtf
--directory-log=daten.csv

Der Inhalt sowie die Beginn- und Endzeile werden in das Logfile geschrieben. Der Inhalt der Logdatei merge.log sieht wie folgt aus:

--directory-set-inline=daten.csv
var1;var2;var3
1.1;1.2;1.3
2.1;2.2;2.3
3.1;3.2;3.3
end-of-file

6.22. Parameter --directory-read

Der Parameter --directory-read legt im virtuellen Verzeichnis den Inhalt einer Datei ab. Dabei wird ggfs. der bereits existierende Inhalt überschrieben.
Dieser Parameter wird auch für den Merge-Recombine verwendet. (ab CIB merge Version 3.9.181)

Syntax

--directory-read=<Dateiname>

oder

--directory-read=<virtueller Dateiname>=<Dateiname>

oder (ab CIB merge Version 3.9.181)

--directory-read=cibrec-snippetN.rtf=<Dateiname>
N=0,1,2….

Beschreibung

Für <Dateiname> sind alle Angaben möglich, die auch mit dem Parameter --inputfile erlaubt sind.  Die Kurzschreibweise für den Parameter lautet --directory-read=<Dateiname>, wobei der <Dateiname> auch als <virtueller Dateiname> verwendet wird.

Hinweis: Enthält der <Dateiname> die Zeichen „+“ „-“ „!“, so werden diese als Schalter interpretiert und nicht als Bestandteil des Dateinamens angesehen.

Etwa angegebene Schalter +/-/! usw. werden nicht in den Namen übernommen.

Merge-Recombine (ab CIB merge Version 3.9.181):
Die CIB viewer (CIB view&rec und CIB jview&rec2) bieten die Möglichkeit, in CIB REC-Feldern Textpassagen zu erfassen bzw. zu editieren. Diese Textpassagen werden von den CIB viewern in sogenannten RTF-Snippet-Dateien abgelegt. Nach Abschluss des Editiervorgangs eines Dokuments werden durch den CIB merge die RTF-Snippets in das Dokument eingemischt und als neues Ausgabe-RTF gespeichert.
Die Übergabe der Snippet-Dateien an den CIB merge erfolgt durch den Parameter „--directory-read=cibrec-snippetN.rtf=<Dateiname>“, falls sich die Dateien auf Platte befinden.

Beispiel

--directory-read=inNeu.log=in.log
--directory-write=inNeu.log=!out.log

Der Parameter --directory-read legt den Inhalt der Datei in.log in die virtuelle Datei inNeu.log ab. Im nächsten Schritt wird die virtuelle Datei mit dem Namen inNeu.log genommen und der Inhalt in out.log geschrieben.

6.23. Parameter --directory-remove

Der Parameter --directory-remove entfernt den angegebenen Eintrag aus dem virtuellen Verzeichnis, oder alle Einträge, wenn kein Name angegeben wird.

Syntax

--directory-remove

oder

--directory-remove=<virtueller Dateiname>

Beispiel

--directory-remove=name

Der Eintrag „name” wird aus dem Verzeichnis entfernt.

--directory-remove

Alle Einträge werden aus dem Verzeichnis entfernt.

6.24. Parameter --directory-set

Der Befehl --directory-set=<virtueller Dateiname> definiert eine virtuelle Datei unter <virtueller Dateiname> und ist im Arbeitsspeicher von CIB merge abgelegt. Eine sinnvolle Anwendung ist zum Beispiel CSV-Daten dateilos zu übergeben. Für eine Übergabe in einer Parameterdatei ist der Aufrufparameter --directory-set-inline.zu verwenden.
Dieser Parameter wird auch für den Merge-Recombine verwendet. (ab CIB merge Version 3.9.181)

Syntax

--directory-set=<virtueller Dateiname>

oder (ab CIB merge Version 3.9.181)

--directory-set=cibrec-snippetN.rtf={\rtf1 ...}
N=0,1,2….

Beschreibung

Merge-Recombine (ab CIB merge Version 3.9.181):
Die CIB viewer (CIB view&rec und CIB jview&rec2) bieten die Möglichkeit, in CIB REC-Feldern Textpassagen zu erfassen bzw. zu editieren. Diese Textpassagen werden von den CIB viewern in sogenannten RTF-Snippets abgelegt. Nach Abschluss des Editiervorgangs eines Dokuments werden durch den CIB merge die RTF-Snippets in das Dokument eingemischt und als neues Ausgabe-RTF gespeichert.
Die Übergabe der Snippet-Dateien an den CIB merge erfolgt durch den Parameter „--directory-set=cibrec-snippetN.rtf={\rtf1 ...}“, falls die Übergabe im Speicher erfolgt.

6.25. Parameter --directory-write

Der Befehl --directory-write=<virtueller Dateiname>=<Dateiname> schreibt den Inhalt von <virtueller Dateiname> aus dem virtuellen Verzeichnis in die Datei <Dateiname>. Etwa angegebene Schalter +/-/! usw. werden nicht in den Namen übernommen.

Syntax

--directory-write=<virtueller Dateiname>=<Dateiname>

Beispiele

--directory-set=out=out.log
--directory-write=out.log=!out.log

Die virtuelle Datei mit dem Namen out.log wird genommen und der Inhalt in out.log geschrieben

• Gegenüberstellung: dateibehaftete und dateilose Dateneingabe

Ausgehend von einem klassischen dateibehafteten Beispiel werden Alternativen mit den eben genannten Mitteln vorgestellt.

Die Ausgabe des RTF kann dateilos mit in anderen Dokumenten beschriebenen Mitteln erfolgen und wird hier nicht erwähnt!

• Java Mischauftrag (Merge-Job) und Abholung des Fehlertextes und der Fehlernummer

Dateneingabe mit Datei:

Die daten.csv soll in die Eingabe input.rtf gemischt werden. Die Ausgabe heißt output.rtf. Fehler kommen in merge.log. Alle Dateien befinden sich im Dateisystem unter Verzeichnis test. 

JCibMergeJob t_Job = new JCibMergeJob();
t_Job.initialize();
t_Job.setProperty(ICibMergeJob.PROPERTY_WORKSPACE, "test\\");
t_Job.setProperty(ICibMergeJob.PROPERTY_ERRORFILE, "merge.log");
t_Job.setProperty(ICibMergeJob.PROPERTY_DATAFILE, "daten.csv");
t_Job.setProperty(ICibMergeJob.PROPERTY_INPUTFILE, "input.rtf");
t_Job.setProperty(ICibMergeJob.PROPERTY_OUTPUTFILE, "output.rtf");
t_Job.execute();
int error =
((Integer)t_Job.getProperty(ICibMergeJob.PROPERTY_ERROR)).intValue();
if(error > 0)
{
String errortext = (String)t_Job.getProperty(ICibMergeJob.PROPERTY_ERRORTEXT);
}

Dateneingabe ohne Datei:

Nur daten.csv soll im ersten Schritt dateilos übergeben werden. Der Inhalt sei in der String Variable csv_data. Hierfür wird folgende zusätzliche Property gesetzt. (Der Rest bleibt unverändert)

t_Job.setProperty(ICibMergeJob.PROPERTY_DICTIONARY_SET, "daten.csv=" + csv_data);

• Mischauftrag über Parameterdatei (Java, C++ oder COModSuite)

Dateneingabe mit Datei:

Inhalt der Datei merge.par:

-L!merge.log
-V
-Ddaten.csv
-Iinput.rtf
-O!output.rtf
-M@
-@1
-MEnde

Logdatei bestimmen

Version melden

Daten-, Ein- und Ausgabedateien bestimmen

Dateinamen melden

Einzeldokument mischen

Rufen Sie „cibmrg32.exe -@merge.par“ auf, um den Auftrag zu starten.

Dateneingabe ohne Datei:

Analog zum Fall in Java ist das in der Parameterdatei auch möglich:

Die Parameterdatei merge.par muss um folgende Angabe ergänzt werden (Rest bleibt unverändert)

--dictionary-set-inline=daten.csv
Var1;Var2;Var3…
Wert1.1;Wert1.2;Wert1.3…
Wert2.1;Wert2.2;Wert2.3…
…
end-of-file

• Auftrag aus C++

Dateneingabe mit Datei:

const char *const arguments[]=
{     
      „cibmerge“, 
      „-L!merge.log“, 
      „-Ddaten.csv“, 
      „-Iinput.rtf“, 
      „-O!output.rtf“,
      0
};
cibmerge(sizeof(arguments)/sizeof(*arguments) – 1, arguments);

Dateneingabe ohne Datei:

Hier werden die Daten in Stringkonstanten übergeben. Eine bessere Möglichkeit wäre es, sie über stringstreams der STL dynamisch zusammenzustellen:

Die Argumente müssen um folgende Angabe erweitert werden (Rest bleibt unverändert):

       „--dictionary-set=daten.csv\n“
       „Var1;Var2;Var3…\n“
       „Wert1.1;Wert1.2;Wert1.3…\n“
       „Wert2.1;Wert2.2;Wert2.3…\n“
       „…\n“

6.26. Parameter --docproperty

(ab CIB merge Version 3.9.181)

Durch diesen Parameter können Dokument-Eigenschaften gesetzt und eingemischt werden.

Syntax

-- docproperty=[key]=[value]

Beschreibung

Durch den Parameter--docproperty ist es dem Anwender möglich, die Dokument-Eigenschaften des Ausgabedokumentes zu definieren.

Es werden sowohl die vordefinierten Werte (Autor, Titel, usw.), als auch selbstdefinierte Dokument-Eigenschaften unterstützt.

Die Einsatzmöglichkeiten sind z.B.:

1. Einfache und zentrale Sicherstellung der Dokumenteigenschaften der Ausgabedokumente, bevor diese in das Kundenumfeld gelangen (einheitlicher Autor für alle ausgehenden Dokumente).
2. Nutzung der Dokumenteigenschaften zum Transport von Zusatzinformationen

6.27. Parameter --encrypt

[-y]

Der Parameter --encrypt erzeugt ein kryptisiertes Ausgabeformat, das von weiteren CIB-Komponenten (beispielsweise CIB format/output) weiterverarbeitet werden kann.

Syntax

--encrypt

Beschreibung

Die Verschlüsselung, die der Parameter --encrypt anwendet, basiert auf einem CIB-eigenen CC9-Algorithmus. Dieser soll „Unlesbarkeit“ der Bausteine bzw. Zwischenergebnisse ermöglichen und somit eine „unmittelbare“ inhaltliche Manipulation verhindern.

Die verschlüsselte Datei kann mit MS-Office Versionen nicht geöffnet werden.

Beispiel

--encrypt

Die Ausgabedatei liegt hier verschlüsselt vor.

Der Parameter wird im Anwendungsbeispiel Lückentext verwendet

6.28. Parameter --field-nesting-level-limit

(ab CIB merge 3.12.10)

Über den Parameter --field-nesting-level-limit kann die Schachtelungstiefe von Feldbefehlen beschränkt werden.

Syntax

--field-nesting-level-limit=number

number=Zahl zwischen 0 und n

Beschreibung

Über den Parameter --field-nesting-level-limit kann die Schachtelungstiefe von Feldbefehlen beschränkt werden.

Default-Wert ist „0“, d.h. die Schachtelungstiefe ist nicht beschränkt.

Bei Werten größer 0 bricht der CIB merge mit Fehler 810 ab, wenn diese Schachtelungstiefe erreicht ist.

Achtung: Der Parameter ist nur beim Merge-Template-Combine wirksam!

Beispiel

--field-nesting-level-limit=10

CIB merge bricht mit Fehler 810 ab, wenn eine Schachtelungstiefe von 10 erreicht ist.

6.29. Parameter --field-results

[-r / -rp]

Über den Parameter --field-results kann gesteuert werden, ob im Rich Text Format alle Field-Results entfernt und damit die Größe der Ausgabedatei reduziert wird.

Syntax

--field-results

oder

--field-results=p

Oder (ab CIB merge 3.9.183)

--field-results= Keepswitch

Beschreibung

MS Word erzeugt Field-Results im RTF. Diese Einträge werden von den CIB office Modulen in den meisten Fällen nicht benötigt. Der Parameter --field-results entfernt diese Einträge.

Für bestimmte Grafikobjekte benötigt CIB format in Einzelfällen (z.B. Grafik über Text positionieren) bestimmte Teile der Field-Results zur Positionierung und Skalierung. Der Schalter p "print" (kurz: -rp) veranlasst CIB merge, diese Daten zu erhalten. Zusätzlich werden weitere Einträge aus dem RTF entfernt, die im Falle einer Weiterverarbeitung mit CIB format nicht benötigt werden. Im Zweifelsfall sollte --field-results=p eingesetzt werden, da die Ausgabedateigröße gegenüber --field-results nur geringfügig steigt und CIB format sicher alle benötigten Informationen zur Verfügung stehen.

--field-results wird im Regelfall zur Optimierung der Dateigröße eines RTF-Projekts vor Test und Auslieferung eingesetzt. Vom CIB Support erhalten Sie auf Anfrage ausführliche Informationen zur Optimierung von RTF-Projekten.

Keepswitch (ab CIB merge 3.9.183):
Es gibt Anwendungsfälle, bei denen die Datenversorgung eines Dokuments über mehrere Mischläufe erfolgen muss, weil zum Zeitpunkt des ersten Laufs noch nicht alle Informationen vorhanden sind. Dann müssen die Feldinhalte der vorhergehenden Mischläufe für die nachfolgenden erhalten bleiben.
Der Parameter „keepswitch“ greift bei Variablen (REF-Felder) im Eingabe-Dokument des CIB merge, die mit einem KEEP/LASSEN-Schalter versehen sind. Gibt es für diese Variablen keine Datenversorgung, so wird bei Ihnen ein vorhandenes Feldergebnis beibehalten.

Beispiel

--inputfile=wurzelbaustein.rtf
--outputfile=!..\result\wurzelbaustein_FieldResults.rtf
--field-results=p
--filter=f

CIB merge mischt keine Feldinhalte ein (--filter=f), entfernt alle Field-Results, die für CIB format keine Bedeutung haben (--field-results=p) und schreibt entsprechend die Ausgabedatei.

Die Verwendung dieses Parameters wird im Anwendungsbeispiel Bausteine veranschaulicht.

Hinweis:

Mit --field-results erzeugte RTF-Dateien sollten nicht mehr mit MS Word bearbeitet werden. Dokumente mit skalierten oder über den Text positionierten Grafiken können in MS Word nicht mehr korrekt angezeigt und bearbeitet werden. Beim Speichern mit MS Word geht außerdem der Vorteil der verkleinerten Dateigröße wieder verloren.

Die Dateigröße der Ausgabedatei kann durch die CIBrtf-Ausgabe mit --short-tokens und eine komprimierte Ausgabe mit --compress zusätzlich verringert werden.

6.30. Parameter --filter

[-f / -ff]

Mit dem Parameter --filter wertet CIB merge die Feldinhalte nicht aus, sondern liest nur die Eingabedatei und schreibt nach den gesetzten Parametern die Ausgabedatei.

Syntax

--filter

oder

--filter=f

Beschreibung

Mit --filter werden die Feldinhalte nicht ausgewertet, aber geparst und übersetzt. Dies kann mit dem Schalter f = "fast" verhindert werden. --filter=f filtert also schneller (ohne Syntaxprüfung des RTF-Stromes), --filter kann dafür Fehler in den Feldern eher entdecken.

--filter=f (oder auch –ff) wird meistens zur Optimierung oder Verschlüsselung von RTF-Projekten vor Test und Auslieferung eingesetzt, siehe Kapitel Übersicht: Optimierung, Verschlüsselung und Komprimierung und Parameter --field-results. 

Beispiel

--inputfile=Optimierung_in.rtf
--outputfile=!Optimierung_out.rtf
--optimize
--short-tokens
--compress=9
--filter=f

Hier werden einige Optimierungen (siehe jeweiliger Parameter) durchgeführt und dabei keine Feldinhalte eingemischt.

Die Verwendung dieses Parameters zusammen mit Optimierungs-Parametern wird im Anwendungsbeispiel Lückentext veranschaulicht.

Im Anwendungsbeispiel Bausteine wird der Parameter zusammen mit --field-results verwendet.

6.31. Parameter --fonts

Mit dem Parameter --fonts können Optimierungen, die für Schriftartentabellen im Kopf des RTF-Dokuments durchgeführt werden, wahlweise abgeschaltet werden.

Syntax

--fonts=<Option>
<Option>: keep, optimize, expand oder adjust

Beschreibung

Jedes RTF-Dokument enthält im Kopf Schriftartentabellen. Dafür muss CIB merge Zeit für den Abgleich wegen Einfügungen oder zur Optimierung aufwenden. Mit dem Parameter --fonts können diese Optimierungen wahlweise abgeschaltet werden. Der Standard ist adjust. Das bezieht sich auch auf den gesamten Kopf.

Für <Option> sind folgende Werte möglich:

Beispiel

--fonts=keep

Obwohl eingefügte Textbausteine zusätzliche Schriften enthalten, werden diese nicht in die Haupt-Schriftartentabelle aufgenommen. Unbenutzte Schriftarten werden nicht entfernt. Dies ist zum Beispiel dann sinnvoll, wenn ein Dokument gedruckt werden soll, der Drucker aber nicht alle verwendeten Schriftarten kennt.

Die Verwendung des Parameters wird im Anwendungsbeispiel Bausteine veranschaulicht.

6.32. Parameter --headerfile

[--header/-h]

Der Parameter --headerfile kann bei der Datenversorgung mit XML eingesetzt werden. Er zeigt auf die gesetzte Datendatei.

Syntax

--headerfile=<Kopfsatzdatenquelle>

Beschreibung

Wird --headerfile in Kombination mit dem Parameter --multidatafile verwendet, so gibt --datafile den XPath zu den Multiknoten an. Eine Verwendung des Parameters mit einer CSV-Datenversorgung wird nicht empfohlen.

Beispiel Multisteuerdaten aus XML

--headerfile=XML:Daten_mitAlias.xml
--datafile=/root/multi
--multidatafile
XML-Datei:
<root>
       <multi>
       <Kunden>XML:$(this);/root/data/Kunden/Kunde</Kunden>
       <Einzelposten>XML:$(this);/root/data/Posten/Einzelposten</Einzelposten>
              </multi>
              <data>
                   <Kunden>                  
                       <Kunde>
                         <Vorname>Franz</Vorname>                  
                         <Name>Meier</Name>
                         <Strasse>Teststr. 4</Strasse>
                         <PLZ>12345</PLZ>                  
                         <Ort>Musterdorf</Ort>
                         <Geschlecht>M</Geschlecht>
                         <KundenNr>9898989</KundenNr>                  
                         <AuftragsNr>111111-2</AuftragsNr>
                         <Betrag>999</Betrag>
                       </Kunde>
                       weitere Kunden ......
                    </Kunden>
             <Posten>
                  <Einzelposten>
                  <KundeAuftragsNr>111111-2</KundeAuftragsNr>                  
                  <Bezeichnung>Artikel1</Bezeichnung>
                  <Betrag>999</Betrag>                  
        </Einzelposten>
                   weitere Einzelposten....
             </Posten>
              </data>
 </root>
    

Die Multi-Knoten befinden sich in der Datei Daten_mitAlias.xml. Die Aliasnamen ergeben sich aus dem Knotennamen(Kunden, Einzelposten), die mit dem angegebenden XPath definiert sind. Die Aliasdefinitionen sind die Knoteninhalte (XML:$(this);/root/data/Kunden/Kunde, XML:$(this);/root/data/Posten/Einzelposten). Der Spezialdateiname XML:$(this) zeigt auf die aktuelle Datei.

Die Verwendung des Parameters wird im Anwendungsbeispiel Serienbrief veranschaulicht.

6.33. Parameter --help

[-?]

Der Parameter --help zeigt die Hilfe-Seite (z.B. in Logdatei).

Syntax

--help

Beschreibung

Mit diesem Parameter gibt man die automatische Programmhilfe aus. Es handelt sich dabei um eine aktuelle Kurzübersicht über alle in der verwendeten Version verfügbaren Aufrufparameter.

Durch die zusätzliche Angabe des Logdateiparameters wird die Hilfe in eine Datei umgeleitet. Eine Ausgabe auf der Konsole ist unter Windows nicht möglich.

Beispiel: CIB merge als Programm

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

Die Hilfe wird in die Datei hilfe.txt umgeleitet. Ein Auszug aus dieser Hilfeausgabe ist im Anwendungsbeispiel Lückentext zu finden.

6.34. Parameter --inline-is-not-this

[--inline-is-not-this]

(Ab CIB merge 3.9.190)

Durch Verwendung des Parameters „--inline-is-not-this“ kann das Verhalten von CIB merge Versionen älter als 3.9.166 betreffend $(inline) wieder hergestellt werden.

Syntax

--inline-is-not-this

Beschreibung

Bis CIB merge Version 3.9.165 wurde intern auf dem Bezeichner $(inline) gearbeitet, d.h. es wurde ein Kontext erzeugt. Ab CIB merge Version 3.9.166 wird das $(inline) durch den tatsächlichen Dateinamen ersetzt.

Damit funktionieren Konstrukte mit "--directory-read=inline=<Dateiname>" ($(inline) wird auf eine Datei umgeleitet) und gleichzeitig „REF "DAT:XML:$(inline);relativ/Pfad” ” nicht mehr, da für relative XPATH-Ausdrucke kein Kontext mehr vorhanden ist. Es müsste mit absoluten XPATH-Befehlen gearbeitet werden.

Durch Verwendung des Parameters „--inline-is-not-this“ wird intern ein Kontext erzeugt und damit die Verwendung relativer XPATH-Befehle ermöglicht.

6.35. Parameter --html-switches

[--html/-s]

Mit dem Parameter --html-switches versteht CIB merge auch erweiterte REF-Anweisungen, die Zusatzschalter für die Ausgabe von Formularen mit CIB format/html enthalten.

Syntax

--html-switches

Beschreibung

CIB Merge versteht standardmäßig nur die in MS Word definierten Schalter. Mit dem Parameter --html-switches werden auch die Zusatzschalter für die Ausgabe von Formularen interpretiert. Eine Spezifikation dieser Zusatzschalter finden Sie in der CIB format Hilfe, die Sie von den Kontaktadressen oder unter http://www.cib.de unter Support | Dokumentation erhalten.

Beispiel

--html-switches

Der Parameter bewirkt, dass CIB merge beispielsweise folgenden Zusatzschalter versteht.

{REF  \* <cib-formfield type="text" info="Vorname" testvalue="Max" />}

Dies ergibt mit CIB format/html ein einzeiliges Textfeld.

Die Verwendung des Parameters wird im Anwendungsbeispiel Lückentext veranschaulicht.

6.36. Parameter --inputfile

[--input/-i]

Mit dem Parameter--inputfile wird die Eingabedatei angegeben, bei mehreren Bausteinen muss dort der Wurzelbaustein angegeben werden.

Syntax

--inputfile=<Inputfile>

Beispiel

--inputfile=Anschreiben_in.rtf

Die Eingabedatei Anschreiben_in.rtf wird im aktuellen Verzeichnis gesucht.

Die Verwendung des Parameters wird im Anwendungsbeispiel Lückentext veranschaulicht.

Hinweis

Geben Sie den Pfad für den Wurzelbaustein nicht bei --inputfile, sondern getrennt mit --source-directory an. So werden auch die inkludierten Bausteine in diesem Verzeichnis automatisch gefunden, absolute Pfadangaben sind für die RTF-Bausteine nicht mehr nötig.

Dies wird im Anwendungsbeispiel Bausteine verdeutlicht.

6.37. Parameter --input-language

Der Parameter --input-language bestimmt für den Schalter „numerisches Format“ (\#) die Ländereinstellung.

Syntax

--input-language=<Sprache>
<Sprache>: englisch/english oder german/deutsch

Beschreibung

Derzeit gültige Werte sind „english“/“englisch“ und „german“/“deutsch“. Die Standardeinstellung ist „german“. Ist der Wert auf „german“ eingestellt, so interpretiert CIB merge Punkte in der Zahlenformatangabe als Anweisung, die auszugebende Zahl mit Tausenderpunkten zu gliedern oder mit Ersatzzeichen der eingestellten Ausgabesprache. Kommata werden als Unterteilung zwischen Vor- und Nachkommastellen gewertet. Auch hier wird das Zeichen ausgegeben, dass zur  eingestellten Ausgabesprache passt. Ist der Wert auf „english“ eingestellt, so werden Punkte und Kommata umgekehrt interpretiert. Die Ausgabe erfolgt dennoch unabhängig davon in der Ausgabesprache.

Die Zahlen müssen in der CSV-Datei deutsch angegeben werden. Sie werden in {=...} Feldern auch nur auf Deutsch verstanden. Ebenso erwartet der Parser des Schalters \#, dass das Feldergebnis vor Anwendung des Schalters die Zahl auf Deutsch enthält.

Beispiele

• Englisches RTF mit englischen Formatierungen

--input-language=english

Das Anschreiben ist auf Englisch verfasst und somit auch die Angabe des Zahlenformats. Diese Tatsache wird über den Parameter --input-language angegeben.

Dies wird im Anwendungsbeispiel Lückentext veranschaulicht.

• Rechenbeispiele

--input-language=german

Sei nun in einem RTF-Dokument folgende Anweisung vorhanden:

{=1234 + 1 \# #.####0,00€}

Ergebnis: 1.235,00€

Die Anweisung

{=12,34 + 1 \# #.####0,00€}

liefert das Ergebnis: 13,34€

--input-language=english

Sei nun in einem RTF- Dokument folgende Anweisung vorhanden:

{=1234 + 1 \# #,####0.00€}

Ergebnis: 1.235,00€

Die Anweisung

{=12,34 + 1 \# #,####0.00€}

liefert das Ergebnis: 1.334,00€

Der Grund für das vom Deutschen abweichende Ergebnis liegt in der Interpretation der Trennzeichen im Englischen:
Tausender-Komma und Dezimal-Punkt

6.38. Parameter --intermediatefile

[--intermediate]

Der Parameter --intermediatefile ermöglicht das Speichern von Zwischenergebnissen in einer Datei oder im Speicher.

Syntax

--intermediatefile=<String>
<String>: RAM, - oder <Dateiname>

Beschreibung

Durch Angabe von RAM als Zwischenergebnisdatei, wird keine Datei auf dem Dateisystem erzeugt. Dies ist nützlich, wenn auf einem System kein (schreibender) Zugriff auf das Dateisystem möglich ist. Das Schreiben einer Zwischendatei benötigt unter Umständen viel Zeit, die so eingespart werden kann.

Mögliche Werte für <String> sind folgende:

Beispiel

--intermediatefile=Zwischenergebnis

Der Parameter --intermediatefile schreibt das Zwischenergebnis in die Datei Zwischenergebnis.rtf .

Hinweis

Die Angabe der Datei für die Zwischenergebnisse kann alternativ auch über die Umgebungsvariable “CIB_MRGINTERMEDIATE” erfolgen.

Der Parameter kann über die "AUTOSTART" – Funktionalität (ab Merge 3.9.104 und 3.8.130) für alle Mischläufe gesetzt werden. Dazu kann die "AUTOSTART" – Parameterdatei per Hex-Editor direkt in die Binär-Datei gepatcht werden oder die Umgebungsvariable "CIB_MRGAUTOSTART" mit dem Parameterdateinamen gesetzt werden.

6.39. Parameter --keep-fields

[-k]

Der Parameter --keep-fields führt den Mischvorgang fort, auch wenn nicht alle Felder über die Datenversorgung gefüllt werden können.

Syntax

--keep-fields=<Option>
<Option>: unresolved-ref, unresolved-ref-as-formfield, all oder none

Beschreibung

Wenn während der Datenversorgung nicht alle Felder gefüllt werden können (Informationen liegen noch nicht vor), dann ist es möglich CIB merge mittels des Parameters --keep-fields dazu zu veranlassen, diese Felder zu übergehen, ohne den Mischvorgang abzubrechen.

Für <Option> sind folgende Werte möglich:

Beispiel

--logfile=!cibmerge_Bausteine_KeepFields.log
--target-directory=csv
--source-directory=..\templates
--inputfile=wurzelbaustein.rtf
--outputfile=!..\result\KeepFields_out.rtf
--datafile=multi_undef.csv
--multidatafile
--charformat
--keep-fields=unresolved-ref

Hier wird in einem der RTF-Bausteine die Variable kont_kontoart verwendet. Für diese Variable erfolgt jedoch keine Versorgung aus den Datenquellen. Durch den Parameter --keep-fields=unresolved-ref wird der Mischvorgang fortgeführt, das REF-Feld für kont_kontoart bleibt in der Ausgabedatei KeepFields_out.rtf erhalten.

Die Verwendung des Parameters wird im Anwendungsbeispiel Bausteine verdeutlicht.

Hinweis:

Wenn CIB merge wegen des Parameters keep bzw. wegen des Schalters \* LASSEN ein Feld als solches schreibt (ohne die Daten einzumischen), erscheint eine textuelle Fehlermeldung im Logfile. Diese Aktion wird nicht als Fehler gewertet und erzeugt daher keinen Fehlerrückgabewert.

(Ab CIB merge Version 3.9.181)

Bei Steuerung über Feldschalter gibt es außer \* LASSEN noch die Möglichkeiten:

\*keepalways: Diese Feldanweisung bleibt immer im Ausgabedokument stehen.

\*keepuntilresolved: Diese Feldanweisung bleibt solange im Ausgabedokument bestehen, bis sie versorgt ist.

Tipp:

Dieser Parameter eignet sich als --keep-fields=unresolved-ref hervorragend zur Realisierung einer Restdatenerfassung mit den CIB office Modulen. Fragen Sie den CIB Support nach weiteren Informationen für Ihren Anwendungsfall.

6.40. Parameter --keep-refs-if-in-list

(ab CIB merge Version 3.9.186)

Über den Parameter --keep-refs-if-in-list kann der Keep-Schalter von außen für die angegebenen Felder gesetzt werden.

Syntax

--keep-refs-if-in-list=<Variable>|<Variable-List>
<Variable-List>=<Varable>;<Varable>;…

Beschreibung

Über den Parameter --keep-refs-if-in-list kann dem CIB merge ein einzelnes oder auch eine Liste von Feldern übergeben werden, für die ein Keep-Schalter zu setzen ist. Diese REF-Felder werden im gemischten Dokument belassen, ein eventueller Variablenwert wird im Fieldresult gespeichert. Kommt ein REF-Feld in einem RTF mehrfach vor, bleiben alle in der Ausgabe erhalten.

Bereits im RTF enthaltene Keep-Schalter zu diesen Feldern bleiben davon unberührt und haben Vorrang.

6.41. Parameter --LicenseCompany

Name des Lizenznehmers für den in Verbindung  mit dem Parameter LicenseKey lizenzpflichtige Funktion(en) des CIB merge freigeschalten werden.

Syntax

--LicenseCompany"=<Name>

6.42. Parameter --LicenseKey

Lizenzschlüssel, welcher in Verbindung mit dem richtigen Lizenznehmer lizenzpflichtige Funktion(en) freischaltet..

Syntax

--LicenseKey=4e4e-c1c1-12345678

6.43. Parameter --lists

Mit dem Parameter --lists können Optimierungen, die für Listentabellen im Kopf des RTF-Dokuments durchgeführt werden, wahlweise abgeschaltet werden.

Syntax

--lists=<Option>
<Option>: keep, optimize, expand oder adjust

Beschreibung

Jedes RTF-Dokument enthält im Kopf Listentabellen (\listtable, \listoverridetable). Bei der Verarbeitung dieser Tabellen muss CIB merge Zeit für den Abgleich von Einfügungen und zur Optimierung aufwenden.
Über den Parameter --lists können diese Optimierungen wahlweise abgeschaltet werden.

Für <Option> sind folgende Werte möglich:

„Wichtiger Hinweis“

Es handelt sich bei NEWLISTID um einen Feldschalter und dies wird verwendet, wenn bei mehrere Ausfertigungen die gleiche Datei includiert wird.

Beispiel: {INCLUDETEXT “neu1.rtf” \* NEWLISTID}

Version 3.13

Achtung:
Dieser Parameter steht in Abhängigkeit des Parameters "--replace-header".

"replace-header=never"
Keine Steuerungs-Möglichkeit der Behandlung der Listentabellen. Das Verhalten ist wie bei "lists=keep".

"replace-header=always"
 (default value) Hier findet grundsätzlich eine Erweiterung des Wurzel-Dokuments um Listentabellen aus eingefügten Textbausteinen statt. Es wird nur zwischen Optimierung und Nicht-Optimierung unterschieden.
Das bedeutet, dass "lists=keep" wie "lists=expand" (keine Optimierung) und "lists=optimize" wie "lists=adjust" (Optimierung) behandelt werden.

 "--replace-header=auto"
Nur in dieser Einstellung werden alle 4 Varianten des “—lists“-Parameters wie oben beschrieben ausgeführt.

Beispiele

--lists=adjust

Hier soll die Listentabelle um die Listen erweitert werden, die in den Textbausteinen verwendet werden. Unbenutzte Listen sollen entfernt werden. Dadurch stehen die verwendeten Listen auch bei einer späteren Bearbeitung in MS Word wieder zur Verfügung.

Dieser Parameter wird im Anwendungsbeispiel Bausteine veranschaulicht.

6.44. Parameter --logfile

[--log/-l]

Der Parameter --logfile setzt den Dateinamen und Pfad für die Fehlerprotokolldatei, die CIB merge für jeden Mischlauf schreibt.

Syntax

--logfile=<Fehlerprotokolldatei>

Beschreibung

Mit --logfile=!<Fehlerprotokolldatei> wird eine bereits vorhandene Fehlerprotokolldatei überschrieben, mit --logfile=+<Fehlerprotokolldatei> werden die aktuellen Einträge einfach an die Datei angehängt. Tritt kein Fehler auf, so wird eine leere Fehlerdatei geschrieben.

Beispiel

--logfile=!Komma_log.log

Eine evtl. bereits vorhandene Datei Komma_log.log im aktuellen Verzeichnis wird überschrieben.

Die Verwendung des Parameters wird im Anwendungsbeispiel Lückentext veranschaulicht.

Hinweis

Es empfiehlt sich, den Parameter --logfile in die erste Zeile der Parameterdatei zu schreiben. Dadurch werden bereits Fehler in der Parameterdatei protokolliert.

Ab der CIB merge Version 3.9.x kann --logfile zusätzlich mit --verbose skaliert werden. Zu den Details von --logfile und --verbose siehe Kapitel Fehlerprotokolldatei. Beachten Sie auch die weiterührenden Informationen zu Trace-Möglichkeiten und Programmrückgabewerten im Buch "CIB merge Fehlerbehandlung".

6.45. Parameter -m

Der Parameter -m<Text> weist CIB merge an, einen angegebenen <Text> in der Meldung/Fehlerprotokolldatei auszugeben.

Syntax

-m<Text>

Beschreibung

Der Parameter -m<Text> ermöglicht das Einfügen von selbst definierten Texten in die Meldungsdatei. Mit -m@ gibt CIB merge automatisch die gesetzten Parameter für Eingabe- und Ausgabedateinamen aus.

Beispiel

--logfile=!Komma_log.log
--inputfile=Anschreiben_in.rtf
--outputfile=!Komma_out.rtf
--datafile=Adresse_Komma.csv
-m
-mDer Mischvorgang verwendet folgende Ein- und Ausgabedateien:
-m@

Der hinter -m angegebene Text wird in die Logdatei geschrieben. Durch -m@ werden die Namen der Eingabe- und Ausgabedateien ausgegeben.

Ein Auszug aus der Logdatei ist im Anwendungsbeispiel Lückentext zu finden.

Hinweis

Treten Fehler im Mischlauf auf, so werden diese nach den Meldungen aus -m ausgegeben.

Die Ausgabe der Programmversion von CIB merge wird mit dem Parameter --version gesteuert

6.46. Parameter -- max-executiontime

(ab CIB merge Version 3.10.3)

Dieser Parameter beschränkt die maximale Ausführungszeit.

Syntax

-- max-executiontime=[#milliseconds]

Beschreibung

Dieser Parameter legt die maximale Ausführungszeit in Millisekunden fest. Sobald dieser Wert überschritten wird, hält CIB merge mit Fehler 821 an.

Wenn dieser Wert 0 (Null) ist oder nicht gesetzt wurde, ist die Ausführungszeit unbegrenzt.

Dieser Parameter dient dazu Risiken, die durch Endlosschleifen entstehen können, zu vermeiden. Die folgende Feldkombination ist ein Beispiel für eine solche Schleife:

{ IF {MERGEREC \* keepalways} <> "{REF value}" \* SOLANGE}

6.47. Parameter --maxOutputSize

(ab CIB merge Version 3.9.174)

Der Parameter maxOutputSize setzt die maximal zulässige Größe für den gesamten Serienbrief im „serialletter“ Fall.

Syntax

--maxOutputSize=[#bytes]

Beschreibung

Bei diesem Parameter handelt es sich um ein Abbruchkriterium für Serienbriefe, die mit CIB merge erstellt werden. Wird der Serienbrief größer als die eingestellte maximale Größe, dann quittiert CIB merge dies mit einem Returncode 818.

Damit kann der Anwender sicherstellen, dass die Erzeugung (die in der Regel automatisiert und ohne menschliche Kontrolle passiert) abgebrochen wird, wenn es zu einem ungewollten Verhalten im Bereich der Dateigröße kommt.

6.48. Parameter --maxSingleSize

(ab CIB merge Version 3.9.174)

Der Parameter maxSingleSize setzt die maximal zulässige Größe für ein einzelnes Dokument im „serialletter“ Fall.

Syntax

--maxSingleSize=[#bytes]

Beschreibung

Bei diesem Parameter handelt es sich um ein Abbruchkriterium für Seriernbriefe, die mit CIB merge erstellt werden. Wird ein einzelnes Dokument eines Serienbriefes größer als die eingestellte maximale Größe, dann quittiert CIB merge dies mit einem Returncode 817.

Damit kann der Anwender sicherstellen, dass die Erzeugung (die in der Regel automatisiert und ohne menschliche Kontrolle passiert) abgebrochen wird, wenn es zu einem ungewollten Verhalten im Bereich der Dateigröße kommt.

6.49. Parameter --merge

[-@[<Ziffer>]]

Ein einfaches --merge einzelner -@ als Argument sorgt dafür, dass CIB merge sofort zu mischen beginnt und alle vorher belegten Argumente dafür benutzt.

Syntax

--merge

oder

--merge=<Ziffer>

Beschreibung

Mit diesem Aufrufparameter können in einer Parameterdatei mehrere Aufträge hintereinander stehen, die jeweils getrennt voneinander bearbeitet werden.

Hinweis:

Ein bereits gesetzter Parameter ist so lange gültig, bis diesem ein neuer Wert zugeordnet wird.

Sollten in den beteiligten Datendateien nicht alle Datensätze/Variablen abgearbeitet sein, dann interpretiert CIB merge den Mischlauf als Seriendruck, fügt einen Abschnittswechsel in das Zieldokument ein und mischt beginnend vom Wurzeldokument weiter.

Ein --merge=1 wird dazu im Gegensatz als Einzelmischlauf ausgeführt und endet am Ende der RTF-Textbausteine, egal wie viele versorgte Daten noch unberührt sind. Die Ziffer gibt an, wie viele Datensätze durchlaufen werden und begrenzt somit den Seriendruck auf eine bestimmte Anzahl von Datensätzen.

Beispiele

--merge=1

Hier wird ein Einzelmischlauf ausgeführt, d.h. das Ergebnis-RTF enthält lediglich die Daten vom ersten Datensatz.

--merge=3

Das Ergebnis ist ein RTF-Dokument mit den ersten drei Datensätzen, auch wenn die Datenquellen mehr als drei Datensätze beinhalten.

Die Verwendung des Parameters wird im Anwendungsbeispiel Serienbrief veranschaulicht.

Hinweis:

Erfolgt die Übergabe der Parameter an CIB merge in einer Parameterdatei, so werden nur die Parameter ausgewertet, die vor dem Parameter --merge stehen.

6.50. Parameter --multidatafile

[--meta/--metadatafile/--multi/-c]

Wird eine Multisteuerdatei/Multi-CSV-Datei als Datenquelle verwendet, so muss zusätzlich der Parameter --multidatafile gesetzt werden. 

Syntax

--multidatafile

Beschreibung

Der Parameter --multidatafile kennzeichnet, dass die mit dem Parameter --datafile angegebene Datendatei weitere Datendateien beinhaltet.

Beispiele

• Paramterdatei mit Multisteuerdaten aus Multi-CSV-Datei:

--datafile=multi.csv
--multidatafile

Der Parameter --datafile definiert eine Multi-CSV-Datei. Die Aliase sind in der ersten Zeile der CSV-Datei definiert, alle weiteren Zeilen sind die Aliasdefinitionen.

Die Verwendung des Parameters im Zusammenhang mit CSV-Dateien wird im Anwendungsbeispiel Serienbrief veranschaulicht.

Hinweis:

Bei Verwendung von Multi-CSV-Dateien wird der Parameter --headerfile nicht eingesetzt.

• Parameterdatei mit Multisteuerdaten aus zwei getrennten CSV-Dateien

--datafile=Daten.csv
--multidatafile
--headerfile=Alias.csv

Alias-CSV-Datei:

Adresse;Lizenzinformationen

Daten-CSV-Datei:

Adresse.csv;Lizenzinfo.csv

Hinweis:

Die Aliasnamen und Aliasdefinitionen sind in diesem Beispiel in zwei CSV-Dateien getrennt gespeichert. Um die CSV-Datei für die Aliasnamen anzugeben wird der Parameter --headerfile verwendet. Die Aliasdefinitionen befinden sich in der CSV-Datei, die mit dem Parameter --datafile gesetzt wird. Jede Zeile stellt eine neue Definition (Datensatz) dar.

• Parameterdatei mit Multisteuerdaten aus XML:

--headerfile=XML:Daten_mitAlias.xml
--datafile=/root/multi
--multidatafile

Der Parameter --headerfile definiert die XML-Datei. Die Aliase ergeben sich aus den Knotennamen in der XML-Datei, die mit dem angegebenen XPath definiert sind. Die Aliasdefinitionen sind die Knoteninhalte.

6.51. Parameter --next-mode

[--next-modus/--next]

Der Parameter --next-mode steuert das Verhalten des {NEXT}-Befehls und wirkt auf Variablen, die zwar in einem Datensatz, im nächsten aber nicht mehr vorhanden sind.

Syntax

--next-mode=<Option>
<Option>: delete, empty oder keep

Beschreibung

Variablen, die zwar in dem einen, aber im nächsten Datensatz nicht mehr vorhanden sind, können mithilfe des Parameters --next-mode gelöscht, geleert oder beibehalten werden.

Mögliche Werte für <Option> sind:

Beispiel

--next-mode=delete

Ist eine Variable im nächsten Datensatz nicht mehr vorhanden (z.B. fehlender Knoten im XML), so wird diese Variable gelöscht, was daraufhin zu einem Fehler führt. Dies ist erwünscht, damit der Fehler nicht unerkannt bleibt, indem der fehlende Wert einfach ausgelassen wird.

Dieser Parameter wird im Anwendungsbeispiel Serienbrief veranschaulicht.

6.52. Parameter --old-compare

Mit diesem Parameter kann die neue Interpretation von Bedingungen abgeschaltet werden.

Syntax

--old-compare=<Option>
--alter-Vergleich=<Option>
<Option>: +, - oder „“

Beschreibung

MS-Office hat mit neueren Versionen einen erweiterten Funktionsumfang im automatischen Vergleich von Datentypen bekommen. Dieser hat eine Erneuerung in CIB merge (seit Version 3.8.126) erforderlich gemacht. Kunden die ein älteres (konservatives) Vergleichsverfahren wünschen, können dies über den --old-compare Aufrufparameter erwirken.

Die Abschaltung der neuen Interpretation von Bedingungen kann über den Parameter --old-compare gesteuert werden. Der Parameter kann über die “AUTOSTART” - Funktionalität (ab Merge 3.9.104 und 3.8.130) für alle Mischläufe gesetzt werden. Dazu kann die "AUTOSTART" – Parameterdatei per Hex-Editor direkt in die Binär-Datei gepatcht werden oder die Umgebungsvariable "CIB_MRGAUTOSTART" mit dem Parameterdateiname gesetzt werden.

Spezifikation

Der Parameter heißt „OLD-COMPARE“. Alternativ kann auch „ALTER-VERGLEICH“ angegeben werden. Wie bei allen Merge - Parametern wird die Groß-/Kleinschreibung nicht berücksichtigt.

Für <Option> sind folgende Werte möglich:

Beispiel

--old-compare=+

CIB merge interpretiert die Bedingungen nach dem alten Vergleichsverfahren.

6.53. Parameter --optimize

Der Parameter --optimize entfernt die durch MS Word eingefügten überflüssigen Schalter.

Syntax

--optimize

Beschreibung

MS Word fügt beim Einfügen oder Umformatieren von REF-Feldern teilweise einen Schalter \* FORMATVERBINDEN oder \* MERGEFORMAT ein, der die Rohtexte schlechter lesbar macht und in CIB merge zu Performancenachteilen führt. CIB merge entfernt diese überflüssigen Schalter mit dem Parameter --optimize.

Beispiel

--inputfile=Optimierung_in.rtf
--outputfile=!Optimierung_out.rtf
--optimize
--filter=f

Hier werden alle MERGEFORMAT-Schalter aus dem RTF Optimierung_in.rtf entfernt, ohne Feldergebnisse einzumischen (--filter=f). Das Ergebnis Anschreiben_optimiert enthält keine solchen Schalter mehr.

Die Verwendung dieses Parameters wird zusammen mit anderen Optimierungs-Parametern im Anwendungsbeispiel Lückentext veranschaulicht.

6.54. Parameter --outputfile

[--output/-o]

Der Parameter --outputfile spezifiziert die Ausgabe- oder Ergebnisdatei.

Syntax

--outputfile=<Ausgabedatei>

Beschreibung

Der Aufruf --outputfile=! überschreibt eine bereits vorhandene Ausgabedatei, --outputfile=+ hängt die Ausgabedatei an die bereits vorhandene Datei an und erzeugt so eine MultiRTF-Datei.

Ist keine explizite Pfadangabe vorhanden, so wird die Datei im mit --target-directory angegebenen Arbeitsverzeichnis erzeugt, ohne gesetztes --target-directory wird die Ausgabedatei im aktuellen Verzeichnis abgelegt.

Beispiele

• Erzeugung einer einfachen RTF-Datei

--outputfile=!Anschreiben_out.rtf

Die Datei Anschreiben_out.rtf wird in das aktuelle Verzeichnis geschrieben. Das Ausrufezeichen überschreibt ggfs. eine bereits existierende Datei.

Die Verwendung des Parameters wird im Anwendungsbeispiel Lückentext veranschaulicht.

--outputfile=!..\result\Kontenuebersicht.rtf

Die Datei Kontenuebersicht.rtf wird in das Verzeichnis result geschrieben. Das Ausrufezeichen überschreibt ggfs. eine existierende Datei.

Die derartige Verwendung des Parameters wird im Anwendungsbeispiel Bausteine veranschaulicht.

• Erzeugung einer Multi-RTF-Datei

--logfile=!multirtf.log
--outputfile=!multirtf.rtf
--inputfile=input1.rtf
-@1
-m@
--outputfile=+multirtf.rtf
--inputfile=input2.rtf
-@1
-m@
--inputfile=input3.rtf
-@1
-mfertig.

Dieses Beispiel erzeugt aus drei RTF-Dateien eine MultiRTF-Datei und gibt die Aufrufparameter jeweils aus. Im ersten Mischlauf wird die multirtf.rtf mit --outputfile=!multirtf.rtf überschrieben, anschließend werden die weiteren Dateien mit --outputfile=+multirtf.rtf angehängt.

6.55. Parameter --output-language

Der Parameter --output-language steuert die sprachabhängige Ausgabeformatierung von Datumsangaben und Zahlen, die über die Feldschalter \# und \@ vorgenommen wurden.

Syntax

--output-language=<Sprache>

oder

--Ausgabesprache=<Sprache>

<Sprache>: english/englisch, french/franzoesisch,
german/deutsch, spanish/spanisch, italian/italienisch, swiss/schweizerisch oder
dutch/niederlaendisch

Beschreibung

Der Parameter --output-language beeinflusst nur die Ausgaben der Tausender- und Dezimaltrennzeichen sowie die Wochentage und Monatsnamen. Die Versorgung der Zahlen erfolgt derzeit auf Deutsch.

Die Ausgabe von Feldern ohne \# und \@ wird nicht beeinflusst, wie zum Beispiel {Aktualdat/Time/Date} oder {=…}.

Für <Sprache> sind folgende Werte möglich:

Die Ausgabe der Tausender- und Dezimaltrennzeichen wirkt sich zum Beispiel für 1234567 mit \# #.###,00 so aus:

Voreingestellt ist die deutsche Ausgabe. Lässt man die Sprachangabe hinter dem Schalter weg, dann wird wieder auf deutsche Ausgabe zurückgesetzt. (initial value is german and default for output-language is german)

Die Einstellung gilt für alle Mischvorgänge (-@/-@1) nach „output-language“, bis die Parameter restlos abgearbeitet wurden oder erneut „output-language“ verändert wird.

Die Ausgabe der Wochentage und Monatsnamen erfolgt entsprechend. Der 28.8.2001 wird beispielsweise mit dem Format \@ „dddd, d. MMMM yyyy“ zum Ergebnis „Dienstag, 28. August 2001“, wenn die Ausgabesprache auf Deutsch eingestellt ist. Für Englisch ergibt es „Tuesday, 28. August 2001“.

(Für ein „echtes“ englisches Datum muss man den Schalter weiter verändern, sodass die Reihenfolge und Füllzeichen der jeweiligen landesüblichen Ausgabe entsprechen.)

Beispiel

--output-language=english

Das Ausgabeformat ist englisch. Die Ausgabe der Datumsangaben und Zahlenformate erfolgt im englischen Format. Der Parameter wird im Anwendungsbeispiel Lückentext veranschaulicht.

6.56. Parameter --parameterfile

[--parameter/-@<Parameterdatei>]

Mit dem Parameter --parameterfile wird der Name der Parameterdatei angegeben. Es wird ein Mischvorgang gestartet, der die gesetzte Parameterdatei verwendet.

Syntax

--parameterfile=<Parameterdatei>

Beschreibung

Der Parameter --parameterfile spezifiziert einen Dateinamen, der als Parameterdatei interpretiert wird. CIB merge erwartet dann in dieser Parameterdatei alle für den Mischlauf relevanten Aufrufparameter. Startet Einzel-Mischvorgang (Merge mischt nicht solange noch Daten in der Datenbank sind). @<Parameterdatei> CIB merge wertet sofort alle Parameter in der angegebenen Parameterdatei aus und ignoriert die restlichen Zeilen.

Beispiel (Aufruf in der Kommandozeile):

cibmrg32.exe --parameterfile=Komma_par.par

Alle für den Mischlauf relevanten Aufrufparameter befinden sich in der Datei Komma_par.par.

Die Verwendung des Parameters wird im Anwendungsbeispiel Lückentext veranschaulicht.

Hinweis

Der Parameter ist nur in Kombination mit dem Aufruf der Merge-EXE über die Kommandozeile anwendbar. Dabei können beliebige Aufrufparameter davor und danach stehen und beliebig viele Parameterdateien an beliebiger Stelle zwischen den anderen Parametern stehen. Es können auch weitere Parameterdateien von Parameterdateien aus aufgerufen werden. Dabei muss jedoch darauf geachtet werden, dass unendliche Rekursionen vermieden werden.

6.57. Parameter --prefix-delimiter

Der Parameter --prefix-delimiter definiert ein Trennzeichen zwischen Alias und Variablennamen und schaltet den Präfix-Mechanismus fest ein.

Syntax

--prefix-delimiter=<Trennzeichen>

Beschreibung

Durch Setzen des Parameters --prefix-delimiter wird das Trennzeichen angegeben, das zusammen mit dem Alias den Variablen im Rohtext vorangestellt wird. Dies ist z.B. sinnvoll beim Einsatz von Multiknoten, um die Variablen eindeutig zu halten. Der Default-Wert ist „.“.

Beispiel

--headerfile=XML:Daten_mitAlias.xml
--datafile=/root/multi
--multidatafile
--prefix-delimiter

XML-Datei:

<root>
      <multi>
       <Kunden>XML:$(this);/root/data/Kunden/Kunde</Kunden>
       <Einzelposten>XML:$(this);/root/data/Posten/Einzelposten</Einzelposten>
      </multi>
      <data>
            <Kunden>
                  <Kunde>
                        <Vorname>Franz</Vorname>
                        <Name>Meier</Name>
                        <Strasse>Teststr. 4</Strasse>
                        <PLZ>12345</PLZ>
                        <Ort>Musterdorf</Ort>
                        <Geschlecht>M</Geschlecht>
                        <KundenNr>9898989</KundenNr>
                        <AuftragsNr>111111-2</AuftragsNr>
                        <Betrag>999</Betrag>
                  </Kunde>
                  weitere Kunden ......
            </Kunden>
            <Posten>
                  <Einzelposten>
                        <KundeAuftragsNr>111111-2</KundeAuftragsNr>
                   <Bezeichnung>Artikel1</Bezeichnung>
                        <Betrag>999</Betrag>
                  </Einzelposten>
                  weitere Einzelposten....
            </Posten>
      </data>
</root>

Als Trennzeichen ist ein „.“ definiert (Default). Bei den Rohtexten sind alle Zugriffe auf Variablennamen um den Aliasnamen und das Trennzeichen zu ergänzen. Dadurch ist die Variable Betrag beispielsweise eindeutig. Ausschnitt aus dem Rohtext:

{REF Kunden.Betrag}
{REF Einzelposten.Betrag}

Im Anwendungsbeispiel Serienbrief wird dieser Parameter verwendet.

6.58. Parameter --remove-hidden-text

Der Parameter –remove-hidden-text entfernt vollständig alle Inhalte aus dem Dokument, die als „Hidden“ markiert sind.

Syntax

--remove-hidden-text

Beschreibung

Durch Setzen des Parameters –remove-hidden-text wird der als „Hidden“ markierter Text entfernt. Andere Inhalte werden, abhängig von anderen Standardparametern, ohne Änderungen verarbeitet

Beispiel

--remove-hidden-text
-iInputfile.rtf
-o!Outputfile.rtf
-ff

6.59. Parameter --replace-header

Der Parameter --replace-header dient dazu, das Neuschreiben des Kopfes der RTF-Ausgabe wahlweise abzuschalten.

Syntax

--replace-header=<Option>
<Option>: always, never oder automatic

Beschreibung

Der Kopf der RTF-Ausgabe wird am Ende neu geschrieben. Wegen der Farb-,Listen- und Schriftartentabellen im Kopf der RTF-Ausgabe, muss CIB merge Zeit für den Abgleich wegen Einfügungen oder zur Optimierung aufwenden. Dieser Abgleich oder diese Optimierungen interessieren aber nicht jeden Anwender. Daher sind sie wahlweise abschaltbar. Das bezieht sich auch auf den gesamten Kopf.

Mögliche Werte für <Option> sind:

Beispiele

--replace-header=automatic

Dieser Parameter wird zusammen mit --fonts, --colors und --lists im Anwendungsbeispiel Bausteine veranschaulicht.

6.60. Parameter --serialletter

Der Parameter verändert das Verhalten beim Schreiben von Multi-RTF-Dateien.

Syntax

--serialletter=<Option>
<Option>: auto oder multi

Beschreibung

Mögliche Werte für <Option> sind:

Beispiel

--serialletter=multi
--outputfile=!Serialletter_out.rtf

Das Ergebnisdokument Serialletter_out.rtf ist ein Multi-RTF, das alle Datensätze enthält.

Die Verwendung des Parameters wird im Anwendungsbeispiel Serienbrief veranschaulicht.

6.61. Parameter --set

[-:]

Setzt eine Variable, die man in RTF-Textbausteinen verwenden kann. Ist diese Variable auch in der Datenversorgung (CSV, XML) vorhanden, wird vorrangig dieser Wert aus dem zugesteuerten Datenstrom verwendet.

Syntax

--set=Variable=Wert

Beispiel

--set=XmlDateiname=Daten.xml

Die Variable „XmlDateiname“ wird auf den Wert „Daten.xml“ gesetzt. Diese Variable kann in den RTF-Bausteinen abgefragt werden.

Die Verwendung des Parameters wird im Anwendungsbeispiel Serienbrief veranschaulicht.

Hinweis:

Dieser Parameter kann auch mehrfach für einen Mischaufruf benutzt werden

Aufrufbeispiele

• CIB runshell

Cibrsh .....-m–set=Vorname=Hans -m–set=Nachname2=Wurst.......

• CIB merge mit Parameterdatei

...
# setze Vorname auf Hans
--set=Vorname=Hans
# setze Nachname auf Wurst
--set=Nachname=Wurst
...

1.1.3.4    CIB merge aus JAVA

...
t_MergeJob.setProperty("--set=Vorname=", "Hans");
t_MergeJob.setProperty("--set=Nachname=", "Wurst")
...

6.62. Parameter --short-tokens

[--rta/--cibrtf]

Mit diesem Parameter erzeugt CIB merge eine Zieldatei in einem Format mit verkürzten RTF Tokens (CIBrtf).

Syntax

--short-tokens

Beschreibung

Durch die mit dem Parameter --short-tokens erzeugten verkürzten RTF Tokens wird die Dateigröße wesentlich verkleinert. Durch den Einsatz von so optimierten CIBrtf-Dateien, kann die Performance von CIB format und CIB merge optimiert werden.

Eine Weiterverarbeitung dieses Zieldokumentes ist mit CIB format/view und mit CIB merge ab Version 3.8.106 möglich. CIBrtf ist CIB spezifisch und kann von Fremdprodukten nicht verarbeitet werden, CIB merge kann es jedoch einlesen und ohne --short-tokens als RTF wieder ausgeben.

Beispiel

--inputfile=Optimierung_in.rtf
--outputfile=!Optimierung_out.rtf
--short-tokens
--filter=f

CIB merge mischt keine Feldinhalte ein (--filter=f) und schreibt 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.

Die Verwendung dieses Parameters wird zusammen mit anderen Optimierungs-Parametern im Anwendungsbeispiel Lückentext veranschaulicht.

Nachteil:

Das RTF-Format kann nur von der CIB format/output Komponente weiterverarbeitet werden.

6.63. Parameter --source-directory

[--source/-a]

Der Parameter --source-directory setzt ein eigenes Verzeichnis für das RTF-Wurzeldokument und die RTF-Bausteine.

Syntax

--source-directory=<Verzeichnis>

Beschreibung

Der Parameter --source-directory setzt das Verzeichnis, in dem das RTF-Wurzeldokument und die RTF-Bausteine erwartet werden. Es kann auch eine Liste von Arbeitsverzeichnissen angegeben werden. Die einzelnen Angaben werden durch Semikolon getrennt. Für jede verwendete Datei wird eine Suche gestartet und die erste Fundstelle genutzt. Mit dem Parameter --source-directory kann ein Pfad absolut angegeben werden oder relativ zu dem Parameter --target-directory. Der Parameter --target-directory ist daher vor dem Parameter --source-directory zu setzen. Damit können z.B. in Multithreadanwendungen für jeden Thread das gleiche Quellenverzeichnis --source-directory, aber verschiedene Ausgabe/Logverzeichnisse --target-directory angegeben werden. Wird kein Quellenverzeichnis angegeben, dann gilt das Ausgabeverzeichnis auch als Quellenverzeichnis.

Ausnahme:

Haben Dateien eine eigene qualifizierte Pfadangabe im Namen, so werden die Parameter --source-directory und --target-directory für diese Dateien ignoriert.

Beispiel einer optimalen Parameterdatei mit --target-directory und --source-directory:

--target-directory=csv
--source-directory=..\templates
--inputfile=wurzelbaustein.rtf
--outputfile=!..\result\Kontenuebersicht.rtf
--datafile=multi.csv

Mit --source-directory wird das Verzeichnis gesetzt, in dem alle RTF-Bausteine zu finden sind. Somit ist eine explizite Pfadangabe bei --inputfile nicht notwendig. --source-directory wird relativ zu --target-directory angegeben.

Die Verwendung des Parameters wird im Anwendungsbeispiel Bausteine veranschaulicht.

6.64. Parameter --statistics

Der Parameter --statistics gibt die Anzahl der erzeugten Dokumente in einer spezifizierten Datei aus.

Syntax

--statistics=<Filename>

Beispiel

--statistics=!count.txt

Die Anzahl der von CIB merge erzeugten Dokumente werden in der Datei count.txt ausgegeben.

Im Anwendungsbeispiel Serienbrief werden beispielsweise 3 Dokumente erzeugt. Die Datei count.txt enthält nach dem Mischlauf folgenden Inhalt:

GeneratedDocumentCount=3

6.65. Parameter --target-directory

[--target/-q]

Der Parameter--target-directory bestimmt das Verzeichnis für die Daten- und Ausgabedateien.setzt das aktuelle Arbeitsverzeichnis, in dem CIB merge die übergebenen Dateien sucht.

Syntax

--target-directory=<Verzeichnis>

Beschreibung

Zusätzlich zum Verzeichnis für die Daten- und Ausgabedateien --target-directory,  kann mit dem Parameter --source-directory ein Pfad angegeben werden, in dem der Wurzelbaustein und weitere RTF-Bausteine gesucht werden.

--source-directory ist relativ zu --target-directory, kann aber auch absolut angegeben werden. Damit können für Multithreadanwendungen für jeden Thread das gleiche Inputdirectory --source-directory, aber verschiedene Output/Logdirectories --target-directory angegeben werden.

Beispiele

--target-directory=csv
--datafile=multi.csv
--outputfile=!..\result\Kontenuebersicht.rtf

Hier wird --target-directory verwendet, um das Verzeichnis für die CSV-Dateien anzugeben, das Ausgabeverzeichnis wird direkt mit --outputfile gesetzt. Ohne explizite Pfadangabe bei --outputfile, würde das Ergebnis ebenfalls in das --target-directory geschrieben werden. Das RTF-Wurzeldokument und die RTF-Bausteine liegen in --source-directory, außer sie haben eigene Pfadangaben im Namen.

Die Verwendung des Parameters wird im Anwendungsbeispiel Bausteine veranschaulicht.

Hinweis:

--target-directory setzt immer auch gleich --source-directory, kommt also --target-directory nach --source-directory, so wird --source-directory überschrieben.

6.66. Parameter --template-combine

(Ab CIB merge Version 3.9.181)

Der Parameter “--template-combine“ führt dazu, dass alle {INCLUDETEXT} Anweisungen aufgelöst werden, alle anderen Feldanweisungen aber unverändert bleiben.

Syntax

--template-combine

Beschreibung

Damit wird dem Mischlauf vorgegeben, dass ausschließlich INCLUDETEXT Anweisungen aufgelöst werden. Alle anderen Feldanweisungen bleiben bestehen. Man generiert damit aus einem Dokumentprojekt mit n Bausteinen ein großes Eingabedokument

6.67. Parameter --verbose

Mit --verbose kann man die Menge/Art der Fehlermeldungen im Logfile bestimmen.

Syntax

--verbose=<verbose-level>
<verbose-level>: 0-9

Beschreibung

<verbose-level> kann Werte zwischen 0 und 9 annehmen. 0 bedeutet, dass keine Fehler angegeben werden, 9 hingegen, dass auch relevante Folgefehler ausgegeben werden.

Die verfügbaren Verbosity-Levels finden Sie hier. Beachten Sie auch die Fehlerkategorien.

Beispiel:

--verbose=9+all+source

6.68. Parameter --version

[-v]

Mit dem Parameter --version gibt CIB merge die CIB merge Programmversion in der Meldung/Logdatei aus.

Syntax

--version

Beispiel

--logfile=!Komma_log.log
--version

Die Logdatei enthält neben Fehlermeldungen auch eine Ausgabe der CIB merge Programmversion.

Ein Auszug des Inhalts der Logdatei ist im Anwendungsbeispiel Lückentext zu finden.

6.69. Parameter --window-handle

[--window/-w]

Der Parameter --window-handle bewirkt, dass eine Applikation, welche CIB merge aufruft, eine Meldung erhält, wenn CIB merge fertig gemischt hat.

Syntax

--window-handle

Hinweis

Vermeiden Sie diesen Parameter in der Kommandozeile und dem CIB documentserver

6.70. Parameter --workingset-size

[--workingsetsize]

Der Parameter --workingsetsize setzt die InitHeap- und Workingset-Größe.

Syntax

--workingset-size=<min-Wert>;<max-Wert>

Beschreibung

Das Setzen der InitHeap- und Workingset-Größe kann auf manchen Servern die Performance von CIB merge verbessern.

Umgebungsvariablen und Parameter

Um die WorkingSet-Size zu definieren kann der Parameter: „--WORKINGSETSIZE“ benutzt werden.

Die alternative Schreibweise „--WORKINGSET-SIZE“ wird ebenfalls erkannt.

Wie bei allen Merge - Parametern wird die Groß-/Kleinschreibung nicht berücksichtigt.

Alternativ kann dies auch über die Umgebungsvariable „CIB_MRGWORKINGSETSIZE“ gesetzt werden. Die Variable „WORKINGSETSIZE“ kann mittels eines HEX- Editors auch direkt in der Binärdatei gepatcht werden. Die WorkingSet-Size definiert die minimale und maximale Größe der Windows Process-WorkingSet-Size. Der minimale und maximale Wert werden durch eine „;“ getrennt. (Beide sind erforderlich)

Mit der Umgebungsvariable „CIB_MRGINITHEAPSIZE” kann die Initiale Thread-Heap-Größe in KByte eingestellt werden.

Die Initialen Heap- Größe kann auch in der Binärdatei gepatcht werden.(„INITHEAPSIZE")

Patchen geht vor Umgebungsvariable.

Die Erweiterung wird in CIB merge 3.9 aufgenommen. (Nur für Windows)

Beispiele

Setzen der InitHeap- und Workingset-Größe. Das Setzen der InitHeap- und Workingset-Size kann auf manchen Servern die Performance von CIB merge verbessern. Die optimale Konfiguration hängt von vielen Parametern wie Speicher, Netzwerk etc. ab. Deshalb kann nicht die “beste” Einstellung für alle Systeme ermittelt werden. Die für den verwendeten Server kann eine möglicherweise bessere Einstellung durch geeignete Tests ermittelt werden. Der Parameter kann über die "AUTOSTART" – Funktionalität (ab Merge 3.9.104 und 3.8.130) für alle Mischläufe gesetzt werden. Dazu kann die "AUTOSTART" – Parameterdatei per Hex-Editor direkt in die Binär-Datei gepatcht werden oder die Umgebungsvariable "CIB_MRGAUTOSTART" mit dem Parameterdateiname gesetzt werden.

7. Besondere Funktionalitäten: Textcaching

CIB merge kann die Ergebnisdatei nicht nur im RTF Format als Datei auf der Festplatte ausgeben. Es können auch verschiedene Parameter für eine Optimierung, Komprimierung und/oder Verschlüsselung des Ergebnisdatenstromes eingesetzt werden.

1. Egal mit welcher Wurzel gemischt wird, der Include-Cache wirkt unabhängig davon über die Aufträge hinweg, die innerhalb eines Merge-Aufrufes abgesetzt werden.
2. Die Wurzel ist derzeit noch nicht im Include-Cache enthalten. Der Include-Cache ist wirklich nur für Includes.

Hinweis zu 2: Allerdings gibt es für die Wurzel schon immer eine andere Optimierung: Wenn man den Parameter -I angibt und einmal mischt, dann bleibt die Wurzel im Speicher bis wieder ein -I angegeben wird.

Mischt man also viele Dateien mit der gleichen Wurzel direkt hintereinander und gibt nur einmal -I an, dann hat man den gleichen Cache-Effekt.

Hinweis zu 1 und 2: Die Optimierung über den Include-Cache ist ein trade-off für Laufzeit auf Kosten Speicher _und_ Funktionalität:

Wenn man mit Wurzel X mischt, dann werden für X die Fonttables, Colortables usw in Bezug auf das jeweilige Include verändert (erweitert). Dagegen werden für die Includes die Font-, Color- usw Schlüssel (\f12, \cf1...) in Bezug auf die aktuelle Wurzel angepasst und so im Cache abgelegt.

Wenn die Wurzeln salopp gesprochen "zusammenpassen", dann stimmen die Farben, Fonts usw. nachher auch. Wenn nicht, dann nicht.

Um absolute Sicherheit zu haben, muss man also die Dokumente mit derselben Wurzel hintereinander mischen, um den Cache-Vorteil zu haben und anschließend den Cache leeren. Danach kann man mit der nächsten Wurzel mischen usw.

Den Cache löscht man indirekt mit einem der Befehle zum Steuern des Verhaltens beim Include in Bezug auf Fonts, Colors, Listtables usw. Es reicht zum Beispiel ein einziges --replace-header um den Cache zu löschen. (Es wird dabei der Standard --replace-header=always eingestellt, aber der dürfte sowieso gelten.)

Wegen des letzten Hinweises oder vielmehr wegen der Arbeitsweise beim Zusammenführen der Tabellen aus dem Header der RTF, ist ein Wurzel-Cache meist nicht sinnvoll und wegen der nötigen Sortierung der Aufträge nach Wurzel auch nicht erforderlich.

8. Besondere Funktionalitäten: Ergebnisoptimierung, Verschlüsselung und Komprimierung

CIB merge kann die Ergebnisdatei nicht nur im RTF Format als Datei auf der Festplatte ausgeben. Es können auch verschiedene Parameter für eine Optimierung, Komprimierung und/oder Verschlüsselung des Ergebnisdatenstromes eingesetzt werden.

Die folgende Tabelle zeigt die Kompatibilität aller möglichen Kombinationen mit den CIB office Modulen und Fremdprodukten.

Zu den Details der Ansteuerung mit CIB merge siehe die entsprechenden Parameter zu Optimierung, Verschlüsselung und Komprimierung

*) Ab Version 3.8.106

**) Ab Version 3.9.115

Hinweis für CIB merge:

Aus Steuerdateien und Set-Variablen kann weder verschlüsseltes, komprimiertes noch CIB RTF eingelesen werden.

9. Besondere Funktionalitäten: Mischen von Dokumenten-Eigenschaften

Implementiert ab CIB merge Version 3.9.174

In einem RTF können über den Editor (z.B. MS-Word) die Dokumenten-Eigenschaften (Doc-Properties) gesetzt werden. Beispiele dafür sind Autor, Titel, Abteilung, Projekt etc. Des Weiteren gibt es auch noch die sogenannten User-Properties. Der CIB merge behandelt Doc Properties und User-Properties gleich.

Über den Befehl INCLUDETEXT im Roh-RTF kann eine Dokumenten-Hierarchie aufgebaut werden. Jedes dieser RTFs kann eigene Dokumenten-Eigenschaften mitbringen. Der CIB merge mischt diese Dokumenten-Hierarchie zu einem einzigen Ausgabe-RTF.

Die Dokumenten-Eigenschaften des Ausgabe-RTFs bestimmen sich nach folgenden Regeln:

(bis CIB merge Version 3.12.2)

• Beim Zusammenmischen überschreibt das letzte RTF die Angaben der vorhergehenden, d.h. es "gewinnt" das tiefste RTF der Hierarchie.Bereits belegte 
• Properties werden nicht durch leere gelöscht.

Beispiel:

Ausgehend von der Aufruf-Hierarchie

WURZEL.rtf -> BAUST1.rtf -> BAUST2.rtf

mit folgenden Dokumenten-Eigenschaften der einzenen Dokumente:

WURZEL.rtf:                 Titel-W / Autor-W / Projekt-W
BAUST1.rtf:                  Titel-1 / Projekt-1 / Ablage-1
BAUST2.rtf:                  Titel-2 / Ablage-2 / Abteilung-2

erhält das das gemischte Ergebnisdokument folgende Dokumenten-Eigenschaften:
Titel-2 / Autor-W / Projekt-1 / Ablage-2 / Abteilung-2

(ab CIB merge Version 3.12.3)

• Beim Zusammenmischen werden die Dokumenten-Eigenschaften in der Misch-Reihenfolge „eingesammelt“. Dadurch hat immer die Wurzel Vorrang.
• Bereits belegte Properties werden dabei nicht überschrieben, es werden nur neue Eigenschaften ergänzt.

Beispiel:

Ausgehend von der Aufruf-Hierarchie

WURZEL.rtf -> BAUST1.rtf -> BAUST2.rtf

mit folgenden Dokumenten-Eigenschaften der einzenen Dokumente:

WURZEL.rtf:                 Titel-W / Autor-W / Projekt-W
BAUST1.rtf:                  Titel-1 / Projekt-1 / Ablage-1
BAUST2.rtf:                  Titel-2 / Ablage-2 / Abteilung-2

erhält das das gemischte Ergebnisdokument folgende Dokumenten-Eigenschaften:
Titel-W / Autor-W / Projekt-W / Ablage-1 / Abteilung-2

10. Anwendungsbeispiele

In diesem Kapitel werden anhand anschaulicher Beispiele die verschiedenen Aufrufparameter erklärt. An den entsprechenden Stellen wird dazu auf die ausführlichen Parameterbeschreibungen verwiesen.

Um die folgenden Beispiele zu testen, müssen die Binaries in einem Verzeichnis abgelegt werden, welches dann der PATH-Umgebungsvariablen hinzugefügt werden sollte. Um die Beispiele über die Kommandozeile auszuführen, müssen Sie sich im jeweiligen Verzeichnis befinden. Für jedes Beispiel gibt es eine ausführbare Batch-Datei.

Zum Zeitpunkt der Entwicklung der Anwendungsbeispiele kamen folgende Versionen zum Einsatz:

cibmrg32.dll, cibmrg32.exe: 3.9.171.0

CibJob32.dll: 1.4.20.0

CibChart.dll: 1.1.4.0

JComod.dll: 2.2.52.1

10.1. Anwendungsbeispiel Lückentext

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

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;
}

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

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

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

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;
}

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-mode=all
--default-prefix=Default.
…

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.

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:

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

--input-language=english

--output-language=english
…

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

--inputfile=Optimierung_in.rtf

--outputfile=!Optimierung_out.rtf

--optimize

#--short-tokens

#--compress=9

--filter=f

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.

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

--html-switches

--charformat=plain-values-only

--codepage=pca

--encrypt

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.

10.2. Anwendungsbeispiel Serienbrief

Allgemein

Soll die Zahlungserinnerung aus vorigem Beispiel nicht nur an einen Kunden verschickt werden, sondern an mehrere, kann dies ohne Änderungen am Anschreiben erfolgen. Nur die CSV-Datei muss um die zusätzlichen Daten der weiteren Kunden ergänzt werden. Die automatische Serienbrieffunktionalität ist am einfachsten so zu verstehen, dass um den Text herum eine gedankliche Schleife existiert, die die Steuerdatei weiterschaltet (implizite Schleife). Im Folgenden wird davon ausgegangen, dass Sie sich im Unterverzeichnis Serienbrief befinden.

Die CSV-Datei Adressen.csv enthält 4 Datensätze:

Vorname;Name;Strasse;PLZ;Ort;Geschlecht;KundenNr;AuftragsNr;Betrag
Max;Müller;Teststr. 3;99999;Testort;M;0987392;232222-4;123118
Franz;Meier;Teststr. 4;12345;Musterdorf;M;9898989;111111-2;999
Maria;Huber;Teststr. 5;54321;Testheim;W;1234567;876564-1;500
Franziska;Bauer;Teststr. 6;77777;Neumusterdorf;W;6665554;981234-0;3333
Franziska;Bauer;Teststr. 6;77777;Neumusterdorf;W;6665554;981234-0;3333

Einfacher Mischaufruf über die Kommandozeile

Folgender einfacher Kommandozeilenaufruf erzeugt den gewünschten Serienbrief (Serienbrief.bat):

cibmrg32.exe ..\Lueckentext\Anschreiben_in.rtf !Serienbrief_out.rtf
Adressen.csv

Das Anschreiben aus dem Lückentext-Beispiel dient als Eingabe, die Ausgabedatei heißt Serienbrief_out.rtf und als Datenquelle wird die erweiterte CSV-Datei mit 4 Datensätzen verwendet. CIB merge erzeugt in diesem Mischlauf automatisch einen Serienbrief, der für jeden Datensatz aus der CSV-Datei eine Zahlungserinnerung (durch Abschnittswechsel voneinander getrennt) enthält. Änderungen bei den Parametern oder im RTF sind nicht notwendig.

Serienbrief mit 3 Datensätzen als Multi-RTF

Es soll nun ein Serienbrief erzeugt werden, der nicht alle Datensätze enthält, sondern nur die ersten drei. Außerdem soll das Ergebnis ein Multi-RTF sein und nicht, wie bisher, ein durch Abschnittswechsel getrenntes RTF. Desweiteren soll die Information geliefert werden, wie viele Dokumente in diesem Mischlauf erzeugt wurden.

Aufgrund der Übersichtlichkeit, wird der Mischlauf wieder über eine Parameterdatei gesteuert, die neben Eingabe-, Ausgabe- und Datendatei die nötigen Parameter enthält, um das gewünschte Ergebnis zu erhalten (Serialletter.bat):

cibmrg32.exe --parameterfile=Serialletter_par.par

Inhalt der Parameterdatei Serialletter_par.par

Fehler sollen protokolliert werden

--logfile=!Serialletter_log.log

--inputfile=..\Lueckentext\Anschreiben_in.rtf
--outputfile=!Serialletter_out.rtf
--datafile=Adressen.csv

--serialletter=multi

--statistics=!count.txt
-mDer Mischvorgang verwendet folgende Ein- und Ausgabedateien:
-m@
--merge=3

Der Parameter --merge=3 startet den Mischlauf und verwendet alle zuvor gesetzten Parameter. Die Ziffer 3 gibt an, dass ein Serienbrief erzeugt werden soll, in dem die ersten drei Datensätze aus der Datenquelle verwendet werden.

Mit --serialletter=multi wird der Serienbrief als Multi-RTF erzeugt und nicht, wie default-mäßig eingestellt, ein Dokument, welches durch Abschnittswechsel die verschiedenen Datensätze beinhaltet.

Durch den Parameter --statistics wird eine weitere Datei erzeugt, die die Anzahl der generierten Dokumente enthält. In diesem Fall hat die Datei count.txt den Inhalt:

GeneratedDocumentCount=3

Serienbrief mit dynamischer Tabelle und Multi-CSV

Die Zahlungserinnerung soll nun um weitere Informationen ergänzt werden. Für jeden Kunden soll eine Übersicht der offenen Einzelposten auf einer separaten Seite aufgeführt werden.

Die Einzelposten müssen in geeigneter Form zur Verfügung gestellt werden. Am einfachsten erfolgt dies über eine zusätzliche CSV-Datei Einzelposten.csv. Um zu bestimmen, welche Einzelposten zu welchem Kunden gehören, enthält diese CSV-Datei für jeden Einzelposten die zugehörige Auftragsnummer des Kunden. Nach diesen Auftragsnummern sind die Zeilen sortiert (sowohl in der Datei Adressen.csv, als auch in der Datei Einzelposten.csv).

Nun muss angegeben werden, dass für diesen Mischlauf mehrere CSV-Dateien geladen werden sollen. Dies geschieht mit Hilfe einer Multi-CSV-Datei (multi.csv). Sie enthält die Namen aller CSV-Dateien, die im aktuellen Mischlauf geladen werden sollen. Über die Felder in der Kopfzeile der Multi-CSV-Datei, erhält jede CSV-Datei einen Alias zugeordnet, über den dann im Dokument auf diese CSV Dateien zugegriffen werden kann.

Auszug aus Adressen.csv:

Vorname;Name;Strasse;PLZ;Ort;Geschlecht;KundenNr;AuftragsNr;Betrag
Franz;Meier;Teststr. 4;12345;Musterdorf;M;9898989;111111-2;999
Max;Müller;Teststr. 3;99999;Testort;M;0987392;232222-4;123118
…

Auszug aus Einzelposten.csv:

KundeAuftragsNr;Bezeichnung;EinzelBetrag
111111-2;Artikel1;999
232222-4;Artikel1;18
232222-4;Artikel2;123100
…

multi.csv:

Kunden;Einzelposten
Adressen.csv;Einzelposten.csv

Im Anschreiben muss eine dynamische Tabelle eingefügt werden, die die einzelnen Posten auflistet.

Nach dem Text des Anschreibens wird hierfür ein Abschnittswechsel eingefügt. Die neue Seite enthält eine Tabelle mit der Auflistung aller zugehörigen Einzelposten. Dies erfolgt über eine Schleife.

Auszug aus Einzelposten_in.rtf

…
Der Auftrag {REF AuftragsNr } setzt sich aus folgenden Einzelposten zusammen:

{ IF { = AND({ MERGEREC ?Einzelposten};{ COMPARE { REF AuftragsNr } = { REF KundeAuftragsNr } })} = 1

{ NEXT Einzelposten }“ \* SOLANGE }
…

Solange ein Einzelposten vorhanden ist (Prüfung mit { MERGEREC ?Einzelposten}) und die KundeAuftragsNr der AuftragsNr des Kunden entspricht (COMPARE { REF AuftragsNr } = { REF KundeAuftragsNr }), wird die Bezeichnung und der Betrag des Einzelpostens in einer Tabelle ausgegeben und in der Einzelposten.csv zum nächsten Datensatz weitergeschaltet ({ NEXT Einzelposten }). Wären die Daten für den Vergleich rein numerisch, könnte auf das COMPARE verzichtet werden.

Die implizite Schleife bei der automatischen Serienbrieffunktionalität schaltet die Steuerdatei weiter. Wenn nun wie in diesem Fall mehrere Steuerdateien am Mischlauf beteiligt sind, würden alle Steuerdateien weitergeschalten werden. Da die Datei Einzelposten.csv jedoch im RTF selbst mit Hilfe des NEXT-Befehls weitergeschaltet wird, ist dies hier unerwünscht. Um das zu vermeiden wird deshalb eine explizite Schleife um das Anschreiben gesetzt und die Serienbrieffunktion ausgeschaltet.

Auszug aus Einzelposten_in.rtf

{ IF {MERGEREC ?Kunden } = 1“

…Hier folgt das komplette Anschreiben…

{ NEXT Kunden }{ IF {MERGEREC ?Kunden } = 1“… Hier Abschnittswechsel …“}“ \*SOLANGE }

Die Schleife durchläuft alle Kunden aus der Datei Adressen.csv und fügt nach jedem Anschreiben einen Abschnittswechsel ein, wenn es noch einen weiteren Kunden gibt.

Folgender Aufruf erzeugt den gewünschten Serienbrief mit dynamischer Tabelle (Einzelposten.bat):

cibmrg32.exe --parameterfile=Einzelposten_par.par

Fehler sollen protokolliert werden

--logfile=!Einzelposten_log.log

--inputfile=Einzelposten_in.rtf
--outputfile=!Einzelposten_out.rtf
--datafile=multi.csv

--multidatafile
-mDer Mischvorgang verwendet folgende Ein- und Ausgabedateien:
-m@

--merge=1

Als Eingabe dient die RTF-Datei Einzelposten_in.rtf. Diese enthält wie beschrieben zwei Schleifen, mit denen die Steuerdateien weitergeschaltet werden.

Der Parameter --multidatafile gibt an, dass es sich bei der Datei, die mit dem Parameter --datafile angegeben wird, um eine Multi-Steuerdatei handelt.

Wie bereits beschrieben, werden die Steuerdateien im RTF selbst weitergeschaltet. Eine Weiterschaltung, die sich durch die automatische Serienbrief-Funktionaltät ergibt, soll unterdrückt werden. Der Parameter --merge=1 führt den Mischlauf als Einzelmischlauf aus. Der Serienbrief wird hier also rein mit Hilfe von RTF-Feldbefehlen erzeugt.

Abbrechen des Mischlaufs über Fortschrittsanzeige

Die RTF-Datei Endlosschleife_in.rtf enthält durch ein vergessenes NEXT-Feld eine Endlosschleife. Unterläuft dem Textprogrammierer ein solcher Fehler, kann der Mischlauf nur über den Task-Manager abgebrochen werden. Um dies zu vermeiden soll im Folgenden ein Fortschrittsdialog angezeigt werden, über den ein Abbruch des Mischlaufs vorgenommen werden kann.

Folgender Aufruf startet den Endlos-Mischlauf mit Fortschrittsanzeige (Endlosschleife.bat):

cibmrg32.exe --parameterfile=Endlosschleife_par.par

Fehler sollen protokolliert werden

--logfile=!Endlosschleife_log.log

--inputfile=Endlosschleife_in.rtf
--outputfile=!Endlosschleife_out.rtf
--datafile=multi.csv

--multidatafile
-mDer Mischvorgang verwendet folgende Ein- und Ausgabedateien:
-m@

--dialog=top

--merge=1

Als Eingabe dient die RTF-Datei Endlosschleife_in.rtf. Diese produziert beim Mischlauf eine Endlosschleife.

Der Parameter --dialog=top setzt eine Fortschrittsanzeige in den Vordergrund, die auch einen Button zum Abbrechen des Mischlaufs enthält.

Serienbrief mit XML-Datenquelle und Aliasdefinition im RTF

Im Folgenden sollen die Daten nicht als CSV-Dateien übergeben werden, sondern als XML. Die Daten sollen in einer einzigen Datei Daten.xml stehen. Es soll keine Multi-CSV-Datei mehr verwendet werden.

Folgender Auszug aus der Datei Daten.xml zeigt eine mögliche Umsetzung der Daten von CSV nach XML:

<?xml version="1.0"
encoding="ISO-8859-1" ?>
<root>
      <data>
            <Kunden>
                  <Kunde>
                        <Vorname>Franz</Vorname>
                        <Name>Meier</Name>
                        <Strasse>Teststr. 4</Strasse>
                        <PLZ>12345</PLZ>
                        <Ort>Musterdorf</Ort>
                        <Geschlecht>M</Geschlecht>
                        <KundenNr>9898989</KundenNr>
                        <AuftragsNr>111111-2</AuftragsNr>
                        <Betrag>999</Betrag>
                  </Kunde>
                  weitere Kunden ......
            </Kunden>
            <Posten>
                  <Einzelposten>
                        <KundeAuftragsNr>111111-2</KundeAuftragsNr>
                   <Bezeichnung>Artikel1</Bezeichnung>
                     <EinzelBetrag>999</EinzelBetrag>
                  </Einzelposten>
                  weitere Einzelposten....
            </Posten>
      </data>
</root>

Die Aliasdefinitionen werden direkt in der RTF-Eingabedatei NextDef_in.rtf mit Hilfe des Befehls { NEXT ”DEF:Aliasname;<Dateipfad>” } angegeben. Mit dieser besonderen Variante des NEXT Schalters kann im laufenden Dokument einem aktuellen Aliasnamen eine neue Steuerdatei zugewiesen werden. Dieser Befehl lädt gleichzeitig automatisch den ersten Datensatz dieser Datei.

In diesem Fall stehen folgende Aliasdefinitionen im RTF:

{ NEXT ”DEF:Kunden;XML:{ REF XmlDateiname };/root/data/Kunden/Kunde“ }

{ NEXT ”DEF:Einzelposten;XML:{ REF XmlDateiname };/root/data/Posten/Einzelposten“ }

Um den Namen der XML-Datei nicht fest im RTF zu verdrahten wird hier stattdessen eine Variable XmlDateiname verwendet. Diese muss von außen über Parameter gesetzt werden. Hinter dem Dateinamen folgt durch Semikolon getrennt die XPath-Angabe zu den jeweiligen Daten. /root/data/Kunden/Kunde liefert alle <Kunde>-Knoten aus der Datei XmlDateiname.

Folgender Aufruf erzeugt den gewünschten Serienbrief mit XML-Datenversorgung (NextDef.bat):

cibmrg32.exe --parameterfile=NextDef_par.par

Fehler sollen protokolliert werden

--logfile=!NextDef_log.log

--inputfile=NextDef_in.rtf
--outputfile=!NextDef_out.rtf

--set=XmlDateiname=Daten.xml
-mDer Mischvorgang verwendet folgende Ein- und Ausgabedateien:
-m@

--merge=1

Als Eingabe dient die RTF-Datei NextDef_in.rtf. Diese enthält auch die Aliasdefinitionen für die XML-Daten.

Der Parameter --set weist der Variablen XmlDateiname den Wert Daten.xml zu. So kann der Dateiname von außen variabel gesetzt werden.

Durch die Aliasdefinitionen im Rohtext ist keine Multi-Steuerdatei mehr erforderlich. Die Parameter --datafile und --multidatafile können daher entfallen.

Da auch hier die Serie durch explizite Schleifen im Rohtext erzeugt wird, wird mit dem Parameter --merge=1 die Serienbrieffunktion ausgeschaltet.

Serienbrief mit XML-Datenquelle, Aliasnamen in XML-Datei, Verwendung von Präfixen

Jetzt sollen die Aliasdefinitionen nicht mehr im Rohtext stehen, sondern zusammen mit den Daten in der XML-Datei. Außerdem soll durch Verwendung von Präfixen im Rohtext die Eindeutigkeit der Variablen gewährleistet werden. Diese Präfixe sollen mit dem Trennzeichen „.“ dem Variablennamen vorangestellt werden.

Um dies zu realisieren, wird die Datei Daten.xml folgendermaßen erweitert. (Daten_mitAlias.xml)

<multi>
 <Kunden>XML:$(this);/root/data/Kunden/Kunde</Kunden>
 <Einzelposten>XML:$(this);/root/data/Posten/Einzelposten</Einzelposten>
</multi>

Das Konstrukt XML:$(this) gibt an, dass sich eine Aliasdefinition auf Daten bezieht, die in der selben XML-Datei stehen, in der sich die Aliasdefinition befindet.

Die Eingabedatei muss so erweitert werden, dass allen Variablennamen der jeweilige Alias gefolgt von einem Punkt vorangestellt wird.

Aus { REF Vorname } wird demnach { REF Kunden.Vorname } usw..

Wird die Variable Betrag z.B. sowohl bei Einzelposten, als auch bei Kunden verwendet, ist durch das Präfix die Eindeutigkeit sichergestellt. Die Parameter können wie immer über eine Parameterdatei definiert werden. Eine Alternative dazu wäre, die Parameter und Daten zusammen in einem sogenannten XML-Job bereitzustellen. Dieser kann ebenfalls über Kommandozeile ausgeführt werden. Ausführungsvarianten über Java und C++ werden im Folgenden ebenfalls erläutert.

Folgender Aufruf erzeugt den gewünschten Serienbrief mit XML-Datenversorgung (Prefix.bat):

cibmrg32.exe --parameterfile=Prefix_par.par

Inhalt der Datei Prefix_par.par:

Fehler sollen protokolliert werden

--logfile=!Prefix_log.log

--inputfile=Prefix_in.rtf
--outputfile=!Prefix_out.rtf

--headerfile=XML:Daten_mitAlias.xml

--datafile=/root/multi
--multidatafile

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

--merge=1

Als Eingabe dient die RTF-Datei Prefix_in.rtf, welche wie beschrieben um Aliasnamen bei den Variablen erweitert wurde.

Der Parameter --headerfile gibt die zu verwendende Datenquelle (Daten_mitAlias.xml) an und der Parameter --datafile den XPath zu den Aliasnamen.

Durch Hinzufügen des Aufrufparameters --multidatafile, interpretiert CIB merge dann die Aliasdefinitionen selbständig und stellt die zugehörigen Aliasnamen bereit.

Dadurch können die {next}-DEF-Feldanweisungen im Rohtext entfallen.

Der Parameter --prefix-delimiter definiert den Punkt als Trennzeichen zwischen Alias und Variablennamen. Der Rohtext muss so erweitert werden, dass allen Variablen der entsprechende Alias gefolgt von diesem Trennzeichen vorangestellt wird.

Das Ergebnis wird in die Datei Prefix_out.rtf geschrieben.

Aufruf eines XML-Jobs über Kommandozeile

Liegen die Daten ohnehin als XML vor, ist es möglich, die Parameter ebenfalls in einem XML zu setzen. So lassen sich die Daten und die Parameter in einer einzigen XML-Datei unterbringen. In einem sogenannten merge-Step werden alle notwendigen Properties gesetzt. Diese Job-XML (PrefixJob.xml) kann dann folgendermaßen über die Kommandozeile aufgerufen werden (PrefixJob.bat):

cibrsh.exe -d PrefixJob.xml

Auszug aus der Datei PrefixJob.xml (Kommentare beginnen mit <!-- und enden mit -->)

<step name="merge" command="merge">
<!-- Liste der Properties für diesen Step -->
<properties>
      <!-- Daten werden in diesem XML mitgegeben -->
      <property name="--logfile">!PrefixJob_log.log</property>
      <property name="--inputfile">Prefix_in.rtf</property>
      <property name="--outputfile">!Prefix_out.rtf</property>
      <property name="-h">XML:$(inline)</property>
      <property name="--datafile">/root/multi</property>
      <property name="--multidatafile"/>
      <property name="--prefix-delimiter"/>
      <property name="-@">1</property
</properties>
</step>
      

Die Daten, die zuvor über die Datei Daten_mitAlias.xml bereitgestellt wurden, können direkt mit in der PrefixJob.xml übergeben werden. Dies wird mit XML:$(inline) beim Parameter -h angegeben. Hier muss explizit die Kurzschreibweise -h verwendet werden, da diese genau so erwartet wird. Das gleiche gilt für -@.

Die Daten aus Daten_mitAlias.xml können dann direkt in die PrefixJob.xml übernommen werden, indem sie direkt unterhalb des <root>-Knotens eingefügt werden.

Aufruf eines XML-Jobs über Java

Wird ein XML-Job verwendet, kann dieser auch über Java ausgeführt werden. Hierfür wird die Klasse JCibJobJob verwendet. In folgendem kleinen Java-Programm wird ebenfalls die Datei PrefixJob.xml ausgeführt:

Auszug aus MergeJob.java:

…
JCibJobJob t_Job = new JCibJobJob();
t_Job.initialize();
if (!t_Job.isInitialized())
{
            // Fehler beim Initialisieren
            System.err.println("Fehler beim Initialisieren");
            System.exit(1);
}
try
{
 t_Job.setProperty(ICibJobJob.PROPERTY_INPUTFILENAME,
"PrefixJob.xml");
            //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();
}
…

Verhalten von NEXT bei fehlenden Variablen festlegen

Im Folgenden fehlt in einem Datensatz ein XML-Knoten. Die Datei Daten.xml wird so angepasst, dass im dritten Kunden-Datensatz der Knoten <KundenNr> fehlt (Daten_NextMode.xml). Im Ergebnis würde an der Stelle, an der diese Variable eingesetzt wird, einfach nichts stehen. Im Folgenden soll eine Variable, die in einem Datensatz enthalten ist, im nächsten jedoch nicht mehr, gelöscht werden. Dies soll zu einem Fehler führen und der Mischvorgang soll abgebrochen werden.

Folgender Aufruf erzeugt das gewünschte Verhalten (NextMode.bat):

cibmrg32.exe --parameterfile=NextMode_par.par

Inhalt der Datei NextMode_par.par:

Fehler sollen protokolliert werden

--logfile=!NextMode_log.log

--inputfile=NextDef_in.rtf
--outputfile=!NextMode_out.rtf

--set=XmlDateiname=Daten_NextMode.xml
-mDer Mischvorgang verwendet folgende Ein- und Ausgabedateien:
-m@

--next-mode=delete

--merge=1

Der Parameter --next-mode bewirkt mit der Belegung „delete“, dass die fehlende Variable KundenNr gelöscht wird und somit nicht mehr definiert ist. Es kommt zu einem Fehler

unbekannte Variable:
Name: KundenNr

und der Mischvorgang wird abgebrochen.

10.3. Anwendungsbeispiel Report mit mehreren Bausteinen

Allgemein

Im Folgenden wird davon ausgegangen, dass Sie sich im Unterverzeichnis „Bausteine“ befinden. Das folgende Beispiel beinhaltet ein Anschreiben einer Bank an einen Kunden, das über den aktuellen Status seiner Konten informiert. Es enthält eine Auflistung seiner Konten, inklusive Kontoart, aktuellen Salden und eine Summe der Salden. Außerdem ist ein Bankenlogo eingebunden. Dies erfolgt im RTF über den Feldbefehl { INCLUDEPICTURE „Logo.jpg“}.

Die Daten liegen in mehreren CSV-Dateien vor. Diese beinhalten Kundendaten (knd_kunde.csv), Informationen über seine Konten (kont_konten.csv), die Daten der Bank (bnk_bank.csv) und Informationen zu seinem Ansprechpartner (ber_berater.csv). Es ist sinnvoll die Datenquellen in einem separaten Verzeichnis abzulegen. In diesem Fall liegen die Dateien im Unterverzeichnis „csv“.

Dieses Mal ist der Brief nicht in einer einzigen RTF-Datei untergebracht, sondern auf mehrere Bausteine aufgeteilt. Diese RTF-Bausteine befinden sich ebenfalls in einem separaten Unterverzeichnis „templates“. Es gibt einen Wurzelbaustein (wurzelbaustein.rtf), der mehrere Bausteine anzieht. Dies geschieht mit Hilfe des Feldbefehls { INCLUDETEXT „Baustein.rtf“ }. Unter anderem gibt es Bausteine für Kopf- und Fußzeilen (unterschiedliche für erste Seite und Folgeseiten), für das Anschreiben und für die Kontenübersicht.

Die Kontenübersicht ist als dynamische Tabelle realisiert, welche bereits im Anwendungsbeispiel Serienbrief näher erklärt wurde:

{ SET Saldo_Summe 0 } { IF { MERGEREC ?Konten } = 1

{ SET Saldo_Summe { = { REF Saldo_Summe } + { REF kont_saldo } } }{ NEXT Konten }" \* SOLANGE }

Um eine Summe über die Salden zu bilden, wird vor der Schleife eine Variable Saldo_Summe mit Hilfe des SET-Feldbefehls definiert und auf 0 gesetzt. In der Schleife wird für jedes Konto der zugehörige Saldo hinzuaddiert. Am Ende wird eine Gesamtsumme ausgegeben.

Das Ergebnis soll ebenfalls in ein eigenes Unterverzeichnis „result“ geschrieben werden.

Verwendung von Unterverzeichnissen für Datenquellen und RTF-Bausteine

Folgender Aufruf erzeugt den fertigen Brief inklusive Kontenübersicht (Bausteine.bat):

cibmrg32.exe --parameterfile=Bausteine_par.par

Inhalt der Datei Bausteine_par.par

Fehler sollen protokolliert werden

--logfile=!Bausteine_log.log

--target-directory=csv

--source-directory=..\templates

--inputfile=wurzelbaustein.rtf

--outputfile=!..\result\Kontenuebersicht.rtf

--datafile=multi.csv
--multidatafile
--charformat

Das Beispiel setzt mit Hilfe des Parameters --target-directory die Pfadangabe für die Datendateien. Somit ist keine explizite Pfadangabe beim Parameter --datafile erforderlich. Hier reicht es, den Dateinamen der Multi-CSV anzugeben. Alle weiteren CSV-Dateien werden dann ebenfalls in diesem Verzeichnis erwartet.

Der Parameter --source-directory setzt das Verzeichnis, in dem das RTF-Wurzeldokument und die RTF-Bausteine erwartet werden. Der Pfad ist relativ zu dem Pfad, der mit --target-directory angegeben wurde. Durch das Setzen dieses Aufrufparameters, ist keine explizite Pfadangabe beim Parameter --inputfile erforderlich. Hier reicht es, den Namen des Wurzelbausteins anzugeben. Alle weiteren Bausteine werden dann ebenfalls in diesem Verzeichnis erwartet. (sofern keine expliziten Pfadangaben mit INCLUDETEXT gemacht werden).

Das Ergebnis Kontenuebersicht.rtf wird durch eine explizite Pfadangabe in das Unterverzeichnis „result“ geschrieben. Wäre hier kein Pfad angegeben, würde das Ergebnis nach --target-directory geschrieben werden.

Der Parameter --multidatafile gibt an, dass es sich bei der Datei, die mit dem Parameter --datafile angegeben wird, um eine Multi-Steuerdatei handelt.

Optimierungen für Bausteine mit neuen Farben, Schriften, Listen steuern

In den Bausteinen werden neue Farben, Schriften und Listen verwendet. Standardmäßig sind diese auch im Ergebnisdokument enthalten, da der RTF-Kopf am Ende neu geschrieben wird. Hier sind unterschiedliche Optimierungen möglich, die wahlweise durch den Benutzer abgeschaltet werden können. Im Folgenden sollen die neuen Schriften ignoriert werden, alle Farben sollen aber enthalten sein, auch die, die nicht benutzt werden. Dies ist zum Beispiel dann sinnvoll, wenn ein Drucker nur bestimmte Schriftarten drucken kann. Da das Dokument nach dem Mischlauf eventuell noch bearbeitet wird, sollen hier auch alle verwendeten Listen zur Verfügung stehen. Unbenutzte Listen sollen jedoch entfernt werden.

Folgender Aufruf erzeugt das gewünschte Ergebnis (Header.bat):

cibmrg32.exe --parameterfile=Header_par.par

Auszug aus Header_par.par:

…
--replace-header=automatic
--fonts=keep
--colors=expand
--lists=adjust

Ohne den Parameter --replace-header werden sowohl die Schriften und Listen, als auch die Farben in das Ergebnis-RTF übernommen. --replace-header=automatic bewirkt hier, dass der RTF-Kopf unter Berücksichtigung der Belegungen der Parameter --fonts, --lists und --colors neu geschrieben wird.

Der Parameter --fonts mit der Belegung „keep“ bewirkt, dass die Haupt-Schriftartentabelle nicht um die neuen Schriften erweitert wird. Es wird auch keine zusätzliche Optimierung durchgeführt, welche die unbenutzen Schriftarten entfernt.

Der Parameter --colors mit der Belegung „expand“ bewirkt, dass die Haupt-Farbtabelle um neue Farben erweitert wird und unbenutzte Farben nicht entfernt werden.

Der Parameter --lists mit der Belegung „adjust“ bewirkt, dass die Haupt-Listentabelle um neue Listen erweitert wird, unbenutzte Listen aber entfernt werden.

Zeipunkt des Abbruchs beim Auftreten von Fehlern festlegen

CIB merge bricht die Verarbeitung ab, wenn zum Beispiel eine Variable eingesetzt wird, die nicht definiert ist. Im Folgenden wird statt der korrekten CSV-Datei kont_konten.csv die CSV-Datei kont_konten_undef.csv verwendet. In dieser ist die Variable kont_kontoart falsch geschrieben (kont_kontart). Wird nun ein Mischlauf gestartet, der diese fehlerhafte CSV-Datei verwendet, entsteht ein Ergebnis-RTF mit einer defekten Tabelle. (OhneBreak_out.rtf).

Folgender Aufruf erzeugt das RTF mit defekter Tabelle (OhneBreak.bat):