						UGUIDE.TXT

 
 * Read the INSTALL.TXT and README.TXT files, as well as this
file, in their entirety before attempting to use the NOVQSERV
job server software.  Understanding how to install and configure
this software, in addition to understanding how it operates, is
imperative in order that you may customize and utilize the
NOVQSERVer properly.



Kicking off the NOVQSERV utility:



	To initiate the NOVQSERV utility go to the directory where the
utility (and associated files) resides and type NOVQSERV from
the DOS prompt:

			  novqserv


	The only command line parameter recognized by NOVQSERV is the
'config' switch. No other command line options are supported. 
Specifying the 'config' switch:


			  novqserv config
			  
will cause NOVQSERV to display the values of all configurable
global parameters before normal operations begin.  Manual
intervention (a keystroke) is required in order to cause
NOVQSERV to begin operating normally after the configuration has
been displayed.  



The NOVQSERV.TAB file:
----------------------
			  
The name of the queue service configuration file is
NOVQSERV.TAB.  This file is used for specifying where jobs
serviced via a particular queue are routed (destination queue
and/or custom command (batch) file).  The NOVQSERV.TAB file is
discussed in depth in the INSTALL.TXT file.

			  
No comments are allowed in this (NOVQSERV.TAB) file.



The NOVQSERV.CFG file:
----------------------

All configurable parameters are set within the NOVQSERV.CFG
file.  All valid parameters (identifiers) are shown in the
accompanying sample NOVQSERV.CFG file. 


Spaces are not allowed adjacent to the equal sign.   Any line
beginning with a forward slash is a comment.  


Following is a description of all valid parameters which are
configurable via the NOVQSERV.CFG file:



*********************************************************************



configurable value:
	
	postscript scan chars
	

explanation:

This parameter sets the maximum number of characters (starting 
with the first character in a job) which are scanned before a 
determination is made as to whether that job is postscript 
or non-postscript.  Because there is no standard as to what must
appear in a postscript job, you must configure the 'ps filter
string' parameter(s) properly so as to reflect what postscript
commands will be found in postscript jobs at your site.  These
strings may need to change or be added to  depending on the
postscript print drivers that are being used at your location. 
The first 'ps filter string' value is set internally by NOVQSERV
to "%!PS-Adobe".  This string catches most postscript jobs
printed by way of the Windows 3.11 postscript drivers.  As soon
as a match of any 'ps filter string' is found, the job is
assumed to be postscript and no more characters are scanned.  If
a match is not found before 'postscript scan chars' characters
are read, then the job is assumed to be non-postscript and is
treated as such.  Only jobs that are found in queues which are
filtered ('P'ostscript or 'A' non-postscript) have characters
checked using this parameter.  Jobs that are found in queues
which are not filtered ('N'o filtering) are blindly passed
through to the destination command (batch) file for processing.


notes:

Be careful of setting this value too high.  Scanning the maximum
number of characters (65000) for every job that is not
postscript can cause unneccessary overhead and slow the NOVQSERV
machine down.  Try to set this value only as high as is required
to accurately  determine the presence of actual postscript jobs.
 Use the associated filtering parameters to tune what this value
should be.


defaults, min, max:

	default is 100, no minimum, maximum is 65000


example:

	postscript scan chars=300


	_____________________________________  



configurable value:

	postscript dump chars

	
explanation:
	
This parameter sets the number of characters which are dumped in
the event that a non-postscript job is found in a 'P'ostscript
filtered queue.  'postscript dump chars' characters are written
to the file specified by the 'dumpfile' parameter.  Use these
characters to aid in the tuning of the 'ps filter string'
parameter(s) so that all postscript jobs can be accurately
interpreted as postscript.  This value is only used if the
'enable dumps' parameter is set to on.  If dumps are not
enabled, then this value is ignored.


notes:
 
Setting this value too high can cause disk space to be eaten
quickly if your 'ps filter string' parameter(s) are not properly
tuned.  Be sure to set the NOVQSERV user's disk quota high
enough so that it will not run out of disk space when using
dumps.


defaults, min, max:

	default is 200, no minimum, maximum is 65000

	
example:
	
	postscript scan chars=300
	
	_____________________________________

	
configurable value:
	
	ps filter string
	

explanation:      
	
