Getting Support

When contacting technical support please provide us with as much information as possible including the following:

• Name of the Product
• Product Version Number
• Operating System
• Your Name
• Company Name
• Your Email Address
• Your Phone Number
• Product Registration Number
• Any files to help us reproduce your problem (if needed)

Support E-mail

You can contact support directly by sending an e-mail to support@appligent.com
Support e-mails are answered within one business day during the normal business hours listed below.

Support Telephone & Fax

Telephone: +1 610 284 4006
Fax: +1 610 284 4233

To better serve you, please call us during our normal business hours, Monday – Friday, 8:00 am – 5:00 pm U.S. EST/EDT. A member of our friendly, knowledgeable support staff will reply as soon as possible, generally within one business day.

In this chapter…

…we present a collection of hints and tips for working with FDFMerge Lite and FDFMerge. If you are having trouble with the software, consult this list of issues for a possible solution. Information that is specific to FDFMerge is in green text followed by a notation: (FDFMerge only).

Common Error Checklist

Before proceeding, if you are having problems with your PDF files, check that they are well formed, and not corrupt. Refer to Cleaning Up PDF Documents.

• When using FDFMerge Lite or FDFMerge in a script, be sure to use full path names for all files and applications accessed from within the script. If you cannot get your script to work, make sure that you can run FDFMerge Lite or FDFMerge from a command line.
• If you find your files are not working as you had expected, you may wish to try re-saving them in Acrobat as Optimized.
• Check to see that the PDF file is listed before the FDF file on the command line. However, if you are running with -reverse, then the FDF should be listed before the PDF file.
• Review the command-line options to be sure they are entered properly. Make sure options -f <FormInfo file>, -cmds <CommandFile.txt>, -l <logfile> and -o <output file> have file names specified after them. Missing file names will cause unintended results.
• Make sure all file and path names are correct. If you are working in one directory and FDFMerge Lite or FDFMerge resides in another, you must account for that in the command-line call. We recommend that you always use full paths to all files including FDF, input, output and log files.
• Even if you are running FDFMerge Lite or FDFMerge in its own directory, enter the command with the dot-slash in front (./fdfmergelite or ./fdfmerge), to tell your system that the application is in the current directory. This is more important for UNIX than for Windows.
• We recommend that you always use the -o <output file> option so that you do not overwrite your original file in case you may need it later.
• If you get an error from FDFMerge Lite or FDFMerge that the file was unable to write, check to make sure that the file isn’t open in Adobe Acrobat or any other application. Also be sure the file is not set as read-only or encrypted.

If you are using a FormInfo file with FDFMerge, double check the following (FDFMerge only):

• Are all the Form Field names correct, including capitalization and spelling?
• Are the parameter names correctly spelled, such as ColorRed, not Color Red, etc.?
• Are the paths correct for font files?
• Are the .pfm and .pfb files for the fonts in the same directory?
• If you are using colors for fonts, borders, backgrounds, etc., have you specified values for all three colors: Red, Green, and Blue? or all four colors: Cyan, Magenta, Yellow, and Black?

In this chapter…

… we present a collection of hints and tips for working with AppendPDF and AppendPDF Pro. If you are having trouble with the software, consult this list of issues for a possible solution.

Common error checklist

Before proceeding, if you are having problems with your PDF files, check that they are well-formed and not corrupt. Refer to Cleaning Up PDF Documents.

• AppendPDF or AppendPDF Pro will not work properly with files that contain active form fields. You must flatten the form fields before running the files through AppendPDF or AppendPDF Pro.
• AppendPDF or AppendPDF Pro will not work with encrypted or write-protected files. Full permission on all files and paths is required for AppendPDF or AppendPDF Pro to work properly.
• When using the log file option, -l, there must be a log file name immediately following the -l option. If there is no file name, AppendPDF or AppendPDF Pro will not process and an error message will be appended to the bottom of your parameter file.
• Make sure all file and path names are correct. If you are working in one directory and AppendPDF or AppendPDF Pro resides in another, you must account for that in your parameter file and command line. We recommend that you always use full paths to all files used in your parameter file.

For parameter files:

• Be aware that if even one path or file name is wrong in your parameter file the entire append will fail.
• Recheck the construction of the parameter file. Misspelled keywords (i.e., BeginSource instead of begin_source in the text parameter file) or keywords left out will cause AppendPDF or AppendPDF Pro to fail. For xml parameter file, make sure tags are balanced, each tag has a begin and end tag: <inputpdf>file.pdf</inputpdf>
• Make sure there are no commas in filenames. AppendPDF or AppendPDF Pro will try to interpret the commas as part of a page range for the document.
• Make sure there are no spaces in source file entries. All items in the source files block of the parameter file should have no spaces between filename, commas, and page numbers.
• Make sure there is at least one space between an individual parameter and the parentheses that hold the value for that parameter, like this:

  parameter1 (value)
  parameter2 (value)

• Comments must be at the beginning of a line and start with the # symbol. If you are using comments in your parameter file, make sure they start at the beginning of a line.
• A parameter file should contain only one source files block. AppendPDF and AppendPDF Pro will ignore any source files block after the first one. Add all files to be appended together into one block. Use multiple parameter files to generate multiple output PDF files.

In this chapter…

…we will discuss ASP and Java examples.

Apart from Perl, whose sample script appears in the previous appendix, ASP and Java are two more popular technologies used today. Here are some sample code fragments and notes to help you get started using FDFMerge Lite or FDFMerge within either ASP or Java. These samples are provided “as is” and Appligent does not provide scripting support other than the provision of these examples.

If you have trouble running FDFMerge Lite or FDFMerge within a script, try to run the software directly from the command line. This will tell you whether the problem is with the script or with FDFMerge Lite or FDFMerge.

FDFMerge with ASP

This first example uses Windows Scripting Host to call FDFMerge. Windows Scripting Host comes with most current versions of Windows. This example states where FDFMerge is located, sets up the command to be used, and sets up a shell for running FDFMerge.

'Built the Executable statement
sFdfMergeAppl = sFdfMerge & " -r " & sFdfMergeRegNum
sFdfMergeParms = " -s -p -l " & sLogFile & " -o " & sOutPDFFile
sFdfMergeParms = sFdfMergeParms & " " &InPdfFile & " " & sInFdfFile
sFdfMergeCmd = sFdfMergeAppl & " " & sFdfMergeParms

'Create the Shell object to run the FDFMerge command line.
Set wShell = Server.CreateObject("WScript.Shell")

'Execute the FDFMerge command line and get the return code.
iReturn = wShell.Run( sFdfMergeCmd, 10, True )
Set wShell = Nothing

FDFMerge in a Java Servlet

The following is a sample Java servlet that runs FDFMerge. This example has been adapted from a Sun example. Users may wish to visit Sun’s Java website for more information. Keep the following tips in mind when using this example:

• Use the full path for the fdfmerge executable and for each of the argument files (out.pdf, in.pdf, and in.fdf).
• Give the target directory full permissions to be certain that the Servlet can execute and write without restriction.
• Since FDFMerge outputs to STDOUT when the -p option is included, the Servlet can report the results in addition to creating the target PDF file.
• By capturing this output in a string variable, “Initializing…done.” can be included in the generated HTML.
• In the Windows environment directory paths are separated using the backslash (\) character. Since the backslash (\) is also an escape character you must use double backslashes (\\) for directory paths on Windows.

The sample Java servlet is shown below.

// Example Servlet -- Sample execution of Appligent FDFMerge
 
import java.io.*;
 
import javax.servlet.*;
import javax.servlet.http.*;
 
 
/**
* This is a simple, Sun-provided, example of an HTTP Servlet.
* The example has been modified to demo Appligent Merge execution!
* It responds to the GET and HEAD methods of the HTTP protocol.
*/
 
