CIB merge technical documentation (EN)

1. Introduction

CIB merge is a central component from the document construction kit of the CIB office modules. With CIB merge, the user is provided with a tool with which he can interpret document modules (=templates), which can also contain field instructions (=commands), and mix them with variable data to form a target document. CIB merge supports the RTF format of Microsoft as document format. The variable data can be merged from one or more CSV files, XML files or from database(s). It is also possible to add your own UserExit functions to CIB merge.

This documentation gives a quick overview of the possible use.

2. Installation

Windows 32/64-Bit

For active use of the RTF text interpreter, the respective CIB merge program version has to be accessible.

Unix in general

Because of multiple libs archives, the installation instructions are available for various Unix derivatives.

Systems

CIB merge runs on Windows 32- and 64-bit.

CIB merge is available for the following platforms:

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

Further platforms on request.

Additional modules

According to the well-proven modular principle of the CIB office modules (=CoMod), there are also additional components around CIB merge, which can either facilitate the technical integration into the developer's preferred architecture or which can sensibly supplement the functional range of the CIB merge module.

All additional products are documented in detail in separate technical guides. You can request this information from CIB Support.

CIB runshell

The CIB runshell is a command line tool that can be used to control all CIB products delivered as DLLs or shared libraries. With the CIB runshell it is possible to set all call parameters ("properties") that each individual CIB office module makes available to the user.

It is also ideally suited for use within (batch) jobs and for designing your own processes (instances) with the modules. A Java encapsulation is also available for the CIB runshell.

.

With the JCoMod Wrapper you get a complete JAVA/JNI encapsulation, which allows an easy control of CIB merge from JAVA. The corresponding JAVA/JNI interfaces also operate the CIB runshell, so that the CIB components can also be started in your own processes within the JAVA VM.

If you want to use CIB merge and other CIB modules in a .net environment, please ask us for the appropriate interfaces. These are available for CIB format/output, CIB merge, CIB pdf toolbox, CIB view and CIB job in a common assembly.

The CIB documentServer serves to optimize the use of the CIB office modules (CoMod), especially when used on servers (document and print services). With the J2EE standard package of the CIB documentServer, a fast realization - even of complex document requirements - is possible in the respective customer system.

Calling and using the CIB documentServer releases the developers of the calling application from the details of the respective technical connection of the CIB docgen modules:

The call for document generation is made by means of a standardized job description in XML format, in which the input, outputs, options and even data for CIB merge are formally specified.

The CIB workbench is an addin for almost all versions of MS Office. In particular, it supports the creation of text modules, which makes it much easier to add field commands. A test environment and a reporting functionality are also integrated.

The CIB pdf toolbox is an interpreter for PDF files comparable to the CIB merge. It offers multiple processing possibilities for PDF and supplied data streams. It is also possible to process additional PDF templates into a target document in existing RTF document projects.

3. CIB merge as a document interpreter

CIB merge is a universal interpreter for the dynamic processing of documents with field commands, external data supply via CSV or XML files, SQL accesses and own user exits.

The user has access to the entire functional range of the CIB merge via the call interface.

3.1. CIB merge

With CIB merge it is possible:

• to merge data from external XML and CSV data sources into RTF. Variable fields contained in the RTF document are addressed by their unique name and filled with the specified content. The possibility of processing data records supports both the single letter and serial letter functionality.
• to execute SQL queries directly from documents.
• to control documents from user side.

3.2. CIB merge&optimize

The document base (=templates) is created using text systems (usually MS Office, Open Office) of different versions that are widely used on the market. Accordingly, the individual modules are partly enriched with various very redundant information.

3.3. CIB merge&crypt

3.4. CIB merge&analyse

With its own environment "report & analyse", CIB offers the possibility to create your own reporting from document projects. The CIB merge component provides valuable services in this analysis environment, both for evaluating the contents of the analysis project modules and for generating the actual output report.

3.5. Supported field commands

General

MS-Office provides about 85 different field commands that can be used to program dynamic documents. All commands that are not directly related to the formatting of text are evaluated and supported by the CIB merge component during a merge process.

The interpretation of the remaining field commands that are important for the layout/print display (e.g. (total) page numbering, print date, signature fields, etc.) is reserved for the CIB format/output component. CIB merge passes these field commands unfiltered in the result document.

From CIB merge version 3.13.7:
The same behavior applies to a calculation expression that contains references to table elements: The expression is passed to the result document unfiltered.

Overview of basic field commands

The following field commands of a document are interpreted directly by the CIB merge component during a merge process and dynamically converted into the output file (the field commands here are only listed alphabetically and not described with their full syntax):

Some of these field commands allow an extension of their functionality with additional switches.

Supported text functions

From CIB merge version 3.12.0 the text functions described in the following chapter are supported.

Notes:

• The possibility for linked (multiple) processing of text functions is described here.
• Fixed texts (strings) can be used as parameters of a text function. The content of a string must be specified in quotation marks. The string itself must not contain quotation marks.

Supported date functions

From version 3.12.12 CIB merge supports the date functions described below.

The date functions are defined analogous to calculation or text functions in the form
{ =DATUMSFUNKTION }

{ =DATE FUNCTION }
into the document.

A requirement for these functions is that the date used as input (or a variable "date") has a valid date value and is formatted in a valid date format.

Rules for processing text and date functions

Within a text or date function the name of a variable from the data supply can be used to process the content of this variable.

Example1:

{ SET myVar " My content from the data supply " }

{= LEFT(myVar; 4) }
Result: My

The content of the variable myVar may contain any characters, including special characters such as quotation marks, semicolons, commas, brackets, etc.

Example2:

To be able to correctly process special characters that would otherwise be interpreted by RTF processing, the following procedure is recommended:

{ SET COMMA "," }

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

Result: 123,45

The special character is assigned to a variable by the SET command, which can then be used in the SUBSTITUTE command.

Example3:

{ SET myDate "15.02.2015" }

To process text or date functions concatenated, i.e. to continue working within a text/date function with the result of another text/date function, the detour via variables is necessary.

Example:

{SET a "   abc  "}

{SET b { = TRIM (a)} }

{ = LEFT(b;2)}

Result: ab

Here b is first assigned the value abc (the blanks are removed by the TRIM function). Then b is passed to the LEFT function.

3.6. Handling of field switches

The various field switches that can be used in the RTF and are evaluated by the CIB merge are explained in detail in the RTF training documents:

Dynamische Dokumente - Band 1 - Grundlagen.pdf

They are mentioned in this guide only insofar as they are relevant for the treatment of some parameters, e.g. \* CHARFORMAT.

3.7. Additional functionality of interest

CIB merge offers - in direct connection with further CIB components - useful additional functionalities for dynamic document generation or for the evaluation of such a document project.

Dynamic charts with CIB chart

Often the tables in raw texts, which are filled with current data by CIB merge, are not informative enough. A supplement by an optical business graphic, for example by a line, pie and bar chart, is desirable here. Of course, these graphics must be generated dynamically, also from the same current data of the application.

CIB chart is a module for the creation of dynamic business graphics, both for screen interface and for integration into documents. The product CIB chart consists of:

• the CIB chart designer which enables the text organizer to create graphic templates
• the CIB chart generator which is used at runtime of CIB merge to generate diagrams from supplied variable data.

The CIB chart designer is a stand-alone Windows application and is used by the text organizer to design a graphic template with sample data. The template is an Enhanced Metafile (EMF) with extensions in the form of CCR (=CIB chart Resource) commands.

