The following example is located in the subdirectory Lueckentext (gap text). Its usage is a cover letter, which is available as RTF. It contains variables that are to be filled from a data source. This is a CSV file with the data of the recipient. The result of the merge process is a payment reminder that contains the customer data from the CSV file.

Calling the CIB merge help
Simplest form of a merge process (IOD)
Calling single parameters via command line
Calling single parameters via JAVA
Calling single parameters via C++
Calling the parameter file via command line
the parameter file via JAVA
Optimizing raw texts before delivery

---

Calling the CIB merge help

The CIB merge help cannot be displayed on the console under Windows because it is a windowed application to display a progress dialog during the merge process (see parameter --dialog). To get an overview of all possible call parameters, the help can be output to a file. To do so, enter the following call in the command line, or execute the batch file hilfe.bat.

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

The help is redirected to the file help.txt and is structured as follows:

Usage of CIB merge:

>CIBMRG32 <Parameter1> <P2> ...

Each parameter should start with a start character from "-/".

 

Otherwise, the first parameters without a start character are assigned the parameter characters from "IODH" in sequence.

After evaluation of all parameters "/@" is executed automatically.

 

Parameter            : Effect

Q<working directory> : sets the working directory (has to be at the beginning!)

A<template directory>           : sets the template directory

I<input>                                 : sets RTF input source

?                                              : show help page

Further parameters

Simplest form of a merge process (IOD)

The simplest form of a merge process is to fill an input file with data and write the result to an output file. This can be specified using the individual parameters --inputfile (I), --outputfile (O) and --datafile (D). The following describes how these parameters can be specified on the command line. Furthermore, variants for control from JAVA and C++ are presented.

Calling single parameters via command line

To mix an input file with data and write it to an output file, a simple call on the command line is sufficient. The --inputfile call parameter is used to specify the file that serves as input file for the merge process. The parameter --datafile specifies the name of the data source and --outputfile specifies the output file.

The following call supplies the input file Anschreiben_in.rtf with the data from Adresse.csv (which is located in the same directory) and writes the result to the output file Anschreiben_out.rtf, overwriting any existing file.

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

If the order IODH (inputfile, outputfile, datafile, headerfile) is kept, the parameters can be omitted. The following call then leads to the same result (Anschreiben.bat):

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

Calling single parameters via JAVA

Instead of setting the parameters via the command line, the control can also be done via JAVA. The same result is achieved with the following JAVA code

 (MergeEinzelneParameter.java) achieved:

Excerpt from 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();
}
…

Here the job class is used for the usage of the CIB merge from Java. With the JCibMergeJob a mixed job from Java can be passed to the CIB merge. The job class first collects the parameters that are set with setProperty. CIB merge is then called with execute().

Calling single parameters via C++

If a control via C++ is desired, cibmerge(int argc, char *argv[]) usage is required. This way the desired parameters can be set. The directory C:\\comod\\, which contains the CIB modules, must be adapted accordingly. This directory is required for the initialization of CIB merge.

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

• Logging and usage of another separator in the data source

In the following, possible occurring errors are to be logged in a log file and in this file also contains messages as well as information about the program version used are to be output. Furthermore, the data source is structured in such a way that instead of the character ";" a comma is used as separator in the CSV file.

To realize this, additional call parameters must be considered during the merge process. This makes a call from the command line slightly confusing. In this case it is advisable to store the parameters in a parameter file. This parameter file can then be called via the command line. The variants how the parameter file can be executed via JAVA and C++ are also explained in the following.

Calling the parameter file via command line

The parameters required for this merge process are all located in the file Komma_par.par. If CIB merge is called from the command line, the parameter file is specified using the call parameter --parameterfile (Komma.bat):

cibmrg32.exe --parameterfile=Komma_par.par

All lines that do not begin with "--" or "-" in the parameter file are comments (parameters indented with spaces are also comments).

Content of the parameter file Komma_par.par:

Errors shall be logged

--logfile=!Komma_log.log
--version

Involved files for the merge process

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

Here the comma is the separator in the CSV

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

• Explanations