public class FDFMerge_Servlet_27 extends HttpServlet
{
/**
* Handle the GET and HEAD methods by building a simple web page.
* Include the execution and output of Appligent FDFMerge
* HEAD is just like GET, except that the server returns only the
* headers (including content length) not the body we write.
*/
public void doGet (HttpServletRequest request,
HttpServletResponse response)
  throws ServletException, IOException
  {
   PrintWriter out;
   String title = "Example Apache JServ Servlet --
    Executing Appligent FDFMerge!";
 
   // set content type and other response header fields first
   response.setContentType("text/html");
 
   // then write the data of the response
   out = response.getWriter();
 
 
  // define the FDFMerge command-line components
  String fdfmerge_cmd = "/usr/apache/servlets/fdfmerge -p -s -o ";
  String fdf_file = " /usr/apache/servlets/gen_srvlt_frm1.fdf ";
  String pdf_infile = " /usr/apache/servlets/GenDBform01.pdf ";
  String pdf_outfile = " /usr/apache/servlets/test_srvlt_27_1200.pdf ";
  String fdf_result = "FDF Result:= ";
  String fdf_error = "FDF ERROR MESSAGE:= ";
 
  if (fdfmerge_cmd !=null && fdf_file !=null
   && pdf_infile !=null && pdf_outfile !=null) {
 
   Runtime rt = Runtime.getRuntime();
 
    String exec_strg = fdfmerge_cmd +
     pdf_outfile +
     pdf_infile +
     fdf_file;
 
  // DEBUG: use a standard OS cmd like 'cat' or 'type' to test the Servlet
  // String exec_strg = "cat /usr/apache/servlets/TEST_STDOUT_1.txt";
 
   try
{
 
   Process p = rt.exec(exec_strg);   // Start the cmd
   
   InputStream os = p.getInputStream();   // Read bytes from cmd
 
   InputStreamReader osr = new InputStreamReader(os);
   // Convert to chars
 
   BufferedReader br = new BufferedReader(osr);  // Read Lines of chars 
 
     String s = br.readLine();
 
    fdf_result = "std_out> " + s;
 
   br.close();    
 
   }
    catch(IOException e)
   {
   // System.err.println("Caught ioexception in
     // testdatamerg.runFDFtest: " + e);
   fdf_error = "std_err> " + "Caught ioexception in
    testdatamerg.runFDFtest!!!" + e;
   // System.out.println(e.toString());
   }
 
 
 
  } else {
 
   fdf_result = "Error: Null FDFMerge cmd or arguments!";
 
  }
 
 
    out.println("<HTML><HEAD><TITLE>");
       out.println(title);
    out.println("</TITLE></HEAD><BODY bgcolor="#FFFFFF">");
    out.println("<H1>" + title + "</H1>");
    out.println("<H2> ApacheJServ 1.1.2 - Sample Appligent
     FDFMerge Servlet!<br>");
 
   out.println("FDF_RESULT> " + fdf_result);
   out.println("<br>");
   out.println("FDF_ERROR> " + fdf_error);
   out.println("<br>");
    out.println("</BODY></HTML>");
    out.close();
   } 
}

In this chapter…

…we will discuss implementing a Perl CGI scripts.

This sample script is based on an FDFMerge sample script on the Appligent website. The algorithm of the script is discussed in FDFMerge – Automating or FDFMerge Lite – Automating.

#PERL cgi source for FDFMerge Mutual Fund Demonstration

####################################################################################
##Configuration section-replace paths with your own data if not using default.##
####################################################################################
## Webmasters E-mail address, replace with your own. Make sure 
## a \ is included before the @ and .
# Address appears on server error page if error occurs.
$webmaster = "webmaster\@appligent\.com";
$Platform = "WIN"; # WIN or Unix

# set up general paths and program locations
## Path to fdfmerge without extension
$FDFMergeRoot  = "C:/Appligent/FDFMerge/fdfmerge";

## Main Directory where files are located
$MainDir = "C:/Appligent/Demos/WebSiteExamples/FDFMerge_PerlDemo";

## Path/filename for FDFMerge to create output file. 
## ("output file" is the new copy of PDF returned by FDFMerge 
## with the merged/stamped data)
## If you do not want to include the time in the output file name, 
## remove the $tm.
## Prints as filename120101.pdf. (if time was 12:01:01)
$outputDirName = "output"; # name of folder to contain all output files
$outputDir = "$MainDir/$outputDirName"; #Full path to output files
$outfileName = "out_SimpleDemo.pdf"; # name for output pdf file
$outfile = "$outputDir/$outfileName"; # Path & name for output PDF file

$pdffile = "$MainDir/input/SimpleDemo.pdf"; #Path & name for input PDF form
$fdffile = "$outputDir/SimpleDemo.fdf"; #Path & name for fdf or xfdf file
$logfile = "$outputDir/logfile.txt"; #Path & name for log file for FDFMerge

# Remove Comment marks to print to Debug text file
#open(DEBUG,  ">" . "$outputDir/debug.txt")  || die "problem: $!";
#print DEBUG "Starting Log\n";

############################## End Configuration Section ########################
#################################################################################

### Start main section of script ###

# set up executable and reg number
$FDFMerge = $FDFMergeRoot . "app";

# Read the Data submitted from the server:
&parse_form_data (*simple_form);

# Read submitted data into variables and set merge option
$merge = ReadFormData();

# Write FDF file to disk.
&WriteFDF($fdffile);



# Run FDFMerge
$execute = "$FDFMerge -r $FDFMergeRegNum $merge -p -l $logfile 
  -o $outfile $pdffile $fdffile";
`$execute`;
#print DEBUG "$execute\n";

#start of html page with link to newly created file
$wpth = "$outputDirName/$outfileName ";
print "Location: $wpth\n\n";
print "Content-type: application/pdf\n";
print "<html>","\n";
print "<head>","\n";
print "<title>FDFMerge Demo PDF File</title>","\n";
print "</head>\n";
print "</html>";

##############################################################################

## If you need help setting up this demo or if you have any questions about
## FDFMerge, please contact our Technical support dept. by e-mail, 
## support@appligent.com
## or by phone, 610-284-4006

## Copyright©2002 Appligent, Inc. All rights reserved.
## Sample Code supplied as example, use at your own risk. 
## We have tried to make this example easy to read and use. 
## However, Appligent makes no guarantees of any kind that this 
## code will work on your system.

############################## Subroutines ##################################
#############################################################################
# Parse the submitted HTML form data or the PDF Form data submitted as HTML.
## Parse form
sub parse_form_data
{
    local (*FORM_DATA) = @_;
    local ( $request_method, $query_string, @key_value_pairs,
           $key_value, $key, $value);

    $request_method = $ENV{'REQUEST_METHOD'};
    if ($request_method eq "GET") {
        $query_string = $ENV{'QUERY_STRING'};
    } elsif ($request_method eq "POST") {
        read (STDIN, $query_string, $ENV{'CONTENT_LENGTH'});
    } else {
        &return_error (500, "Server Error",
                       "Server uses unsupported method");
    }

    @key_value_pairs = split (/&/, $query_string);

    foreach $key_value (@key_value_pairs) {
        ($key, $value) = split (/=/, $key_value);
        $value =~ tr/+/ /;
        $value =~ s/%([\dA-Fa-f][\dA-Fa-f])/pack ("C", hex ($1))/eg;

        if (defined($FORM_DATA{$key})) {
            $FORM_DATA{$key} = join ("", $FORM_DATA{$key}, $value);
        } else {
            $FORM_DATA{$key} = $value;
        }
    }
}

############################################################################
## Get data from parsed form to variables

sub ReadFormData{

$name = $simple_form{'name'};
$co = $simple_form{'company'};
$city = $simple_form{'city'};
$state = $simple_form{'state'};
$country = $simple_form{'country'};
$email = $simple_form{'email'};
$merge_option = $simple_form{'merge_option'};

if ($merge_option eq "merge") {
 $merge = "";
 } else {
 $merge = "-s";
 }
 
$ReadFormData = $merge;
}


############################################################################
## Create FDF File
sub WriteFDF {

$fdffile = $_[0];
open FILE, join ("",">",$fdffile);

#if above line fails with your version of perl try the line below.
#open (FILE, ">" . $fdffile);

print FILE<<EOT;
%FDF-1.2

1 0 obj
<< 
/FDF 
<< /Fields [ 
<< /V ($city)/T (city)>> 
<< /V ($co)/T (company)>> 
<< /V ($country)/T (country)>> 
<< /V ($email)/T (email)>> 
<< /V /$merge_option /T (merge_option)>> 
<< /V ($name)/T (name)>> 
<< /V ($state)/T (state)>> 
] 
>> 
>> 
endobj
trailer
<<
/Root 1 0 R 
>>
%%EOF
EOT

close FILE;
}

############################################################################
## Return Error
sub return_error
{
    local ($status, $keyword, $message) = @_;

    print "Content-type: text/html\n\n";
    print "Status: ", $status, " ", $keyword, "\n\n";

    print <<End_of_Error;

<title>CGI Program - Unexpected Error</title>
<h1>$keyword</h1>
<hr>$message</hr>
Please contact $webmaster for more information.

End_of_Error

    exit(1);
}

In this chapter…

…we give a brief overview of CGI scripts and outline how you can use them to build applications that incorporate FDFMerge Lite and FDFMerge.

• FDFMerge Lite or FDFMerge and CGI Scripts Together briefly describes how combining these two elements creates solutions.
• Sample Scripts tells you where to find sample scripts and describes the algorithm for one of our demo scripts.
• Using FDFMerge Lite or FDFMerge as a Database Solution gives an outline of one way to incorporate FDFMerge Lite or FDFMerge in a database solution.

FDFMerge Lite or FDFMerge and CGI Scripts Together

If you are using FDFMerge Lite or FDFMerge to process information taken from a web server, you will find that you will rarely run FDFMerge Lite or FDFMerge from the command line. In order to incorporate FDFMerge Lite or FDFMerge into the operation of your web server you can use CGI scripts to provide a world wide web interface. CGI stands for Common Gateway Interface, and allows a web server and browser to interact. When a user clicks a web link, the CGI script associated with the link runs.

To create CGI scripts you can use any programming language that can call a command-line driven application. Some of the more popular languages include Visual Basic, Perl, ASP, Java, and C.

Sample Scripts

We make sample ASP, Perl, Java, PHP, and Visual Basic scripts available for you to review at our web site. The scripts are written for FDFMerge and can be found on our Sample Scripts webpage.

How the sample script might work

The following steps briefly summarize how a sample script works:

1. A customer fills out an HTML form and submits it. A PDF form version of the HTML form exists on the server. As an alternative, you could use a PDF form that submits the export format of HTML form (URL encoded).
2. The CGI script parses the form data and creates the FDF file with the field names and values the customer submitted.
3. The CGI script calls FDFMerge Lite or FDFMerge.
4. FDFMerge Lite or FDFMerge runs with the -o flag and makes a unique output file when it merges the form data and the PDF form document.
5. The CGI script renames the merged file by appending the system time to the name to make it unique. For more information about this step, see below.
6. The CGI script opens up the new merged PDF document.

Generating a unique filename for the completed form

Because the output filename is the same each time the CGI script runs, the script needs to rename the file so it won’t be overwritten. The current sample script appends the system time to the completed form name.

As an alternative to appending the time to your form name, you can have your CGI generate incrementing numbers instead. Each time the script runs, the number can be incremented by 1 and appended to the filename.

Using FDFMerge Lite or FDFMerge as a Database Solution

You can use FDFMerge Lite or FDFMerge to allow customers to retrieve and update information in a database. For example, a customer of a bank might want to visit her bank’s website to change her mailing address and access balances for several accounts.

1. The customer fills out and submits a form that requests specific information. The request will require authorization in the form of an account number and password.
2. A CGI script finds and extracts the requested information from the bank’s database and saves it to an FDF file.
3. The CGI script runs FDFMerge Lite or FDFMerge to merge the data with a PDF form and returns the completed form to the customer’s browser.
4. The customer views the completed form, makes the desired changes, and submits the updated information.
5. The script can then update the database with the new information the customer has submitted.

In this chapter…

…we will discuss automating AppendPDF and AppendPDF Pro with scripts. Content that is specific to AppendPDF Pro is followed by the notation: (AppendPDF Pro only).

It is likely that you will wish to incorporate AppendPDF or AppendPDF Pro into scripts that you build to make appending and delivering documents an automatic process.

AppendPDF and AppendPDF Pro, as command-line driven applications, can be run from any programming or scripting language (or other application) that can make a call to a command line.

This is especially true for regular weekly and monthly reports, or web pages that contain variable information, but in a consistent or standardized format. For example: a monthly sales report can be automatically generated by programmatically selecting individual sales reports from a standard set of directories. In addition to appending the periodic reports into a single document, a cover sheet, table of contents, and bookmarks can be generated.

When AppendPDF or AppendPDF Pro is combined with Appligent’s FDFMerge product, an application that merges FDF data files with PDF forms, it becomes practical to generate a complete report from dynamic information that is either entered manually (for example, via web forms) or automatically using database queries. Individual standardized report sections can be automatically filled in and saved into a standard set of directories with standardized file names. These dynamically generated PDF sections can then be appended into a single document.

Be Aware of Your Options

In addition to dynamic control of automatic document generation via parameter files, you can dynamically utilize the AppendPDF or AppendPDF Pro command-line options to produce different output under different conditions. Options to consider when dynamically executing AppendPDF or AppendPDF Pro include:

• Showing Progress (-p) — An if statement can determine whether this is an interactive run or a background run and can then turn progress on or off as appropriate.
• Writing to a Log File (-l <logfile>) — This is usually a good idea for batch document processing. Either the same log file can be appended, or a new log started with each run. A sophisticated script could check the log for errors and e-mail the administrator with any problems.
• Adding Bookmarks (-b) — Whether a script is designed to be interactive or run in the background as a batch process, an argument can be set to turn bookmarks on or off according to user preference.
• Version Information (-v) — Using this option with the log file option will capture the product version information in the log file.

When dynamically generating a parameter file, you should consider such options as:

• Page ranges — Using page ranges lets you specify partial documents to be included, and the -1 notation can be used in a range to indicate the last page.
• Document info — Any information you would like to attach to a document can go into the Document Info area of the output file.

Dynamically Generate Parameter Files

One way to automate AppendPDF or AppendPDF Pro would be to avoid having to type in each of your source files in the parameter file by creating a simple shell script to enumerate the contents of a directory directly into the parameter file.

Dynamic parameter files may be generated from Perl, Java, VBScript, Tcl or any shell script. Developing scripts to generate parameter files is a more efficient approach to PDF document generation when the document contents, file paths, and parameters are variable. Such scripts are also easier to maintain than many separate static parameter files.

For larger batch document runs, you can take advantage of the ability of AppendPDF and AppendPDF Pro to process several parameter files at a time.

The dynamic generation of one or more parameter files enables you to utilize the full power of AppendPDF and AppendPDF Pro. Examples of some of these advanced capabilities, include:

Cover page block — AppendPDF Pro only

The user could select from a list of pre-made cover pages, or select from any desired combination of cover sheet and cover sheet stamps. This would permit periodic “standardized” reports to retain a fresh look with each edition.

TOC block — AppendPDF Pro only

In addition to turning Table of Contents (TOC) information on or off, the user could be given the option of determining the appearance of the TOC by selecting from a list of standardized fonts, font sizes and colors. The application of stamp(s) to the TOC (for example, page numbers) could also be optional. The user could even override the default section titles in the generated TOC.

Extras block — AppendPDF Pro only

Since Extras stamps are only applied to the body of the generated document and not to the Cover Page or TOC, the user can be encouraged to provide additional stamped information for the body, for example, in the page header and footer. Stamped information containing text strings can contain variable items. An appropriate stamp could be programmatically generated or selected from a pre-defined or pre-generated collection of stamp files (for example, one for each department, group, or individual for which the document is targeted).

Dynamically generate stamp files — AppendPDF Pro only

The same considerations that have been given to dynamic parameter file generation can be given to the dynamic generation of stamp files. By combining both techniques, an up-to-date or even fully custom document can be generated. Either the user or the program can provide values for such variables and attributes as:

• Text to be stamped
• Stamps for the cover page
• Stamps for the TOC
• Headers and Footers
• Watermarks (DRAFT, Confidential, etc.)
• Font, Font Size and Color of the Stamped Text
• Text Mode (solid, outline, invisible)
• Location or Position of the Stamped Text
• Pages (and pages within Sections) to receive a particular stamp
• % variables for dates, times, page numbers and section numbers

Since AppendPDF Pro is sensitive to the exact format of stamp files, it is very important to understand the format requirements and that the program or script generates only well-constructed stamp files (for example, balanced parentheses, % signs, etc.).

Develop Large Documents in Stages

Large documents should be developed in stages, rather than in a single AppendPDF or AppendPDF Pro execution, so the results of each processing stage can be checked before proceeding. Customizations can be applied to each individual stage as well as to the final document as a whole. All of this “multi-stage” processing could be accomplished under the control of a single program or script, for example, a period (daily, weekly, monthly) report or web-content generation program.

AppendPDF and AppendPDF Pro can be integrated into a program or script that generates multiple parameter files, then executes AppendPDF or AppendPDF Pro to compile various “Sections” or “Chapters”. Then after error checking, append the resultant PDF documents into a single complete PDF document. A file listing all parameter files can be used as the input to a script for a single execution of AppendPDF or AppendPDF Pro.

The illustration below shows appending multiple sections in stages with AppendPDF Pro. When running AppendPDF, there will be no Table of Contents (TOC) or cover page generated since AppendPDF does not have those features.

Error Checking

When dynamically generating parameter files and executing AppendPDF or AppendPDF Pro with various option settings, it is important to perform checks in your scripts to eliminate or minimize possible errors that may otherwise occur. Common errors to search for:

• source file path strings for internal spaces—especially true of MS Windows file names
• source file path strings for internal commas

If errors are found, then the script or program can report them and log them and either halt the AppendPDF or AppendPDF Pro run or skip the appending of the erroneous files such as a section or chapter. A script could also insure that file paths are processed properly by surrounding the paths with double quotes.

A complex script or program could perform an operating system level check for the existence of each file path and check to make sure the read-permission is correct before proceeding.

When generating even moderately large or complex documents into “compound documents” that include separate sections, a cover page and a TOC (AppendPDF Pro only), it is prudent to programmatically check the results (return codes, error log contents, etc.) of each step before proceeding to the next, thus eliminating an attempt to append all of the components into an incorrectly created document.

Cleaning Up PDF Documents

Not all PDF files are created equal. The way in which a PDF document is generated makes a difference, and PDFs generated by third party tools in particular can vary in quality. PDF documents can also become corrupted.

To check how the file was created:

• In Acrobat X, XI and DC select File > Properties… and click Description. Under Advanced, look at PDF Producer.

If the PDF Producer field is blank, consider the file suspect.

Making a Clean PDF

If you are having problems with a specific PDF, try to create “clean” version of your document. There are two ways of doing this using Adobe Acrobat. If you use other PDF manipulation software, check the documentation for functions that may be equivalent to those found in Adobe Acrobat.

Method 1: “Optimize” your PDF

• In Acrobat X, XI and DC > File Menu > Save As > Optimized PDF

If saving as optimized does not work, distill the document by following the steps below.

Method 2: Distilling PDF Documents

Distilling a document will remove all comments and form-fields from the PDF. If the PDF contains these items and you wish to preserve them, you must save them before Distilling.

To save existing comments

• In Acrobat X, XI and DC select Comments > Comments List > click the Options icon > Export All to Data File… In the Export Comments dialog box, select a name and location for the Forms Data File (.fdf), and click Save.

See the additional step below for saving form fields (if any):

Delete all comments:

• In Acrobat X, XI and DC select all the comments in the Comments List pane and press the Delete key.

To save form fields (if any):

• Save a copy of the original file. You will copy and paste the form fields from the original file into the new file after the distilling procedure.

Distilling the document

To distill a PDF document do the following:

• In Acrobat X and XI select File > Save As > More Options > PostScript. Choose a name and location for the file and click Save.
• In Acrobat DC select File > Export to > PostScript. Choose a name and location for the file and click Save
• Open Acrobat Distiller > select File > Open… In the Open PostScript File dialog, locate the PostScript file created in the previous step and click Open.

The distiller will create a new PDF file with the same name and location as the PostScript file.

Restoring comments

To restore the comments:

• In Acrobat X and XI, select Comments > Comments List > click the Options icon > Import Data File… In the Import Comments dialog box, locate the Forms Data File (.fdf) previously saved and click Select. In the next pop-up box, click Yes. The comments are restored.
• In Acrobat DC, select Tools > Comments > Comments List > click the Options icon > Import Data File…In the Import Comments dialog box, locate the Forms Data File (.fdf) previously saved and click Select. In the next pop-up box, click yes. The comments are restored

Restoring form fields

To restore form fields:

• Open the original PDF file that includes form fields.
• In Acrobat X and XI select Tools > Forms > Edit Form)
• In Acrobat DC > select Tools > Prepare Form > Form fields will automatically appear
• The form fields will appear, do a Control-A to select all the form fields.
• Open the new distilled PDF file which has no form fields.
• Do a Control-V to paste all the form fields onto the page.

You may need to reposition the fields by selecting them again with the Select Object Tool and moving them to the correct position. For multi-page forms you must do this for each page separately.

The -cmds option allows you to process a collection of files at one time

To process multiple commands quickly and efficiently, use the -cmds <filename> option. The file specified by -cmds, the commands file, should contain one or more single line commands. Each command is just like an ordinary AppendPDF or AppendPDF Pro command-line without the executable name. The commands file does not support wildcards in filenames. Below are examples of command line syntax when running with -cmds:

$ ./appendpdfapp -p -l logfile.txt -cmds CommandFile.txt

$ ./appendproapp -p -l logfile.txt -cmds CommandFile.txt

CommandFile.txt contains a list of commands for AppendPDF or AppendPDF Pro to process. This is an example of a CommandFile.txt file:

-p -iso32000 /appligent/appendpro/samples/parameters.txt
-p -iso32000 /appligent/appendpro/samples/paramsbasic.xml
-p -optimize /appligent/appendpro/samples/tutorial.txt
-p -w /appligent/appendpro/samples/paramscomplete.xml

In this chapter…

…you will learn how to run FDFMerge Lite and FDFMerge on the command line. Information that is specific to FDFMerge is followed by the notation: (FDFMerge only).

• Running FDFMerge Lite and FDF Merge shows how to run the software.
• Examples of Merging FDF files and PDF Forms presents basic examples of running FDFMerge Lite and FDFMerge and guides you through the procedure of merging an FDF file with a PDF form to create a PDF document.
• Additional merging examples for UNIX and Windows provides several more complex examples.

Running FDFMerge Lite and FDFMerge

You’re ready to start merging FDF data files and PDF forms. Before you begin, remember these important points about FDFMerge Lite and FDFMerge:

For FDFMerge Lite or FDFMerge to run successfully, the PDF form file name must precede the FDF data file name on the command line unless you are running with the -reverse option.

• The order in which options are listed on the command line is not important. However, any file names associated with an option must immediately follow that option.
• The proper directory paths must be given for the fdfmergelite or fdfmerge executable and all of the files that you use.
• To prevent overwriting your original PDF file, save your output to a new file using the -o <outfile.pdf> option.

Example Command-Line Syntax

Listed below is an example of a simple command line for calling FDFMerge Lite or FDFMerge:

$ fdfmergeliteapp [options] -o out.pdf input.pdf input.fdf

$ fdfmergeapp [options] -o out.pdf input.pdf input.fdf

Examples of Merging FDF Files and PDF Forms

For your first merge of FDF data files and PDF forms, try using the samples included with the installation of FDFMerge Lite or FDFMerge in the /samples/testfiles directory.

Basic merging data and forms on UNIX

• Make sure you’re in the directory you want to be in; the examples below assume you are in the directory where FDFMerge Lite or FDFMerge is installed.
• Using the sample files try:

$ ./fdfmergelite -p -o ./samples/testfiles/out_testfile.pdf ./samples/testfiles/testfile.pdf ./samples/testfiles/testfile.fdf

$ ./fdfmerge -p -o ./samples/testfiles/out_testfile.pdf ./samples/testfiles/testfile.pdf ./samples/testfiles/testfile.fdf

In this example the -p flag shows progress, and the -o flag specifies an output file to prevent overwriting the input PDF file.

• When you press Return the following progress messages appear on your screen:

Processing : ./samples/testfiles/testfile.pdf
Open : ./samples/testfiles/testfile.fdf
Close : ./samples/testfiles/testfile.fdf
Done : ./samples/testfiles/out_testfile.pdf
fdfmerge completed successfully.

• Open out_testfile.pdf to see the completed form.

Basic merging data and forms on Windows

If you are not familiar with using the command line, refer to FDFMerge – Command Line Introduction or FDFMerge Lite – Command Line Introduction.

• Click the Start button.
• Go to Programs > Accessories and select Command Prompt.
• Make sure you’re in the directory you want to be in; the examples below assume you are in the directory where FDFMerge Lite or FDFMerge is installed.
• Using the sample files try:

>.\fdfmergelite -p -o .\samples\testfiles\out_testfile.pdf .\samples\testfiles\testfile.pdf .\samples\testfiles\testfile.fdf

>.\fdfmerge -p -o .\samples\testfiles\out_testfile.pdf .\samples\testfiles\testfile.pdf .\samples\testfilestest\file.fdf

In this example the -p flag shows progress, and the -o flag specifies an output file to prevent overwriting the input PDF file.

• When you press enter the following progress messages appear on your screen:

Processing : .\samples\testfiles\testfile.pdf
Open : .\samples\testfiles\testfile.fdf
Close : .\samples\testfiles\testfile.fdf
Done : .\samples\testfiles\out_testfile.pdf
fdfmerge completed successfully.

• Open out_testfile.pdf to see the completed form.

Additional Merging Examples for UNIX and Windows

In the previous sections the resulting out_testfile.pdf file was a filled-in form with active form fields. Here we give a few more examples, using command-line options and FormInfo files for form flattening (or stamping).

The examples are shown in the UNIX format, which is only slightly different from the DOS format on Windows in that directories are separated by a forward-slash ( / ) in UNIX, rather than the backslash ( ) in Windows/DOS.

Merging data and forms with the sample FormInfo file — FDFMerge only

$ ./fdfmerge -p -o ./samples/testfiles/out_testfile.pdf -f ./samples/testfiles/testfile1.txt ./samples/testfiles/testfile.pdf ./samples/testfiles/testfile.fdf

The out_testfile.pdf file is a new form with text attributes as specified in testfile1.txt. Some form fields remain active while the fields specified in testfile1.txt are flattened.

Merging data and forms with form flattening

$ ./fdfmergelite -p -s -o ./samples/testfiles/out_testfile.pdf ./samples/testfiles/testfile.pdf ./samples/testfiles/testfile.fdf

$ ./fdfmerge -p -s -o ./samples/testfiles/out_testfile.pdf ./samples/testfiles/testfile.pdf ./samples/testfiles/testfile.fdf

The out_testfile.pdf file is a new PDF document with no active form fields; the text is stamped into the document as it appears in testfile.pdf.

Merging data and forms with FormInfo and form flattening — FDFMerge only

$ ./fdfmerge -p -o ./samples/testfiles/out_testfile.pdf -s -f ./samples/testfiles/testfile1.txt ./samples/testfiles/testfile.pdf ./samples/testfiles/testfile.fdf

The out_testfile.pdf file is a new PDF document with no active form fields; the text is stamped into the document as specified in testfile1.txt.

Merging data and forms using several options

$ ./fdfmergelite -p -l logfile.txt -o ./samples/testfiles/out_testfile.pdf -s ./samples/testfiles/testfile.pdf ./samples/testfiles/testfile.fdf

$ ./fdfmerge -p -l logfile.txt -o ./samples/testfiles/out_testfile.pdf -s -f ./samples/testfiles/testfile1.txt ./samples/testfiles/testfile.pdf ./samples/testfiles/testfile.fdf

All of the progress messages are written to logfile.txt. The out_testfile.pdf file is a new PDF document with no active form fields. The text is stamped into the document by FDFMerge Lite. FDFMerge stamps the data into the form fields and fields specified in testfile1.txt have their attributes changed to what is set in this file.

In this chapter …

… we discuss general command-line options for Appligent server applications.

Common command-line options are used in all Appligent server applications. These options deal with product information, progress messages, and file maintenance. For information on command options that are specific to AppendPDF and AppendPDF Pro see AppendPDF Options or AppendPDF Pro Options.

This chapter provides detail for the common options only. The following table provides a summary of the common command-line options.

General options — summary

General options — detailed

The following sections provide details on using the general command-line options.

-r <RegNum> — Pass registration number to AppendPDF or AppendPDF Pro

This option can be used to supply your registration number to AppendPDF or AppendPDF Pro from a script or another application:

$ appendpdfapp -r XXXX-XXXX-XXXX-XXXX-XXXX-XXXX [other options]parameterfile1.xml [parameterfile2.xml...]

$ appendproapp -r XXXX-XXXX-XXXX-XXXX-XXXX-XXXX[other options] parameterfile1.xml [parameterfile2.xml...]

This option is typically not necessary and is available for use in cases where the Appligent License File can not be located by the application because of runtime environment restrictions.

-l <logfile> — Create a log file (optional)

Specify a text file for any errors and progress messages. This option is helpful for debugging. The -l <logfile> option must be followed by a file name. If there are no errors, no file is written. If a log file is not specified, errors are written to the default log file, appendpdf.log. The default log file name is the same for both AppendPDF and AppendPDF Pro. Make sure that your log file is write enabled.

-p — Show progress (optional)

Write progress messages to the screen STDOUT, the standard output of your system, and to the default log file, appendpdf.log. This option is helpful for debugging and for understanding how AppendPDF or AppendPDF Pro works. If the -p option is present on the command line, all errors and progress messages are written to the default log file, appendpdf.log.

A note on using -p and -l <logfile> together

As outlined in the above sections, the -p option gives you progress messages and errors on your screen and the -l <logfile> option writes error messages to a file you specify. The table below provides more detail on using these options alone or together.

Using -p and -l <logfile>

Therefore, -l <logfile> used on its own will only go into action if there are errors. With -p and -l <logfile> combined, you will get a text file with full details on AppendPDF or AppendPDF Pro operations whether there are errors or not.

-n — Do not write anything to screen (optional)

Do not write anything to the screen (or STDOUT). If you are running batch mode, this prevents progress messages from building up.

-v — Display version information (optional)

Display the version of AppendPDF or AppendPDF Pro you are running. This is important when corresponding with support@Appligent.com. In order to better understand your problem, we must know what version of the software you have. AppendPDF or AppendPDF Pro will not do anything else if you use this option.

-h or -help — Show usage (optional)

Display all available command-line options. AppendPDF or AppendPDF Pro will not do anything else if you use either of these options.

-i — Perform incremental save (optional)

An incremental save appends changed information to the end of the file. This is faster than a full save, but may result in a larger file. A full save is similar to using the “Save As…” command in Adobe Acrobat. It is a save that attempts to clean up a PDF file, often reducing its size.

-w — Linearize the file upon save (optional)

Save the output file as a linearized document (also known as optimization). Linearization reorganizes the file to make it more efficient for web delivery. Individual pages can be rendered before the entire document has downloaded, so the user can start reading the document sooner.

-optimize — Optimize the file (optional)

This flag will do the following: 1) encode any non-encoded streams using Flate compression, 2) remove ASCII85 filters from all streams, 3) replace LZW encoded streams with Flate encoding, 4) merge identical XObjects and images, 5) optimize common sequences in page content, and 6) merge identical font descriptors and encodings. This option will usually result in a smaller file size.