This EMF shows the example graph based on test data with the layout (colors, dimensions and labels) designed by the CIB chart designer. It can be displayed with the usual graphic tools, such as the preview in Windows Explorer.

In Microsoft Word, the EMF can be inserted, positioned and scaled comfortably like any other graphic file via the menu option "Insert/Graphics/File...".

Document analysis with CIB report&analyse

Many users create very complex document projects. In order to generate internal project reports or to carry out weak-point analysis in document modelling, there is the possibility of a "CIB report&analyse".

This reporting procedure is also integrated into the CIB workbench (AddIn under MS Office). Its use is described in a separate detailed guide.

4. Data supply

Besides the interpretation of field commands such as conditions, loops, formulas and insert commands, the insertion of variable data is a central task of CIB merge.

There are 4 different variants of data supply, which can also be used in mixed form.

• The supplied data has a structure in CSV file format
• (Distribution to several CSV files is also possible)
• Data is supplied via an XML file
• SQL queries are made directly from a document module
• UserExits are generated directly from a document module

4.1. CSV

General

The CSV files are one or more text files containing the names of the input fields and the corresponding values. The abbreviation CSV stands for "Comma Separated Values".

The first line of the control file contains the so-called control record, which consists of field names separated by ";". The tax record can contain any number of field names, limited only by the free working memory.

Each subsequent line contains exactly one data record. A data record contains the text modules or data to be inserted, also separated by ";", in the order of the field names. The number of entries in the data record must match the number of field names in the tax record.

CIB merge can process a single CSV file or multi-CSV files.

Usage with CIB merge:

The parameter -d<Dataset source> sets the CSV file for CIB merge, see chapter Parameter –d.

Notes for the usage of separation and special characters inside the CSV file

If a text passage to be inserted contains a semicolon, a tab character or a quotation mark, the entire text passage must be placed in quotation marks. Quotation marks in a text passage must then be doubled. For example, to insert the company name Laundry "Weißer Riese" in a raw text, the entry in the control file must have the following appearance: ; "Laundry""Weißer Riese"";.

CIB merge can also use the -T parameter to apply a different separator than ";" to the CSV files, see chapter Parameter –T.

Notes on UTF-8 encoded data CSVs

To merge UTF-8 encoded data files correctly using the CIB merge, the following steps are necessary:

1. The CIB merge par file needs to be extended by the following parameter:
-putf-8
This parameter indicates that the data files are encoded in UTF-8 format.

2. Remove the "byte order mark" (BOM) from the data files.

Since for the processing of UTF-8 encoded data files by CIB merge the parameter described under 1.) is used, all characters contained in the data file are interpreted according to the UTF-8 character set. This also applies to a BOM. This results in error messages during processing. For this reason all BOMs must be removed from the data files used.

Single CSV file

Description

With the single CSV file, the input fields are directly assigned to their values. The user uses the field name directly in the document module to access a value.

Multi CSV file

Description:

A multi CSV file can be used to manage several CSV files. It contains the names of all CSV files to be loaded in the current merge process. Using the fields in the header of the multi CSV file, each CSV file is assigned an alias name, which can then be used to access these CSV files in the document.

Usage with CIB merge

For a multi CSV data supply, in addition to the parameter -d with the multi CSV file, the parameter -c must also be set, see chapter Parameter -c.

Advantages over XML:

• Simple format
• Simple 1-n relationship
• Smaller file size

4.2. XML

General

Since version 3.9.x CIB merge also supports the processing of data in XML format. There is also a separate documentation for long-term CIB merge users to convert a document project, which was previously based on CSV data supply, step by step into XML based data supply.

Additional XML components

Support of the XML data supply is provided by means of additional DLLs, which must be installed in addition to the CIB merge DLL. These additional components are automatically included in CIB merge transfer packages and are dynamically activated by CIB merge only in case of XML data supply.

XML properties

XML documents have a physical and a logical structure.

An XML declaration is optionally used to specify XML version, character encoding, and process ability without document type definition.

A document type definition is used optionally to specify entities and the permitted logical structure.

The logical structure of an XML document is a tree structure and thus hierarchically structured. The following tree nodes exist:

Elements whose physical attributes are identified using

(<Tag-Name>) and end tag (</Tag-Name>) or

(<Tag-Name />) can be used,

Comments ( <!-- comment text -->)

Text, which can appear as normal text or in the form of a CDATA section (<![CDATA[ beliebiger Text]]>).

An XML document must contain exactly one top-level element. Further elements can be nested below this document element.

The parameter -d<Dataset source> sets the CSV file for CIB merge, see chapter Parameter –d.

Advantages over CSV:

• Fewer files
• Works internally via nodes
• RTF structures can be simplified with XPATH

4.3. ODBC and SQL

General

SQL can be accessed directly from CIB merge via the CIB SQL DLL additionally stored in the program directory. The result of a query (a table) is used like a CSV dataset file. Instead of specifying a control file in the multi control file, a query is placed there in SQL. It is also possible to dynamically assign a control file or SQL query to existing or new control file aliases. Dynamic alias assignment is also allowed without any control file or multi control file. Furthermore, it is possible to insert the value of the first column and first row of a result table of an SQL query immediately into the raw text (without the detour via an alias, the field "Next" and variables).

ODBC versions

The CIB SQL Dll uses internally ODBC API conformance levels Core, Level 1 (e.g.: long data) and Level 2 (e.g.: scrollable cursor). The SQL conformance level Extended SQL Grammar is required for data fields. See ODBC SDK 2.10 Programmers Reference.

It is therefore important to ensure that the ODBC versions and driver versions used support the corresponding levels.

The CIB SQL functionalities have been tested with ODBC 3.51 under Windows NT 4.0 using the Microsoft Jet ODBC drivers for MS Access, which are supplied with the corresponding ODBC versions.

SQL

SQL access should be possible directly from CIB merge. The result of a query (a table) should be used like a control file. Instead of specifying a control file in the multi-control file, a query is placed in SQL. A second extension should be able to dynamically assign a control file or SQL query to existing or new control file aliases. A third extension is to insert the value of the first column and first row of a result table of an SQL query immediately into the raw text (without the detour via an alias, the "Next" field and variables). A fourth extension should allow dynamic alias assignment even without a multi-control file and possibly even without a normal control file.

SQL queries in multi control files

The entry of a field in the multi-control file usually looks like this: "[;]control file" or "header file;dataset file". For SQL accesses, there is the option of "SQL:Database;Query".

The new function is only available with a DLL for SQL queries.

The query is sent to the database. Further accesses are made with the known commands for control files with unchanged meaning. The only difference is the data source: The table is not in the control file as a set of records, but in a database. (The database must be set up as a user or system data source in the system settings for ODBC.)

The following example provides two control files with the aliases NormalDat and SqlDat The control file SqlDat contains two columns from the prices table. The database containing the table is made available via ODBC with the name ODBC Tariffs Database.

Multi control file:

Dynamic assigning of aliases

The "Next" command usually reads the next data row or places the read position in front of the beginning of the data source. But it is also possible to redefine or reassign an alias with "NEXT DEF:Alias;Data source”.

The alias will be redefined if it does not exist yet. If the alias is already occupied, the associated data source will be closed and the alias reassigned.

The data source can be a control file or an SQL query. The value behind the semicolon must therefore look like an entry in the multi control file.

This function is also available without any control file or multi control file being specified in the parameters passed to CIB merge.

The example dynamically defines the alias SqlDyn in the raw text as the entire tariffs table. Certain fields are then listed in a table.

Raw text:

{ NEXT “DEF:SqlDyn;SQL:ODBC Tariffs table;SELECT * FROM Tariffs table ORDER BY TariffNo” }

{ IF { DATASET ?SqlDyn } = 1 “

{ Next SqlDyn }” \*while }

Restriction: Initially this function should only be available if a multi-controller file has been specified. A later extension to the case without any control file or at least without multi control file is intended.

SQL-Queries in the field “REF”

The command "REF" previously inserted the value of a variable into the raw text. The goal is to use "REF SQL:Database;Query" to insert the value of the first row and first column of the query result table into the text.  No alias or variable is required, but the rest of the table is no longer available without a new query. (However, the purpose of this type of query is also to retrieve a single special value from the database, for which an extra query was necessary anyway.)

The following example inserts the name of a tariff into the raw text. The tariff is selected via the previously defined variable N. For this example, this variable must have the content "'801"" according to the database structure and SQL syntax. (including the single quotation marks), because the condition field TariffNo used is a text field.

Control file:

N;...
"'801'"; ...

Raw text:

{ REF "SQL:ODBC Tariffs Database;SELECT TariffNo FROM Tariffs WHERE TariffNo = {REF N}" }

Limitation:

This way, no memo fields can be selected in the first version. This is due to a technical limitation of Microsoft ODBC.

5. Technical interfaces

This chapter gives a short overview of the available API and its parameters. In general you can use the function cibmerge to set your desired parameters in CIB merge.

5.1. Operating principle

The interface philosophy of the CIB merge component is for historical reasons still different from the other CIB modules. The function for executing a mixing run still gets the call parameters set directly.

Very few of the properties are mandatory (e.g. input file(stream)). Many parameters are optional and enable the user to determine the desired result (e.g. working directories, optimization, encryption, default values, ...).

5.2. cibmerge

Syntax:

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

Call parameters:

The call parameters are described in detail under Call parameters.

Return value:

        0  if everything is successful

     - 1  on abortion by user

    > 0  on abortion by error

Troubleshooting:

An error code greater than 0 means that a problem has occurred and the mixing job was not completed properly. An error code less than 0 means that the user deliberately cancelled the mixing order. In addition, an error log file can be written during a CIB merge run, which contains detailed information about the error that occurred.

5.3. CibMergeVB

The individual parameters are passed to this function in a long character string (=string), whereby a blank must be set for the separator, e.g.: "-I Input.rtf –o Output.rtf -@1"

Syntax:

int WINAPI CibMergeVB(char* strParameters)

Return value:

Troubleshooting:

No special troubleshooting is active.

Fallback

Calling concept

5.4. CibMergePFile

A parameter file name will be transferred to this function, for example D:\Test.par.

Syntax:

int WINAPI CibMergePFile(char* szParamFile)

Return value:

Troubleshooting:

No special troubleshooting is active.

5.5. GetMergeVersion

This function returns the current version number of the CIB merge DLL. This allows you to ensure that a minimum version is available in your application if, for example, you are using special program features that were not made available until a certain release.

Syntax:

unsigned long WINAPI GetMergeVersion()

Return value:

The return value returns the current version number of the CIB merge DLL. The long value returns the information in two ranges. The first two bytes contain the version counter of the main release. Bytes 3 and 4 contain the corresponding current release counter. Depending on the programming language the high and low ranges have to be considered accordingly (see code examples below).

Troubleshooting:

No special troubleshooting is active.

6. Call parameters in detail

The following chapter describes all available call parameters in alphabetical order. Many of the available parameters are optional and not mandatory.

Parameters can be transferred as single letters, such as -Iinput.rtf. However, it is also possible to transfer written-out parameters, such as --inputfile=input.rtf.

Formally, CIB can receive merge parameters in the form ('-'| '/') (("letter" | ("property" '=')) "value") | "property" from the command line.

6.1. General notes

• Upper and lower case of the parameters is not relevant.
  
• All values supplied by letters also exist as long versions.
• Necessity to use "-" or "/" as start characters for parameters that are transferred as letters. For parameters that are written out in full, the start character is "--".
• The first parameters that are transferred without a start character are assigned the parameter characters from "IODH" in order (input, output, data).
• After evaluation of all parameters, "/@" is automatically executed.
• "Property" may contain any character except '='.
• The capitalization of the property is not important.
• Characters other than a-z, A-Z or 0-9 are treated like a '-'.
• The input of
  ('-' | '/') "Property"
  
stands for
('-' | '/') "Property" '=' "Value"
with the empty string as value.
• A "+" after a file name appends to the already existing file
  a "!" after a file name overwrites an existing file (applies to parameter -o output file and parameter -l log file)

6.2. Note Calling examples

The parameter description contains short notes on how to use the parameter from a specific environment.

A more detailed description based on use cases can be found in the chapter "Application examples" Detailed code examples for various programming languages can be found in the chapter "Quick start".

6.3. Overview about the abbreviations for call parameters

6.4. Parameter --analyse

The parameter --analyse is only relevant for the reporting tool "CIB report&analyse". It determines the static field structure.

Syntax

--analyse=<Dateiname>

Description

The structure, which is determined by means of --analyse, can be used for further analysis or presentation. The message is sent to a separate file in CSV format. Initially, only Ref, Mergerec, Next and Includetext (Ref, Record, Next and Insert text) fields are determined. They have only one parameter, which is also reported. This parameter is useful in the additional project CIB report&analyse.

The static field structure is the same order of the fields as written down.

Example for static field structure

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

The dynamic field structure is the order of the fields during the evaluation.

Examples for dynamic field structure

{If {Mergerec ?Data} <> 0 „{Ref Name}{Next data}” \* Solange} reports 1. If, 2. Mergerec, 3. Ref, 4. Next, 5. Mergerec, 6. Ref, 7. Next, 8. Mergerec, 9. Ref, 10. Next, … etc., until the loop is complete.

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.

Example: Extract from the parameter file:

--logfile=!fields.csv
-mPath;Field;Value
--logfile=!cibmerge_blocks_analyse.log
--source-directory=templates
--outputfile=-
--analyse=+fields.csv
# for all text 
--inputfile=basicblock.rtf
-m@
--filter
--inputfile=reference.rtf
-m@
--filter
... for all RTF blocks...
--inputfile=rootblock.rtf
-m@
--filter
-mdone 

This example consists of several RTF blocks. The --analyse parameter is used to generate the output "fields.csv". This file has the following structure:

Path;Field;Value

A more detailed description of the output can be found in the application example blocks.

Note:

Because of the static field sequence, fields in loops are output only once. For the same reason, fields from both the then and else branches of an if statement will be output. Since the filter and not the merge process generates the output, no fields are calculated and therefore no embedded texts (include text) are expanded or their fields output.

If you do a related field analysis over a whole lot of texts and blocks, you will also get the call tree with the inserted blocks. Identical fields that occur more than once are also reported several times (e.g.: two times {Ref Name})

6.5. Parameter --break

[-b]

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

Syntax

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

Description

CIB merge aborts the processing in various situations with error messages. This occurs especially in mixing processes, for example, when a variable is used that is not defined.

In some situations, however, it is desirable that CIB merge does not terminate immediately on every error, but continues with the processing if possible. For this purpose the parameter B for break was introduced in version 3.7.62.

In order to find the position in the raw text or text module, CIB merge also outputs the subsequent errors or situations after the cause of the error. (This corresponds to a kind of "stack unrolling".) CIB merge also writes the closing brackets of the raw text, as far as the situation allows, so that the text can be opened by other applications.

