General
Usage of subdirectories for data sources and RTF templates
Optimizations for templates with new colors, fonts, control lists
Define time of cancellation when errors occur
Handling unsupplied fields
Removing field results from raw text
Insert dynamic business graphics embed graphics
Analysis of the field structure in RTF templates

---

General

The following assumes that you are in the "Templates" subdirectory. The following example contains a letter from a bank to a client informing him of the current status of his accounts. It contains a list of his accounts, including account type, current balances and a total of the balances. A bank logo is also included. This is done in RTF using the field command

{ INCLUDEPICTURE „Logo.jpg“}.

The data is available in several CSV files. These contain customer data (knd_kunde.csv), information about his accounts (kont_konten.csv), bank data (bnk_bank.csv) and information about his contact person (ber_berater.csv). It is useful to store the data sources in a separate directory. In this case the files are located in the subdirectory „csv“.

This time the letter is not in a single RTF file, but is divided into several blocks. These RTF templates are also located in a separate subdirectory "templates". There is a root templates (wurzelbaustein.rtf), which attracts several building blocks. This is done with the field command { INCLUDETEXT "Baustein.rtf" }. Among other things, there are templates for headers and footers (different for the first page and subsequent pages), for the cover letter and for the account overview.

The account overview is realized as a dynamic table, which was already explained in detail in the application example serial letter:

LfdNo	AccountNo	Balance	AccountType