-nocomp — Do not compress using Object Streams (optional)

This flag will not compress Object Streams, resulting in a document that is compatible with all versions of Acrobat.

-comp — Compress using Object Streams (optional)

This flag will compress Object Streams, resulting in a document that is compatible with Acrobat 6.0 and later.

-iso32000 — Set file for ISO 32000-1 compliance (optional)

This flag sets the file for compliance with ISO 32000-1:2008 (PDF 1.7).

In this chapter…

.…you will learn about the options available within FDFMerge Lite and FDFMerge. Information that is specific to FDFMerge is followed by the notation: (FDFMerge only).

FDFMerge Lite and FDFMerge Options

Refer to FDFMerge Lite – General Command-Line Options or FDFMerge – General Command-Line Options for details on the general options.

Refer to FDFMerge Lite – Applying Standard Security or FDFMerge – Applying Standard Security for more information about the security options and working with encrypted documents.

The following are examples of simple command lines for calling FDFMerge Lite or FDFMerge:

$ fdfmergeliteapp [options] -o out.pdf input.pdf input.fdf

$ fdfmergeapp [options] -o out.pdf input.pdf input.fdf

The table below shows command-line options for FDFMerge Lite and FDFMerge.

Options summary

-x — Input is an XFDF file

Specifies that the input data file is an XFDF file, which is an XML version of an FDF file. Required if using an XFDF input file instead of an FDF file.

