This section contains introductory information about VDPMill.

VDPMill is a library of Java classes for splitting, collecting XML data and converting it to printable formats, such as PDF, PostScript, AFP and to the RenderX intermediate XML format XEPOUT.

The VDPMill concept is to build a complete solution for small to large businesses for collecting, composing and creating print packages of content to address batch print for mailing and distribution, as well as creating of scheduled volumes of information for archive or other forms of distribution such as email.

The document processing steps are described in Chapter 3, VDPMill Document Processing

VDPMill distribution includes a GUI-based tools suitable for the users that prefer graphical user interface to use VDPMill functionality interactively, to make VDPMill job tickets, apply them to VDPMill job processing engine, run, stop, configure VDPMill components. For detailed description, see Chapter 4, VDPMill Interactive GUI Application, Chapter 5, VDPMill Ticket Application , Chapter 7, VDPMill Control Panel.

There are command-line interfaces (CLI) for VDPMill which provide full functionality and are suitable for users, who prefer Unix-like systems. They also can be used to call VDPMill from shell/batch scripts and Makefiles.

To install VDPMill, run the VDPMill installer via the command line:

java -jar setup-vdpmill-4.0.1.084.jar

and follow the instructions given by the installer.

1.3.1. Unattended Installation

Normal, interactive installation of Java-based application assumes the user to answer several questions asked by the GUI installer. These questions may include target installation directory, answering Yes/No if you agree with the license terms, etc.

RenderX products, including VDPMill, are also capable of unattended installation. It requires an Answer File that holds answers to questions the user would normally answer to a GUI-based installation.

To create the Answer File:

Open command line and start installation in the interactive command line mode (-c option):

java -jar setup-vdpmill-4.0.1.084.jar -c

Answer the questions the installer asks until the last one ("I'm going install VDPMill:").

Figure 1.1. Creating an Answer File

Save every answer you entered into a text file (e.g., answers.txt). An empty line assumes the default answer.

For the answers listed in the screenshot above, the answers.txt would be like this:

YES E:\RenderX\VDPMill YES E:\VDPMill\license.xml YES YES

Each line represents an answer for a particular question.

Important:

Mind the empty lines kept intact since a missed or an extra one may lead subsequent answers being applied to wrong questions.

As soon as the Answer File is ready, apply this file with the installer's command line at each host the application is being installed:

Windows:

type answers.txt | java -jar setup-vdpmill-4.0.1.084.jar -c

Linux:

cat answers.txt | java -jar setup-vdpmill-4.0.1.084.jar -c

The installer will read the answers and apply them within the installation process.

Figure 1.2. Applying the Answer File

VDPMill package includes the following:

VDPMill components store intermediate and temporary data in the file system during running. They use the following files and directories:

To uninstall VDPMill, remove the VDPMill installation directory and all its content. Also remove the directories and files listed in the list above.

VDPMill includes the following configuration files:

splitter.conf defines splitter type and input XML document splitting rules, split start type and split point type.

The splitter types can be the following:

The split start types can be the following:

The split point types can be the following:

The splitting rules are explained in the table below

controlpanel.conf stores VDPMill Control Panel Configuration.

The logical flow of document processing can be divided into three phases:

Pre-formatting steps are the following:

XSLT transforms a user-defined XML document to another XML document. Several tasks can be done in this stage of processing (adding barcodes to a document, etc). Basically XSLT is used to generate XSL-FO files from XML documents.

Splitting divides a file into smaller chunks. The content and size of the chunks depend on the source file and the splitting rules. The split chunks can be formatted and then delivered in a printable format. They can be joined after the formatting into one large file. Splitting large files helps to avoid out of memory errors on large file formatting processes.

Formatting converts XSL-FO files to the XEPOUT format. If the source file contains a reference to a stylesheet, or an external stylesheet specified (in the GUI, from the command line, or via VDPMill API), XSLT is done before formatting.

Custom Post-processing can be used to customize a formatted document before generation (adding watermarks to a document, applying transpromo, filtering OMR marks or any user-defined actions).