Besides the already described call parameters --help, --inputfile, --datafile and --outputfile, the parameter file contains further call parameters that are taken into account during the merge process.

The --logfile parameter creates a file to which all errors occurring during the merge process are written. The log file is generated without path specification in the current working directory, so after the merge process the following text is also in the log file:

CIB merge 3.9.171
CIB software GmbH 1991-2009

This software is protected by copyright law and international treaties protected. Unauthorized duplication and distribution, independent in what way or by what means, electronically or mechanically and independently for what purpose, whether in whole or in part, may have serious civil and criminal consequences and is punished to the fullest extent of the law.

The mixing process uses the following input and output files:
Input file:                     Anschreiben_in.rtf
Control file:      Adresse_Komma.csv
Data set file:
Output file:                  Komma_out.rtf
log file:                        Komma_log.log
…

As delimiter in the CSV file the comma character is defined with the --delimiter parameter. The CSV file Adresse_Komma.csv therefore looks like this

first name,last name,street,postal code,city,gender,customer no,order no,amount,Max,Müller,Test Street 3,99999,Test City,M,0987392,232222-4,123118

Calling the parameter file via JAVA

Instead of setting the parameter file via the command line, it can also be called via JAVA. The same result is achieved with the following JAVA code (MergeParameterfile.java):

Extract from 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();
}
…

Calling the parameter file via C++

If the control is done via C++, the corresponding parameter file can be executed with the help of CibMergePFile. The directory C:\\comod\\, in which the CIB modules are located, must be adapted accordingly, since it is required for the initialization of CIB merge.

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

• Set default behavior for undefined/empty variables

Now a defined default value should be output in the result RTF if a variable cannot be filled by the data supply or if it is empty. For this purpose, the value "<unknown value>" in red letters is assigned to a variable named "Default" in the Default_in.rtf RTF file using the SET field command.{ SET Default. „<unbekannter Wert>“ }

All empty or undefined variables should get this value. The CSV file Adresse_Default.csv is modified so that there is no value for the variable City. To support this behavior, it is necessary to set additional parameters.

The following call starts the merge process with desired default behavior (Default.bat):

cibmrg32.exe --parameterfile=Default_par.par

Extract from parameter file Default_par.par:

…
Involved files for the merge process

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

Setting Default behavior

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

• Explanation

The --default-mode parameter defines in which cases the default behavior, i.e. the insertion of a substitute value, should be activated. In this case, a default value should be inserted, if a variable cannot be filled by the data supply, because it is not defined or because it is empty. If the behavior is to apply only to undefined variables, the default mode must be set to "undefined" (instead of "all").

The prefix, which is prefixed to unknown/empty variables, is defined with the parameter --default-prefix. Here it is the prefix "Default". For the variable Location no value was found in the data source, so it is checked if a value for Default.Location is defined. Since this is also not the case, the value that is defined for "Default. namely "<unknown value>". The result can be found in the file Default_out.rtf.

• Set input and output language for number format/date format

The RTF Language_in.rtf has been modified to include a number format switch for formatting the invoice amount. The amount should now be displayed with thousands separators and 2 decimal places. The cover letter is written in English. Accordingly, in this case, the number format is specified in English. The output of the numbers should also be in English number format. In the RTF, the following expression is therefore displayed:

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

In order to achieve a correct display in the result document, the parameters must be set to indicate that the input is an English number formatting (and not a German one, as assumed by default). To keep this formatting in the output document, an additional parameter must be set.

The following call starts the merge process to create the English payment reminder (Language.bat):

cibmrg32.exe --parameterfile=Language_par.par

Extract from the parameter file Language_par.par:

…
Involved files for the merge process:

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

Input format for numbers is in English

--input-language=english

Output format for numbers and date is in English

--output-language=english
…

• Explanations

The calling parameter --input-language=English indicates that the number format specification in the RTF is in English. In order to achieve a correct display in the result, this information must be given, otherwise it is automatically assumed that the formatting is German, which may lead to unwanted results.

To get the numbers and dates in the result document also in English, the call parameter --output-language is set.