{ SET Balance_Sum 0 } { IF { MERGEREC ?Accounts } = 1

“{ MERGEREC Accounts }	{ REF Acc_AccountNo }	{ REF Acc_Balance \# 0,00 }	{ REF Acc_AccountType }

{ SET Balance_Sum { = { REF Balance_Sum } + { REF Acc_Balance } } }{ NEXT Account }" \* WHILE }

Sum balances	{ REF Balance_Sum \# 0,00 }

To form a sum over the balances, a variable Balance_Sum is defined before the loop using the SET field command and set to 0. In the loop, for each account the corresponding balance is added. At the end, a grand total is output.

The result should also be written in a separate subdirectory "result".

Usage of subdirectories for data sources and RTF templates

The following call creates the finished letter including account overview (Bausteine.bat):

cibmrg32.exe --parameterfile=Bausteine_par.par

Content of the file Bausteine_par.par

Errors shall be logged

--logfile=!Bausteine_log.log

Data sources can be found under this path

--target-directory=csv

Templates are located (relative to target) here

--source-directory=..\templates

Input file (can be found in source)

--inputfile=wurzelbaustein.rtf

Output explicitly to own directory

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

Data source is multi-CSV

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

• Explanations

The example uses the --target-directory parameter to set the path for the data files. Thus, no explicit path specification is required for the parameter --datafile. Here it is sufficient to specify the file name of the multi-CSV. All further CSV files are then also expected in this directory.

The --source-directory parameter sets the directory where the RTF root document and RTF templates are expected. The path is relative to the path specified with --target-directory. By setting this call parameter, no explicit path specification is required in the --inputfile parameter. Here it is sufficient to specify the name of the root module. All further templates are then also expected in this directory (if no explicit path specification is made with INCLUDETEXT).

The result Kontenuebersicht.rtf will be written though an explicit filepath in the subdirectory „result“. If no path were specified here, the result would be written to --target-directory.

The --multidatafile parameter specifies that the file with the --datafile parameter is a multi-control file.

Optimizations for templates with new colors, fonts, control lists

New colors, fonts and lists are used in the templates. By default these are also included in the result document, because the RTF header is rewritten at the end. Here different optimizations are possible, which can be switched off by the user. In the following the new fonts should be ignored, but all colors should be included, even those that are not used. This is useful, for example, if a printer can only print certain fonts. Since the document may still be edited after the merge process, all usage lists should be available here. Unused lists, however, should be removed.

The following call produces the desired result (Header.bat):

cibmrg32.exe --parameterfile=Header_par.par

Extract from Header_par.par:

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

• Explanations

Without the --replace-header parameter, the fonts and lists as well as the colors are included in the result RTF. --replace-header=automatic causes the RTF header to be rewritten taking into account the settings of the parameters --fonts, --lists and --colors.

The --fonts parameter with the assignment “keep“ causes that the main font table is not extended by the new fonts. Also no additional optimization is performed, which removes the unused fonts.

The --colors parameter assigned to “expand” causes new colors to be added to the main color table and unused colors are not removed.

The --lists parameter with assignment „adjust” causes new lists to be added to the main list table, but unused lists are removed.

Define time of cancellation when errors occur

CIB merge aborts the processing if, for example, a variable is used which is not defined. In the following, instead of the correct CSV file kont_konten.csv, the CSV file kont_konten_undef.csv is used. In this file the variable kont_kontoart is written incorrectly (kont_kontart). If now a merge process is started, which uses this incorrect CSV file, a result RTF with a defective table is created. (OhneBreak_out.rtf).

The following call creates the RTF with defective table (OhneBreak.bat):

cibmrg32.exe --parameterfile=OhneBreak_par.par

Extract from OhneBreak_par.par:

…
--outputfile=!..\result\OhneBreak_out.rtf
--datafile=multi_undef.csv
…

The merge process should now be continued, if possible, although the variable kont_kontoart is not defined. The table should still be output in such a way that a valid RTF is generated. Afterwards, however, the mixing process should be aborted.

The following call creates the desired result (BreakLoop.bat):

cibmrg32.exe --parameterfile=BreakLoop_par.par

The following parameter is additionally set here:

--break=loop

Now, even if errors occur, the mixing process should be carried out to the end and return an error.

The following call produces the desired result (BreakNever.bat):

cibmrg32.exe --parameterfile=BreakNever_par.par

The following parameter is set here:

--break=never

• Explanations

The --break parameter shifts the point in time at which CIB merge stops the mixing process in case of an error.

With --break=loop the following behavior is achieved: if the merge process is currently in a loop, it is only run to the end after the error, i.e. it is not repeated. Immediately afterwards the mixing process will be aborted.

--break=never causes CIB merge to execute the merge job to the end regardless of any errors and returns the error code of the first error.

Handling unsupplied fields

In some cases it may be desirable that a certain variable is not supplied by the data sources (e.g. for a possible later residual data acquisition). In the following, the variable kont_kontoart is intentionally not defined (the same input files can be used as in the previous example). In this case, the merging process should be continued and all unsupplied fields should remain as REF fields in the output file.

The following call produces the desired result (KeepFields.bat):

cibmrg32.exe --parameterfile=KeepFields_par.par

The following parameter is additionally set here:

--keep-fields=unresolved-ref

• Explanations

The --keep-fields=unresolved-ref parameter ensures that the merging process is continued despite missing data supply for the variable kont_kontoart and that the REF field for kont_kontoart in the output file KeepFields_out.rtf is preserved.

Removing field results from raw text

MS Word inserts so-called field results into the raw text, most of which are not required by the CIB modules. By the INCLUDETEXT statements in wurzelbaustein.rtf the RTF contains some of these unnecessary field results. To optimize the file size, most of them can be removed. The result should no longer contain unnecessary field results.

The following call produces the desired result (FieldResults.bat):

cibmrg32.exe
--parameterfile=FieldResults_par.par

The following parameters are set here:

Errors should be logged

--logfile=!FieldResults_log.log

Data sources can be found under this path

--target-directory=csv

Templates are located (relative to target) here

--source-directory=..\templates

Input file (to find in source)

--inputfile=wurzelbaustein.rtf

Output explicitly to own directory

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

Remove field-results

--field-results=p

Do not merge contents

--filter=f

• Explanations

The unnecessary field-results inserted by MS Word are removed by the --field-results parameter. By assigning a "p", those necessary for positioning images are retained.

Insert dynamic business graphics embed graphics

In the following, the overview of the account types will be presented graphically in a pie chart. For this purpose, a new CSV file is created which contains the distribution of the assets per investment type (investment type.csv). This CSV file looks like this:

Anlageform;Wert;Legende
Girokonto;530,46;Girokonto 0,56%
Sparkonto;16.700,00;Sparkonto 17,67%
Festgeld;74.000,00;Festgeld 78,29%
Depot;3.288,33;Depot 3,48%

This file contains the legend of the chart and the sum of the balances per investment. The file Vermoegensstruktur_torte.emf contains the graphic template that is to be used to create the dynamic business graphic. This graphic and the logo (Logo.jpg), which is inserted in the module Logo.rtf, should be embedded in the result RTF.

The following call generates the desired result (Chart.bat):

cibmrg32.exe --parameterfile=Chart_par.par

The following parameters are set here:

Errors shall be logged here

--logfile=!Chart_log.log

Data sources can be found under this path

--target-directory=csv

Templates are located (relative to target) here

--source-directory=..\templates

Input file (to find in source)

--inputfile=wurzelbaustein_chart.rtf

Output explicitly to own directory

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

Data source is multi-CSV

--datafile=multi_chart.csv
--multidatafile
--charformat

Setting the chart parameters

--chart-source=file
--chart-target=embed
--merge=1

Explanations

With --chart-source=file specifies that the business graphic should be calculated from the graphic inserted with { INCLUDEPICTURE }.

The --chart-target=embed specifies that all graphics should be embedded in the result RTF (both chart and non-chart graphics).

Analysis of the field structure in RTF templates

In the following, the field structure of the RTF modules is to be determined. The result is to be written into a CSV file Felder.csv This file contains all variables which could be evaluated by an application.

The following call generates the desired result (Analyse.bat):

cibmrg32.exe --parameterfile=Analyse_par.par

The following parameters are set here:

--logfile=!Felder.csv
-mPfad;Feld;Wert
--logfile=!Analyse_log.log
--source-directory=templates
--outputfile=-
--analyse=+Felder.csv

# for every text

--inputfile=Basisbaustein.rtf
-m@
--filter
--inputfile=Bezug.rtf
-m@
--filter

... für jeden RTF-Baustein...

--inputfile=wurzelbaustein.rtf
-m@
--filter
-mdone

• Explanations

The --analyse parameter creates the file Felder.csv, which looks like this after the analysis run (excerpt):

Pfad;Feld;Wert
Basisbaustein.rtf;REF;knd_geschlecht
Basisbaustein.rtf;REF;knd_nachname
Basisbaustein.rtf;REF;ber_vorname
Basisbaustein.rtf;REF;ber_nachname
Basisbaustein.rtf;REF;ber_vorname
Basisbaustein.rtf;REF;ber_nachname
Bezug.rtf;REF;knd_bezug
Briefkopf.rtf;REF;bnk_name
Briefkopf.rtf;REF;bnk_erg_1
Briefkopf.rtf;REF;bnk_erg_2
Datum.rtf;REF;bnk_datumort
…
Logo.rtf;INCLUDEPICTURE;Logo.jpg
wurzelbaustein.rtf;INCLUDETEXT;?KopfFolgeSeiten.rtf
wurzelbaustein.rtf;INCLUDETEXT;KopfFolgeSeiten.rtf
wurzelbaustein.rtf;INCLUDETEXT;?FussFolgeSeiten.rtf
wurzelbaustein.rtf;INCLUDETEXT;FussFolgeSeiten.rtf
wurzelbaustein.rtf;INCLUDETEXT;?FussErsteSeite.rtf
wurzelbaustein.rtf;INCLUDETEXT;FussErsteSeite.rtf
wurzelbaustein.rtf;INCLUDETEXT;?Briefkopf.rtf
…

This output file thus provides an overview of all occurring variables. No output RTF is generated (--outputfile=-) and no fields are evaluated (--filter).

 

Fileless data entry with directory parameters:

Total balances (Summe Salden)	{ REF Saldo_Summe \# 0,00 }