DocMgr

From CometWiki

Latest revision as of 23:41, 29 May 2012

DocMgr is the way to organize and launch your documents. The concept is similar to the use of spooling printers and QSPOOL, but with more flexibility and the convenience of a Windows interface.

The DocMgr screen consists of a tree control and the main list control. The tree control contains the names of all the archives configured on your system. When you select one, the details of the jobs in that archive will be displayed in the list control. Double-click on a document's name to launch the viewer for the document, or right click on any document for a popup menu to view, print, delete, rename, copy, or export it. Multiple documents may be selected at one time for printing, deletion, copying, moving, or export. Note when choosing the "print" option DocMgr simply ShellExecutes the document file with the "print" action. You must have a program associated with this action for the type of document selected in order for this to work. It is best used on .pdf documents.

The toolbar and menu at the top of the screen provide a "Refresh" option to update the display, a "Clear archive" option to delete all documents from the archive, and an "Import" option to add any file on your system to the archive.

Clicking on a column heading in the list control determines the sorted order of the documents. DocMgr remembers your sort order choice so that the next time you run it, you'll see the display in your preferred order. This makes it easy, for example, to see all documents for a particular user grouped together regardless of when they were created.

You can launch DocMgr from QMONITOR by clicking on "Document Manager" or by running DOCMGR from READY or the utility menu.

How to Configure an Archive
The configuration of the archive is done directly in the printer configuration:

Printer = LP6, P, X, SPL:JIMSDOCS, Adobe PDF,,;

The third parameter ("X") indicates that an archive is associated with this printer. "SPL:JIMSDOCS" specifies the CFAM directory (SPL) and archive name (JIMSDOCS). Unlike a spool name which is limited to 3 characters and must begin with "S", your archive name may be any name valid for a keyed file. Thus, you can use names like "INVOICES" or "ORDERS".

A Document Archive may also be used with your html and text printers:

Printer = LPH, H, X, SPL:HTMDOCS, HTM,HTMLPTR,;

Printer = LPT, X, X, SPL:TXTDOCS, TXT,EXTPTR,;

Sub-archives
Sub-archives to the Document Archives may be created from within DocMgr. To create a sub-archive, first select the parent archive in the tree then click on "Documents"->"Create sub-archive" from the menu at the top of the screen. Sub-archives are always created in a folder directly below the parent archive folder. A dialog will pop up asking you to supply the name of the new sub-archive, a Comet directory name for it, and a Windows folder name for it. You do not need access to the new Comet directory. DocMgr will dynamically access it for you. Likewise, the Windows folder where the documents will be stored will automatically be created one level below the parent archive. Sub-archives can be handy for further categorizing the documents in a main archive. For example if you have an archive called INVOICES you may want sub-archives for each year to reduce the total number of documents in the INVOICES archive. Sub-archives can be used just like main archives with two exceptions. You may not create a sub-archive under a sub-archive. And you cannot print directly to a sub-archive since it is not associated with a Comet printer. NOTE: At the time of the first release, only a Comet32 user will be allowed to create a sub-archive. Once the sub-archive has been created, Comet16 users may use them. This restriction is due to problems encountered with dynamic access under Comet16.

A "Print All" option
DocMgr has a "Print Text Docs" option that allows you to unspool your text documents to a Comet printer. Like the similar option in QSPOOL it can be started in "forever mode" so that it continues to monitor the archive for the addition of new documents. If you plan to use this option, you will probably want to configure your text archive using the EXTNOL DES program. This differs from EXTPTR in that it suppresses launching your text editor when the printer is closed. Instead, the document is just added to the archive and may be viewed or printed from there.

Programmer's Interfaces
There are sample files in XTL which show you how you can programmatically interface with DocMgr and the archives.

DocMgrMK.ibs demonstrates how you can convert your archive to a multi-keyed file. You can choose which fields to use for the sub-keys. This gets you setup to write your own program to list or access the archived documents in customer order.