-s — Replace all fields with stamps (optional)

Flattens a form, changing active form fields into static text or images. For more information about how this works, see To merge and flatten, or to merge and not flatten.

-stampnewvalues — Stamp fields with new values (optional – FDFMerge only)

Partially flatten form fields passed in using FDF and XFDF files. When this feature is present on the command line, all unfilled fields will remain active.

-reverse — Make FDF file come first followed by multiple PDF input files (optional)

Processes multiple PDF forms with a single FDF file. An output directory must be used with -reverse. FDFMerge Lite and FDFMerge normally require the PDF form before the FDF file on the command line. However, when running multiple forms with the same FDF file, the FDF file must appear before the PDF form on the command line. For example, the following command:

$ fdfmergelite [options] -o ./merged -reverse fdf_filename.fdf pdf_filename1.pdf pdf_filename2.pdf...pdf_filename3.pdf

$ fdfmerge [options] -o ./merged -reverse fdf_filename.fdf pdf_filename1.pdf pdf_filename2.pdf...pdf_filename3.pdf

Merges the same form information into each PDF file, and writes the new files to the ./merged directory using the same PDF filename as the input PDF form file. Required when running multiple PDFs.

-norebuild — Don’t rebuild appearances (optional)

Specifies that Acrobat, rather than FDFMerge Lite or FDFMerge builds the form appearances for an output PDF form. Use this option when merging text fields containing formats or calculations to have Acrobat keep the formatting.

-mergeflags — Merge F and Ff flags along with the field values in the FDF

Can be used to set fields to ReadOnly. For example, having the following in an FDF file will set the form field to ReadOnly when merging

/T(name) /V(John Smith) /Ff 1

-f <FormInfo.txt> — Field information file for field customization (optional) — FDFMerge only

Specifies that a FormInfo file be used for flattening, customizing form fields, or stamping them with JPEG, TIF or PDF images.

More information on merging and flattening form fields can be found below in To merge and flatten, or to merge and not flatten. For information on available parameters and how to put together a FormInfo file, see FormInfo Files.

To merge and flatten, or to merge and not flatten, and the FormInfo file — FDFMerge only

The results of using the -s option can vary if you also specify a FormInfo file. See flattening variations in the table below describes the different scenarios (see FormInfo Files).

Flattening variations

-cmds <CommandFile.txt> — Allows you to process a collection of files at one time

To process multiple commands quickly and efficiently, use the -cmds <filename> option. The file specified by -cmds, the commands file, should contain one or more single line commands. Each command is just like an ordinary FDF Merge Lite or FDFMerge command-line without the executable name. The commands file does not support wildcards in filenames. The following is an example of command-line syntax when running with -cmds:

$ fdfmergeliteapp -p -l logfile.txt -cmds CommandFile.txt

$ fdfmergeapp -p -l logfile.txt -cmds CommandFile.txt

CommandFile.txt contains a list of commands for FDFMerge to process. An example of a CommandFile.txt file:

-p -optimize -f /appligent/fdfmerge/samples/testfiles/testfile1.txt-o /appligent/fdfmerge/samples/testfiles/outfile1.pdf/appligent/fdfmerge/samples/testfiles/testfile.pdf/appligent/fdfmerge/samples/testfiles/testfile.fdf

-p -x -o /appligent/fdfmerge/samples/testfiles/outfile2.pdf/appligent/fdfmerge/samples/testfiles/testfile.pdf/appligent/fdfmerge/samples/testfiles/testfile.xfdf

-p -w -x -f /appligent/fdfmerge/samples/healthform/healthform3.txt-o /appligent/fdfmerge/samples/healthform/outfiles3.pdf/appligent/fdfmerge/samples/healthform/healthform.pdf /appligent/fdfmerge/samples/healthform/healthform.xfdf

The -cmds option allows you to process a collection of files at one time

To process multiple commands quickly and efficiently, use the -cmds <filename> option. The file specified by -cmds, the commands file, should contain one or more single line commands. Each command is just like an ordinary FDFMerge Lite or FDFMerge command-line without the executable name. The commands file does not support wildcards in filenames. Below are examples of command line syntax when running with -cmds:

$ ./fdfmergeliteapp -p -l logfile.txt -cmds CommandFile.txt

$ ./fdfmergeapp -p -l logfile.txt -cmds CommandFile.txt

CommandFile.txt contains a list of commands for FDF Merge Lite or FDFMerge to process. This is an example of a CommandFile.txt file:

-p -optimize -f /appligent/fdfmerge/samples/testfiles/testfile1.txt  -o /appligent/fdfmerge/samples/testfiles/outfile1.pdf /appligent/fdfmerge/samples/testfiles/testfile.pdf /appligent/fdfmerge/samples/testfiles/testfile.fdf
-p -x -o /appligent/fdfmerge/samples/testfiles/outfile2.pdf /appligent/fdfmerge/samples/testfiles/testfile.pdf /appligent/fdfmerge/samples/testfiles/testfile.xfdf
-p -w -x -f /appligent/fdfmerge/samples/healthform/healthform3.txt  -o /appligent/fdfmerge/samples/healthform/outfiles3.pdf /appligent/fdfmerge/samples/healthform/healthform.pdf /appligent/fdfmerge/samples/healthform/healthform.xfdf

Introduction

The Document Information Block is optional. Within Adobe Acrobat there is a feature to view information about a file by choosing Document Properties from the File menu. With AppendPDF Pro and AppendPDF it is possible to populate certain fields of the Document Info with the parameter file. A sample of a Document Properties dialog screen from Acrobat is shown below.

Document Info screen

Below is a Document Info screen in Acrobat for a Sample PDF, also called Document Properties.

Title, Author, Subject, and Keywords are fields in the Document Info screen as shown in the figure above. These are the fields that can be modified by AppendPDF Pro and AppendPDF. Enter values in the parameter file as you would like to see them appear when you call up the Document Properties in Acrobat. The fields Title, Subject and Author refer to information specific to that document. Keywords (this is Acrobat’s Keywords, not to be confused with the many other references to keywords in this manual) are usually simple words used for sorting and grouping (December, ProjectX, personal, etc.) and are useful for those who will be indexing their documents with Acrobat Catalog and would like to improve searching efficiency. More about indexing can be found in the Acrobat Guide or the Reader Guide if you don’t have the full version of Acrobat. (Either guide can be found under the Help menu of its respective application.)

To specify document information in a parameter file, list the name of the field followed by its value in parentheses. Before beginning this section the keyword begin_info must be added to the parameter file. At the end of the list close the section with the end_infokeyword:

begin_info
Title (AppendPDF Pro Test)
Subject (testing AppendPDF Pro with sample files)
Author (Appligent, Inc.)
Keywords (testing AppendPDF Pro sample files)
end_info

There is no set number of tabs or spaces that need to appear between the field name and the value in parentheses, as long as there is at least one tab or space. Also, if you do not want to include a Document Info field (for example, if you want Title and Subject, but not Author and Keywords) make sure that keyword is not listed in the Document Info block. Items listed with empty parentheses will cause AppendPDF or AppendPDF Pro to fail.

Make sure that all Document Info keywords (Title, Subject, Author, Keywords) are spelled correctly or AppendPDF and AppendPDF Pro will treat them as custom strings. Custom strings are discussed in the next section.

Optional Custom Information to Add within Document Info

AppendPDF and AppendPDF Pro support two custom field types: strings and dates. These can be added within the Document Info block of the AppendPDF or AppendPDF Pro parameter file which saves them in the keywords section of the Document Properties. The keywords can then be indexed with Acrobat Catalog.

The name of a custom string can be anything you want. Give it any name that will have meaning to you and/or be easy for you to remember. For example:

String1 (This file created by AppendPDF Pro)

or

ExtraText (AppendPDF Pro document)

Custom dates need to conform to the format D:YYYYMMDDHHMMSS. Acrobat Catalog allows dates to be searched using boolean operators. You can tell Catalog to find, for example, invoices whose date is greater than 1999 and less than 2000. A custom date in the Document Info block of the parameter file can be entered as:

DocDate (D:20170714235659)

This example indicates a date of 14 July 2017 with a time of 23:56:59.

Overview

FDFMerge Lite and FDFMerge fill data into PDF forms automatically or on the fly. You can deliver live forms or “flattened” forms so field data cannot be changed. Filled in forms can be opened in Adobe® Reader®. You can also fill in high volumes of PDF forms on your server.

What Do FDFMerge Lite and FDFMerge Do?

FDFMerge Lite and FDFMerge are server-based, command-line applications that reliably combine PDF forms with form data to create a new populated PDF form.

In addition to combining forms and data, FDFMerge Lite and FDFMerge can:

• Flatten forms — remove the active field and stamp the field contents directly onto the PDF document
• Encrypt files — apply standard Acrobat security settings at 40- or 128-bit strength
• Process XML — use XFDF in addition to FDF files
• Process multiple forms using one FDF file

Addition features in FDFMerge only; a FormInfo file can be used to provide for:

• Partial form flattening — you can flatten the entire form, or specify individual fields to flatten
• Additional support for fonts — specify font information for form fields
• Image stamping — you can stamp an image onto a form field
• Format text fields — set font, point size, alignment, color, and more
• Advanced typography – manage character spacing, word spacing and line leading
• RGB and CMYK Color

FDFMerge Lite and FDFMerge can be used within a world wide web interface with CGI scripts. For your reference we have included a sample CGI script in Sample Perl CGI Script. CGI scripts are discussed in more detail in Automating FDFMerge Lite or Automating FDFMerge.

FDFMerge Lite and FDFMerge Components

FDFMerge Lite and FDFMerge use the following components:

• PDF forms — PDF documents with form fields
• FDF files — Text files which contain form data
• XFDF files — XML files which contain form data
• FormInfo files — Text files which contain information about customizing form fields (FDFMerge only)

PDF forms

PDF forms are interactive documents you create by inserting form fields into existing PDF documents. FDFMerge Lite and FDFMerge support the following form fields:

• Buttons
• Radio buttons
• Check boxes
• Combo boxes
• Text boxes
• List boxes
• Multi-line text boxes

FDFMerge Lite and FDFMerge identify the form fields by the names you assign to each. Refer to Acrobat’s on-line help for information on creating and using forms.

FDF files

An FDF file is a text file that contains data for a PDF Form. Data is associated with each form field by the name you assigned. FDFMerge Lite and FDFMerge can combine this data with a PDF form to fill in the form fields with the FDF data.

An FDF file or set of files may be generated from information contained in a database or gathered from data submitted on a web page. This kind of conversion requires user written scripts (for example, using Perl, Visual Basic, or JavaScript) to transform the raw data into one or more FDF files.

XFDF files

An XFDF file is an XML version of an FDF file. Data and form field names are embedded in XML tags.

FormInfo files (FDFMerge only)

FormInfo files allow you to specify individual fields to flatten, and to customize the properties of those fields.

Preliminary Concepts

Merging

When FDFMerge Lite or FDFMerge merges a PDF form with an FDF file, it places the data from the FDF file into the form fields on the PDF form. Each form field on the form has an associated value in the FDF file, identified by the name of the field. The form fields remain “live” fields, their values can be changed, and form actions taken.

Flattening

When FDFMerge Lite or FDFMerge flattens a form field, it removes the field and places the value of the field directly into the document. This is called stamping the information into the document. The information becomes a static part of the document.

How FDFMerge Lite and FDFMerge process a document

FDFMerge Lite and FDFMerge can merge and/or flatten a document in several ways. FDFMerge Lite and FDFMerge can:

• Merge a form with an FDF file, leaving it a live form
• Merge a form with an FDF file, and flatten the entire form at the same time
• Flatten an already filled-out form. You do not need to use an FDF file for this
• Merge a form with an FDF file, and flatten and customize some or all of the fields, using a FormInfo file to specify which fields (FDFMerge only)
• Flatten and customize some or all of the fields of an already filled-out form, using a FormInfo file. You do not need to use an FDF file for this (FDFMerge only)

User Guide Conventions

This User Guide uses certain styles of text to indicate different information throughout the documentation. The following is a description of these styles:

• Command Line user input:

  $fdfmergeliteapp  -p -l <logfile.txt>

  $fdfmergeapp  -p -l <logfile.txt>

• Cross Reference to other locations in the documentation: Introduction to FDFMerge. Click the colored text to go to the referenced link.
• References to web sites for information: www.appligent.com. Click the colored text to open a browser to the website.
• Code snippets: #!/usr/local/bin
• Content that is specific to FDFMerge is followed by the notation: (FDFMerge only).

Introduction

We will be using the sample parameter file, paramsletter.txt, in the samples directory as an example throughout this chapter. The default location for AppendPDF on Windows is C:\Appligent\AppendPDF\ and AppendPDF Pro is located in C:\Appligent\AppendPro. On other platforms, it will be wherever you installed it. The paramsletter.txt example, (AppendPDF Pro only), contains most of the features described in these chapters for the purpose of explanation and examples.

What is a Parameter file?

To run AppendPDF Pro or AppendPDF you will need a parameter file. A text parameter file is a simple text file that contains the instructions AppendPDF Pro or AppendPDF uses to build your new document. Sample parameter files are included with the AppendPDF Pro and AppendPDF installation and are located in the samples directory.

A parameter file includes:

• The name and directory path of the new, appended PDF file
• Source file information is a list of the documents to be used for appending, including page ranges and Table of Contents (TOC) entries (AppendPDF Pro only)
• Cover page information includes the cover page file and the stamp file for the cover page (AppendPDF Pro only)
• Table of Contents information includes the TOC file, style information, and the stamp file for the TOC (AppendPDF Pro only)
• Document Info is Title, Author, Subject, Keywords which are viewable within Adobe Acrobat and Acrobat Reader
• Extras specify additional information such as how the document should open and a stamp file for the body of the document (AppendPDF Pro only)

Building a Text Parameter File

New file name

The first line of the parameter file is the name of the new PDF file — the output file that will be created by AppendPDF or AppendPDF Pro. For example:

paramsletter.pdf

It is likely that you will be appending files that do not reside in the directory that holds AppendPDF or AppendPDF Pro. To avoid losing track of where your files are being written, we recommend that you include the full pathname for each file that you use. For example:

C:\MyDir\WorkFiles\paramsletter.pdf

Parameter file details

The following sub-chapters describe in detail how to build the rest of the parameter file in text format.

Introduction

Common command-line options are used in all Appligent server applications. These options deal with product information, progress messages, and file maintenance. Information that is specific to FDFMerge is distinguished by green text.

General options — summary

The following table provides a summary of the general command-line options:

General options — detailed

The following sections provide details on using the general command-line options.

-r <RegNum> — Pass registration number to FDFMerge Lite or FDFMerge

This option can be used to supply your registration number to FDFMerge Lite or FDFMerge from a script or another application:

$fdfmergeliteapp -r XXXX-XXXX-XXXX-XXXX-XXXX-XXXX [other options]

$fdfmergeapp -r XXXX-XXXX-XXXX-XXXX-XXXX-XXXX [other options]

This option is typically not necessary and is available for use in cases where the Appligent License File can not be located by the application because of runtime environment restrictions.

-l <logfile> — Create a log file (optional)

Specify a text file for any errors and progress messages. This option is helpful for debugging. The -l <logfile> option must be followed by a file name. If there are no errors, no file is written. If a log file is not specified, errors are written to the default log file fdfmergelite.log or fdfmerge.log. Make sure that your log file is write enabled.

-p — Show progress (optional)

Write progress messages to the screen STDOUT, the standard output of your system and to the default log file fdfmergelite.log or fdfmerge.log. This option is helpful for debugging and for understanding how FDFMerge Lite or FDFMerge works.

A note on using -p and -l <logfile> together

As outlined in the above sections, the -p option gives you progress messages on your screen and the -l <logfile> option writes error messages to a file if errors occur. The table below provides more detail on using these options alone or together.

Therefore, -l <logfile> used on its own will only go into action if there are errors. With -p and -l <logfile> combined, you will get a text file with full details on FDFMerge Lite or FDFMerge operations whether there are errors or not.

-n — Do not write anything to the screen (optional)

Do not write anything to the screen (or STDOUT). If you are running batch mode, this prevents progress message from building up.

-v — Display version information (optional)

Display the version of FDFMerge Lite or FDFMerge you are running. This is important when corresponding with support@Appligent.com. In order to better understand your problem, we must know what version of the software you have. FDFMerge Lite or FDFMerge will not do anything else if you use this option.

-h or -help — Show usage (optional)

Display all available command-line options. FDFMerge Lite or FDFMerge will not do anything else when you use these options.

-i — Perform incremental save (optional)

An incremental save appends changed information to the end of the file. This is faster than a full save, but may result in a larger file. A full save is similar to using the “Save As..” command in Adobe Acrobat. It is a save that attempts to clean up a PDF file, often reducing its size.

-w — Linearize the file upon save (optional)

Save the output file as a linearized document, also known as optimized. Linearization reorganizes the file to make it more efficient for web delivery. Individual pages can be rendered before the entire document has downloaded, so the user can start reading the document sooner.

-optimize — Optimize the file (optional)

This flag will do the following: 1) encode any non-encoded streams using Flate compression, 2) remove ASCII85 filters from all streams, 3) replace LZW encoded streams with Flate encoding, 4) merge identical XObjects and images, 5) optimize common sequences in page content, and 6) merge identical font descriptors and encodings. This option will usually result in a smaller file size.

-iso32000 — Set file for ISO32000 compliance (optional)

This flag will set the file for ISO 32000 compliance, resulting in a document that is PDF version 1.7.

-nowarning – Do not issue warnings about unused fields

This flag will suppress messages to STDOUT when form fields appear in the FDF file but not in the PDF form.

-d <string> — Owner password to open the document (optional)

If the PDF document you wish to stamp has been encrypted, you must pass the owner password with the -d <string> option in order to stamp the file. If you are processing more than one input file at a time, the owner password must be the same for all files.

-o — Create a new output file or directory

Save the modified file as a new PDF.

Overview

AppendPDF and AppendPDF Pro provide a fast and efficient way to combine documents dynamically and on-demand. This documentation provides instructions for both AppendPDF and AppendPDF Pro. Content specific to AppendPDF Pro is followed by a notation: (AppendPDF Pro only).

With AppendPDF and AppendPDF Pro you can:

• Combine documents
• Combine page ranges and sections from a series of documents
• Add Document Information
• Generate a Table of Contents including corresponding PDF bookmarks (AppendPDF Pro only)
• Add a Cover page (AppendPDF Pro only)
• Stamp information onto the finished document — Add watermarks, copyright information, headers or footers to further customize your document delivery (AppendPDF Pro only)

The final presentation is professional and complete.

AppendPDF and AppendPDF Pro use a parameter file to build the new PDF file from lists of several PDF files or specific pages from those files. Two versions of parameter files are supported:

• XML parameter files — Files coded in XML.
• Text parameter files — Plain text parameter files.

User Guide Conventions

This User Guide uses certain styles of text to indicate different things throughout the documentation. The following is a description of these styles:

• Command-line user input examples:

  $appendpdfapp -r <Reg Number> -p -l <logfile.txt>

  $appendproapp -r <Reg Number> -p -l <logfile.txt>  (AppendPDF Pro only)

• Cross Reference to other locations in the documentation: AppendPDF Pro. Click the colored text to go to the referenced link.
• References to web sites for information: www.appligent.com. Click the colored text to open a browser to the website.
• Code snippets: <appendparam version=’1.0′>
• Content that is specific to AppendPDF Pro is followed by the notation: (AppendPDF Pro only).

You may see some paragraphs which look like the following:

In this chapter…

…we discuss the standard Acrobat security options and how to set them.

• Acrobat Standard Security is an overview of the three levels of Acrobat security and passwords.
• Security Options lists the options and how to use them to set either low level or high level encryption.
• Verifying Security Features shows how to verify that the document is encrypted the way you want it.

Acrobat Standard Security

Acrobat standard security allows you to control who can access your document and, by setting permissions, how much they can edit or print. Acrobat offers three levels of security:

• Low-level encryption (40-bit key length) — Compatible with Acrobat versions 3 and later.
• High-level encryption (128-bit key length) — Compatible with Acrobat versions 5 and later.
• AES encryption (128-bit key length) — Available only with Acrobat 8 and later.
• AES encryption (256-bit key length — available for SecurSign & APCrypt only) — Available only with Acrobat X, XI and DC.

High level encryption provides a higher level of security and finer control over security features. The minimum level of security that you can set is to allow any changes except extracting pages.

Once you set encryption on a document, it cannot be processed in other ways unless the password is available to the processing software. You can also change or remove encryption in Acrobat.

Owner and user passwords

All levels of security allow you to set passwords for the document:

• User password: controls who may view a document.
• Owner password (required): controls who may make changes to permissions and passwords securing a document.

You must set an Owner password to apply encryption. Do not use the same password for both User and Owner. If the same password is used for both, only the User password will be set.

Different versions of Acrobat use different terminology to refer to the same concepts. You’ll see more of this in High-level encryption password nomenclature as described in the following table for various versions of Adobe Acrobat:

Encryption Permissions

Acrobat allows you to set various permissions to limit access to the information in the document. Adobe changes the use of permissions when they moved from 40-bit key lengths to 128-bit key lengths. The sections below detail the different options and permissions based on using 40-bit or 128/256 bit key lengths.

The following is an example of the security options in Acrobat X, XI & DC:

Refer to Verifying Security Features for instructions on displaying the security options.

Encryption options

The table below describes low-level encryption options.

High level encryption provides additional security options as are defined in the table below.

The first four permissions can be used in any combination, except you can’t use -noprint and -nohighres together. Choose one or the other. The last four must be used in specific combinations that Acrobat accepts.

-encrypt — Encrypt output file (optional)

Specifies applying encryption to the output file using the RC4 stream cypher. This option is the same as -rc4.

-aes — Encrypt using the AES cryptography algorithm (optional) (SecurSign & APCrypt Only)

Encrypt the output file using the Advanced Encryption Standard (AES) cryptography algorithm.

-rc4 — Encrypt using the RC4 cryptography algorithm (optional)

Specifies applying encryption to the output file.

-keylength <int> — Encryption level (optional)

Specifies the encryption key length used to encrypt the document: either 40-bit, 128-bit or 256-bit. (256- bit SecurSign & APCrypt Only)

If you do not specify key length, the default is 128-bit.

-ownerpass <password> — New owner password (required)

Specifies a new Owner password to apply encryption. An Owner password restricts you from altering the security settings. You are not prompted for a password to open the document, only if you try to change the security settings. Passwords are case sensitive and are required when applying encryption.

Choose passwords carefully. They should not be able to be guessed easily but at the same time should not be too difficult for you to remember. If you forget a password, there is no way to recover it from the document. Therefore, it is a good idea to note passwords in another secure location.

-userpass <password> — Set user password (optional)

Specifies a User password for the document. Setting a User password prevents a document from being opened unless the correct password is supplied. Passwords are case sensitive.

Below is the Document Open Password dialog box.

When someone tries to open the document in Acrobat they will be asked for the password.

User password is optional. If you do not specify a User password, anyone can open the document.

-onlyattach — Secure Envelope(optional) (SecurSign Only)

Utilize PDFs as secure envelopes; apply 256-bit AES security to PDF and non-PDF file attachments while leaving the PDF itself unencrypted.

-remove — Remove all encryption from the PDF document

Removing encryption from the PDF document requires the document owner password using -ownerpass.

-d <string> — Old owner password to decrypt the file (Not available for AppendPDF & AppendPDF Pro)

If a PDF file already has encryption set and you wish to change the settings or remove encryption (APCrypt/SecurSign only), you need to supply the owner password in order to make changes to the file.

Document Permissions

-noprint — Do not allow printing (optional)

Specifies that the document cannot be printed. When the document is opened, the print icon on the toolbar and the Print option under the file menu will be grayed out.

At the 128-bit and 256-bit encryption level there is also an option to allow low resolution printing only. See the section High-level encryption for more detail.

-nomodify — Do not allow modifying the document (optional)

Specifies that the document cannot be modified. You will not be able to modify text or pages in the document when this option is used. You can fill in form fields, or add notes or other annotations.

With -nomodify, the following tools are grayed out and cannot be used when the document is opened in Acrobat:

• Crop tool
• Movie tool
• Link tool
• Article tool
• Form tool
• Digital Signature tool

Text can be selected for copying but cannot be cut, pasted or cleared.

-nocopy — Do not allow copying text or graphics (optional)

Specifies text and graphics cannot be copied.

With -nocopy, the following tools are grayed out and cannot be used when the document is opened in Acrobat:

• Text Select tool
• Touch-Up Text tool
• Table/Formatted Text Select tool

-nonotes — Do not allow adding or changing notes or form fields (optional)

Specifies that annotations cannot be added or changed in the document. Annotations include notes, highlighted text, form fields and pencil marks. Annotations can be in text, graphic or audio format, or even attached external files.

With -nonotes, the following tools are grayed out and cannot be used when the document is opened in Acrobat:

• Notes tool
• Pencil tool
• Highlight Text tool
• Form tool
• Digital Signature tool
• Free Text tool
• Sound Attachment tool
• Stamp tool
• File Attachment
• Square tool
• Circle tool
• Line tool

-noaccess — Do not allow accessibility (optional)

Specifies content accessibility is not allowed. Content accessibility provides the vision and motion-challenged community with the tools and resources to make digital information more accessible. To learn more about content accessibility consult the Acrobat Help guide within Acrobat.

-nohighres — Do not allow high resolution printing (optional)

Specifies low resolution printing only. Acrobat prints each page as a low resolution (150 dpi) bitmap. The document cannot be recreated from these printouts.

-nofill — Do not allow filling form fields or signing fields

Specifies that no changes can be made to form fields or digital signature fields. This setting effectively prevents a filled-in form from being changed.

-noassembly — Do not allow document assembly

Specifies that no new pages can be added or removed from the PDF document. Also prevents rotating pages in the document. Effectively prevents pages being removed from the PDF document to be used elsewhere.

Permissions Allowed with 40-bit Encyption

The table below shows how the software application security options correspond to Acrobat’s security restrictions. The “Changes Allowed” column below lists the features still available after the document is secured.

Permissions Allowed with 128-bit or 256-bit Encryption

Acrobat accepts certain combinations of the “Changes Allowed” options. The Changes Allowed options are:

• -nomodify — Do Not Allow Modifying the Document
• -noassembly — Do Not Allow Document Assembly
• -nonotes — Do Not Allow Adding or Changing Notes or Form Fields
• -nofill — Do Not Allow Filling In or Signing of Form Fields

The table below shows security options vs. restrictions set with high level encryption. These combinations are discussed below.

Allow no changes with -nomodify -noassembly -nonotes -nofill

Turning off all changes means: do not allow document modification (-nomodify), do not allow document assembly (-noassembly), do not allow the adding or changing of notes or form fields (-nonotes) and do not allow the fill-in or signing of form fields (-nofill). These options must all be used together for this setting to be made.

Allow inserting, deleting, and rotating pages with -nomodify -nonotes -nofill

This setting only allows document assembly.

These options specify: do not allow document modification (-nomodify), do not allow the adding or changing of notes or form fields (-nonotes) and do not allow the fill-in or signing of form fields (-nofill).

Allow filling in form fields, and signing with -nomodify -noassembly -nonotes

This setting only allows form field fill-in or signing.

These options specify: do not allow document modification (-nomodify), do not allow document assembly (-noassembly), and do not allow the adding or changing of notes or form fields (-nonotes).

Allow commenting, filling in form fields, and signing with -nomodify -noassembly

This setting allows the adding or changing of notes or form fields and the fill-in or signing of form fields.

These options specify: do not allow document modification (-nomodify), and do not allow document assembly (-noassembly).

Allow any except extracting pages with no options

If you don’t use any Changes Allowed options, Acrobat will allow any changes except extracting pages.

Verifying Security Features

To view the current security settings:

In the example shown below, both a User password and an Owner password are set, only low resolution printing is allowed, changing the document, content copying and extraction, authoring comments and form fields, and form field fill-in or signing are not allowed, content accessibility and document assembly are allowed and encryption is 128-bit.

Introduction

The element <sourcepdfs> specifies the input files, page ranges, and Table of Contents entry text for the appended document. You can specify more than one input file. To specify multiple page ranges from one file, specify an inputpdf, using the same file, for each page range.

The table below describes the elements specifying <sourcepdfs>.

Contents of the <sourcepdfs> Element

XML Code Sample

Specifying an input file.

<appendparam version="1.0">
 <!-- .  Indicates skipped sections--> 
 <!-- . -->
 <!-- . -->
   <sourcepdfs>
      <inputpdf>
         <file>
            /fullpath/input1.pdf
         </file>
         <startpage>
            3
         </startpage>
         <endpage>
            10
         </endpage>
         <TOCEntry>
            Input File 1
         </TOCEntry>
      </inputpdf>
   </sourcepdfs>
<!-- . -->
<!-- . -->
<!-- . -->
</appendparam>

Elements for <sourcepdfs>

inputpdf

Specifies the details of an input file.

You can specify more than one file by including multiple sets of <inputpdf> tags.

file

Specifies the path and filename of an input PDF file.

startpage, endpage

Specifies the start page and end page of a range of pages to extract and append to the output document. The example above will extract pages 3 through 10 of the input document.

Specifying page ranges

The following notes apply to specifying page ranges:

TOCEntry (AppendPDF Pro only)

Specifies the text to use in the Table of Contents to identify this range of pages. <TOCEntry> is only used if you include a TOC page, see Table of Contents — XML. If you want to append an <inputpdf> without an entry in the Table of Contents, use an empty <TOCEntry> tag as shown below:

<TOCEntry/>

Examples

For clarity, the following examples use truncated path names. We recommend that you use full path names for all files. The following examples are from the sample files included with AppendPDF Pro.

Including the entire file

To include the entire file, do not specify a page range:

<sourcepdfs>
   <inputpdf>
      <file>
         ./samples/pdfs/sample1.pdf
      </file>
   </inputpdf>
</sourcepdfs>

To explicitly specify all pages in a file and a TOC entry

<sourcepdfs>
   <inputpdf>
      <file>
         ./samples/pdfs/sample1.pdf
      </file>
      <startpage>
         1
      </startpage>
      <endpage>
         -1
      </endpage>
      <TOCEntry>
         sample document 1
      </TOCEntry>
   </inputpdf>
</sourcepdfs>

Other examples

The following additional examples use a generic example file.

Including one page of a file

To include only page 7 of a file:

<sourcepdfs>
   <inputpdf>
      <file>
         ./samples/example.pdf
      </file>
      <startpage>
         7
      </startpage>
      <endpage>
         7
      </endpage>
      <TOCEntry>
         example document, page 7
      </TOCEntry>
   </inputpdf>
</sourcepdfs>

Including a range to the end of the file

To include from page 7 to the end of the file:

<sourcepdfs>
   <inputpdf>
      <file>
         ./samples/example.pdf
      </file>
      <startpage>
         7
      </startpage>
      <endpage>
         -1
      </endpage>
      <TOCEntry>
         example document, page 7 to end
      </TOCEntry>
   </inputpdf>
</sourcepdfs>

Including the last page only

To specify the last page when you are not sure what number it will be:

<sourcepdfs>
   <inputpdf>
      <file>
         ./samples/example.pdf
      </file>
      <startpage>
         -1
      </startpage>
      <endpage>
         -1
      </endpage>
      <TOCEntry>
         example document, last page
      </TOCEntry>
   </inputpdf>
</sourcepdfs>

Adding Comments

Comments in your parameter file are lines of text that you don’t want to be read by AppendPDF Pro or AppendPDF. They can be either notes to yourself or descriptions of what something does or is used for, which can be useful if others will be accessing the file. Additionally, comments can be used for testing or debugging. You may want to prevent a file from being used in the source list, instead of deleting and retyping the name of the file you can simply “comment it out”. Comments start with the hash or number symbol: # and must be placed at the beginning of a line:

#This is a comment in my parameter file.

The following is an incorrect comment:

begin_source #beginning of the file list

Complete Parameter File Example

Now that we have gone through all of the pieces of a parameter file, we show one in its entirety. This example is almost the same as the sample paramscomplete.txt parameter file that comes with your copy of AppendPDF Pro. The example below uses all the parameter options.