<cancellation level> determines the point up to which the process is continued or aborted. The following values are possible:

Examples

--break=loop

If the mixing run is currently in a loop, it will only run until the end after the error, i.e. will not be repeated. Immediately after this, the mixing process will be cancelled.

--break=never

CIB merge carries out the mixing job to the end regardless of any errors occurring and returns the error code of the first error that occurred.

Note

Independently of --break=<cancellation level> all errors occurring up to the end or cancellation of the mixing process will be logged in the log file.

6.6. Parameter --charformat

With --charformat can be determined, if CIB merge shall use the switch \* CHARFORMAT if the results of fields do not deliver an own formatting.

Syntax

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

Description

With the parameter --charformat can be set, for which fields the character format is to be changed, i.e. for which fields the formatting is to be transferred to the field contents.

With the parameter --charformat most of the \* CHARFORMAT switches can be omitted, making the raw text shorter and more readable.

If the \* NOCHARFORMAT switch is specifically set for a field, this can prevent the --charformat parameter from being applied to this field (from CIB merge version 3.9.156).Nicht formatbehaftet sind Feldinhalte aus CSV-Datei, aus Paramterdatei, Datum Felder mit Schalter sind formatbehaftet.

For <Option> can be set the following values:

Example

--charformat=plain-values-only

The result of

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

gets the formatting of the REF field if --charformat=plain-values-only is set (in this case the text is written bold), although this field has a switch.

Note

There are field contents with formatted values on the one hand and field contents with non-formatted values on the other.

Formatted values that are output as field results do not need the field switch \* CHARFORMAT, but could be formatted in the same way.

Examples of field contents with formatting are:
{includetext}, inserted RTF contents, {REF} (if the variable is formatted).

In these cases it is normally not useful to use the --charformat parameter. If desired, the \* CHARFORMAT switch can be set manually.

Values that CIB merge calculates from fields may be visible in the input text, may be completely new or may originate from the control file.

Examples of visible values are IF fields whose text comes from one of the alternatives exactly as it appears in the field or values assigned with SET. Visible values are formatted and not affected by the parameter.

By using the switch \*NOFORMAT in the SET command, this value can be turned into a non-formatted value (from CIB merge version 3.9.174).