The field { DATE \@ "dddd, d.MM.jjjj" } appears in the result document e.g. as "Friday, 23.10.2009. (German: Freitag, 23.10.2009)

The field {REF Amount \# #,####0.00 } will be formatted to "123,118.00" for an amount of 123118. (German: 123.118,00)

Optimizing raw texts before delivery

In the following, we will demonstrate how to optimize and compress RTF templates. Especially in large projects this plays a role. The optimization is shown exemplarily with the RTF file Optimierung_in.rtf. This file contains some \* MERGEFORMAT switches, which MS Word partially inserts when inserting or reformatting REF fields. These switches should be removed from the RTF. Other ways to speed up the processing in CIB merge and CIB format is to use short tokens. The usage of short tokens offers additional protection against manipulation, because the file can only be processed with CIB modules. If the files are exchanged between different machines, a transfer can be accelerated by compressing the file before. All these steps should be performed without interfering with field contents. Which combination of optimizations makes sense depends on the respective environment and field of application. To test the effects of the various parameters, the respective parameters can be commented ("#" in the respective line can be removed).

The following call optimizes the input file (Optimierung.bat):

cibmrg32.exe --parameterfile=Optimierung_par.par

 

Content of the parameter file Optimierung_par.par:

Errors shall be logged

--logfile=!Optimierung_log.log

Input file

--inputfile=Optimierung_in.rtf

Output explicitly in own directory

--outputfile=!Optimierung_out.rtf

Remove Mergeformat switch

--optimize

Use short tokens

#--short-tokens

Compress

#--compress=9

Do not interfere with content

--filter=f

• Explanations

The --optimize parameter removes all MERGEFORMAT switches in RTF. This makes the file a bit smaller and more readable.

The --short-tokens parameter creates an output file with shortened CIBrtf tokens (CIBRtf). The shortened RTF commands in the output result in a smaller result file compared to the RTF. This leads to an accelerated processing in CIB merge and CIB format. In addition, the file can only be further processed with CIB modules.

The --compress parameter creates a compressed output file. Here the highest compression level 9 was selected. Compression reduces the file size considerably. Additional usage of --short-tokens would not result in a noticeable size advantage.

The --filter parameter the field contents are not evaluated. The assignment "f" (almost) also prevents the field contents from being parsed and translated.

Another way to filter out unneeded fields from the RTF is to use the --field-results parameter, which removes all field-results that are not relevant in CIB format. These field-results are mainly found in the RTF when other blocks are attracted with {INCLUDETEXT}. Therefore, the parameter is introduced in the application example.

• Further possibilities for additional calling parameters

Now a postprocessing in the CIB dialog shall be controlled by switches in the RTF. The output shall be generated encrypted. The data is now created by the application in the code page PCA. In RTF the "\* CHARFORMAT" switch should not have to be set manually for each field.

The parameter file Zusatz_par. contains the necessary additional parameters to support this (Zusatz.bat):

cibmrg32.exe --parameterfile=Zusatz_par.par

Involved files for the merge process

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

Understanding additional switches for HTML output

--html-switches

Accept field formatting despite switch

--charformat=plain-values-only

Support CSV with PCA character set

--codepage=pca

Encrypt output

--encrypt

• Explanations

In the RTF module Zusatz_in.rtf, fields with additional switches are defined, which play a role when converting to HTML. In this example, these are single-line text fields which can be filled in via CIB dialog ({ REF first_name\* <cib-formfield type="text" info="first_name" testvalue="Max" /> }). To understand these additional switches, the parameter --html-switches has to be set.

The --charformat=plain-values-only parameter causes the fields that are equipped with such an additional switch to still retain the formatting of the field. In this case the fields First Name and Last Name are formatted bold. After the merge process, these fields are also displayed in bold, although they contain additional switches.

The used CSV file (address_pca.csv) uses the PCA character set. To display the data correctly (e.g. umlauts), the parameter --codepage=pca must be set.

The --encrypt parameter encrypts the output file Zusatz_out.rtf. Further processing with CIB modules is still possible.