If a queue is filtered ('P' or 'A' filter specification), then
each job which is found in that queue is scanned so that it can
be judged as either postscript or non-postscript.  Essentially,
the scanning process involves checking 'postscript scan chars'
characters from the beginning of the job for the existence of
any 'ps filter string' parameters configured.  If any of these
values are found to be in the job, then the job is judged to be
postscript and treated as such.  List these 'ps filter string'
values as necessary so that all postscript jobs will be found. 
Because there is no standard as to what must appear in a
postscript job for it to be valid, you will have to tune these
strings yourself.  Use the 'postscript dump chars', 'enable
dumps', and 'dumpfile' parameters to gather information on what
postscript commands are generated by the particular postscript
print drivers used at your site.  Then set these values
accordingly in conjunction with 'postscript scan chars' so that
all postscript jobs will be found properly.  

	
notes:
	
The NOVQSERV machine automatically inserts "%!PS-Adobe" as the
first 'ps filter string' value.  This default string catches
most jobs printed via the Windows 3.11 postscript drivers.  See
the section on filtering in the INSTALL.TXT file to learn more
about filtering. A maximum of 99 'ps filter string'
specifications are allowed (100 total with the automatic
internal filter string).

	
defaults, min, max:

	Automatic first 'ps filter string' is "%!PS-Adobe", 
	maximum of 99 others specified 

	
example:
		      
	ps filter string="/manualfeedtimeout"

	ps filter string="serverdict"

	ps filter string="/Encoding"

	_____________________________________


	 
 configurable value: 

	pass all postscript queue jobs

	
explanation:
	
This parameter, when set to on, keeps the NOVQSERVer from
discarding non-postscript jobs from postscript queues.  Even
though a job found in a 'P'ostscript filtered queue is judged 
not to be postscript, it is still passed through to the
appropriate destination command (batch) file when this parameter
is set to on.  This parameter is useful while tuning your 'ps
filter string' values.  If you are not sure that all valid
postscript jobs are being judged as postscript, then you can set
this parameter to on and even non-postscript jobs (judged as
such by the NOVQSERVer) will be passed through to the
appropriate command (batch) file.  In this way you can be
assured that users will still get their valid postscript jobs
even though your 'ps filter string' values may not be properly
tuned yet.


notes:

Having this parameter set to on disables discarding of
non-postscript jobs from 'P'ostscript filtered queues.  Once
your 'ps filter string' values are properly tuned, you should
set this parameter to off so that non-postscript jobs do not
cause postscript printers to hang up or get confused.  You will
not see any discards from postscript queues while this parameter
is set to on, although, you will still get dumps (provided you
have dumps enabled) of non-postscript jobs found in 'P'ostscript
filtered queues to aid in 'ps filter string' tuning.


defaults, min, max:

	default is on, valid values are on and off
	

example:
	
	pass all postscript queue jobs=off

	_____________________________________

	

configurable value:

	enable dumps

	
explanation:

This parameter, when set to on, enables dumping of 'postscript 
dump chars' characters to the file specified by the 'dumpfile' 
parameter in the event that a non-postscript job is found in a 
'P'ostscript filtered queue.  Enable dumps so that the information 
written to 'dumpfile' can be used to aid in the tuning of your 'ps 
filter string' parameter(s) and your 'postscript scan chars' parameter.

				      
notes:

Disable dumps (set enable dumps to off) once your 'ps filter
string' parameter(s) are properly tuned to prevent
non-postscript jobs from being unneccessarily dumped.  Set this
parameter back to on anytime that you have doubts about whether
valid postscript jobs are being incorrectly judged as
non-postscript (so that you can retune your 'ps filter string'
parameters).  See the section later in this file for more
information on dumps.


defaults, min, max:

	default is off, valid values are on and off

	
example:
	
	enable dumps=on

	_____________________________________

	

configurable value:

	discardfile

	
explanation:

This parameter sets the name of the discard file.  The discard
file maintains a log of all jobs that have been discarded from
filtered queues ('P' or 'A' filter specification).  This log
file can be referenced when a user complains that their job
didn't show up at the destination printer (or wasn't serviced
properly in the case of a job queue).  See the section later in
this file which discusses the discard file and the information
which is logged to it.


notes:     

This file continues to grow indefinitely.  Delete it
whenever you choose to, and it will be recreated with the next
discarded job.  


defaults, min, max:

	The default name is "discards.log"

	
example:
	
	discardfile="discard.dat"

	_____________________________________



configurable value:

	dumpfile
	

explanation:

This parameter sets the name of the dump file.  The dump file
maintains a log all non-postscript (recognized) jobs that have
been found in a 'P'ostscript filtered queue.  This file should
be used as an aid in tuning the 'ps filter string' parameter(s)
such that postscript jobs are accurately recognized.  This file
is only written to when the 'enable dumps' parameter is set to
on.


notes:     

This file continues to grow indefinitely.  Delete it whenever you 
choose to, and it will be recreated with the next entry that needs 
to be written.  


