User's Guide

Document Sample
User's Guide Powered By Docstoc
					User's Guide: Imager Converter




                                 Imager Converter
                                   User's Guide




                                       1998-2002

                                 Metasoft Systems, Inc.




1
User's Guide: Imager Converter




Overview
The Imager Converter demonstrates the use of the Imager print driver to convert from any 'printable' file format
to a Fax Image format.

A brief history of document conversion solutions can be summarized as follows:
  - build a custom converter for all file formats
  - get everyone to use the same format
  - use the native application to do the file conversion

Building custom file converters (Inside-out), or getting everyone to use one common file format (PDF) does not
address the fact that many documents are WORD or EXCEL in origin.

For Windows based documents (true-type, graphics, extremely-complex, rapidly changing file formats) the most
efficient (time/cost) rendering solution is to somehow use a Windows machine.

Recognizing that all back-end Web servers are not always Windows Servers, we propose the following solution:

    WEB server accepts a 'file' for rendering from Web
    WEB server connects to pipe on a Windows server on local network
    Windows Server accepts a file to render
    Windows Server renders file
    Windows Server passes completion code back up pipe to UNIX server.

The WEB machine can connect with more than one Windows server. Windows Servers are approximately
$1,000 per server, and are scalable. File conversions are processor intensive, and not something you want to
bog down a Web server with.

The requirements for this are:
  - Imager fax print driver (NT4.0, 2000, XP)
  - Imager Converter and Control Dialog
  - Owner Application executable




2
User's Guide: Imager Converter




Files Provided

GUIDE.DOC              - word format programmer's guide (this document).
README.TXT             - text format guide
PDDLG.EXE              - Control Dialog
WPDAEMON.EXE           - Document Conversion Daemon process (for server rendering)
PDFILCNV.EXE           - Document Conversion Utility (single file)
PDDIRCNV.EXE           - Document Conversion Utility (directory of files)
PRINTDOC.DLL           - File Conversion DLL

img32mfx.dll           - communication dll's
img16mfx.dll
thk32mfx.dll
thk16mfx.dll




3
User's Guide: Imager Converter




Architecture
The following diagrams show the relationship between Document Conversion components.
Single Machine Arrangement

                                    Command line:
                                     Filename.ext
    PDFILCNV.EXE


                                                                          PRINTDOC.DLL
                                                                          communicates print
                                                                          parameters (such as
                       Dll Calls:                                         output filename, etc.)
                   GetDocTypeName()                                       to Control Dialog.
                       PrintDoc()                                         Control Dialog
                                                                          communicates
                                                                          completion status.
                   PRINTDOC.DLL




                                                    Windows Shell Call:
                                                       ShellExec(
                                                      Filename.ext,
                                                          PrintTo
    Filename.                                         PrinterName )
        Ext        Document Owner
                     Application:
                    WinWord.Exe
                    NotePad.Exe                                           Print Control
                                                                             Dialog:
                                                     Windows System       PDDLG.EXE



      Fax
     Format          Imager Print
     Output            Driver
      File




                                              Communication
                                                  DLLs:
                                               Img32mfx.dll
                                               Img16mfx.dll
                                               Thk32mfx.dll
                                               Thk16mfx.dll




4
 User's Guide: Imager Converter




 Client / Server Arrangement



Conversion Server                                     Web Server
                                                                                        Command line:
     Command line:                                        Named Pipe:                    Filename.ext
      Master Share                                        Filename.ext
       Pipe Name
      Printer Name      WPDAEMON.EXE                                     PDFILCNV.EXE




        Pipe Name
                                                           Registry
                                                                                          Pipe Name


      Dll Calls:        PRINTDOC.DLL
  GetDocTypeName()
      PrintDoc()


                                               Windows Shell Call:
                                                  ShellExec(
                                                 Filename.ext,
                                                     PrintTo
                                                 PrinterName )
      Filename.         Document Owner
          Ext             Application:
                         WinWord.Exe
                         NotePad.Exe
                                                Windows System




        Fax             Imager Fax Print        Communication
       Format               Driver                  DLLs:
       Output                                    Img32mfx.dll
        File                                     Img16mfx.dll
                                                 Thk32mfx.dll
                                                 Thk16mfx.dll


                                              PRINTDOC.DLL
                          Print Control       communicates print
                             Dialog:          parameters (such as
                          PDDLG.EXE           output filename, etc.)
                                              to Control Dialog.
                                              Control Dialog
                                              communicates
                                              completion status.

 Setup and Testing
 The Document Conversion software controls file conversion to TIFF by first launching the file owner application
 (e.g. Word, Excel, Netscape), then instructing the owner application to print the document with Windows shell
 commands.




 5