DMImp.inc demonstrates how you can easily write a program to import any file into a document archive.

DMUnspl.inc demonstrates how to start the "Print Text Docs" unspool option programmatically, including the "forever mode" option.

DocProc.ibs is a template program for the "Process Docs" option. The user may select one or more documents for processing as you choose. When the button is clicked DocMgr will attempt to ENTER DocProc. This is a program you write to do whatever you want: print, email, etc.. DocProc will be ENTERed once for each document selected. All the info DocMgr has about the document will be passed to DocProc via # buffer. It also passes 2 numbers: the total number of documents selected by the user and the ordinal number of the current document (ie 1, 2, etc). This will make it easy for you to do special things for the first or last document in the group if you wish such as ask printer preference.

Special Mnemonics
There are two mnemonics which you might want to use with your archive printer. The first is the (SpoolMessage=string$). In the past this mnemonic was used to associate a descriptive message with a spool job as viewed in QSPOOL. When used with a printer that is associated with a document archive it has a new function. It can be used to apply a descriptive name to the actual document file. Look at the first document in the example above. We used

(SpoolMessage="ReporterMacros")

to name our document. The remainder of the name includes the archive name, a serial number for the document, and the appropriate extension based on the printer type. Without the (SpoolMessage) mnemonic, the name of the program which generated the document will be used to form the name.

The other mnemonic available to you is the (Document=File$,Dir$) mnemonic. It can be used to direct a copy of your document to a CFAM directory (Dir$). File$ specifies the name which will be assigned to the document. If the name does not contain an extension, the appropriate one (.pdf, .html, or .txt) will be added depending on the type of printer being used. You may issue the mnemonic several times to produce multiple uniquely-named copies of the output file. Because a qdir entry will not be created for this file, you may use long filenames.

When using this mnemonic, the document is first created in the default folder associated with the printer. For pdf printers this is established in the "Properties" for the printer. For html and text printers it is the Windows user's temp folder. Then, when the printer is closed, a copy of the document will be made for each occurrence of the mnemonic. The original document will remain in its folder. Its full pathname can be retrieved by reading the # LUN following the CLOSE of the printer.

You do not have to be using an archive to use this mnemonic. If you are using an archive, you may also use the (SpoolMessage) mnemonic to specify the name of the document kept in the archive.

Exporting and Importing
Exporting archive files is done through the DocMgr UI. You may select one or more files at a time and a destination folder. CopyFile will be used for the export.

You may import files to the archive either through the DocMgr UI or from your own app. The archive will accept any file type. Just remember that if you attempt to view it, you must have an application installed that is capable of opening that file (ie Adobe for .pdf files). To import from your own app, get the DMImp.inc file from the XTL folder. It includes sample code defining the interface with the DocMgr import subprogram.

You can transfer your old QSPOOL jobs into the archive by using the Archive option in QSPOOL. Archived qspool documents will retain their original date, time, and user properties. You may choose between pdf, text, and html output for the new document type. If you intend to use the "Print Text Docs" unspool option in DocMgr for the old qspool jobs, choose "text" as the type of output when prompted by QSPOOL.

Use of DocMgr requires a COM license for CometLib. Comet Subscribers in good standing have a complimentary COM license for each Comet license.

Options
You may pass option information via #buffer to DocMgr. Currently there are 2 options: a password that would be required for any user attempting anything but View and Print, and an option to turn off the display of the USER id column.

Here's an example using both options:

print (#) "/password=secretword /nouser"  ! secretword is whatever password you want to use

enter "DocMgr" dir="REL"

If the user attempts to do anything other than View or Print Text Docs they will be prompted for the password. Passwords are case-sensitive and limited to 32 characters. The NOUSER option will remove the User column from the display. You may wish to do this if your QMONITOR SECUREs the actual password since whatever if SECUREd is what is displayed in this column. Note: Running DocMgr from QMONITOR or QTILITY will continue to work as it has. You'll have to prevent restricted users from having access to those methods.