#Complete Parameter file for use with AppendPDF Pro with a cover letter

#Name for the new, appended file
./samples/paramsletter.pdf

#List of files and pages for appending with text for Table of Contents
begin_source
./samples/pdfs/sample1.pdf,1,-1,(sample document 1)
./samples/pdfs/sample2.pdf,1,-1,(sample document 2)
./samples/pdfs/sample3.pdf,1,-1,(sample document 3)
./samples/pdfs/sample4.pdf,1,-1,(sample document 4)
end_source

#Cover page block
begin_coverpage
CoverPage (./samples/pdfs/lettersample.pdf)
StampFile (./samples/stampfiles/letterstamp.txt)
end_coverpage

#Table of Contents block
begin_TOC
TOCPage (./samples/pdfs/toc.pdf)
StampFile (./samples/stampfiles/tocstamp.txt)
BookMarkText (TOC Page)
HeaderHeight (100)
FooterHeight (240)
LeftMargin (20)
RightMargin (20)
FontName (Helvetica)
FontSize (14)
ColorSpace (DeviceRGB)
Red (0)
Blue (44)
Green (87)
LineSpace (3)
Leader (.)
PageColumnWidth (40)
end_TOC

#document info block
begin_info
Title (AppendPDF Pro Test)
Subject (testing AppendPDF Pro with sample files)
Author (Appligent, Inc.)
Keywords (testing AppendPDF Pro sample files)
ExtraText (AppendPDF Pro document)
DocDate (D:20170714235659)
end_info

#Extras block for Stamp Files
begin_extras
Open_Mode (ShowBookmarks)
View_Mode (FitPage)
end_extras

#End of parameter file

The parameter file is a text document which requires the new file name and the list of documents to append. The document information is optional. The Cover page, TOC, and Extras blocks are also optional and used only with AppendPDF Pro.

When this example file is run with AppendPDF Pro, the user will get an output file called appendprocomplete.pdf that contains all of the pages listed in the Source files block of the parameter file.

When File > Document Properties or File > Properties is selected in Acrobat, the Title, Subject, Author, and Keywords fields will be populated with the information as shown in the Document Info block of the sample parameter file. A custom string and date have been added for searching with Acrobat Catalog.

The pages of the appended documents (not the cover or the table of contents) will be stamped by the stamp file listed in the Extras block.

Introduction

We will be using the sample parameter file paramsletter.xml in the samples directory as an example throughout this chapter. The default location for AppendPDF Pro on Windows is C:\Appligent\AppendPro\ and AppendPDF is located in C:\Appligent\AppendPDF. On other platforms, it will be wherever you installed it. The paramsletter.xml AppendPDF Pro example contains most of the features described in this chapter for the purpose of explanation and examples.

What is a Parameter File?

AppendPDF and AppendPDF Pro require a parameter file to specify how you want to build a new document. This chapter explains XML parameter files, while Parameter Files — Text (AppendPDF Pro) and Parameter Files — Text (AppendPDF) describe text parameter files:

• XML — the parameter files using XML to code parameter specifications.
• Plain text — the text parameter files used by earlier releases of AppendPDF Pro and AppendPDF. These are supported to maintain backward compatibility with existing workflows. New features will only be available using XML files.

An XML parameter file is a text file containing the XML markup that specifies how AppendPDF Pro or AppendPDF will build your new document. You can specify the name of the output file, list the files to be included in the appended document and set many other options to establish how you want the final document to look when it is opened by the end user.

The parameter file includes:

• <outputpdf> — Output File is the name (including directory path) of the new, appended file.
• <sourcepdfs> — Source Files are the documents to be used for appending, including page ranges and Table of Contents entries.
• <TOC> — Table of Contents information includes the table of contents file, alternate bookmark text, and the stamp file for the table of contents (AppendPDF Pro only).
• <coverpage> — Cover page information includes the cover page file to be used and the stamp file for the cover page (AppendPDF Pro only).
• <docinfo> — Document information is Title, Author, Subject, Keywords, and custom fields. These are viewable within Adobe Acrobat and Acrobat Reader.
• <extras> — Extras specify additional information such as how the document should open or a stamp file for the body of the document.

Building a Parameter File

Elements and structure

We use XML to describe the parameters that AppendPDF Pro and AppendPDF uses to append documents together. As we describe XML elements, there are two sections:

1. A tree view of the elements, which describes the elements and shows how they are related.
2. Examples of XML code for each element.

Content of an element table

An element table contains the following information:

• Element — The element tag.
• Required — Whether the element is required (✔) or optional (blank). If the child of an optional element is marked required, it is only required if the parent is used.
• Content — what information the element contains, i.e., what it specifies. Note that an element can either contain data, or be empty. If it is empty, nothing else is needed.

The element tree structure

All of the tables in the XML Parameter chapter that describe the structure of elements use notations and indents to indicate specific things about individual elements:

• The element tree structure shows the topmost element as being expanded with child elements below.
• The Level column indicates what level from the top parent element described in the table, the current child element resides.
• The notation “+” indicates the element is collapsed and is a parent which contains child elements within its structure.
• Indents are used to assist in understanding the structure levels of the elements in the table.
• When there are elements that come before the current element in the <appendparam> structure, and they are not being shown, there will be a ⇔ symbol before the element tag name in the table.
• Some parent elements contain several options. When only one of the options can be used at a time the word “OR” will appear before the element tag name in the table.

XML Parameter File Details

The XML parameter file contains content and design information for the document that will be built by AppendPDF Pro or AppendPDF. The following sub-chapters describe in detail how to build parameter files in XML format.

In this chapter…

…we explain plain text and XML Forms Data Format (FDF) files: what they look like, how to generate them, and tips for using them.

• Creating an FDF File describes how to build an FDF file.
• Creating an XFDF File describes how to build an XML FDF file.
• Using Unicode describes how to use Unicode in XFDF files to work with Asian character sets.
• Notes on JavaScript and Formatting Fields provides tips for getting the correct results when using JavaScript to calculate fields or when formatting form fields.

Creating an FDF File

An FDF file is a plain text file that contains a list of form fields and their values. Although we’ll show you how to create one by hand, most often FDF files are software generated. These are some of the more common methods to create FDF files:

• Use Adobe Acrobat to export forms data directly to a file.
• Use a Submit Form action in Acrobat’s Field Properties pop-up to export FDF data to a web server.
• Export data from a database and save it as an FDF file, using a script that you create.
• Write a program that will build an FDF file as a plain text file, using a script that you create.
• Use Adobe’s FDF Toolkit, see FDF resources for more information.

The FDF file format

An FDF file has the following format:

• An FDF file must begin with (Percent)FDF and end with (PercentPercent)EOF
  %FDF and end with %%EOF
• The data is given as name-value pairs, enclosed in double angle brackets: << >>:
  /T indicates form field name
  /V indicates form field value

In this section we’ll use the sample file: samples/testfiles/testfile.fdf as an example. Within it are six name-value pairs. The lines before and after these pairs are identification and formatting information.

%FDF-1.2
%âãÏÓ
1 0 obj
<<
/FDF << /Fields [
<< /T (CheckBox1) /V /Yes>>
<< /T (CheckBox2) /V /Off>>
<< /T (ComboBox) /V (6)>>
<< /T (ListBox) /V (fontsize)>>
<< /T (Basefont) 
/V (This is a Multi-line text box. Note that the text wraps around to the next line!)>>
] >> 
/ID[<B5B9EA85E3E2A7372D233185314E367E><7CA8657022DA815A340A57D516E030DC>
] >> 
>> 
endobj
trailer
<<
/Root 1 0 R
>>
%%EOF

Line breaks and new lines in FDF files

When long character strings are used in text fields, you may need to manually insert line breaks, so that the text wraps in the form field the way you would like it to. If you put a line break in a field value, you need to adjust the spaces between words.

Inserting line breaks in FDF files, \r and \n

In order to make a multi-line text field format the way you want it to, you may have to add newline characters, using \r or \n. They both work the same way. A single new line results from any of the following: \r, \n, or \r\n. For example, if your text is:

Among these are time management

and you would like it to look like:

Among these are
time management

enter this into the FDF value for the form field:

Among these are\rtime management

Using the line continuation character \

The value of a name-value pair should be on a single line. If you need to break a value onto the next line, use the \ line continuation character.

Entering the following into the FDF value for the form field:

Among these \
are time man\
agement

Will look like this in the output PDF:

Among these are time management

Using special characters

Special characters can be entered directly into the FDF file, or they can be represented by octal characters. An octal character is represented by a \ followed by a three digit octal code. FDFMerge Lite and FDFMerge use octal codes with PDF encoding. A list of octal codes can be found in Appendix D of the PDF Reference manual on Adobe’s website.

Entering the following into the FDF value for the form field:

\200 Among these are time management

Will look like:

• Among these are time management

FDF resources

For more information about FDF, refer to Adobe for the following resources:

• The FDF Toolkit. Adobe provides this free API (Application Program Interface) for writing a server application that generates FDF data, or to parse FDF data from a form.
• The PDF Reference Manual provides useful FDF documentation.
• Be sure to check the FDFMerge Lite or FDFMerge pages of the Appligent website.

Creating an XFDF File

XFDF is an XML version of an FDF file. You can create XFDF files the following ways:

• Use Adobe Acrobat to export forms data directly to a file.
• Export data from a database and save it as an XFDF file, via a script that you create.
• Write a program that will build an XFDF file as a plain text file, via a script that you create.
• Use the Submit Form action in Acrobat’s Field Properties pop-up to export XFDF data to a web server.

You cannot use the FDF Toolkit to create XFDF files.

XML is a structured language that begins with the XML file itself as the topmost object. XFDF files have an element called fields that contain field and value.

Basic XFDF file structure

The table below shows the basic XFDF file structure.

Refer to the XML Forms Data Format Specification on the Adobe website for more information about XFDF files. You can go to https://www.immagic.com/eLibrary/ARCHIVES/TECH/ADOBE/A070914X.pdf to download the specification.

An example of an XFDF file which shows this simple structure follows. The sample FDF form data would look like this in XFDF:

<?xml version="1.0" encoding="UTF-8"?>
<xfdf xmlns="http://ns.adobe.com/xfdf/" xml:space="preserve">
   <fields>
      <field name="CheckBox1">
      <value>A</value>
      </field>
      <field name="CheckBox2">
      <value>Off</value>
      </field>
      <field name="CheckBox3">
      <value>Off</value>
      </field>
      <field name="ComboBox1">
      <value>Option 1</value>
      </field>
      <field name="ListBox1">
      <value>Item2</value>
      </field>
      <field name="MultiLineText1">
      <value>This is a Multi-line text box. Note that the text wraps around to the next line!</value>
      </field>
      <field name="RadioGroup1">
      <value>Yes</value>
      </field>
      <field name="TextBox1">
      <value>Sample Text</value>
      </field>
   </fields>
</xfdf>

Line breaks and new lines in XFDF files

To manually insert a line break in form field text, type a carriage return directly into the value in the XFDF file. You do not need to use /r or /n characters. Make sure to check Multi-line on the Options tab of the Text Field Properties dialog in Acrobat.

Using Unicode

FDFMerge Lite and FDFMerge can use Unicode to place Asian language characters in a text form field. The only place double-byte characters can be used is in the value parameter of a text form field.

Prerequisites for Acrobat full version

In order to use Acrobat to view and print Asian text, you must have Asian language support files installed for both the Operating System (OS) and Acrobat. The table below shows whether Asian font support is automatically installed for your combination of OS and Acrobat, or whether you have to manually install it.

Unicode font support

Operating system

Asian font support is automatically installed for all OS platforms except Windows 2000/NT. To install Asian font support, open Regional Options in the Control Panel, and add the fonts you want. You may need your original installation disk. Refer to the Windows on-line help for more information. You can also install keyboard support.

Acrobat

Asian font support is automatically installed only in Acrobat 6 under Mac OS X. For all other versions, you will need to do a custom installation, and choose to install Asian font support. Refer to the Acrobat on-line help for more information.

Prerequisites for Acrobat Reader

In order to use Acrobat Reader to view and print Asian text, you must install the Asian Font Pack from Adobe.

Windows/UNIX

Download and install the Asian Font Pack.

Reader components can be updated in a variety of ways. Some updates are available when you open a PDF that triggers the updating process automatically. For example, if you open a form that uses Asian language fonts, Reader asks whether you want to download the fonts. Other updates are available only from the Help menu, and you must install them manually. Some updates are available both automatically and manually.

Mac OS X

You cannot download the Asian Font Pack for Mac OS X. You must choose to install it when you install Acrobat Reader. If you did not, you must reinstall Reader.

Available fonts

There are standard Adobe fonts that are available when using Unicode characters. The table below lists the seven fonts that are available for double-byte character stamping:

Double-byte character fonts

Use the font name in the left-hand column above in the Font parameter in your FDF, XFDF or FormInfo file.

Character encodings

Create UTF encoded XFDF files with a text editor that supports UTF-8.

UTF-8

Type double-byte Unicode characters directly into the XFDF file using any text editor which supports UTF-8. Your system must have the appropriate fonts installed. For example:

Only the value field can have Asian fonts or any other higher level Unicode character. All other fields must use only the Latin character set (the first 128 characters, equivalent to “ASCII”).

UTF-16

UTF-16 requires the double-byte characters in big-endian hexadecimal. Each character is represented by &#x and the four digit code for the character, followed by a semi-colon (;). Enter the entire Text parameter as a string of hex codes with no breaks. For example:

For example, to enter the three characters 5185 5BC6 306E, enter:

Refer to Unicode resources for help finding codes.

Multi-line UTF-8/UTF-16 stamps

In order to get multi-line text fields, you must make sure to check “Multi-line” in the Options tab of the Text Field Properties dialog. Then, either:

• For UTF8, enter a newline character directly by typing a carriage return. For example:

• For UTF16, place the newline character (below) directly into the text string.
  
  For example:

Both values result in this field value:

Text containing double-byte characters will not automatically wrap.

Unicode resources

1. The Unicode Consortium has the complete Unicode specification, providing a wealth of information on Unicode, character sets, and conversions.
2. SC UniPad provides a free trial of UniPad, a Windows-based Unicode text editor.
3. IT and communication provides an extensive tutorial on character sets, including Unicode.

Notes on JavaScript and Formatting Fields

Using JavaScript in PDF forms

FDFMerge Lite and FDFMerge do not have the capability to calculate form fields. If you use JavaScript in your PDF forms to calculate fields, the value in the FDF file is what will appear in the flattened output PDF file. Therefore, you need to have the correct field value present in the form or in the FDF file prior to merging.

If you will be merging and not flattening your form fields you can add a JavaScript to your form that will perform all calculations when the file is opened. However, you will get a warning from Adobe Acrobat to save the file when it is closed.

Formatting form fields

If you are flattening your form fields and you have set one or more fields as formatted, for example, as currency, then you will need to include the formatting for that value in the FDF file. For example, if you wish the value of a field to be $1,234.00 in the output PDF file, then the value in your FDF file needs to be /V ($1,234.00). If you put the value into the FDF as “1234” it will appear in the flattened PDF document as “1234.”

This behavior will sometimes also be true for non-flattened forms, when the form fields are still active. After merging the formatting settings may not appear to have “taken.” However, if the value in the field is modified (by adding and/or removing a character), formatting settings will take effect and format the value correctly to the settings. Therefore, whether merging and flattening or only merging, it is good practice to format the field as you would like it to appear directly within the FDF file.

Using PDF images in button fields

Using an FDF file, FDFMerge Lite or FDFMerge can merge the first page of a PDF document onto a button field. You must specify the value of a button to be a PDF filename in the FDF file. The button will remain active after merging with FDFMerge Lite or FDFMerge. For example:

/T (ThisButton) /V (C:\FDFMerge\ThisPDFfile.pdf)

This technique may also be used to stamp the first page of a PDF document onto a button if -s is specified.

Merging a PDF onto a button is different from stamping a PDF, JPEG or TIF onto a form field. When an image is stamped onto a button, the action of the button is lost in the form flattening. Active buttons appear on flattened documents if:

• A PDF file path is set in the FDF file for the fieldname,
• The button has had an icon set.

Buttons which contain nothing but text (Label only) will not be stamped. This feature only works on buttons containing PDF Images.

Introduction

The element <outputpdf> specifies the output file for the appended document. The following table lists all the elements and their attributes along with the tree view.

The table below describes the elements specifying <outputpdf>.

Contents of the <outputpdf> Element

XML Code Sample

To specify an output file, outputfile.pdf, insert the code:

<appendparam version="1.0">
   <outputpdf>
      <file>
         /fullpath/outputfile.pdf
      </file>
   </outputpdf>
<!-- . Indicates skipped sections -->
<!-- . -->
<!-- . -->
</appendparam>

Element for <outputpdf>

file

Specifies the path and filename of the output, appended PDF file.

Introduction

The Document Information Block is optional. Within Adobe Acrobat there is a feature to view information about a file by choosing Document Properties from the File menu. With AppendPDF Pro and AppendPDF it is possible to populate certain fields of the Document Info with the parameter file. A sample of a Document Properties dialog screen from Acrobat is shown below.

Document Info screen

Below is a Document Info screen in Acrobat for a Sample PDF, also called Document Properties.

Title, Author, Subject, and Keywords are fields in the Document Info screen as shown in the figure above. These are the fields that can be modified by AppendPDF Pro and AppendPDF. Enter values in the parameter file as you would like to see them appear when you call up the Document Properties in Acrobat. The fields Title, Subject and Author refer to information specific to that document. Keywords (this is Acrobat’s Keywords, not to be confused with the many other references to keywords in this manual) are usually simple words used for sorting and grouping (December, ProjectX, personal, etc.) and are useful for those who will be indexing their documents with Acrobat Catalog and would like to improve searching efficiency. More about indexing can be found in the Acrobat Guide or the Reader Guide if you don’t have the full version of Acrobat. (Either guide can be found under the Help menu of its respective application.)

To specify document information in a parameter file, list the name of the field followed by its value in parentheses. Before beginning this section the keyword begin_info must be added to the parameter file. At the end of the list close the section with the end_infokeyword:

begin_info
Title (AppendPDF Pro Test)
Subject (testing AppendPDF Pro with sample files)
Author (Appligent, Inc.)
Keywords (testing AppendPDF Pro sample files)
end_info

There is no set number of tabs or spaces that need to appear between the field name and the value in parentheses, as long as there is at least one tab or space. Also, if you do not want to include a Document Info field (for example, if you want Title and Subject, but not Author and Keywords) make sure that keyword is not listed in the Document Info block. Items listed with empty parentheses will cause AppendPDF or AppendPDF Pro to fail.

Make sure that all Document Info keywords (Title, Subject, Author, Keywords) are spelled correctly or AppendPDF and AppendPDF Pro will treat them as custom strings. Custom strings are discussed in the next section.

Optional Custom Information to Add within Document Info

AppendPDF and AppendPDF Pro support two custom field types: strings and dates. These can be added within the Document Info block of the AppendPDF or AppendPDF Pro parameter file which saves them in the keywords section of the Document Properties. The keywords can then be indexed with Acrobat Catalog.

The name of a custom string can be anything you want. Give it any name that will have meaning to you and/or be easy for you to remember. For example:

String1 (This file created by AppendPDF Pro)

or

ExtraText (AppendPDF Pro document)

Custom dates need to conform to the format D:YYYYMMDDHHMMSS. Acrobat Catalog allows dates to be searched using boolean operators. You can tell Catalog to find, for example, invoices whose date is greater than 1999 and less than 2000. A custom date in the Document Info block of the parameter file can be entered as:

DocDate (D:20170714235659)

This example indicates a date of 14 July 2017 with a time of 23:56:59.

Introduction

The element <appendparam> specifies that this is an AppendPDF Pro or AppendPDF parameter file. It has one attribute, version, which should be 1.0. The table below describes the attributes of the element <appendparam>.

Content of the <appendparam> Element

XML Code Sample

<appendparam version="1.0">
     Insert parameter specifications here
</appendparam>

Introduction

The Source Files Block is required. Following the first line of the parameter file is the list of input or source files that AppendPDF Pro or AppendPDF will use to create the new document. Before beginning the list you must enter the keyword begin_source and at the end of the list insert the keyword end_source. Files will be appended in the order that they appear in the source files list. After each filename are commas and page numbers; this is the notation that AppendPDF Pro and AppendPDF uses for specifying pages and page ranges. Specifying pages is discussed in detail below.

This is an example source file block:

begin_source
Sample1.pdf
Sample2.pdf,1,2
Sample3.pdf,1,1
Sample3.pdf,3,3
Sample4.pdf,2,4
end_source

It is important to make sure that none of your source files have names with commas in them. Since AppendPDF Pro and AppendPDF uses commas for describing page ranges, it will try to interpret any comma it sees as being a part of page information. Each parameter file can have only one source files block. Extra source blocks will be ignored.

Specifying page ranges in your source files block

In AppendPDF and AppendPDF Pro page ranges are delimited by commas. In the source files block shown above, each file has a range of pages specified. The different ways for specifying which pages you want to use are described below. When specifying pages do not insert spaces between file names and commas, or commas and numbers.

• If no pages are specified with a file, all pages from that file will be appended to the new document. For example:

Sample1.pdf

• To specify a single page to append from a file, after the file name add a comma, the page number to be appended, another comma and the same page number. This indicates that the beginning and ending page are the same, as in Sample3.pdf below:

Sample3.pdf,1,1

• To specify a range of pages place a comma after the file name, the number of the first page in the range, another comma, and the last page number of the range. The following example of Sample4.pdf specifies the range of pages 2 through 4:

Sample4.pdf,2,4

• To specify multiple, non-contiguous pages from a single document, multiple entries need to be made in the parameter file. Below, see that Sample3.pdf is listed twice, once to add page 1 and a second time to add page 3:

Sample3.pdf,1,1
Sample3.pdf,3,3

• To specify all pages from a specific page in a document, list the starting page only. Appending will start from this page and go to the end of the document. The sample below will append pages 2 through the end of Sample3.pdf:

Sample3.pdf,2

• To specify that only the last page of a document be appended, use the special notation -1 as shown with Sample2.pdf below:

Sample2.pdf,-1

sample4.pdf,2,-1

Usage: appendpdf [options] paramFile1 [paramFile2 ...]]
Usage: appendpro [options] paramFile1 [paramFile2 ...]]

-b                  : Include bookmarks
-eb                 : Include embedded files
-extra              : Include named destination links and bookmarks, article threads (recommended)

The Following parameters are available in AppendPDF Pro only

-f                  : Number from first page in output document
-u <string>         : Remove old stamps with UndoLabel

-listfonts          : Print list of available fonts in the appligent_home fonts folder
                      
-portfolio <string> : Build Portfolio; options "icons" or "details", also called portable collections

-vars               : List of variables to be substituted in the Cover, TOC, or Extras stamp File 
                      Example variable list - ( "name,value,name,value" )
-vardelimiter       : Delimiter character for variables in the Stamp File ( default is % )

Save Options

-i                  : Save using an incremental save
-w                  : Save as linearized pdf
-optimize           : Optimize the output file to try to reduce file size
-nocomp             : Do not compress using Object Streams; compatible with all versions of Acrobat
-comp               : Compress using Object Streams; Acrobat 6 and later
-iso32000           : Set file for ISO 32000 compliance (PDF 1.7)
-o                  : Path to the output file or directory

Command List File

-cmds               : Path to the file of commands -cmds only compatible with General Options

Encryption Options

-encrypt            : Encrypt output file
-keylength <int>    : Key Length.  Valid options are 40 and 128.  Default is 128.
-ownerpass <string> : New Owner Password (Required)
-userpass <string>  : New User Password
-noprint            : Do Not Allow Printing
-nomodify           : Do Not Allow Modifying the Document
-nocopy             : Do Not Allow Copying text or graphics
-nonotes            : Do Not Allow Adding or changing notes or form fields
-nofill             : Do Not Allow Fill or Sign of Form Fields
-noaccess           : Do Not Allow Accessibility
-noassembly         : Do Not Allow Document Assembly
-nohighres          : Do Not Allow High Resolution Printing

General Options

-v                  : Version information
-help               : Help information
-h                  : Help information
-l                  : Log to a file
-p                  : Show progress information
-n                  : Show no information on the screen
-r <string>         : Product registration code