Introduction:
This document is a guide to installing, configuring and using the JetTrac DocSplit™ Custom Agent. This document includes detailed instructions for installation and configuration in the Adobe Central Job Management Database and example files to help you see how the program works.
Background:
Often a batch of documents will need to be sorted into two groups: one group above a certain number of pages, and one group below. This threshold could determine a processing difference. For instance, a finishing machine that can only handle one-page documents. The one page documents could then be placed on the finishing machine while the multi-page documents are processed by hand.
At the same time, page x of y functionality in a batch of documents was added to JetForm Central in the 5.3 release. The trace file that is created contains the keys to know which documents contain how many pages. The second pass of jfmerge is then able to show page x of y functionality.
JetTrac DocSplit runs after the first jfmerge pass. Using the information in the trace file, it breaks the input field-nominated stream into two pieces, according to how many pages in each document, as specified in the trace file. It also breaks the trace file into two pieces so that when jfmerge is run on each piece, the page x of y functionality is retained.
JetTrac DocSplit™ is written in Java so it will run on any platform that supports the Java RunTime Environment (JRE), which includes Windows, Unix and AS/400.
Technical Support:
If you need assistance in installing and configuring JetTrac DocSplit™, call Pro Technology Automation, Inc. at 805-527-1248 or E-mail us at support@protechinc.com. Please note that the JetTrac DocSplit™ license fee does not cover technical support so there may be an additional charge. Please ensure you read these instructions carefully before calling for technical support.
INSTALLATION AND CONFIGURATION OF JETTRAC DOCSPLIT™:
Installing Java:
Refer to the document What you need to know about Java and JetTrac Licensing for installing the Java Runtime Environment (Java) and generating a site code for your site. It is available on the web at www.jettrac.net on the products page.
Installing JetTrac DocSplit:
After Java is installed, you are ready to proceed to the JetTrac DocSplit files themselves. The following files need to be installed:
Folder name Filename Description
C:\JetTrac\JTDocSplit JTDocSplit.bat Sample DOS Batch file for testing
C:\JetTrac\JTDocSplit JTDocSplit.jar JetTrac DocSplit executable program file
C:\JetTrac\JTDocSplit JTDocSplit.ini JetTrac DocSplit INI file
C:\JetTrac\JTDocSplit dsplit.lic JetTrac DocSplit license file for your computer
There is also several Page X of Y files included as samples to work with. These files will generate the trace file to work with. They will also give you a sample output as well.
Folder name Filename Description
C:\JetTrac\JTDocSplit Page x of y pass 1.bat Sample DOS Batch file for testing
C:\JetTrac\JTDocSplit Page x of y pass 2 small.bat Sample DOS Batch file for testing
C:\JetTrac\JTDocSplit Page x of y pass 2 medium.bat Sample DOS Batch file for testing
C:\JetTrac\JTDocSplit Page x of y pass 2 large.bat Sample DOS Batch file for testing
C:\JetTrac\JTDocSplit Page x of y pass 1.pre Sample Preamble file for pass 1
C:\JetTrac\JTDocSplit Page x of y.fnf Sample FNF data
C:\JetTrac\JTDocSplit Page x of y.ifd Sample ifd form template
C:\JetTrac\JTDocSplit Page x of y.mdf Sample mdf compiled form
Configuring the JetTrac DocSplit ini file:
There are two main steps to complete the configuration of JetTrac DocSplit. The first is to set up the JTDocSplit.ini file. The second is to set up the tasks and job steps in the Job Management Database in Adobe Central Control to call JetTrac DocSplit™ at the correct time.
There is one ini file for JetTrac DocSplit. Here is a sample:
^comment ***
^define doc%totalpages $
1|JTDocSplit-Small.fnf|JTDocSplit-Small.trf|
8|JTDocSplit-Medium.fnf|JTDocSplit-Medium.trf|
9999|JTDocSplit-Large.fnf|JTDocSplit-Large.trf|
~~
1. First line string in each document
2. Format of trace file, where % is the doc number
and $ is the number of pages, one on each line. Note: this
format is both how to read the input trace file and how to
write the output trace file…
3. smallMaxPages|smalldoc.fnf|smalldoc.pre|
4. medMaxPages|meddoc.fnf|meddoc.pre|
5. largeMaxPages|largedoc.fnf|largedoc.pre|
The lines above the double-tilde (~~) are values that JetTrac DocSplit reads. The rest of the lines are internal documentation to prompt you for what goes on each line. The double-tilde (~~) serves to separate the code lines from the explanations.
Line 1 The string that determines the start of every document in the batch. This could be a field, a comment, whatever. It must be a static string.
Line 2 The format of the trace file. This tells JFDocSplit (and jfmerge) how many pages are in which document. This format is the same for both input and output.
Line 3 The small documents line. The form of this line is: The threshold number. This number and below pages will go to the small documents file|The fully-qualified filename for the smaller output documents|The fully-qualified filename for the smaller output trace file. This file is synthesized out of the main input trace file.
Line 4 The medium documents line. The format of this line is the same as the small file, except that all documents with the number of pages from above the small documents threshold number up to and including the threshold number specified on this line.
Line 5 The large documents line. The format of this line is the same as the medium file, except the threshold number here must be a number large enough to accommodate the maximum number of documents that might be encoutered in the input file. All documents with more pages than the medium documents threshold number will be included in this large documents file.
The JetTrac DocSplit Command Line:
JetTrac DocSplit is a Java program and must be run from withing the Java Runtime Environment. Refer to section 2.1 for more information on acquiring and installing Java. Assuming that you already have Java installed on your system, the format of the command line is:
java –jar [path to java.jar file] [input fnf] [input trace file] [ini file] [log file]
A sample is:
java –jar c:\JetTrac\JTDocSplit.jar “test.out test”.”trace” “JTDocSplit.ini” “jfserver.log”
Section 2.7 will instruct you how to implement this command line for use with Central.
The JetTrac DocSplit License File:
As with all JetTrac products, JetTrac DocSplit is protected from piracy by the JetTrac License Manager system. This system locks JetTrac DocSplit for use exclusively to one server or system in your organization. It works in this manner:
1. You run JetTrac SiteCode on your computer and generate a unique site code file for your system.
2. You send that site code file to Pro Technology Automation.
3. Pro Technology uses your site code file to generate a product license key file.
4. Pro Technology sends the product license key file back to you.
5. When JetTrac DocSplit runs, it scans the system and compares the tokens it finds with the tokens found in the license key file, and if they match, it runs normally.
Refer to the document What you need to know about Java and JetTrac Licensing for further information.
Configuring the task in the Job Management Database:
To add the JetTrac DocSplit custom agent in Adobe Central Control for Windows platforms:
1. Start Adobe Central Control.
Create a new task by clicking New Task. Set up the Task Definition with the following information:
Task Id: JTDocSplt
Program name: java –jar c:\JetTrac\JTDocSplit\JTDocSplit.jar
Program options: @InFile trace.out @MDFName @LogFileName
Comment: JetTrac DocSplit Custom Agent by Pro Technology
4. Click OK to save the Task Definition.
5. Now you must create a job step that calls the JetTrac DocSplit task. This would be one of the job steps in the complete job you are setting up. To set up a new job, from Central Control main screen click File, Job Management Database, Jobs, then New Job. Define the rest of the steps that you need.
6. Close all windows, go back to the main Central Control screen and update the Job Management Database by clicking on Control, Reload Job Management DB.
Configuring the Job in the Job Management Database:
1. Now you must create a job step that calls the JetTrac DocSplit task.
2. From the main screen of Central Control, click File, Job Management Database, Jobs. You will get a list of all jobs you have set up in Central Central. We will assume that you already have a job set up and you are adding the JetTrac DocSplit task. Click on the Job that you want to add notification to, then click “New Step”. The New Job Step screen will appear.
The following are the fields that you need to fill in:
Task ID – from the drop down list, select JTDocSplt
Input File – Whatever the output letter from the last step was
Output file – leave this as *
On Error – Select S to Stop the Job if there is an error in JetTrac DocSplit
Form File – put the fully qualified name of the INI file
Preamble file – This should be *
Printer Name – leave it as *
Macro Number – leave it at 1
Load Flag – leave it at T
Comments – type in a description like “Separates docs by number of pages”
Considering the overall job in the Job Management Database:
1. In order to obtain the trace file used as an input to JetTrac DocSplit, first a pass of jfmerge must be run. This jfmerge must use a specifically formatted preamble that will produce the trace file in exactly the manner needed by JetTrac DocSplit.
2. JetTrac DocSplit runs, providing three output files and three corresponding trace files.
3. Jfmerge is run once for the small document batch.
4. Jfmerge is run once for the medium document batch.
5. Jfmerge is run once for the large document batch.
2.9 Sample Preamble coding to drive JetTrac DocSplit
Pass One
The principle is that on the first pass, jfmerge must use its knowledge of where it is in a document to record this to the trace file. There must be an event triggered at the end of every document. That event must include this command:
\trace”^define doc@user:docnum.totalpages @$page.@lf.”
Where @user:docnum contains which document number this is and @$page contains the current page count number. This will create trace file lines like this:
^define doc1totalpages 3
which JetTrac DocSplit will read and understand.
Also be careful in your pass one preamble to initialize your variables like this:
^define docnum 1
^global numberofpages 1
and to both increment the document number like this:
\defineresolve”docnum”,”@(@user:docnum.+1)”
and to reset the page count like this:
\$page1
Remember to run the trace file update on the last file in the batch, usually with:
JfEndData!EndData
Pass 2
After JetTrac DocSplit has run, jfmerge needs to run separately on each output. The pass 2 preamble needs to have this command:
^file [trace file] in order to bring the new trace file in.
This command:
\defineresolve”global:numberofpages”,”@user:doc@user:docnum.totalpages”.
sets the total number of pages value as the number of pages variable so it can print on the form during the merge. Only this time, instead of running at the end of the documents, it has to run at the beginning.
Remember to still increment the document number as before.