General
Additional instructions
Examples
Remarks on pages in different formats
Examples with different formats

---

General

By specifying the "BackgroundFilename" property for the PdfJoin, the result document of the join is stored with the PDF files specified in this property. Various specifications are possible here to distribute the background document as required over the pages of the main document.

Via the property "BackgroundFilenameAsForeground" it can be arranged that the result document is not stored, but that the file specified here is placed in the foreground.

BackgroundFilenameAsForeground:

Possible Values:
0          Document lies in the background (default)
1          Document lies in the foreground

 

The "BackgroundFilename" property is assigned as follows:BackgroundFilename=“{Page number(s)};FileName;{Page number(s)};FileName;...“

Description	Value	Effect
Page number(s)	not specified or “All”	Distribute on all pages
	Distribute on all pages	Distribute on odd pages
	“Even”	Distribute on even pages
	“First”	Only on the first page
	“Last”	Only on the last page
	“NoFirst”	All pages except the first
	“NoLast”	All pages except the last
	Number	Only on page number
	Number1-Number2	From page Number1 to Number2
	Number1-Number2,Number3, ...,NumberN-NumberM	Distribute on several pages or page areas (comma as separator)
FileName	Path to file	The pages of this file are stored
BackgroundAdjustment (since version 1.16.1)	AllExactMatches Behaviour as before (Default) FirstExactMatch Apply the first exactly matching background page defined in the BackgroundFilename property for the current page. If none fits, an error code (366) is output and terminated. BestMatch pply the most appropriate background page from those defined in the BackgroundFilename property for the current page. If the application of this background page fails, an error code (366) is output and terminated.

 

The page specifications have different priorities, so that lower priorities can be overwritten by higher ones. The priorities are distributed as follows:

Priority None: All, Odd, Even, NoLast, NoFirst

Priority DIRECT: Last, First, Number

Priority RANGE: Number1 – Number2

The following order of priority applies: Priority None < RANGE < DIRECT

 

If two specifications have the same priority, both apply, otherwise the specification with the higher priority applies and the specification with the lower priority is not used.

If a page of a background document is to be distributed on different pages by several page specifications, these must be separated by commas. For example, First, Last means that the page should be placed behind the first and last page of the input document.

A background document can consist of several pages. In this case, several pages can be specified per file, separated by semicolons (e.g. {First,Last;Even} This way, the first page of the stationery is placed on the first and last page of the main document and the second page on all remaining even pages). The first specification thus refers to the first page of the background document, the second specification to the second page, and so on. Note that the page specifications must be placed in curly brackets as soon as they refer to several pages. This allows great flexibility in specifying on which pages of the main document which page of the background documents is to be stored. The property "BackgroundFilename" can also be used to specify several stationery statements one after the other.

Additional instructions

To express that certain instructions are to apply in addition, the information should be separated by curly brackets.

Everything inside the curly brackets is governed by the priorities mentioned above, but no priority is given between the curly brackets.

If one side of the stationery is not to be used, simply enter a 0.

{1;0;2} thus means that the first page is placed behind the first page of the main document, the 2nd page behind none and the 3rd page behind the 2nd page.

The following examples illustrate the use of the stationery functionality:

Examples

The examples show possible calls via the CIB runshell.

The command line of the examples reads as follows:

1.     Set Backgroundfilename Property

2.     Runshell command PDF-Join = cibrsh.exe –fj

3.     input output

 

A.     cibrsh.exe BackgroundFilename=“{First;All};backgrounds.pdf“ –fj content.pdf output.pdf

Here the first page of backgrounds.pdf is placed behind the first page of content.pdf, and the second page of backgrounds.pdf is placed behind the remaining pages of content.pdf. The result is saved in output.pdf.

B.     cibrsh.exe BackgroundFilename=“First;firstbackground.pdf;All;normalbackground.pdf“ –fj content.pdf output.pdf

Here the first page of firstbackground.pdf is placed behind the first page of content.pdf, and the first page of normalbackground.pdf is placed behind the remaining pages. B. does the same as A., except that the two pages of the background are now spread over two files.

C.     cibrsh.exe BackgroundFilename=“{Odd;Even};background.pdf;1-2;mainbackground.pdf“ –fj content.pdf output.pdf

Here the first page of mainbackground.pdf is placed behind the first and second page of content.pdf (because of higher priority of "1-2" over "Odd" and "Even"), the first page of background.pdf is placed behind all remaining odd pages of content.pdf and the second page of background.pdf is placed behind all remaining even pages of content.pdf.

D.     cibrsh.exe BackgroundFilename=“{1;2;3;4;5;6;7;8};background_8Pages.pdf“ –fj content.pdf output.pdf

Here the first page of background_8Pages.pdf is placed behind the first page of content.pdf, the second behind the second, the third behind the third and so on.

E.      cibrsh.exe BackgroundFilename=“{First;All};backgrounds.pdf“ –fj content1.pdf;content2.pdf;content3.pdf output.pdf

First, a regular join of the three input documents (content1.pdf ... content3.pdf) is carried out and then the stationery is deposited as described under A.

Remarks on pages in different formats

A page can only be backed with another page if the heights and widths are the same, with a tolerance of 3 pt. This means that the side to be backed may be no more than 3 pt (equivalent to 0.35 mm) higher or wider than the other.

Two pages can only be mixed together if their heights and widths are the same (up to a tolerance of 3 pt). If no letter paper fits, a warning is issued in the trace but no program termination is generated.

Since version 1.16.1 of the CIB pdf toolbox the selection of the background page can be controlled via the BackgroundAdjustment property: Selection of the first exactly fitting background page or selection of the best fitting background page.

If one of these two options is set and the background page fails, the program is aborted and an error message (366) is displayed.

If you want to add a background to a document that consists of a mixture of horizontal and vertical pages, this is possible if the background document contains pages for both formats.

However, the pages for the different formats must not be distributed over several files.

Examples with different formats

cibrsh.exe BackgroundFilename=“{All;All};backgrounds.pdf“ –fj AlternatingFormats.pdf output.pdf

The first page of backgrounds.pdf is a page in horizontal format, the second page is a page in vertical format. The input file consists of both horizontal and vertical pages, where all horizontal pages are placed with the first page of backgrounds.pdf and all vertical pages with the second page of backgrounds.pdf

Natürlich kann man auch hier verschiedene Seitenangaben machen, wie etwa BackgroundFilename=“{Odd;Even;Odd;Even};backgrounds.pdf“

Of course, you can also enter different page specifications here, such as BackgroundFilename="{Odd;Even;Odd;Even};backgrounds.pdf".

Here, the file backgrounds.pdf consists of 4 pages, the first two in horizontal format, of which the first one is deposited on all odd horizontal format pages and the second one on all even horizontal format pages. The third and fourth pages are in vertical format and are to be placed on odd and even vertical format pages respectively.