The Joining functionality can be used to get one large output file after Splitting and Formatting and generate large printable documents. It also can be used to concatenate XEPOUT files from other sources.

Separated output generation makes printable documents /PDF, PostScript, AFP/ from XEPOUT files.

VDPMill uses RenderX XEP and EnMasse to format XSL-FO files.

The XML file will be transformed before formatting if it contains a reference to a stylesheet. This option is supported only if the formatter-type is enmasse (See Section 2.2, “ vdpmill.conf Description”). VDPMill also allows pre- and post- split xsl transformations (See Pre-split XSLT and Post-split XSLT points in Chapter 3, VDPMill Document Processing).

XEPOUT documents can be processed specially before final format files are generated. Since XEPOUT documents are in XML, a special post-processor can handle them and pass modified XEPOUT document to the final format generator or joiner.

For the detailed description of document post-processing see Appendix D, Document Post-processing.

Some printers can accept large files (PostScript, AFP). Large print files can be generated with VDPMill by joining XEPOUT chunks. Simply, XEPOUT files are concatenated by adding the pages sequence from the second file to the first and so on. In the example below there are three separated XEPOUT files and the joining of these files is the result:

the separated files:

<?xml version="1.0" encoding="UTF-8"?>

<xep:document xmlns:xep="http://www.renderx.com/XEP/xep" producer="XEP 4.13" 
              creator="Unknown" author="Unknown" title="Untitled">

  <xep:page width="576000" height="792000" page-number="1" page-id="1">
    <xep:word-spacing value="0"/>
    <xep:letter-spacing value="0"/>
    <xep:font-stretch value="1.0"/>
    <xep:font family="Helvetica" weight="400" style="normal" variant="normal" 
              size="12000"/>
    <xep:gray-color gray="0.0"/>
    <xep:text value="D" x="56400" y="725334" width="8184"/>
    ...
  </xep:page>
</xep:document>

<?xml version="1.0" encoding="UTF-8"?>

<xep:document xmlns:xep="http://www.renderx.com/XEP/xep" producer="XEP 4.13" 
              creator="Unknown" author="Unknown" title="Untitled">

  <xep:page width="576000" height="792000" page-number="1" page-id="1">
    ...
  </xep:page>
</xep:document>

<?xml version="1.0" encoding="UTF-8"?>

<xep:document xmlns:xep="http://www.renderx.com/XEP/xep" producer="XEP 4.13" 
              creator="Unknown" author="Unknown" title="Untitled">

  <xep:page width="576000" height="792000" page-number="1" page-id="1">
    ...
  </xep:page>
</xep:document>

the result:

<?xml version="1.0" encoding="UTF-8"?>
  
<xep:document xmlns:xep="http://www.renderx.com/XEP/xep" producer="XEP 4.13" 
              creator="Unknown" author="Unknown" title="Untitled">
  
  <xep:page width="576000" height="792000" page-number="1" page-id="1">
    <xep:word-spacing value="0"/>
    <xep:letter-spacing value="0"/>
    <xep:font-stretch value="1.0"/>
    <xep:font family="Helvetica" weight="400" style="normal" variant="normal"
              size="12000"/>
    <xep:gray-color gray="0.0"/>
    <xep:text value="D" x="56400" y="725334" width="8184"/>
    ...
  </xep:page>
  
  
  <xep:page width="576000" height="792000" page-number="1" page-id="1">
  ...
  </xep:page>
  
  <xep:page width="576000" height="792000" page-number="1" page-id="1">
  ...
  </xep:page>
</xep:document>

VDPMill supports flexible Join operations. For example, it is possible to get joined PDF output, separated PS, joined AFP, joined and separated XEPOUT files (see Chapter 4, VDPMill Interactive GUI Application and Chapter 9, VDPMill Command Line Interface).

Chunk document appearance in the joined output files can be controlled using special XML PIs. See Section 3.2.5, “Final Format Generation Control using XML PIs”.

The Generation process makes printable files from chunk XEPOUT documents. For available output formats and final format options see XEP User Guide.

Chunk document appearance in the joined output files can be controlled using special XML PIs. See Section 3.2.5, “Final Format Generation Control using XML PIs”.