User's Guide: Imager Converter



Our experience is that no one utility can convert all file formats. However, most applications have a mechanism
used by the Windows shell to support file printing.

The PDFILCNV.EXE application is a console application that is launched with a command line. The command
line includes the name of the source file (among other things). The PDFILCNV.EXE application terminates with
a 'number of pages' printed return code, or a negative value if
There was a timeout. This way, even if a document conversion does fail (due to some required user
intervention); other conversions can still take place. In addition, a Windows Daemon application
(WPDAEMON.EXE) is provided to support file conversions from a Service application (such as a CGI script
running on a web based server).

To test out the Imager Converter, you need to do the following:

1. Run the self extracting zip file DOCCNVT.EXE. A Windows based installation wizard will guide you through
   the installation process. The installation process is the same for Windows 95/98 and Windows NT4 / 2000
   but in the latter case you will have an additional shortcut in your start menu for the Windows Document
   Conversion Daemon.


Testing Without WPDAEMON (NT4/2000/XP):
2. Start a command-line prompt.
3. Change to the directory in which you installed the Imager SDK Document Conversion Toolkit.
4. Type the command:
   PDFILCNV GUIDE.DOC -FGUIDE.TIF -C2
   this will start the document conversion process.
5. From your start menu run the Imager SDK fax viewer program to view the output file GUIDE.TIF


Testing With WPDAEMON on A Single Machine (NT4/2000/XP):
2. From your start menu run the Windows Document Conversion Daemon.
3. In the Windows Daemon main window press the stop button to stop the service and select "configure" from
   the "Service" menu. Enter the printer name that you chose during installation. Press OK then press the
   start button to start the service.
4. Start a command-line prompt.
5. Change to the directory in which you installed the Imager SDK Document Conversion Toolkit.
6. Type the command:
   PDFILCNV GUIDE.DOC -FGUIDE.TIF -C2 -DR
   this will start the document conversion process.
7. From your start menu run the Imager SDK fax viewer program to view the output file GUIDE.TIF


Distributed Testing With WPDAEMON (NT4/2000/XP):
2. The machine on which you installed DOCCNVT package will be known as the "Conversion Server". The
   second machine on which you'll run PDFILCNV.EXE will be known as the "Conversion Client". Copy
   PDFILCNV.EXE and PRINTDOC.DLL from the installation directory on the conversion server machine to a
   directory on the conversion client machine.
3. From your start menu on the conversion server machine run the Windows Document Conversion Daemon.
4. In the Windows Daemon main window press the stop button to stop the service and select "configure" from
   the "Service" menu. Enter the machine name of the web server. Press OK then press the start button to
   start the service.
5. On the conversion client machine start a command-line prompt.
6. Change to the directory in which you copied PDFILCNV.EXE and PRINTDOC.DLL




6
User's Guide: Imager Converter



7. Type the command:
   PDFILCNV GUIDE.DOC -FGUIDE.TIF -C2 -DR
   this will start the document conversion process.
8. From your start menu on the conversion server run the Imager SDK fax viewer program to view the output
   file GUIDE.TIF

NOTE: When you run WPDAEMON it writes its pipe name to the registry key
HKLM\\Software\\Imager\\PrintDoc\\PipeNames on the conversion client machine. When you run PDFILCNV
with the -DR option it looks to this registry key for available pipes. When WPDAEMON exits it removes its pipe
name from the registry.

NOTE: The WPDAEMON.EXE application communicates with the PDFILCNV.EXE application via a pipe. It
will not work on Win95/Win98.

To convert multiple documents, run the PDDIRCNV.EXE application.

We have tested this conversion process with many document types, including Word, Adobe, and HTML. To
ensure best results, set the default document type for .TXT to be WordPad (rather than notepad). Also, for
HTML files, set the default document type to be Netscape (Rather than Internet Explorer). The Adobe
conversion of .PDF files requires the user to respond to a dialog. We are hoping for some form of resolution on
this problem.

The PDDIRCNV.EXE application repeatedly calls the PDFILCNV application, and is a superset program.




7
User's Guide: Imager Converter




Command-line Parameters
Command line parameters for each application (use the /? switch to get this) are listed below.

PDFILCNV Conversion Utility - Copyright (c) Metasoft Systems Inc
Converts document files from other formats to .tif fax images.

