nQ programmers information

nQ Programmers Information
revision 2 - June 2002.

The preferred method of submitting a file to the nPortal spooler is by using the LPR protocol. This mechanism has the advantage that key disposition information can be described that may be useful to downstream processes and there is good scheme for maintaining multiple queues. This control file information contains commands that affect formatting, printing and job tracking.

A complete description of the available options that may be found in some printing environments is in the original rfc1179 and later documents. Many of the options are obsolete but a core sub-set are implemented by many printers and supported by LPR clients on many platforms.

The spooler implements an LPD service that will accept multiple connections from remote LPR clients. Entries created in the spooler are processed in accordance with a rule table that may promote incoming files. Data may be forwarded by LPR, TELNET (streamed data), EMAIL or plug-in processes. The spooler exposes a number of formal parameters that correspond closely to entries in the LPD control files and environment information. There is a syntax provided to allow actual parameters to be passed to forwarding processes. e.g. !!LPRC; will be substituted by the actual CLASS parameter obtained from a control file. This process is best understood by examining an actual example.

Programmers Information - LPR Windows NT provides a simple LPR client:-


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 ip address 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

The syntax shown betrays the UNIX origins of the LPR/LPD process. In the nPortal spooler, a printer or queue is implemented as a sub-directory of the spooler root directory. The following command assumes our spooler is running on 195.72.138.22

lpr -S195.72.138.22 -Pa -Cyup -JJOBBY -ol t.ppg

Programmers Information - Control File Format The LPR/LPD protocol transfers a file called "t.ppg" to a data file in the spooler folder "c:\spool\dfA083REDGHOST" (for example) and creates a control file with the following content.


  cfA083REDGHOST
  !195.72.138.19
  HREDGHOST
  PAdministrator
  Cyup
  JJOBBY
  LAdministrator
  ldfA083REDGHOST
  UdfA083REDGHOST
  Nt.ppg

Most users need not be concerned about the content of this control file but during this 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. Programmers Information - Control file parameters

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.
l	<=99	Filename	LPRLOWERL	Enagage binary file transfer
f	<=99	Filename	LPRF	Print formatted file. Usage deprecated.
U	<=99	Filename	LPRU	Unlink after printing. Nportal always deletes the data file after processing.
;	<16k	Status	COMMENT	Displayed by spooler active server page interface. Internal to nPortal.
f	<=99	Filename	LPRF	Print formatted file. Usage deprecated.
!	formatted IP	IP address	IP	Client host IP

Programmers Information - Plug-in programs A plugin process (free-standing program) is launched by the rule table RUN action. The full path to the relevent data file is passed as the only command line parameter. The corresponding command file can be deduced by replacing "DF" with "CF" in the filename. The spooler thread will camp on the plugin thread process until the program exits. During this time the plugin has "carte blanche". When the plug-in program exits the data file is deleted and the control file status is updated. The default behaviour may be changed by using the program exit code to supply a new printer folder in which the job is to be reproduced. e.g.


  procedure nQPromote(s:string);
  begin
     Halt(GlobalAddAtom(Pchar(s)));
  end;

In this pascal example, nQPromote('NQ!PCLJOB') would stop the plugin and cause the job to be moved to the spooler PCLJOB directory. This is intended to support ad hoc data recognition programs or job step processes. The complete CONTROL and DATAFILE is moved both may have been modified by the plug-in. Note:- The "NQ!" preamble is a signature added for reasons of security.

Exit codes less than $c000 (i.e. Numbers that cannot represent atoms) are reported in the active server page status field. e.g. halt(3)

Other methods are available to submit local jobs to the spooler. An entry may be fabricated by first creating a datafile with a unique name conforming to the above format. The control file should then be written to a temporary file and then renamed into the appropriate CF filename. e.g.

C:\spool\sinbox>type cfa2741local
  Nlph.ggg
  CINBOX_lph.ggg
  HFile
  !-
  UdfA2741Local

A simple minded program may create a file in the configured scan directory. e.g. Writing a file called ALPHA.TXT will create an entry in the same folder with the class INBOX_ALPHA.TXT. Data separation is achieved by testing the filename e.g. IF lprc contains INBOX_ALPHA. Print capture

The nQ Port Monitor re-directs print files sent to a windows printer driver to the nQLPD spooling system. Any printer driver can be configured to use the nQ Port Monitor. If the printer driver is shared then remote users may send files directly to the nQ spooler. A captured printer port will bypass the printer driver services.

To install the nQ port monitor on Windows 95 or 98

Run the program SETUP98. This will copy the required DLL to the system directory and install the port monitor called nQ:
Install a new printer on the machine hosting the nQLPD spooler. Any driver may be selected. GENERIC / TEXT ONLY is sufficient for most applications.
To engage the new port monitor select the DETAILS tab from the printer Properties Choose the NQ: Port Monitor. Click APPLY and OK
To make the printer visible to other users of The Network Neighborhood. Select the SHARING tab from the printer PROPERTIES.

Programmers Information - Notes

The rule table is processed for each valid entry in sub-directories of the spooler root directory.
An entry is valid if both a CF and a DF file are present.
The numeric sequence is provided by the process submitting the entry. (The remote or client LPR program). The remote host name is added after the sequence number and must start with an alpha character.
Job separation is maintained by the selected printer folder and then a unique combination of sequence number and remote host name.
The XML condition tag may contain a series of tests
e.g.
```
IF lprj=PCL and printer=xxx.
```
Complex conditions are not supported by the wizard but a individual rule may be edited.
If all the conditions are met the action is executed. By default, the actions associated with a single rule are single threaded. There is more documentation within the example rule table - NQRULES.XML.
There is no attempt to prevent loops.
Stacking actions is not recommended except for STARTS and ENDS job ticket directives associated with a TELNET command.

The following actions are defined.

DUPLICATE	Clones copies of the queue entry to a list of printer folders
RUN	Execute a names plug-in
TELNET	Stream data to a cooperating program
LPR	Forward data to a remote LPD process (Most networked printers support this protocol
DELETE	Delete the named job entry