C PQM - Printer Queue Manager for Users and Operators - Documentation C ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~   L PQM is written and maintained by Jeremy Begg, VSM Software Services Pty Ltd.E Copyright  2000-2013 VSM Software Development.  All rights reserved.   H This software maybe freely used, distributed and modified subject to the following conditions:   N     - No responsibilty is accepted by anyone associated with this software forN       any adverse effects it may have on any system.  Use it at your own risk.  O     - Ownership of the software and derivative works remain with the author and        the copyright holders.  E     - This file, including the copyright notice, is included with all        distributions.  @     - The copyright notice must be displayed when PQM starts up.  O Please direct all bug reports or requests for enhancements to <pqm@vsm.com.au>. D If you modify the code and think that others would benefit from yourG modification, feel free to submit the modifications to that address for % inclusion in a future release of PQM.   ) Documentation for PQM V2.0-00	27-Aug-2013 + ===========================================    1.  Installing PQM ------------------N PQM is supplied as a ZIP archive containing source files, object libraries andL executable images for all three OpenVMS platforms.  The supplied executablesI will run on OpenVMS VAX V7.3, OpenVMS Alpha V7.3-2 and OpenVMS IA64 V8.4. < They might run on earlier versions but have not been tested.  L Begin by using the Info-ZIP UNZIP utilty to unpack the archive to a suitableH location on your system.  (If you use FTP to transfer the ZIP archive to= your OpenVMS system, make sure you use BINARY mode to do so.)   J The result should be a directory structure containing the following files:   Directory dev:[dir.PQM020]   ALPHA.DIR;1  DOCUMENTATION.TXT;1 
 IA64.DIR;1 PQM_HELPLIB.HLB;1  PQM_STARTUP.TEMPLATE;1 RELEASE_NOTES.TXT;1 	 SRC.DIR;1 	 VAX.DIR;1    Total of 8 files.     Directory dev:[dir.PQM020.ALPHA]  	 PQM.EXE;1 	 PQM.MAP;1 	 PQM.OLB;1    Total of 3 files.    Directory dev:[dir.PQM020.IA64]   	 PQM.EXE;1 	 PQM.MAP;1 	 PQM.OLB;1    Total of 3 files.    Directory dev:[dir.PQM020.SRC]   BROWSER.PAS;14 BUILD.COM;1  DESCRIP.MMS;13 GLOBALDEF.PAS;69 JOBS.PAS;132	 PQM.OPT;9 
 PQM.PAS;96 PQM_COMMAND.HLP;5  PQM_FOREIGN.CLD;4  PQM_MENUS.HLP;1  PQM_VERSION.TXT;18 QUEUES.PAS;207 VERSION.OPT;24   Total of 12 files.   Directory dev:[dir.PQM020.VAX]  	 PQM.EXE;1 	 PQM.MAP;1 	 PQM.OLB;1    Total of 3 files.   ' Grand total of 5 directories, 29 files.   N You may choose to leave PQM in the directory created by UNZIPPing the archive,L or you may copy selected files to suitable site-specific directories on your system.   F  * The PQM.EXE file for your system's architecture should be copied to8    suitable site-specific location with W:RE protection.  G  * The PQM_HELPLIB.HLB file should be copied to a suitable directory on #    your system with W:R protection.   = Those are the only two files which users MUST have access to.   J If you wish to recompile or relink PQM using the supplied source files andK object libraries, you can run the BUILD.COM procedure to do so.  By default - BUILD.COM will simply relink PQM.  If you run    	$ @BUILD.COM COMPILE   H the procedure will rebuild PQM from the supplied source files.  A Pascal compiler will be required.  K Installing PQM with privileges is entirely optional and will depend on your  site-specific requirements:   L     - OPER privilege will be required if you wish to allow PQM to manipulateC       all jobs and all queues regardless of ownership and job/queue H       protection.  Alternatively, use ACLs to provide finer control over        access to queues and jobs.  I     - ALTPRI privilege will be required if you wish to allow PQM to raise J       job priorities above the SYSGEN paramenter MAXQUEPRI (normally 100).  D In the top-level PQM directory is a command procedure template file,D PQM_STARTUP.TEMPLATE.  You may like to edit this file and save it asB PQM_STARTUP.COM.  It can be invoked as part of your OpenVMS system startup procedure.       2.  Running PQM  --------------- J PQM is intended to be run using a DCL foreign command.  To enable this forC all users, add the following to your system-wide SYLOGIN procedure:    	$ PQM == "$dev:[dir]PQM.EXE"   ; where 'dev:[dir]' is the directory were you placed PQM.EXE.   : The PQM command accepts the following optional qualifiers:   	/BROWSER="DCL-command"   > 		Specify a DCL command to invoke a program which will be used: 		to display the contents of files in printer queues.  The7 		command should accept a single parameter, the file to 
 		display.  = 		If not specified, PQM will attempt to translate the logical + 		name PQM_BROWSER to find the DCL command.    	/INITIAL_SCREEN=QUEUE=queue  : 		Begin with the Queue display, highlighting the specified 		queue.  4 		If /INITIAL_SCREEN is not specified, PQM begins by7 		displaying on the Queues display with the first queue  		highlighted.   	/INITIAL_SCREEN=JOBS=queue   8 		Being by displaying the Jobs display for the specified 		queue.  4 		If /INITIAL_SCREEN is not specified, PQM begins by7 		displaying on the Queues display with the first queue  		highlighted.   	/NOSERVER_SYMBIONTS  = 		Do not display server symbiont queues, i.e. symbiont queues 7 		which process files without sending them to an output 	 		device.   
 	/UPDATE=n  4 		Automatically update the screen every 'n' seconds.8 		If this qualifier is not specified, the screen will be 		updated every 15 seconds.   
 	/NOUPDATE  ) 		Do not automatically update the screen.    3. Queue Display ----------------H The Queue Display lists the print queues on the system.  The top part ofL the screen shows detailed information about the currently highlighted queue.  G The following table shows the actions which are available in the Queues  display.  D      Prev Screen	Select the queue which appears approximately 2/3 of)      or letter "P"	the way up the screen.   D      Next Screen	Select the queue which appears approximately 2/3 of+      or letter "N"	the way down the screen.   C      Up Arrow		Select the queue which appears immediately above the      			current queue.   E      Down Arrow		Select the queue which appears immediately above the      			current queue.   ?      Do or PF4		Display a menu of operations appropriate to the @      or letter "M"	current queue.  (See below for menu details.)  8      Return/Enter	Display the jobs in the current queue.  A      Space bar		Update the display.  (This is useful if /NOUPDATE :     			was specified when starting PQM, or if an update is     			required now.)   A      Letter "F"		Display the file currently being printed by each      			queue (if any).  @      Letter "J"		Display the job currently being printed by each     			queue (if any).        Letter "Q"		Quit PQM.  *      Question Mark	Display on-screen Help.        Ctrl/W		Redraw the screen.         Ctrl/Z		Quit PQM.  H Pressing the "M", <Do> or <PF4> key displays a menu of actions which areG appropriate to the currently highlighted queue.  These actions include:   =      Set Formtype	Change the queue's formtype.  By default it - 			will be set to match that of the first job + 			in the queue, so that the job will start  			printing.  <      Pause Queue	Suspends output to the printer, but the job 			stays on the queue.  9      Stop Queue		Lets the job which is currently printing / 			(if any) finish, but prevents any other jobs      			from starting.   9      Reset Queue	Causes the queue to stop immediately; no * 			more jobs will be printed.  This is the. 			same as "Stop Queue" but aborts the current/ 			job mid-stream and causes that job to remain  			in the queue.  2      Start Queue	Starts a Paused or Stopped queue.  4      Display Jobs	PQM displays the jobs in the queue 			(see "Jobs Display", below).   5      Abort Job		Kill the currently executing job, and . 			remove it from the queue.  This menu option* 			will not be shown if the queue is idle.  A      Cleanup Queue	Delete jobs whose input files no longer exist. 1 			Note: this option is subject to authorisation.   /      Empty Queue	Delete all jobs in this queue. 1 			Note: this option is subject to authorisation.   :      SHOW QUEUE/FULL	Runs the DCL command SHOW QUEUE/FULL.  =      Exit this menu	Exits the menu without changing anything.   L Within the above menu you can use the Up and Down arrow keys to move around.K Pressing PF1-Up will jump to the top of the menu; PF1-Down will jump to the I bottom of the menu.  Pressing Up or Down at the top or bottom of the menu G (respecively) will take you to the bottom or top of the menu.  Pressing I Ctrl/Z exits the menu without doing anything.  Pressing Help will display F help text from the PQM_HELPLIB library; press <Return> at the "Topic?" prompt to return to PQM.     4. Jobs Display  --------------- L This shows the jobs in the selected queue.  The top part of the screen shows9 detailed information about the currently highlighted job.   N The list of jobs is presented in the order that the VMS queue manager suppliesM them to PQM, with the exception that jobs which are retained in the queue are M listed in reverse order of completion: those jobs which printed most recently M are listed first.  In effect this means that jobs are listed in the following  order:  2 	1.  The job which is currently printing (if any).> 	2.  Jobs which are waiting their turn to print, i.e. Pending.? 	3.  Jobs which are waiting until a particular time before they  	    start printing.F 	4.  Jobs which are Holding (and therefore must be manually released).= 	5.  Jobs which have recently completed printing (or failed). = 	6.  Jobs which completed printing (or failed) less recently.   L For groups 2-4, within each group, the order of jobs is usually the order inJ which they were submitted for printing.  However, VMS allows a priority toN be assigned to a job thus altering its position in the queue.  Also, dependingL on the printer queue definition, jobs might be ordered in reverse size order+ -- large jobs are printed after small jobs.   G The following table shows the actions which are available in the Queues  display.  B      Prev Screen	Select the job which appears approximately 2/3 of)      or letter "P"	the way up the screen.   B      Next Screen	Select the job which appears approximately 2/3 of+      or letter "N"	the way down the screen.   A      Up Arrow		Select the job which appears immediately above the      			current job.   C      Down Arrow		Select the job which appears immediately above the      			current job.   ?      Do or PF4		Display a menu of operations appropriate to the >      or letter "M"	current job.  (See below for menu details.)  C      Return/Enter	Update the display.  (This is useful if /NOUPDATE E      or Space Bar	was specified when starting PQM, or if an update is      			required now.)   .      Letter "Q"		Return to the Queues display.  *      Question Mark	Display on-screen Help.        Ctrl/W		Redraw the screen.         Ctrl/Z		Quit PQM.  L The "M", <Do> and <PF4> keys display a menu of actions which are appropriate to the highlighted job:   F      Display File	Uses the command specified by the /BROWSER qualifier6 			or the PQM_BROWSER logical name to display the file7 			currently being printed or the first file in the job * 			(if the job is not currently printing).  4      Pause		Pauses the queue; suspends output to the& 			printer until the queue is started.  :      Stop & Retain	Aborts execution of the current job but+ 			retains that job in the queue so that it / 			can be reprinted.  The queue is not stopped; / 			it will begin to print the next job if there 
 			is one.  =      Abort Job		Aborts (kills) the current job and removes it  			from the queue.  <      Release Job	Changes a Holding job so that it will print- 			immediately (or as soon as the printer can . 			print it) or reprints a Completed or Failed 			job.   ?      Hold Job		Force the job into the Holding state, so that it 7 			must be manually released before it will be printed.   =      Move to Queue	Allows you to move a job to another queue.   7      Raise Job Priority	Increase the job priority by 5.   7      Lower Job Priority	Decrease the job priority by 5.   0      Delete Job		Removes the job from the queue.  C      Set Job Formtype	Changes the form type of the job.  By default - 			it will change the job's form to match the  			queue's.   ?      Set Queue Formtype	Changes the form type of the queue.  By / 			default it will be set to match the selected  			job.   =      Stop Queue		Stops the queue, i.e. waits for the queue to . 			finish the current job (if any) and doesn't# 			start the next job in the queue.   ;      Reset Queue	Immediately stops the queue; the currently - 			printing job is aborted but remains on the $ 			queue.  No more jobs are started.  <      SHOW ENTRY/FULL	Runs the DCL command SHOW ENTRY/FULL to0 			display as much information as possible about 			the job.   !      Exit this menu	Does nothing.   I Within the menu the arrows and other keys behave as they do for the Queue 
 action menus.     @ 5. Authorisation for the Cleanup Queue and Empty Queue functions@ ----------------------------------------------------------------J Starting with PQM V2.0, there is an authorisation mechanism for the use ofK some PQM functions.  This mechanism uses a combination of logical names and I VMS rights identifiers to determine if the user is allowed to perform the G function.  These checks are performed when PQM starts up, not each time  the function is accessed.    The mechahism is as follows:  D Step 1 - translate the system-wide logical name PQM_function_IDENTS,C          converting the value to uppercase and removing leading and           trailing whitespace. F Step 2 - if the logical name does not exist, the function is disabled.G Step 3 - if the logical name translates to "*", the function is enabled  	 for all users.G Step 4 - look for the VMS rights identifier named by the logical name's  	 translation.B Step 5 - if there is no such identifier, the function is disabled.B Step 5 - the user is allowed to access the function if the process  	 currently holds the identifer.  / Enabling Access to the "Cleanup Queue" function / -----------------------------------------------  To enable access for all users:   - 	$ DEFINE/SYSTEM PMDF_QUEUE_CLEANUP_IDENT "*"   K To enable access for selected users, create a VMS rights identifier (or use F an existing one) and grant the identifier to the required users.  Then  3 	$ DEFINE/SYSTEM PQM_QUEUE_CLEANUP_IDENT identifier   M The logical name definitions should be added to your system startup procedure  (e.g. in PQM_STARTUP.COM).  - Enabling Access to the "Empty Queue" function - ---------------------------------------------  To enable access for all users:   + 	$ DEFINE/SYSTEM PMDF_QUEUE_EMPTY_IDENT "*"   K To enable access for selected users, create a VMS rights identifier (or use F an existing one) and grant the identifier to the required users.  Then  1 	$ DEFINE/SYSTEM PQM_QUEUE_EMPTY_IDENT identifier   M The logical name definitions should be added to your system startup procedure  (e.g. in PQM_STARTUP.COM).    
 6. Known Bugs 
 ------------- I There are a couple of bugs or behavioural "features" which I have not yet  been able to fix.   J   - if the Help screen is pressed in an action menu and PQM_HELPLIB is notH     defined or not readable by the user's process, the screen displays a3     traceback stack dump; press Ctrl/W to remove it   I   - the completion time and/or failure reason for a job is not displauyed 6     (use SHOW ENTRY/FULL to display this information).