defaults, min, max:

	The default name is "dumpjobs.log"

	
example:

	dumpfile="dumpjobs.dat"

	_____________________________________



configurable value:

	delay seconds

	
explanation:

This parameter sets the number of seconds that the NOVQSERV
machine waits between queue poll iterations.  The NOVQSERVer
traverses the list of queues specified in NOVQSERV.TAB and polls
each one to determine if there are existing jobs that require
servicing.  After reaching the end of the list, 'delay seconds'
seconds must elapse before the next queue list traversal.  This
is necessary because if list traversals were done back to back
with no waiting period, a prohibitive amount of network traffic
would be generated.  Set this value low enough so that jobs are
serviced quickly enough to satisfy users, but, high enough so
that the network is not monopolized by the NOVQSERVer.


notes:

See the 'jobs serviced per queue' parameter for more
information on servicing jobs promptly


default, min, max:

	default is 5, minimum is 3, maximum is 60

	
example:

	delay seconds=6

	_____________________________________     



configurable value:

	interqueuewait

	
explanation:

This parameter sets whether or not the NOVQSERV machine waits
between queue polls.  The NOVQSERVer traverses the list of
queues specified in NOVQSERV.TAB and polls each one to determine
if there are existing jobs that require servicing.  After
polling a queue (and servicing jobs if there are any), the
NOVQSERVer then checks the next queue to see if there are jobs
waiting to be serviced.  If this parameter is set to on, the
NOVQSERVer will wait a short period of time (about 50-60
milliseconds) before checking the next queue for jobs.  This
parameter should only be set to on if more than two NOVQSERV
machines are servicing a particular file server in parallel, and
that server's utilization is consistently maxed out (close to
100%).


notes:

This parameter, when set, provides that at least one clock tick 
goes by before the next queue is checked by the NOVQSERVer.  If 
a file server's queues are being serviced by more than two NOVQSERV 
machines, and these NOVQSERV machines are fast, then utilization on 
that file server (if it's already highly utilized) can get higher 
than you might like while queue poll iterations are occurring on 
multiple NOVQSERV machines.  Version 4.x servers are more likely to 
exhibit this high utilization consistently because bindery emulation 
is expensive and if more than 255 users are connected, the file server
hardware is probably already being pushed hard... Setting this
parameter to on causes the NOVQSERVer to take more time between
individual queue checks (not queue list iterations), thus
requiring fewer processing resources on a file server for a
given time period. 


default, min, max:

	default is off, valid values are on and off


example:

	interqueuewait=off  

	_____________________________________ 



configurable value:
	
	discard line


explanation:

This parameter sets the message which is printed on discard
notifications.  When the NOVQSERVer finds a postscript job in a
'A' non-postscript filtered queue, or a non-postscript job in a
'P'ostscript filtered queue, it generates a discard notice and
sends it off to the appropriate destination queue (command/batch
file).  This 'discard line' string is printed, along with other
information, on that discard notice.  Use this parameter to
provide additional information to users who submit jobs that get
discarded.


notes:     

A useful piece of information to put here is who to
contact (users that have jobs discarded will probably be
confused...)


default, min, max:

	the default string is "Questions? - Please contact your LAN
	manager..."
	
	the maximum number of characters is 80


example:

	discard line="Your job was bogus, you've no one to blame
	but yourself"

	_____________________________________


      
configurable value:

	jobs serviced per queue


explanation:

This parameter sets the maximum number of jobs that a queue
will have serviced before the next listed queue is checked.  The
NOVQSERVer traverses the list of queues specified in
NOVQSERV.TAB and polls each one to determine if there are
existing jobs that require servicing.  Up to 'jobs serviced per
queue' jobs are serviced for a particular queue before the
NOVQSERVer moves off to check the next listed queue.  Set this
parameter high enough so that highly utilized queues don't have
jobs waiting for the next queue list iteration before being
serviced.  If there are more than 'jobs serviced per queue' jobs
in a queue when the NOVQSERVer checks it, only 'jobs serviced
per queue' jobs are serviced just then.  The remainder of the
existing jobs (and any additional jobs sent to the queue before
the next check of that queue) must wait until the next queue
list iteration before being serviced.


notes:

See the 'delay seconds' parameter for more information on
servicing jobs promptly.


default, min, max:

	default is 2, minimum is 1, maximum is 50


example:

	jobs serviced per queue=3

	_____________________________________



configurable value:
	
	controlwindowheight


explanation:

This parameter sets the height of the window where the
queue table (list) and statistics are displayed.  


notes:

none...


default, min, max:

	default is 10, minimum is 4, maximum is 18


example:

	controlwindowheight=8

	_____________________________________



configurable value:
	
	controlwindowcolor


explanation:

This parameter sets the color of the window where the queue
table (list) and statistics are displayed.


notes:

Applicable values are as follows:

	BLACK 0, BLUE 1, GREEN 2, CYAN 3, RED 4, MAGENTA 5, BROWN 6,           
	WHITE 7, DARK GRAY 8, LIGHT BLUE 9, LIGHT GREEN 10,           
	LIGHT CYAN 11, LIGHT RED 12, LIGHT MAGENTA 13, YELLOW 14,      
	BRIGHT WHITE 15


default, min, max:
	
	default color is light green (10)


example:
	
	controlwindowcolor=12

	_____________________________________     



configurable value:
	
	promptlinecolor


explanation:
	
This parameter sets the color of the lower prompt lines.


notes:

Applicable values are as follows:        

	BLACK 0, BLUE 1, GREEN 2, CYAN 3, RED 4, MAGENTA 5, BROWN 6,   
	WHITE 7, DARK GRAY 8, LIGHT BLUE 9, LIGHT GREEN 10,         
	LIGHT CYAN 11, LIGHT RED 12, LIGHT MAGENTA 13, YELLOW 14,      
	BRIGHT WHITE 15


default, min, max:
	
	default color is light cyan (11)


example:

	promptlinecolor=11

	_____________________________________     



configurable value:

	password


explanation:     

This parameter must be set to the password of the NOVQSERV user
(the username that the NOVQSERV PC logs in as).  This password
is used by the NOVQSERVer for logging in and/or attaching to
file servers that have queues requiring service. 


notes:     

The username and password of the NOVQSERV user must be
synchronized across all file servers which have queues requiring
service (all file servers listed in column 1 of the NOVQSERV.TAB
file).  This does not mean that the username and password must
be the same.  This means that the username must be the same on
all file servers, and that the password must be the same on all
file servers.


default, min, max:
	
	there is no default value 


example:
	
	password="NOVQPWORD"

	_____________________________________     



configurable value:
	
	spooldir:<fileservername>


explanation:    

This parameter specifies a directory to be utilized for spooling
jobs on a particular file server.  Every file server having
queues that require servicing (all those that appear in column 1
of the NOVQSERV.TAB file), except for the home server (that
which is originally logged into by the NOVQSERV PC), must have
an associated spooldir specification in the NOVQSERV.CFG file. 
When a job is removed from an origination (source) queue, it is
spooled to an intermediate file before being serviced by the
appropriate command (batch) file.  This spooling is done via a
Netware mechanism which provides intra-fileserver copying
service.  This intra-fileserver service is very fast and
efficient because it allows intermediate job file spooling to be
accomplished entirely at the file server.  Because of this, data
is spooled very quickly (the fileserver is usually one of the
fastest machines on the network) and is not required to
traverse, and congest, the network.  


notes:     

The spooldir specification for a particular fileserver reflects
where intermediate jobs will be created when queues residing on
said server are serviced.  Any fileserver which does not have an
associated spooldir line cannot be serviced by the NOVQSERVer
(unless that fileserver is the home server - which does not
require an associated spooldir line).


default, min, max:
	
	only the home file server (the one originally logged into by
	the NOVQSERV machine has a default spooldir - which cannot be
	overridden).  This implicit spooldir is the directory where the
	NOVQSERVer is initiated from (this directory must reside on a
	network drive).  All other file servers on which serviced queues
	reside must have a spooldir specification line.  Up to 7
	spooldir lines may appear.  Only the first spooldir line for
	each server is used - subsequent  lines for that server are
	ignored.  Fileserver name and volume must be specified. 
	Directory specifications are optional.  Be certain that spooldir
	lines do not end with a backslash (leave off the last one), and
	that the directory specified does not carry a NOVQSERV disk
	quota which will preclude the proper creation of intermediate
	files (make sure the NOVQSERV user has enough space in the
	directory to operate).  The directory specification, including
	volume, may be up to 255 characters long.  Every directory
	specified by a spooldir line (as well as the home file server
	directory where the utility resides - this directory is used as
	the implicit spooldir for the home file server) should be
	flagged for immediate purge.  If immediate purge is not
	specified for these directories, then old intermediate job files
	can pile up under certain circumstances and cause problems.

syntax:

	spooldir:<fileservername>=<volume>:[<directory>..<directory>...]
    

example:

	spooldir:NOVSERV=sysvol1:userdata\novqdir          

	spooldir:ACCTNG=usrvol1:novqsrv

 

*************************************************************************



The DUMPJOBS.LOG (or whatever name you've changed it to) file:
--------------------------------------------------------------

	The dump log file contains only (pieces of) jobs which were
dumped from postscript queues because they could not be
identified as postscript (via scanning for 'ps filter string'
values).  Every time a non-postscript job is found in a
'P'ostscript filtered queue, and dumps are enabled, an entry is
written to the dump log file.  Remember that 'dumped' is used
above to mean 'flagged non-postscript' - jobs which cause an
entry to be logged to the dump log file may still be passed
through to the appropriate command(batch) file (if the 'pass all
postscript queue jobs' parameter is set to on).  Use the
information found in this file to aid in tuning your 'ps filter
string' parameter(s).  Delete this file periodically, as it
continues to grow indefinitely.


 Each entry found within the dump log file contains:

      - A date/time stamp indicating when the job was dumped 
      (recognized as non-postscript), the name of the queue that 
      the job was dumped from, the name of the file server where 
      the queue lives, and the name of the user that submitted the job.

      - Along with the above information, a number of characters
      (specified via the 'postscript dump chars' parameter) contained 
      within the job is shown. 


 The characters found within the job are surrounded 
 with these two delimeters:

		******->    <-******



 Look through the entries in this file to determine the best 
 postscript commands to use for 'ps filter string' parameters 
 so that postscript jobs can be accurately determined at your site.

 

The DISCARDS.LOG (or whatever name you've changed it to) file:
-------------------------------------------------------------- 

	The discard log file contains a record of all discarded jobs,
whether they were non-postscript jobs found in a 'P'ostscript
filtered queue, or postscript jobs found in an 'A'non-postscript
filtered queue.  The format of the discard log file is obvious. 
The entries  in this file give you information on what users are
sending inapproriately formatted jobs to which queues.

Delete this file periodically, as it will continue to grow
forever.



The NOVQSERV.LOG file:
----------------------
	
	This file contains important NOVQSERV generated messages.  
If you have difficulty running NOVQSERV or resolving a particular
problem, check this file for any status information which might
help shed light on what is happening.  This file is recreated
every time that the  NOVQSERV utility is initiated, thus you do
not need to delete it.  Remember to make a backup copy of this
file if you wish to retain it when restarting the NOVQSERVer -
the existing NOVQSERV.LOG file will be overwritten when the
utility is restarted.



General information:  
--------------------

	All directories used for the creation of intermediate spool
files (including the implicit spool directory used for the home
file server, the default directory where the NOVQSERV utility
lives) should be flagged for immediate purge.  If these
directories (specified via the SPOOLDIR parameter in the
NOVQSERV.CFG file) are not flagged for immediate purge, then old
(deleted) intermediate spool files could pile up and and cause
problems.


	Make sure that the NOVQSERV user has enough disk space
available such that the largest possible job (postscript jobs
can obviously get very large) can be spooled to an intermediate
file without overstepping its disk quota.  Remember that log
files are written as well (some of which must be manually
deleted, lest they grow too big), so be generous with the
NOVQSERV user's disk quota if you must enable disk quotas for
this user.  



	NOVQSERV machines can be configured redundantly so as to 
provide for backup in the event of machine failure, and so as to 
provide for faster job servicing.  Just use the same NOVQSERV.TAB
configuration file for both (or more) NOVQSERV machines and they
will service the queues specified with the speed of dual processors...  

	
	Redundant NOVQSERV machines must each have their own username
and operating directory.  Two NOVQSERVers CANNOT be run from the
same directory.  Copy the NOVQSERV.TAB file and the NOVQSERV.CFG
file (you'll need to change the password value to the proper one
for the new NOVQSERV user) to the redundant NOVQSERVER's
operating directory, and they will be both service the specified
queues in exactly the same manner (but faster in the
aggregrate). 




Using NOVQSERV with 4.x:
------------------------

	The NOVQSERV utility will service 4.x queues without a 
problem as long as these queues exist within a context which has 
bindery emulation enabled.  Queues which exist outside a bindery
emulated context cannot be serviced by NOVQSERV.  In the event
that you wish to run the NOVQSERV utility from a 4.x server
(using a 4.x server as the home file server), then Bindery
emulation must also be enabled for the context used by the
NOVQSERV user.  


*NOVQSERV may pass an inaccurate username (parameter %4) to a
destination command (batch) file when servicing a job originated
by a user using a connection slot higher than 255.


________________________________________________________________
DISCLAIMER OF RESPONSIBILITY: 
While significant effort has been undertaken to make certain that 
this documentation is accurate and that the NOVQSERV utility operates
correctly, no responsibility for its operation is assumed by the
author or distributor.   No liability for damages arising from
or in conjunction with its usage is implied or assumed by the
author or distributor. 

