nQ browser remote control and spooling
Functional Overview - revision 1.5
June 2002.
nQ is an interface to a collection of RedTitan server applications running on a PC. A remote control system provides a simple interface using a web browser like INTERNET EXPLORER.

The principle components of nQ are

  1. An extended HTTP server
  2. An FTP server
  3. A store and forward spooling system.
  4. An Email forwarding system
  5. A Document server.
The RedTitan Dynamic Document Formatting system, Legacy Migration system, PCL transform and data processing systems may also be managed by nQ but are supplied separately.

This document is a functional overview of the data and print management capabilities of nQ.
Minimum system requirements. Windows 98, 2000, NT4 or Windows XP. The system may be optionally installed as an NT SERVICE. Internet Explorer 5 is recommended. Other browsers may be used with restricted function. A static TCP/IP address is required. About 4 megabytes of disk space are used for software. Installation. All nQ files are located in a single directory and sub-directories. It is recommended the software is installed in an empty root sub-directory. Do not choose a directory name that includes spaces. In this document the default root directory is written C:\NQROOT Check if the install system is already running an HTTP server. If you are unsure, run IE5 and browse to the URL http://localhost. If the server cannot be reached, you are not running an HTTP server. Start the installation program SETUP in the CD root directory. If your system is already running an HTTP server accept the recommended port setting, otherwise enter the regular HTTP server port number 80. The install process will copy files to the selected sub-directory, update registry entries, start the service programs and launch the browser. Make a note of the initial URL or add it to your favourites. If your IP address is 191.192.131.66 the nQ home URL will be
http://191.192.131.66 if you chose port 80
orhttp://191.192.131.66:5001 if you used the default private port.
In the examples below it is assumed you have installed on the regular HTTP port 80. Note that http://191.192.131.66 is the same as http://191.192.131.66:80. Check that you have excluded your IP address from any proxy server processing if you have this enabled in your browser. File system components. Four important files should be included in routine archive back ups.
  1. NQRULES.XML - spooler forwarding rules.
  2. POSTBOX.XML - email template.
  3. USERS.ACL - remote access login control list.
  4. nqsetupreg.htm - list of registered components
Program components. In the default system 3 processes are running after system start-up.
  1. nQStart - This program installs the nQ tray icon and launches the other two services.
  2. nQServer - This is the extended HTTP server.
  3. nQFTP - This is a simple FTP server.
To shut down these services and all other nQ client programs right click on the tray icon. If nQserver or nQFTP reported a failure when starting, see the section on resolving port conflicts. Other programs may be started from the browser interface or included in the nQStart auto-launch list. in particular, nQLPD may be required for spooling services. Getting started. The minimum system will make the host PC a web server. This means that other users will be able to browse HTML files published in the nQ root directory. If a particular page is not specified then the default server page is index.html.
i.e. http://191.192.131.66 is the same as http://191.192.131.66/index.html.
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. 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 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)
Directory: (Spool queue root directory path)
Rules: (XML rules stem name)
Inbox: (Sub-directory name to be scanned for files)
Timeout: (Receive time-out in seconds)
Printers: (Automatic creation of printer sub-directory)
Dates: (List in chronological order)


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.