Syntax: PDFILCNV <docname.ext> [options]
Where:
 <docname.ext> Document filename [required]
 /cn         Command, [optional, default is 0]
              n=0 -use printer default settings
              n=1 -use dialog settings
              n=2 -use command line parameter settings
 /d[:server|r[:server]] Communicate request to Conversion Daemon,
           instead of calling printdoc() directly. If server name
           is specified use the Conversion Daemon on that server.
           If 'r' is specified then look to the local registry for
           First available Conversion Daemon. If r:server is
           specified then look to the registry on <server> for first
           available Conversion Daemon.
 /fs        s is output filename [required if /c2 used].
 /in        n is interval in seconds to wait between queries to locate an
           available Conversion Daemon using the reqistry. Default is 0.
           A lower priority PDFILCNV should use a higher number.
 /l       Log debugging info to file.
 /mn          Page format [required if /c2 used]
              n=0 specifies single page per output file
              n=1 multiple pages per file
 /nt        t [optional] is the pipe name used to communicate with driver
 /on         n [optional] specifies the timeout in seconds. We will wait n
           seconds for the print job to complete.
 /p<printer> specify the name of the printer to print to. Use only without
           the /d option. If name has spaces enclose in quotes.
 /q         makes PDFILCNV produce no output (quiet)
 /r        makes PDFILCNV skip mfx calls to driver
 /tn        Output file type [required if /c2 used]
 /wn          Communications timeout for the Conversion Daemon.
           If the /d:server option is specified specified, we wait
           n seconds for the Conversion Deamon to become available.
 /?         This help screen


Returns:
 Number of pages printed
 Else:
    1. Problem parsing command line
    2. Timeout connecting to Daemon
    3. Keyboard hit
    4. Disk access error
    5. Daemon not running
    6. Daemon not running

Note: 'PDFILCNV <docname.ext>' alone will use /c0 which will skip the control



8
User's Guide: Imager Converter



dialog, and will use printer defaults.
Note: Create file: "\log\pdtest.log" to enable logging.




9
User's Guide: Imager Converter




PDDIRCNV Conversion Utility - Copyright (c) Metasoft System, Inc.
Converts multiple document files from other formats to .tif fax images.

Syntax: PDDIRCNV [<dirname>] [/on] [/r] [/pt] [/q] [/?]
Where:
 <dirname> is optional name of directory to process
 /on      is optional and it specifies the timeout in seconds.
       we will wait n seconds for the print job to complete,
       if the job does not complete before the timeout, we quit.
 /r     includes sub-directories (recursively)
 /pt     is optional and it specifies the output files name prefix.
       where t is the prefix, and it can include the full path.
       t can optionaly be enclosed in quotes. Note that when a
       numerical part of filename is created it is appended to
       this prefix to create the oputput filename.
 /q      makes the utility produce no output (quiet)
 /?      is this help screen

Note: 'PDDIRCNV' alone will parse current directory non-recursively with a timeout of 120 seconds, with the
output directory of "c:\"




10
User's Guide: Imager Converter




Debugging Hints

To enable status logging:
--------------------------
To turn logging on, run PDFILCNV with the /l switch. Log files are written to the following files:
   \log\printdoc.log - status from PRINTDOC.DLL
   \log\dialog.log - status from the Control Dialog PDDLG.EXE
   \log\pdfilcnv.log - status from PDFILCNV.EXE
   \log\pddircnv.log - status from PDDIRCNV.EXE
   \log\wpdaemon.log - status from Windows Document Conversion Daemon



If printing fails:
---------------------
Two possible failure modes can occur:
      1. The printing application stops before printing and is looking for user intervention (macro, etc)
                  - Not a problem, as the print operation is not affected. All that will happen is the printing
                       application doesn't return, and PDFILCNV times out.
      2. The printing application hangs, or does not complete.
                  - Two likely causes are the printing process is taking way longer than than the allocated timeout
                       (you need to adjust the time-out), or the print process has stopped (likely caused by a Control
                       Dialog problem).
               All following print jobs will be queued, and nothing will print.
               Remedy is to delete the jobs, stop, and re-start the print spooler.

The key to the conversion process is to process only one JOB at a time. If more than one job is queued, then
pdfilcnv.exe will continue to time out, and nothing will be printed.




11

				
DOCUMENT INFO
Shared By:
Categories:
Tags:
Stats:
views:39
posted:10/4/2012
language:Unknown
pages:11