VDPMill contains a user-friendly GUI tool called the VDPMill Interactive Application. Use of VDPMill Interactive Application simplifies the whole functionality of VDPMill.

VDPMill Interactive application look and feel varies depending on the operating system the application is running on.

To open VDPMill Interactive, launch the vdpmill-gui script (the vdpmill-gui.bat batch file for MS Windows) in the /bin directory located in the VDPMill installation directory.

VDPMill parameters can be configured by using the GUI.

For a detailed description of VDPMill parameters and component types see Chapter 2, VDPMill Configuration and Section 7.4, “Configuring VDPMill Core Parameters ”.

VDPMill Ticket Application (VDPMillTicket) is a GUI tool to create VDPMill Job Ticket files. To launch the application run vdpmill-ticket script (the vdpmill-ticket.bat batch file for MS Windows) in the /bin directory located in the VDPMill installation directory.

Figure 5.1. VDPMillTicket Application Interface

This application is a light-weight variation of VDPMill Interactive application and has a simple user interface to specify input files, pre/post-split stylesheet paths, desired actions, output targets, output directory, splitting options, options for output formats, output directory, path to log file, log level and special processing options.

VDPMillTicket (as well as VDPMill Interactive) saves projects as VDPMill Job Ticket format files. For VDPMill Job Ticket format description see Appendix C, Job Ticket Format Description.

Once the ticket file is created it can be processed by pressing Save And Apply button or using VDPMill CLI tool (Chapter 9, VDPMill Command Line Interface), VDPMill Control Panel (Chapter 7, VDPMill Control Panel), VDPMill XML-RPC Client CLI tool (Section B.2, “XML-RPC Client ”).

In VDPMill terms, an XML generator is an executable file that takes two command-line arguments (the input file in any format and the output XML file), runs modally (without returning the control until it finishes running) and returning 0 on successful generation and a positive integer on failure. The generated XML file becomes an input file for VDPMill Ticket and VDPMill Interactive applications.

XML generators are useful when the input XML files need to be generated from some data providers, such as databases or web-services, or the input XML stream needs to be modified by an external application.

