Figure 1. - Index.html with SPOOL tab selected
INDEX.HTML uses frames to provide a remote control portal for your PC. Note that only authorised users will be able to access applications on your PC (see Security). The frame consists of several HTML files corresponding to the position in the browser window.
TL.HTM (top left) contains the RedTitan Logo as text.
TR.HTM (top right) is a tabbed index.
ML.HTM (middle left) is a context sensitive menu.
BL.HTM (bottom left) contains the RedTitan Logo as a graphic.
The main area of the window depends on the tab index selected - it starts as HOME.HTM. You may return to HOME.HTM by selecting the HOME tab. HOME.HTM is a static HTML page - expert users who wish to customise the appearance of nQ should start here e.g. Add special instructions. (see Customising nQ)
If you have got this far the program nQServer is working correctly.
You can test if the FTP server is working with the browser URL ftp://191.192.131.66. The browser will display the files and folders located in the nQ root directory. Some installations may elect to not install the FTP server; This will not effect other programs controlled by nQ.
You can launch the email server (QEMAIL.EXE) by selecting the EMAIL tab and the spooler by selecting the SPOOLER tab. These programs can only be controlled through a web browser - they have no other user interface! They will not function correctly until properly configured (See Spooler configuration)
The DOCUMENTS tab selects the Document Server. It is not a separate program but an intrinsic part of nQServer (see Document Server)
A summary of active nQ applications is shown on the PROGRAMS tab.
Spooler configuration.
Select the SPOOL tab. Choose "Configure" from the context menu. If you change any of the default settings it is important to stop and re-start the spooler. Until you are familiar with the system it is a good idea to leave "Automatic creation of printer sub-directory" checked.
The function of other parameters is explained below. Provided the cited file directories exist the defaults would be sufficient to test the spooler.
The nQ Spooler Model.
The main purpose of a spooler is to store files until it they can be safely transferred to another process or destination.
The nQ spooler extends this concept to include an automatic "rule based" process that decides on the final destination of a data file depending on the characteristics of the incoming file or the results of a "plug-in" program analysis.
The nQ Spooler Model - input
Firstly we consider the incoming data. The nQ spooler will accept data from several sources.
- Scanning a number of directories for files. This is often the easiest way for any computer program to add data to spooler; just write a file to disk.
- Up-load a file from a web page using the HTTP protocol. This is often the easiest way to demonstrate or test the system.
up-load form example (enspool.htm)
- TCP/IP data streamed to a named port. The spooler listens on port 9100, the nQStream service. This process has the disadvantage that it is difficult to identify the remote data; You may only have the originating computer IP address.
- TCP/IP data using the LPR protocol. The spooler acts as an LPD server. Most network printers also provide LPD service and NT PC printer spools can easily be configured to forward data directly to the nQ spooler. IBM, UNIX and other host computers can often specify the LPR/LPD prototocol.
The nQ Spooler uses the LPR/LPD model to store data for processing, even if the originator was not an LPR client, so it is important to understand a little more of the protocol. The LPR/LPD protocol allows a number of other attributes to be specified for a file. Windows XP and NT provide a command line utility called LPR.EXE which may be used to send a file to an LPD service. Most UNIX/LINUX systems provide this utility.
The LPR utility command interface is described below...
C:\test>LPR
Sends a print job to a network printer
Usage: lpr -S server -P printer [-C class] [-J job] [-o option] [-x] [-d] filename
Options:
-S server Name or ipaddress of the host providing lpd service
-P printer Name of the print queue
-C class Job classification for use on the burst page
-J job Job name to print on the burst page
-o option Indicates type of the file (by default assumes a text file)
Use "-o l" for binary (e.g. postscript) files
-x Compatibility with SunOS 4.1.x and prior
-d Send data file first
C:\test>
Arbitary attributes like the Job name or Class are specified as switches (using a UNIX notation). If the target server is a real printer these switches are intended to have a conventional meaning, like a job name to print on a banner page. In the nQ Spooler these attributes are stored alongside the filename in the "control file" and can be used later to change down stream processing.
To LPR a test file called "test.txt" to the nQ Spooler you might issue a command of the following form
lpr -S191.192.131.66 -Pdem1 -Cclassname test.txt
In this simple example 191.192.131.66 is the address where our spooler is running. The nQ spooler responds by storing the data contained in test.txt in a printer folder called "dem1". The control file will be created to contain the originating file name "test.txt", the Class attribute "classname" and a record of the originating host computer.
Remember, the spooler can process many connections simulataneously; It is multi-threaded. Each incoming transaction is called a "job" and creates a "data file" and an equivalent "control file" in a "printer folder". There can be several jobs in each folder.
If you wish to test this process issue a similar LPR command. If the LPR command was accepted you should see the "dem1" folder on the nQ SPOOL tab page. Open the folder to view the job characteristics. If you repeat the same LPR command a second job will appear with a new serial number - even though the originating filename was the same, the data is held by the spooler as a separate job.
The nQ Spooler Model - rules processing
Now we have the file safely stored, the nQ spooler applies a set of user defined rules that specify how each job is to be processed. Using this technique you could select a different final destination for the job depending on the characteristics of the job.
The rule table NQRULES is in XML format. You could edit this file directly but it is safer to use the built in editor - click edit rules. In a newly installed system a few example rules are defined but they are marked as inactive.
Each rule has a similar format...
IF <condition> Actions <action>
e.g.
IF printer=dem1 Actions LPR to printer myprt on host 191.192.131.134
This rule would apply (the associated actions would be actioned) to our earlier example because the job is located in printer folder "dem1". This rule would send our data from "test.txt" to a networked printer at IP address 191.192.131.134. When the print is completed the data file is deleted and the control file is updated to record the transaction. Of course, if the printer was unavailable the job would remain in the spool queue.
Each rule is applied in turn to every unprocessed job within the spooler. Other "conditions" let you test other characteristics of the job.
e.g.
IF lprc=classname Actions LPR to printer myprt on host 191.192.131.134
This test would have worked equally well for our test example.
Actions include
- RUN a specified program, the data filename is passed on the command line.
- TELNET output to a specified host
- DELETE the job
- DUPLICATE the job to a number of named folders
- LPR the data to a target printer
Special programs called plug-ins use a simple API to change the processing characteristics of the job. e.g. Separate Postscript from PCL print jobs.
The nQ Spooler Model - rule table parameters
During the data files' life within the spooler, the control file and the data file travel around together. Each line of the control file consists of a single character (the command code) followed by a parameter. The nQ spooler may add some private command codes but if the data file is to be sent on to a external computer by LPR, only the parameters that strictly conform to the LPR/LPD protocol are used to reconstruct the LPR interface. Only a sub-set of commands are supported but they are usually enough to print or transmit a binary file.
Command Code
|
Size
|
Usage
|
Rule Symbol
|
Status
|
H
|
<=31
|
Responsible host
|
LPRH
|
Name of computer that sent the job
|
P
|
<=31
|
Responsible user
|
LPRP
USER
|
User login name
|
C
|
<=31
|
Class for banner page
|
LPRC
|
Mostly used to describe the data type.
-C parameter on NT LPR client.
|
J
|
<=99
|
Job name
|
LPRJ
|
-J parameter on NT LPR client
|
L
|
<=99
|
Print banner page
|
LPRL
|
User name for banner page. Class and Job entries must come first.
|
N
|
<=99
|
Print on banner page
|
LPRN
|
Source file name.
|
l
|
<=99
|
Filename
|
LPRLOWERL
|
Engage binary file transfer
|
f
|
<=99
|
Filename
|
LPRF
|
Print formatted file. Usage deprecated.
|
U
|
<=99
|
Filename
|
LPRU
|
Unlink after printing. nQ spooler always deletes the data file after processing.
|
;
|
<16k
|
Status
|
COMMENT
|
Displayed by spooler active server page interface. Internal to nQ spooler.
|
f
|
<=99
|
Filename
|
LPRF
|
Print formatted file. Usage deprecated.
|
!
|
formatted IP
|
IP address
|
IP
|
Client host IP
|
The nQ Spooler Model - rule table parameter substitution
The Rule symbols values that can be checked in the conditional part of of the rule may also be used in the action part to pass on some parameters to a later process. e.g. Print the originating using name on a banner page. A special notation is used to 'substitute' the value of a symbol in a rule definition.
!!symbolname;
For example, to use the incoming CLASS parameter to select the destination printer define the action part of the rule using the value of the LPRC parameter.
LPR to printer myprt on host !!LPRC;
The text !!LPRC; is replaced by the value of the CLASS symbol. The substitution is purely textual and a null value for the CLASS parameter will leave a null field and may cause an error when the LPR is actioned. You can use this notation in combination with other text. e.g. printer!!LPRC;. This may provide a way to define a default target printer name!
The following additional substitution symbols are defined..
Substitution Symbol
|
Use
|
!!STEM;
|
The originating file name excluding file extensions.
|
!!CONTROLFILE;
|
The full path to the control file. e.g. c:\spool\berry\cFA0123RedGhost
|
!!DATAFILE;
|
The full path to the data file within the spooler
|
!!PRINTER;
|
The printer folder name
|
The nQ Spooler Model - rule table example
A common requirement is to process differently depending on the original source. The following example assumes the nQLPD process has the following configuration. (Configure on the the SPOOL tab)
The "INBOX" provides a very easy way to submit files to the spooler where it is not possible to use the LPR/LPD interface. Any file placed in a sub-directory of the inbox will automatically given a CONTROL FILE and be processed by the nQLPD rule table from the INBOX spooler printer folder. Using the CLASS parameter you can select different processing based on the the originating sub-directory.
This example processes HP PCL print files using the RedTitan EscapeE program.
Files placed in the directory C:\SPOOL\INBOX\PDF are to be converted to PDF format. Files placed in the directory C:\SPOOL\INBOX\TIFF are to be converted to TIFF format. The following two rules do the job...
Rule 1: Example rule to create PDF
IF printer=inbox
AND lprc=PDF
Actions
RUN program: c:\program files\redtitan\software\escapee.exe
parameter /mkdir /x /pdf /to c:\pdfout\!!stem;
Rule 2: Example rule to create TIFF
IF printer=inbox
AND lprc=TIFF
Actions
RUN program: c:\program files\redtitan\software\escapee.exe
parameter /mkdir /x /tiff /to c:\tifout\!!stem;
The nQ Spooler - User Interface
In normal operation the Spool tab displays a series of Printer Folders. These correspond to sub-directories of the configured Spool Queue Root Directory Path. To show the contents of the spool click on the folder icon.
If the folder contains jobs you will see a display of the following form.
Id
|
Time
|
User
|
Class
|
Job
|
Host
|
File
|
Status
|
A466 |
Wed, 19 Dec 2001 13:42.16 |
gmb |
A |
pete.txt |
GMB_PICO(195.72.138.45) |
pete.txt |
|
A484 |
Wed, 19 Dec 2001 22:01.01 |
Sante |
PDF |
wsatkin |
argus_servr(62.7.89.234) |
serdrawing.pcl |
PDF rule complete(0) |
If the status field is blank then the job has not been processed by any rule. The ID corresponds to a Control File, Data file pair in the spooler folder. The ID is assigned by the process that submits the job to the spooling system e.g. a remote LPR. Click any part of listing to delete a job. The context sensitive menu provides a clear option that allows all completed jobs to be removed. If a clear operation leaves the folder empty then the sub-directory will also be removed. This display will auto-refresh. The Output History folder also displays the status of recently processed jobs from any folder.
Click the icon or the close menu option to return to the spooler main menu.
A summary of all the rules being processed is displayed on the main menu.
indicates that a rule has been suspended.
indicates that a rule is active.
You can click on a rule listing to toggle the activation status. In the default rule table file the activation status corresponds to the start attribute in the rule tag.
<RULE name="Example of the RUN action" start="no">
You must use the rule table editor to permanently change the activation status of a rule. Select Edit rules from the menu and click on Example of the RUN action. The ACTIVE checkbox will change the start attribute in NQRULES.XML.
The nQ Spooler - Remote operation security
All control features are available through a web browser provided the nQ applet and the user are co-located on the same host computer. i.e. local operation. This means that the browser URL contains the local loopback address (127.0.0.1) or the IP address is of the local machine. A remote user will be challenged for a user name and password. User names and passwords are maintained by the nQUsers program. To change a queue status a remote user requires POST priviledges.