Non-formatted values appear by default in the standard font (Times Roman, font size 10). They will be formatted by the --charformat parameter as if you specified the /* CHARFORMAT switch each time.

Examples for field contents with: {MERGEREC}, {date}, {=…}, values from CSV, {REF} (if the variable is not formatted),.

If --charformat is set for these fields, the \* CHARFORMAT switches can be omitted.

Examples of generated values are Aktualdat or the expression calculation with "=". These values are not formatted and are therefore affected by the parameter when they appear in the output.

6.7. Parameter --chart-…

General

The --chart parameter allow the creation and insertion of dynamic business graphics. In this case, CIB merge can leave the graphic statement in the text or replace it with the updated graphic. CIB merge automatically updates (overwrites) the original file and removes the binary graphic data from the result if the graphic statement is kept. Otherwise, the file remains unchanged and only the result will be embedded in the RTF output instead of the instruction.

It is also possible to embed graphic data from non-chart graphics from a file into the RTF. The following image formats are supported: BMP / DIB, EMF (chart and non-chart graphics), PNG, JPG and WMF.

The following parameters are provided:

Parameter --chart-output-format

CIB merge can deliver all graphic formats offered in CIB chart designer as result. S If you want to leave the graphics statement in the text, you can either set "--keep-fields" for all fields or insert the switch "\* leave" in selected graphics statements.

Syntax:

--chart-output-format=<Bildformat>

<image format>: ccr (CIB chart resources), emf (Enhanced Metafile), or emfccr (Enhanced Metafile extended by CIB chart resources (embedded))

Parameter --chart-source

With --chart-source you specify whether the chart should be calculated from the embedded data, or, in the case of an INCLUDEPICTURE instruction, for the contents of the specified file or never. ({\pict} do not calculate).

 Syntax:

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

Description

For the graphic source, the following settings are available <Option> :

Parameter --chart-target

The --chart-target parameter determines where the output of the updated graphic data is to be written: embedded in the document or over the old content of the specified file.

Syntax:

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

Description:

For the graphic target, the following settings are available for <Option> :

If no chart library is available, chart graphics are treated like normal graphics.

By setting the parameter --chart-target=embed, if --chart-source is not "embed", the image data of EMF, JPG (JPEG), PNG, WMF and BMP or DIP graphic files are embedded in the result RTF. The type of file format is determined by the file content, not by the suffix.

Example:

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

The graphic data here origins from one file. All graphics (chart and non-chart graphics) should be embedded in the result RTF.

The parameter are described in detail in the use case example Templates.

The following table provides an overview:

(1) „Keep“ switch not set

(2) „Keep“ switch set

(3) Data could not be read from the file

(4) Data could be read from the file

6.8. Parameter --codepage

[-p]

The --codepage parameter controls the currently used character set for the control file (for control file see parameter --datafile or --headerfile).  

Syntax

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

Description

If the parameter --codepage is not specified and thus no character set is defined for the control file, the default is the declaration in the RTF input file (e.g. \rtf1\ansi). The following character sets are permitted: pca, pc, utf-8 or ansi.

Examples

--codepage=pca

Here a different character set is used in the CSV files (here pca). This must be specified via the --codepage parameter.

The use of the parameter is described in detail in the use case example Gap Text.

Note:

For the RTF templates the code page specified in the RTF input file is always used.

See also the notes on UTF-8 encoded data files in chapter “Notes for UTF-8 coded data CSVs”.

6.9. Parameter --colors

The parameter --colors can be used to optionally disable optimizations that are performed for color tables in the header of the RTF document.

Syntax

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

Description

Every RTF document contains color tables in the header. Therefore CIB merge has to spend time for matching because of inserts or for optimization. But not every user is interested in this adjustment or optimization. Therefore they can be switched off with the parameter --colors.

Possible values for <Option> are:

Example

--colors=expand

New colors used in RTF components are added to the color table and unused colors are not removed. Therefore no optimization takes place.

6.10. Parameter --compress

[-z]

If the --compress parameter is set, CIB merge compresses the output file using the zlib method.

Syntax

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

Description

If the --compress parameter is used for compression, the priorities between the optimization time and the result for the desired application must be evaluated. More time will produce very small results, but the fastest possible compression will produce a very small but not minimal result.

The user can therefore set the --compress parameter to an integer value from 1 to 9. The default value is 6.

Examples

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

The file is compressed as much as possible. This results in a smaller file size, but a slightly increased time for this merging process.

The use of this parameter is illustrated together with other optimization parameters in the use case example Gap Text.

6.11. Parameter --datafile

[--data/-d]

Set the data source with the --datafile parameter.

Syntax

--datafile=<Dateiname>

Description

A file in CSV or XML format can be specified as data source.

Examples

Single CSV via parameter file

--datafile=Adresse.csv

The data is located in a single data source called Addresse.csv.

This way of using the parameter is demonstrated in the use case example Gap Text.

Multi CSV via parameter file

--datafile=multi.csv
--multidatafile

The data is distributed over several data files, which are specified in the file multi.csv. To define that it refers to a multi CSV, the parameter --multidatafile must also be set.

This way of using the parameter is demonstrated in the use case example serial letter. 

If the parameter --target-directory is also set, the multi.csv and all other data files are expected in this directory:

--target-directory=csv

The use of the combination of the parameters --datafile and --target-directory is demonstrated the use case example Templates.

Multi XML via parameter via

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

The --datafile parameter sets the XPath to the multi nodes.

This context is demonstrated in the use case example serial letter.

Note:

6.12. Parameter --default-mode

[--defaultmodus/--default-modus]

The --default-mode parameter provides a mechanism to determine a default value for each variable if the variable is undefined or empty.

Syntax

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

Description

The --default-mode parameter is only to be used in combination with the --default-prefix parameter. This defines the prefix that is placed in front of a variable name. When the REF field is evaluated, it is determined whether the value is suitable for the default behavior, otherwise the value or an error is output. The default behavior occurs under the following conditions:

• “Variable is undefined and behavior accordingly selected” or
• “Variable is defined and empty and behavior accordingly selected”.
• If one of the conditions applies, the variable name is composed of the default prefix and the old name. If such a default is again not set, there is another one for all together. Only if this does not exist, the usual error is reported that a variable is not defined. You can choose between 'no default', 'default for empty', 'default for undefined' and 'default for both'. The default is "no default“.

Possible values for <Value> are:

Example

--default-mode=all

The system searches for a suitable default value if a variable is empty or undefined.

The use of the parameter is described in detail in the use case example Gap Text.

6.13. Parameter --default-prefix

This parameter defines a prefix for variables, i.e. it sets a prefix before the original variable name.

Syntax

--default-prefix=<prefix>

Description:

With the parameter --default-prefix a variable can be assigned a substitute value (default). The common default is the variable that has the same name as the default prefix. The default prefix is “default”. This parameter must be specified in combination with the --default-mode parameter.

Example 1

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

Here a default value is searched for if a variable cannot be filled by the data supply because the variable does not exist or is empty. To determine the default value, the prefix "Default." is prefixed to the variable.

Example 2

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

Assignment of variables: A=Anton, B=Berta, C=, Default.B=Bruno, Default.C=Cäsar, Default.D=Dora, Default.=Mama

The default mode defines the prefix "Default" for undefined variables. The variables supply the following values:

REF A delivers Anton

REF B delivers Berta

REF C delivers „“

REF D delivers Dora

REF E delivers Mama, because Default.E is not defined. If "Default." were not assigned, there would be an error with the message that E is not assigned.

If the default mode is set to all or empty (--default-mode=all/--default-mode=empty) then the evaluation for REF C provides Cäsar.

REF D returns an error with a default mode off (--default-mode=off) or empty (--default-mode=empty).

6.14. Parameter --delimiter

[-t]

The --delimiter parameter defines a different delimiter for the control files. The default delimiter for the control files is ";".

Syntax

--delimiter=<Trennzeichen>

Example

--delimiter=,

CIB merge now interprets the comma character instead of the semicolon as separator.

The use of the parameter is described in detail in the use case example Gap Text.

6.15. Parameter --destination-colorschememapping

(from CIB merge version 3.12.2)

This parameter can be used to control whether the \*\colorschememapping is included in the output file.

Syntax

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

Description

Possible values for <Option> are:

6.16. Parameter --destination-datastore

(from CIB merge version 3.12.2)

This parameter controls whether the \*\datastore is included in the output file.

Syntax

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

Description

Possible values for <Option> are:

6.17. Parameter --destination-themedata

(from CIB merge version 3.12.2)

Syntax

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

Description

Possible values for <Option> are:

6.18. Parameter --dialog

[-x]

The --dialog parameter displays a percentage bar on the screen during the mixing process (non-modal dialog mask). The mixing process can be stopped using the Cancel (Abbrechen) button.

Syntax

--dialog

Beispiel

--dialog=top

The progress bar moves to the foreground when the mixing process is started.



In the use case example Serial Letter, the progress bar is used to terminate an endless loop.

6.19. Parameter --directory-…

The directory parameters allow a file-less data entry. This is done via entries (virtual files) in virtual directories.

The following parameters are available:       

6.20. Parameter --directory-set-inline

The parameter --directory-set-inline allows a file-less data entry using the parameter file.

Syntax

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

Description

The --directory-set-inline parameter reads the lines of the parameter file up to the end-of-file. This means that all lines between --directory-set-inline and end-of-file are interpreted as contents of <virtual filename>. The content is entered in the virtual directory under <virtual filename>. If a content already exists, it will be overwritten.

Example

Excerpt from a parameter file with file-less data input:

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

The parameter --directory-set-inline=data.csv indicates file-less data entry. The following lines are read in up to the "end-of-file" line and thus form the contents of the virtual file named data.csv.

6.21. Parameter --directory-log

The --directory-log parameter writes the contents of a virtual file with the start and end line to the error output.

The start line is --directory-set-inline.

Syntax

--directory-log=<virtueller Dateiname>

Example

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

The content and the start and end line are written to the log file. The content of the log file merge.log looks like this:

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

The --directory-read parameter stores the contents of a file in the virtual directory. If necessary, the existing content will be overwritten.
This Parameter is also used for Merge-Recombine. (from CIB merge version 3.9.181)

Syntax

--directory-read=<Dateiname>

or

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

or (from CIB merge version 3.9.181)

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

Description

For <filename> all specifications are possible, which are also allowed with the parameter --inputfile.  The short form of the parameter is --directory-read=<filename>, where <filename> is also used as <virtual filename>.

Note: If the <filename> contains the characters "+" "-" "!", these are interpreted as switches and are not considered part of the file name.

Any switches +/-/! etc. are not included in the name.

Merge recombine (from CIB merge version 3.9.181):
The CIB viewers (CIB view&rec and CIB jview&rec2) offer the possibility to enter or edit text passages in CIB REC fields. These text passages are stored by the CIB viewers in so-called RTF snippet files. When the editing process of a document is finished, CIB merge merges the RTF snippets into the document and saves them as new output RTF.

The snippet files are transferred to CIB merge using the parameter "--directory-read=cibrec-snippetN.rtf=<filename>" if the files are on the hard drive.

Example

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

The --directory-read parameter stores the content of the file in.log into the virtual file inNew.log. In the next step, the virtual file with the name inNew.log is taken and the content is written to out.log.

6.23. Parameter --directory-remove

The --directory-remove parameter removes the specified entry from the virtual directory, or all entries if no name is specified.

Syntax

--directory-remove

or

--directory-remove=<virtueller Dateiname>

Example

--directory-remove=name

The entry "name" will be removed from the directory.

--directory-remove

All entries will be removed from the directory.

6.24. Parameter --directory-set

The command --directory-set=<virtual filename> defines a virtual file under <virtual filename> and is stored in the memory of CIB merge. A useful application is for example to transfer CSV data file-less. For a transfer in a parameter file the call parameter --directory-set-inline.is to be used.

This parameter is also used for the merge recombine. (from CIB merge version 3.9.181)

Syntax

--directory-set=<virtueller Dateiname>

or (from CIB merge version 3.9.181)

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

Description

Merge recombine (from CIB merge version 3.9.181):
The CIB viewers (CIB view&rec and CIB jview&rec2) offer the possibility to enter or edit text passages in CIB REC fields. These text passages are stored by the CIB viewers in so-called RTF snippets. When the editing process of a document is finished, the CIB merge merges the RTF snippets into the document and saves them as new output RTF.

The snippet files are passed to the CIB merge using the parameter "--directory-set=cibrec-snippetN.rtf={\rtf1 ...}", if the snippet is transferred to memory.

6.25. Parameter --directory-write

The command --directory-write=<virtual filename>=<filename> writes the contents of <virtual filename> from the virtual directory to the file <filename>. Any switches +/-/! etc. are not included in the name.

Syntax

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

Example

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

The virtual file named out.log is taken and the content written to out.log.

• Comparison: file-based and file-less data entry

Starting from a classic file-based example, alternatives are presented using the means just mentioned.

The output of the RTF can be done file-less with means described in other documents and is not mentioned here!

• Java merge job and retrieval of error text and number

Data input by file:

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

Data input without file:

Only data.csv should be transferred in the first step file-less. The content is in the string variable csv_data. The following additional property is set for this. (The rest remains unchanged)

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

• Merge job via parameter file (Java, C++ or COModSuite)

Data input by file:

Content of the merge.par file:

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

Specify log file

Report version

Specify data, input and output files

Report file names

Merge single document

Call "cibmrg32.exe -@merge.par" to start the job.

Data input without file:

Similar to the case in Java, this is also possible in the parameter file:

The parameter file merge.par must be supplemented by the following specification (rest remains unchanged)

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

• Job from C++

Data input by file:

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

Data input without file:

Here the data is transferred in string constants. A better option would be to assemble them dynamically via stringstreams of the STL:

The arguments must be extended by the following specification (rest remains unchanged):

       „--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

(from CIB merge version 3.9.181)

This parameter can be used to set and merge document properties.

Syntax

-- docproperty=[key]=[value]

Description

The parameter--docproperty enables the user to define the document properties of the output document.

Both predefined values (author, title, etc.) and user-defined document properties are supported.

Possibilities for use are, for example:

1. Simple and central assurance of the document properties of the output documents before they reach the customer environment (consistent author for all outgoing documents).
2. Using the document properties to transfer additional information

6.27. Parameter --encrypt

[-y]

The parameter --encrypt generates an encrypted output format that can be further processed by other CIB components (for example CIB format/output).

Syntax

--encrypt

Description

The encryption used by the --encrypt parameter is based on a CIB proprietary CC9 algorithm. This algorithm is intended to make the modules or intermediate results "unreadable" and thus prevent "immediate" manipulation of the content.

Example

--encrypt

The output file is encrypted here.

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

(from CIB merge 3.12.10)

With the parameter --field-nesting-level-limit the nesting depth of field commands can be limited.

Syntax

--field-nesting-level-limit=number

number=integer between 0 and n

Description

The --field-nesting-level-limit parameter can be used to limit the nesting level of field commands.

The default value is "0", i.e. the nesting level is not limited.

If the value is greater than 0, the CIB merge terminates with error 810 when this nesting level is reached.

Example

--field-nesting-level-limit=10

CIB merge interrupts with error 810 when a nesting level of 10 is reached.

6.29. Parameter --field-results

[-r / -rp]

The --field-results parameter can be used to control whether all field-results are removed in Rich Text Format, thus reducing the size of the output file.

Syntax

--field-results

or

--field-results=p

Or (from CIB merge 3.9.183)

--field-results= Keepswitch

Description

MS Word generates field results in RTF. In most cases, these entries are not required by the CIB office modules. The parameter --field-results removes these entries.

For certain graphic objects, CIB format requires certain parts of the field results for positioning and scaling in individual cases (e.g. positioning graphics over text). The switch p "print" (short: -rp) causes CIB merge to receive these data. In addition, further entries are removed from the RTF, which are not required for further processing with CIB format. If in doubt, --field-results=p should be used, as the output file size increases only slightly compared to --field-results, and CIB format will certainly have all the necessary information available.

--field-results is usually used to optimize the file size of an RTF project before testing and delivery. On request, CIB Support will provide you with detailed information on the optimization of RTF projects.

Keepswitch (from CIB merge 3.9.183):
There are use cases in which the data supply of a document must be carried out over several merge processes, because not all information is available at the time of the first run. In this case, the field contents of the previous merge processes must be retained for the subsequent ones.

Example

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

CIB merge does not merge field contents (--filter=f), removes all field-results which are not relevant for CIB format (--field-results=p) and writes the output file accordingly.

The use of this parameter is illustrated in the application example blocks. CIB merge does not merge field contents (--filter=f), removes all field-results which are not relevant for CIB format (--field-results=p) and writes the output file accordingly.

The use of this parameter is demonstrated in the usage example Templates.

Note:

RTF files created with --field-results should no longer be edited with MS Word. Documents with scaled graphics or graphics positioned over text can no longer be displayed and edited correctly in MS Word. When saving with MS Word, the advantage of the reduced file size is also lost again.

6.30. Parameter --filter

[-f / -ff]

With the parameter --filter CIB merge does not evaluate the field contents, but only reads the input file and writes the output file according to the set parameters.

Syntax

--filter

or

--filter=f

Description

With --filter the field contents are not evaluated, but parsed and translated. This can be prevented with the switch f = "fast". So --filter=f filters faster (without syntax check of the RTF stream), --filter can detect errors in the fields more easily.

--filter=f (or also -ff) is mostly used to optimize or encrypt RTF projects before testing and delivery, see chapter Overview: Optimization, Encryption and Compression and parameter --field-results. 

Example

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

Here some optimizations (see respective parameter) are carried out and no field contents are mixed in.

The use of this parameter together with optimization parameters is demonstrated in the usage example Gap Text.

In the usage example Templates, the parameter is used together with --field-results.

6.31. Parameter --fonts

With the --fonts parameter, optimizations performed for font tables in the header of the RTF document can be switched off optionally.

Syntax

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

Description

Every RTF document contains font tables in the header. Therefore CIB has to spend merge time for matching due to insertions or for optimization. With the parameter --fonts these optimizations can optionally be switched off. The default is adjust. Das bezieht sich auch auf den gesamten Kopf.

The following values are <Option> :

Example

--fonts=keep

Although inserted text templates contain additional fonts, these are not included in the main font table. Unused fonts are not removed. This is useful, for example, if a document is to be printed but the printer does not know all the fonts used.

6.32. Parameter --headerfile

[--header/-h]

The --headerfile parameter can be used for data supply with XML. It points to the set data file.

Syntax

--headerfile=<Kopfsatzdatenquelle>

Description

If --headerfile is used in combination with the --multidatafile parameter, --datafile specifies the XPath to the multi-node. Usage of this parameter with a CSV data supply is not recommended.

Example Multi control file from 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>
    

The multi-nodes are located in the file Data_withAlias.xml. The alias names result from the node name (customers, line items), which are defined with the specified XPath. The alias definitions are the node contents (XML:$(this);/root/data/customers/customer, XML:$(this);/root/data/items/single item). The special file name XML:$(this) points to the current file.

The use of this parameter will be described in detail in the usage example Serial Letter.

6.33. Parameter --help

[-?]

The --help parameter shows the help page (e.g. in log files).

Syntax

--help

Description

This parameter is used to output the automatic program help. This is an up-to-date short overview of all call parameters available in the version used.

If you also specify the log file parameter, the help is redirected to a file. Output to the console is not possible on Windows.

Description: CIB merge as programm

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

The help is redirected to the file hilfe.txt. An excerpt from this help output can be found in the usage example Gap Text.

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

[--inline-is-not-this]

(from CIB merge 3.9.190)

By usage of the parameter "--inline-is-not-this" the behavior of CIB merge versions older than 3.9.166 concerning $(inline) can be restored.

Syntax

--inline-is-not-this

Description

Up to CIB merge version 3.9.165 the identifier $(inline) was used internally, i.e. a context was created. From CIB merge version 3.9.166 the $(inline) is replaced by the actual file name.

This means that constructs with "--directory-read=inline=<filename>" ($(inline) is redirected to a file) and at the same time "REF "DAT:XML:$(inline);relative/path" " no longer work because there is no context for relative XPATH expressions. You would have to work with absolute XPATH commands.

6.35. Parameter --html-switches

[--html/-s]

With the parameter --html-switches, CIB merge also supports extended REF statements that contain additional switches for the output of forms with CIB format/html.

Syntax

--html-switches

Description

CIB merge understands by default only the switches defined in MS Word. With the parameter --html-switches the additional switches for the output of forms are also interpreted. A specification of these additional switches can be found in the CIB format help, which you can get from the contact addresses or under http://www.cib.de under Support à Documentation.

Example

--html-switches

The parameter causes CIB merge to understand the following additional switch, for example.

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

With CIB format/html this results in a single-line text field.

The usage of the parameter is demonstrated in the use case example Gap Text.

6.36. Parameter --inputfile

[--input/-i]

The input file is specified with the parameter--inputfile. If there are several modules, the root module must be specified there.

Syntax

--inputfile=<Inputfile>

Example

--inputfile=Anschreiben_in.rtf

The input file letter_in.rtf will be searched in the current directory.

The usage of the parameter is demonstrated in the use case example Gap Text.

Nore

Do not specify the path for the root module with --inputfile, but separately with --source-directory. In this way, the included modules are also found automatically in this directory, absolute path specifications are no longer necessary for the RTF modules.

This is demonstrated in the example Templates.

6.37. Parameter --input-language

The parameter --input-language determines the country setting for the switch “numeric format” (\#)("numerisches Format”).

Syntax

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

Description

Currently there are the valid values “English“/“englisch“ and “German“/“deutsch“. Default is ”German“. If the value is set to “German”, CIB merge interprets dots in the number format specification as an instruction to structure the number to be output with 1000 dots or with substitute characters of the set output language. Commas are interpreted as subdivisions between places before and after the decimal point. The character that matches the set output language is also output here. If the value is set to "English", dots and commas are interpreted in reverse. Nevertheless, the output is still in the output language.

The numbers must be specified in German in the CSV file. They are written in {=...} fields only understanding them in German. Likewise, the parser of the switch \# expects that the field result contains the number in German before using the switch.

Examples

• English RTF with English formatting

--input-language=english

The cover letter is written in English and therefore the specification of the number format. This fact is specified using the parameter --input-language.

This is demonstrated in the use case example Gap Text.

• Calculation examples

--input-language=german

There is the following statement in an RTF document:

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

Result: 1.235,00€

The instruction

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

delivers the result: 13,34€

--input-language=english

There is the following statement in an RTF document:

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

Result: 1.235,00€

The instruction

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

delivers the result: 1.334,00€

The reason for the different result from the German is the interpretation of the separators in English:

Thousands separator comma and decimal point

6.38. Parameter --intermediatefile

[--intermediate]

The --intermediatefile parameter allows intermediate results to be stored in a file or in memory.

Syntax

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

Description

By specifying RAM as intermediate result file, no file is created on the file system. This is useful if no (write) access to the file system is possible on a system. Writing an intermediate file may take a lot of time, which can be saved by using this parameter.

Possible values for <String> are:

Example

--intermediatefile=Zwischenergebnis

The parameter --intermediatefile writes the intermediate result to the file intermediatefile.rtf .

Note

Alternatively, the file for the intermediate results can be specified via the environment variable "CIB_MRGINTERMEDIATE".

The parameter can be set for all merge processes using the "AUTOSTART" functionality (from Merge 3.9.104 and 3.8.130). For this purpose, the "AUTOSTART" parameter file can be patched directly into the binary file via hex editor or the environment variable "CIB_MRGAUTOSTART" can be set with the parameter file name.

6.39. Parameter --keep-fields

[-k]

The --keep-fields parameter continues the mixing process, even if not all fields can be filled using the data supply.

Syntax

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

Description

If not all fields can be filled during the data supply (information is not yet available), it is possible to tell CIB merge to skip these fields without aborting the merge process using the parameter --keep-fields.

Possible values <Option> are:

Example

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

Here, the variable kont_kontoart is used in one of the RTF modules. However, this variable is not supplied from the data sources. With the parameter --keep-fields=unresolved-ref the mixing process is continued, the REF field for kont_kontoart remains in the output file KeepFields_out.rtf.

The usage of the parameter is explained in the example Templates.

Note:

If CIB merge writes a field as such (without merging the data) because of the parameter keep or because of the switch \* LEAVE (LASSEN), a textual error message appears in the logfile. This action is not considered an error and therefore does not generate an error return value.

(From CIB merge version 3.9.181)

When controlling via field switches, there are other possibilities besides \* LEAVE (LASSEN):

\*keepalways: This field statement always remains in the output document.

\*keepuntilresolved: This field statement remains in the output document until it is filled.

Hint:

As --keep-fields=unresolved-ref, this parameter is perfectly suited for realizing a residual data acquisition with the CIB office modules. Ask the CIB support for further information for your use case.

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

(From CIB merge version 3.9.186)

The --keep-refs-if-in-list parameter can be used to set the keep switch externally for the specified fields.

Syntax

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

Description

The --keep-refs-if-in-list parameter can be used to pass a single or a list of fields to the CIB merge for which a keep switch is to be set. These REF fields are left in the merged document, a possible variable value is stored in the fieldresult. If a REF field occurs more than once in an RTF, all of them are retained in the output.

6.41. Parameter --LicenseCompany

Name of the licensee for the function(s) of the CIB merge to be activated in connection with the LicenseKey parameter.

Syntax

--LicenseCompany"=<Name>

6.42. Parameter --LicenseKey

License key, which in conjunction with the correct licensee unlocks licensed function(s).

Syntax

--LicenseKey=4e4e-c1c1-12345678

6.43. Parameter --lists

The --lists parameter can be used to disable optimizations that are performed for list tables in the header of the RTF document.

Syntax

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

Description

Every RTF document contains list tables (\listtable, \listoverridetable) in its header. When processing these tables, CIB has to spend merge time for insertion matching and optimization.
With the parameter --lists these optimizations can be switched off.

The following values are possible for <Option> :

„Important Note“

NEWLISTID is a field switch and this is usage when the same file is included in multiple copies.

Example: {INCLUDETEXT "new1.rtf" \* NEWLISTID}

Version 3.13

Attention:

This parameter depends on the parameter "--replace-header".

"replace-header=never"
No control possibility of the handling of the list tables. The behavior is the same as with "lists=keep".

"replace-header=always"
(default value) Here the root document is always extended by list tables from inserted text templates. Only optimization and non-optimization is distinguished.

This means that "lists=keep" is treated like "lists=expand" (no optimization) and "lists=optimize" like "lists=adjust" (optimization).

"--replace-header=auto"

Only in this setting all 4 variants of the "-lists" parameter are executed as described above.

Example

--lists=adjust

Here the list table is to be extended by the lists used in the text templates. Unused lists shall be removed. Thus, the usage lists are available again for later editing in MS Word.

This parameter is demonstrated in the use case example Templates.

6.44. Parameter --logfile

[--log/-l]

The --logfile parameter sets the file name and path for the error log file that CIB merge writes for each merge process.

Syntax

--logfile=<Fehlerprotokolldatei>

Description

With --logfile=!<Error log file> an already existing error log file is overwritten, with --logfile=+<Error log file> the current entries are simply appended to the file. If no error occurs, an empty error file is written.

Example

--logfile=!Komma_log.log

A possibly already existing file Comma_log.log in the current directory is overwritten.

The usage of the parameter is illustrated in the use case example Gap Text.

Note

It is recommended to write the parameter --logfile in the first line of the parameter file. This will already log errors in the parameter file.

From CIB merge version 3.9.x on, --logfile can be scaled additionally with --verbose. For details of --logfile and --verbose see chapter Error log file. Please also refer to the book "CIB merge Error Handling" for further information about trace options and program return values.

6.45. Parameter -m

The parameter -m<text> instructs CIB merge to output a specified <text> in the message/error log file.

Syntax

-m<Text>

Description

The parameter -m<Text> enables the insertion of self-defined texts into the message file. With -m@ CIB merge automatically outputs the set parameters for input and output file names.

Example

--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@

The text specified after -m is written to the log file. With -m@ the names of the input and output files are output.

An excerpt from the log file can be found in the Gap Text application example.

Note

If errors occur in the merge process, they are output after the messages --m.

The output of the program version of CIB merge is controlled by the parameter --version.

6.46. Parameter -- max-executiontime

(from CIB merge version 3.10.3)

This parameter limits the maximum execution time.

Syntax

-- max-executiontime=[#milliseconds]

Description

This parameter sets the maximum execution time in milliseconds. As soon as this value is exceeded, CIB merge stops with error 821.

If this value is 0 (zero) or not set, the execution time is unlimited.

This parameter is used to avoid risks that can arise from endless loops. The following field combination is an example of such a loop:

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

6.47. Parameter --maxOutputSize

(from CIB merge version 3.9.174)

The maxOutputSize parameter sets the maximum allowed size for the entire serial letter in the "serialletter" case.

Syntax

--maxOutputSize=[#bytes]

Description

This parameter is a cancellation criterion for serial letters created with CIB merge. If the mail merge exceeds the maximum size, CIB merge will acknowledge this with a return code 818.

This allows the user to make sure that the generation (which usually happens automatically and without human control) is aborted if there is unwanted behavior in the file size range.

6.48. Parameter --maxSingleSize

(from CIB merge version 3.9.174)

Syntax

--maxSingleSize=[#bytes]

Description

This parameter is an abort criterion for merge letters created with CIB merge. If a single document of a mail merge letter is larger than the set maximum size, CIB merge acknowledges this with a return code 817.

This allows the user to make sure that the creation (which usually happens automatically and without human control) is aborted if unwanted behavior in the file size range occurs.

6.49. Parameter --merge

[-@[<Ziffer>]]

A simple --merge as argument makes CIB merge start mixing immediately and use all arguments, which were used before.

Syntax

--merge

or

--merge=<Ziffer>

Description

With this call parameter, several jobs can be stored one after the other in a parameter file, each of which is processed separately.

Note:

An already set parameter is valid until a new value is assigned to it.

If not all data records/variables in the involved data files have been processed, CIB merge interprets the merge process as a mail merge, inserts a section change into the target document, and merges further starting from the root document.

Examples

--merge=1

Here a single merge run is executed, i.e. the result RTF contains only the data from the first record.

--merge=3

The result is an RTF document with the first three data sets, even if the data sources contain more than three data sets.

The usage of this parameter is demonstrated in the use case example Serial Letter.

Note:

6.50. Parameter --multidatafile

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

If a multi-controller file/multi-CSV file is used as data source, the parameter --multidatafile must be set additionally. 

Syntax

--multidatafile

Description

The parameter --multidatafile indicates that the data file specified with the parameter --datafile contains further data files.

Example

• Parameter file with multi control files from multi-CSV files

--datafile=multi.csv
--multidatafile

The parameter --datafile defines a multi-CSV file. The aliases are defined in the first line of the CSV file, all other lines are the alias definitions.

The usage of the parameter in connection with CSV files is demonstrated in the use case example Serial Letter.

Note:

When using multi-CSV files, the --headerfile parameter is not used.

• Parameter file with multi control files from two separated CSV files

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

Alias CSV file:

Address;License information

Data CSV file:

Adress.csv;LicenseInfo.csv

Note:

In this example, the alias names and alias definitions are stored separately in two CSV files. To specify the CSV file for the alias names, the --headerfile parameter is used. The alias definitions are located in the CSV file which is set with the parameter --datafile. Each line represents a new definition (data set).

• Parameter file with multi control files from XML file

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

The --headerfile parameter defines the XML file. The aliases result from the node names in the XML file, which are defined with the specified XPath. The alias definitions are the node contents.

6.51. Parameter --next-mode

[--next-modus/--next]

The --next-mode parameter controls the behavior of the {NEXT} command and affects variables that are present in one data set but no longer exist in the next one.

Syntax

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

Description

Variables that are present in one data set but no longer exist in the next one can be deleted, cleared or retained using the --next-mode parameter.

Possible values for <Option> are:

Example

--next-mode=delete

If a variable is no longer present in the next record (e.g. missing node in the XML), this variable is deleted, which then leads to an error. This is desired so that the error does not remain undetected by simply leaving out the missing value.

The usage of this parameter is demonstrated in the use case example Serial Letter.

6.52. Parameter --old-compare

With this parameter the new interpretation of conditions can be switched off.

Syntax

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

Description

With newer versions, MS-Office has an extended range of functions in the automatic comparison of data types. This has required a renewal in CIB merge (from version 3.8.126). Customers who wish to use an older (conservative) comparison procedure can do so by using the --old-compare call parameter.

Switching off the new interpretation of conditions can be controlled by the --old-compare parameter. The parameter can be set for all merge processes using the "AUTOSTART" functionality (from CIB merge versions 3.9.104 and 3.8.130). The "AUTOSTART" - parameter file can be patched directly into the binary file via hex editor or the environment variable "CIB_MRGAUTOSTART" can be set with the parameter file name.

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.

Possible values for <Option> are:

Example

--old-compare=+

CIB merge interprets the conditions according to the old comparison method.

„“ ist gleich „+“. Die Voreinstellung ist „-“

Wenn „+“ eingestellt ist, interpretiert CIB merge Bedingungen, wie in den vergangenen Versionen (bis 3.9.127 bzw. 3.8.126). Die Erweiterung wird in CIB merge 3.8 und 3.9 aufgenommen.

6.53. Parameter --optimize

The parameter --optimize removes the superfluous switches inserted by MS Word.

Syntax

--optimize

Description

When inserting or reformatting REF fields, MS Word sometimes inserts a switch \* FORMATBINDEN or \* MERGEFORMAT, which makes the raw texts less readable and leads to performance disadvantages in CIB merge. CIB merge removes these superfluous switches with the –optimize parameter.

Example

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

Here all MERGEFORMAT switches are removed from the RTF optimization_in.rtf without mixing in field results (--filter=f). The result letter_optimized does not contain such switches anymore.

The usage of this parameter together with other optimization parameters is described in the Gap Text example.

6.54. Parameter --outputfile

[--output/-o]

The --outputfile parameter specifies the output or result file.

Syntax

--outputfile=<Ausgabedatei>

Description

The call --outputfile=! overwrites an already existing output file, --outputfile=+ appends the output file to the already existing file and thus creates a MultiRTF file.

If no explicit path is given, the file is created in the working directory specified with --target-directory, without --target-directory the output file is stored in the current directory.

Example

• Creation of a single-RTF file

--outputfile=!Anschreiben_out.rtf

The file cover_letter_out.rtf is written to the current directory. The exclamation mark may overwrite an already existing file.