VDPMill Interactive and VDPMill Ticket applications use XML generators, as configured in the vdpmill.conf file. Users are free to configure VDPMill to use any suitable executable as an XML generator. To add a new XML generator to the vdpmill.conf file add a nested xml-generator element to the xml-generators element in vdpmill.conf file (add the xml-generators element first, if it doesn't exist).

Here is an example of a new XML generator configured:

  ...
  <xep configuration="xep.xml"/>
  <xml-generators>
    <xml-generator name="RenderX DB2XML" command="file:/DB2XML/db2xmldriver.exe" 
                      input-file-extensions="dxt/xml"/>
  </xml-generators>
  <formatter type="enmasse">
  ...

For more details, see vdpmill.conf description. The input-file-extensions attribute is a slash-separated (/) list of file extensions, which is used to browse for the input file in XML Generators dialog box.

VDPMill Altova MapForce Edition is preconfigured to use MapForce as an XML generator. In this version, the default vdpmill.conf file includes the following xml-generator element:

  ...
  <xml-generators>
    <xml-generator name="Altova MapForce" command="../bin/mapforcecmd.exe" 
                      input-file-extensions="mfd"/>
  </xml-generators>
  ...

VDPMill Control Panel is a GUI application to run/stop/configure VDPMill XML-RPC Server and EnMasse. It runs VDPMill XML-RPC Server and EnMasse as background processes.

To open VDPMill Control Panel, launch the vdpmill-control-panel script (the vdpmill-control-panel.bat batch file for MS Windows) in the /bin directory located in the VDPMill installation directory.

VDPMill Control Panel displays the status of XML-RPC Server and its parameters on the XML-RPC Server tab. To run/stop/restart the VDPMill XML-RPC Server press Start/Stop/Restart buttons on the XML-RPC Server tab.

Figure 7.1. VDPMill Control Panel XML-RPC Server Configuration

VDPMill Control Panel allows to change configuration parameters via GUI. After parameter changes it is necessary to save changes and restart the server. Press Save button to save parameter changes. For detailed information about configuration parameters see Section 2.4, “ controlpanel.conf Description ”.

If a firewall is used to allow/deny network connections, the TCP port for VDPMill XML-RPC Server must be allowed for incoming connections from the local host.

VDPMill Core Parameters are displayed on the VDPMill tab in the control panel application. It is necessary to save parameters and restart the XML-RPC Server and EnMasse (if EnMasse-related parameter is changed and EnMasse is selected as formatter - Formatter Type = enmasse). For detailed information about VDPMill Core configuration parameters, see Section 2.2, “ vdpmill.conf Description”.

Figure 7.2. VDPMill Core Parameters displayed in VDPMill Control Panel

EnMasse tab contains Start, Stop and Restart buttons to control the EnMasse processing and options table to change EnMasse configuration parameters. After any changes it is necessary to save the configuration changes and restart EnMasse. For detailed information about EnMasse configuration parameters see EnMasse User Guide

Figure 7.3. VDPMill Control Panel EnMasse Configuration

VDPMill Job Monitor is a GUI application to apply and manipulate with jobs.

The Job Monitor connects to the VDPMill XML-RPC Server on the specified port and displays the jobs applied to the server. If it is failed to connect to the server, it tries to reconnect after a time period. Any active job can be paused/resumed or canceled and it is possible to set priority to the non finished jobs.

To open VDPMill Job Monitor, launch the vdpmill-job-monitor script (the vdpmill-job-monitor.bat batch file for MS Windows) in the /bin directory located in the VDPMill installation directory.

Job Monitor is used to apply/pause/resume jobs and view the jobs applied to the server. It displays the jobs as a four-column table, containing ticket file name, status, priority and the job Id created to process the ticket. To use Job Monitor, the VDPMill XML-RPC Server should be started (see Section 7.3, “Configuring and Running XML-RPC Server ”).

To process a job, a ticket file should be applied. Select Apply Job from the File menu or click on the on the processing toolbar. Select the ticket file(s) to be applied from the open file browser. The application applies the selected job tickets to the server which queues the jobs for further processing. If a ticket file contains invalid ticket data corresponding error message appears in the log and the server ignores the ticket.

It is also possible to create a new ticket. The Create New Ticket button opens VDPMill Ticket Application (see Chapter 5, VDPMill Ticket Application ).

Once a job is applied it can be paused/canceled or resumed after pausing. To pause/resume/cancel job processing check the job and click on Pause, Resume and Cancel buttons on the processing toolbar or select Pause, Resume and Cancel from the Process menu respectively.

Until the job is in process, it is possible to set its priority. To change the job's priority, select the job, change priority on the processing tool bar and press Set button. The new priority should appear for the job in the Jobs list table.

Finished jobs are always inactive and manipulations are not allowed.

For detailed information about job states and allowed operations see Section A.3, “Job States”.

Figure 8.1. VDPMill Job Monitor Interface

Job Monitor logs all the job operations in the log panel that is below the jobs table. It is also possible to hide/show the log panel by selecting the Show Log from the File menu. To open the particular job's log separately, select the job and press View Log button on the processing tool bar or double click on the job in the jobs list, then Job Monitor displays log messages for the job (if any) in a separated window that contains Pause/Resume/Cancel buttons as well.

Figure 8.2. VDPMill Job Monitor Log View

Advanced Options tab allows to define the port number to connect to the XML-RPC server. The default port number is 19810. It should be applied after changes by pressing Apply button. To revert port number value to the last value before changes press Revert button. To reload from the state file press Reload from State file button.

Figure 8.3. VDPMill Job Monitor Advanced Options

The VDPMill command line syntax is the following:

            Usage: com.renderx.df.Main -h|--help| 
                or 
            [-d ] -c configfile -p|--project projectfile 
                or
            [-d ] -c configfile -o outputdir actions
            [-f format ] [-j format ]
            [--pre-split-stylesheet stylesheet ]
            [--post-split-stylesheet stylesheet ]
            [--post-process-tranpromo] [--post-process-omr] 
            [--post-process-sequence] files
              

where: