@README.txt for TcsPdfIt

For a Quick Start just ensure you have everything unzipped into a directory set up like C:\tcs

THE FOLLOWING ARE INSTRUCTIONS ONLY IF YOU UNZIPPED EVERYTHING INTO "C:\TCS"

Now	enter new or modified USER (Not system) Environmental Variable "CLASSPATH" (without quotes) to be:

".;c:\tcs\itext-1.3.jar" (without quotes - be sure to enter the period before the ;)

In other words, the User Variable name is CLASSPATH and the variable Value is .;c:\tcs\itext-1.3.jar

to do this, click "start" (lower left of screen)
 then click "Control Panel"
 then double click "System"
 then click "Advanced Tab"
 then click "Environmental Variables"
 then if CLASPATH is NOT defined in "User Variables"
  click "New"  
  in "Variable name" put CLASSPATH
  in "Variable value" put .;c:\tcs\itext-1.3.jar
 then click "OK", "OK", "OK",. . . 
 (if CLASSPATH was already defined, just add ;c:\tcs\itext-1.3.jar to the end of what is there...OR...
  move itext-1.3.jar to where CLASSPATH is pointing.)
 
Then start up a "Command Promt" window

to do this, click "start" (lower left of screen)
 then click "Run"
 in open: box enter "cmd exec"
 click "OK"  
 
Now go to that directory prompt and key in ivp as in:

C:\tcs>ivp

ERROR? ERROR?...If you get an error "something" like the following,
it means your CLASSPATH is missing or set up wrong!
--------------------------------------------------------
C:\tcs>java TcsPdfIt c:\tcs\taxTml.txt
Exception in thread "main" java.lang.NoClassDefFoundError: com/lowagie/text/pdf/PdfReader
        at TcsPdfIt.main(TcsPdfIt.java:134)
C:\tcs>
--------------------------------------------------------
and remember that if you go fix CLASSPATH, you have to close and open a new dos window for it to take!
(little tid bits from the wacky world of windows...)


ERROR? ERROR?...If you get an error "something" like the following,
it means your JAVA JRE is older than the one needed to run TcsPdfIt...(Please download latest JAVA JRE!)
--------------------------------------------------------
C:\tcs>java TcsPdfIt c:\tcs\taxTml.txt
Exception in thread "main" java.lang.UnsupportedClassVersionError: TcsPdfIt (Unsupported major.minor
 version 49.0)
        at java.lang.ClassLoader.defineClass0(Native Method)
        at java.lang.ClassLoader.defineClass(Unknown Source)
        at java.security.SecureClassLoader.defineClass(Unknown Source)
        at java.net.URLClassLoader.defineClass(Unknown Source)
        at java.net.URLClassLoader.access$100(Unknown Source)
        at java.net.URLClassLoader$1.run(Unknown Source)
        at java.security.AccessController.doPrivileged(Native Method)
        at java.net.URLClassLoader.findClass(Unknown Source)
        at java.lang.ClassLoader.loadClass(Unknown Source)
        at sun.misc.Launcher$AppClassLoader.loadClass(Unknown Source)
        at java.lang.ClassLoader.loadClass(Unknown Source)
        at java.lang.ClassLoader.loadClassInternal(Unknown Source)
C:\tcs>
--------------------------------------------------------


After doing the Quick Start above, you can read this and it might make a little sense?

TcsPdfIt is a very simple JAVA program that takes an xml like txt file and updates fields in a PDF (Portable Document Format) file, saving the resulting updated PDF to a disk file and possible (optionally) printing the updated PDF as well.

In order for TcsPdfIt to work, a PDF template must be available that has pre-defined field names that can be updated.  This is usually accomplished using a tool like Adobe Acrobat Professional to define updatable fields in an existing PDF file. 

The xml like txt file mentioned earlier is called TML for now!

(Refer to the "c:\tcs\taxTml.txt" for a working TML text file...you can almost feel what it is doing!)

TML has a beginning TAG name and ending TAG name with TAG data between them.  

The TAG names begin with a < and end with a >.
  
The beginning TAG name and ending TAG name must be exactly the same except the ending TAG name has a forward slash after the <.

The two TAG names are called a TAG name pair.  (a/k/a a TML statement)

TML statements MUST be on one line...TAGs can not start on one line and end on another!

Example:

<FirstName>  John  </FirstName>

Here the TAG name pair, <FirstName> and </FirstName> identify the first name of someone.

The key thing to know that it is the TAG name that must match the PDF field to update and it is the TAG data between the TAG name pair that will be used to updated the PDF form field with that exact same name.
Reserved TAG names and there usage are:

R E Q U I R E D . . .

<TcsPdfFileIn> = (REQ) location of the PDF template file to use (s/b read only)
<TcsPdfFileOut> = (REQ) location of where to put and name the updated PDF file

IMPORTANT NOTE: The above two TAG name pairs MUST be in the above order.  You can have thousands of TML statements in your TML txt file processing hundreds of separate PDF updated output PDF files.  However, each group of TML statements for any particular PDF updating must begin with a <TcsPdfFileIn>  </TcsPdfFileIn> TAG name pair followed directly by the <TcsPdfFileOut>  </TcsPdfFileOut> TAG name pair.

O P T I O N A L . . . 

<TcsPrintPdf> = (OPT) Should we print the updated PDF  Y or N?
<TcsAdobeReaderLocation> = (OPT) Where is the Adobe Reader TcsPdfIt should use?
<TcsTmlComment> = (OPT) Comment to display on screen when encountered

E X A M P L E S . . . 

<TcsPdfFileIn>c:\tcs\AnotherUSTaxForm.pdf</TcsPdfFileIn>
<TcsPdfFileOut>c:\tcs\AnotherUSTaxFormForDoe.pdf</TcsPdfFileOut>
<TcsPrintPdf>N</TcsPrintPdf>
<TcsAdobeReaderLocation>"C:\Program Files\Adobe\Acrobat 5.0\Reader\AcroRd32.exe"</TcsAdobeReaderLocation>

NOTE: Take notice to the fact that the adobe reader path defined with the <TcsAdobeReaderLocation> TAG name is enclosed with double quotes () to ensure we can find the reader of your choice.  (Spaces in paths cause problems, that is the purpose of the ).  This TAG name is used to identify the exact adobe reader to use on your system because you may have more than one or you may not have the reader in your path statement during TcsPdfIt execution.  If you specify <TcsPrintPdf>Y</TcsPrintPdf> but do not specify the <TcsAdobeReaderLocation>, an attempt will be made to just blindly execute acrord32 and if found, it will work.  If not found, wellwe did say simple 
 
IMPORTANT NOTE: this adobe reader printing is tricky stuff and may not work as expected on your system environment!  (Remember, we said simple up front!) 

<TcsTmlComment>This is a comment in the TML to show on screen!</TcsTmlComment> 

Assuming everything has been unzipped and your directory structure looks like C:\tcs\ you can go to C:\tcs\taxTml.txt to see an example of a working TML txt file that is used by our installation verification process BATch file named ivp.bat.  (This is what Quick Start said to use.)

In C:\tcs\ you will also find our tax PDF template file: AnotherUSTaxForm.pdf.

This file was updated with Adobe Acrobat Professional(r) to define fields that could be filled in using C:\tcs\TcsPdfIt (CLASS) which uses C:\tcs\taxTml.txt.

With the TML txt file (C:\tcs\taxTml.txt) and the PDF template file (C:\tcs\AnotherUSTaxForm.pdf) in place, you can now execute the program by go to the command prompt, C:\tcs> and keying in the command as follows:

C:\tcs>java TcsPdfIt C:\tcs\taxTml.txt

NOTE: the ivp.bat file executes the above.

This will cause TcsPdfIt to start reading the TML file, C:\tcs\taxTml.txt, and acting upon the TAG name pairs and the datum they contain.

Check the DOS console for messages or redirect the DOS console to a .log file.

You should get a couple of TCS107-I messages saying a TAG name did not find a PDF Field name in the PDF Template with the exact same name.

You can make a copy of the PDF Template, C:\tcs\AnotherUSTaxForm.pdf, and add those missing field names to equal the TAG names in the TML just for practice...    

Now go look at C:\tcs\taxTml.txt to see the TML used to create two (2) new PDF files that have been updated with the datum provided in C:\tcs\taxTml.txt.

TcsPdfIt is a product of Taylorized Computer Systems and it uses a java PDF interface library known as iText - iText Library - Copyright (C) 1999-2005 by Bruno Lowagie and Paulo Soares. All Rights Reserved.

What do you think?
(Remember, this is a SIMPLE batch production type program! Not a fancy schmancy idiot proof GUI)

Email you questions, comments and improved documentation enhancements to: 

tcspdfit@yahoo.com

TcsPdfIt - Copyright (C) 2005 by Jerry Taylor. All Rights Reserved.
iText Library - Copyright (C) 1999-2005 by Bruno Lowagie and Paulo Soares. All Rights Reserved.

 
