+                                    EXECSYMB   *                                     V3.6.1  ,                                  John Osudar  5                          Chemical Technology Division 4                          Argonne National Laboratory+                                   205 L-213 2                             9700 South Cass Avenue2                             Argonne, IL 60439-4837  1                             Phone: (708) 252-7505 0                              FAX: (708) 252-5912  4                           Electronic mail addresses:5                         Internet:  OSUDAR@CMT.ANL.GOV 0                               DECUServe:  OSUDAR  )                                      NOTE )                                      ====   ? 	If you would like to receive notification of future bug fixes  = 	and enhancements to EXECSYMB, please send your name, mailing @ 	and/or electronic address, and phone number to me at the above 3 	location.  No guarantees or promises, of course...   J    +---------------------------------------------------------------------+J    | See bottom of document for "release notes" for the latest versions! |J    + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +J    | See the file SAMPLEPROC.COM for examples and further documentation. |J    +---------------------------------------------------------------------+   				 Introduction  				 ------------   G EXECSYMB is a VMS server symbiont that feeds queue entry information to N detached processes that are designed to execute specific operations (hence theH name, Executive Symbiont).  It is multi-threaded (it can handle up to 32N queues at the same time); it requires one detached process and one mailbox forJ each queue, plus one mailbox for status information and one for detecting G process exit status for each copy of EXECSYMB (i.e. one per 32 queues).   D EXECSYMB can be used to implement a wide variety of VMS queue-based 0 operations.  Among its present applications are:  G 	(1)  Remote queuing of print jobs (and limited remote queuing of batch  		jobs) C 	(2)  Pre-processing and post-processing of jobs destined for other = 		server symbionts (e.g. performing MFENET gateway operations 3 		on files queued to MFENET inbound-file symbionts) 8 	(3)  Queued file transfer for DECnet and other networks  G This program was written with one major goal in mind:  to simplify the  I system's interface to a user-written queue processor, eliminating (or at  K least hiding) the quirks that are present in the job controller-to-symbiont  interface supplied by Digital.    L Under VMS V4 and later, symbionts operate in a rather strange environment.  N A symbiont is a detached process (unlike VMS V3, where it was a subprocess of H the job controller).  However, it lacks several useful things that most J processes have:  symbionts have no CLI, which means that they can't spawn N commands; symbionts are always created with username SYSTEM and one privilege M (SETPRV); and symbionts cannot access process-permanent logicals (SYS$INPUT,  L SYS$OUTPUT, SYS$ERROR) the way other processes can.  A symbiont's SYS$INPUT M points to a mailbox to which the job controller writes its request messages,  M and SYS$OUTPUT points to another mailbox from which the job controller reads  K status messages from the symbiont.  (Incidentally, the latter has been the  O job controller's "achilles heel"; if your symbiont accidentally writes a bunch  I of stuff to SYS$OUTPUT, the job controller will respond with a series of  L console error messages about "invalid mailbox message received".  Under someM versions of VMS, this is immediately followed by a fatal "end-of-file on job  O controller mailbox" that aborts the queue manager, stopping ALL queues on your  O system and leaving active batch jobs in VMS limbo.  VMS V4.4 and beyond allows  N the queue manager to restart after such an abort, but this usually leads to a N recurrence of the problem, and a hard abort on the part of the queue manager.)  J EXECSYMB was designed to make the symbiont environment easier to use.  Of I course, EXECSYMB itself has to deal with the restrictions listed above.   J However, a queue handled by EXECSYMB is processed by an EXECSYMB detached G process, which is created with the DCL CLI, a real command procedure as K SYS$INPUT, a log file as SYS$OUTPUT, and a pair of mailboxes for talking to M EXECSYMB. The protocol for passing information between the executive symbiont M and the detached process involves transferring "items", which EXECSYMB parses I from the job controller's request message, through a mailbox.  One of the M "items" is created by EXECSYMB itself -- it's called "EXEC_STEP", which is an J "execute trigger", telling the detached process that a string of items hasL been completely transferred and an operation (execute, reset, exit) is to beN performed.  The detached process returns a completion status through the otherH mailbox, which provides EXECSYMB with a task status to return to the jobF controller.  As a result, it is relatively easy to write a DCL commandK procedure to process a queue.  There are just a few requirements for such a L procedure, which are outlined below, in the section "sample queue processing procedure".    			     Features of EXECSYMB 			     --------------------H In addition to providing a safer and less hostile environment for queue J processing, EXECSYMB adds some features that aren't available to ordinary 1 user-written symbionts without additional coding.   B (1)	EXECSYMB is multi-threaded, so that it can handle a number of B 	different queues at the same time.  The code required to do this G 	correctly is rather complex, so concentrating it in EXECSYMB is quite   	practical.   G (2)	EXECSYMB handles the AST-level delivery of job controller messages  ) 	for things like stop and pause requests.   B (3)	EXECSYMB eliminates the need for calling the symbiont support E 	routines to parse, copy, and re-copy the request message components  F 	(request items), as is done in most user-written symbionts.  EXECSYMBH 	parses the request message itself, and keeps pointers to the individualE 	items; only those items required by a particular queue are actually   	passed to the queue processor.   I (4)	EXECSYMB provides a requeue-on-error capability that can be selected  E 	on a per-queue basis.  If a queue specifies a retry interval, and a  @ 	task is aborted with an error status, the job is automatically A 	requeued to try again after the specified interval.  It is also  F 	possible to specify whether the job is to be restarted from the task F 	that aborted, or from the beginning.  (Note that, if this feature is B 	selected for a particular queue, the queue processor must do someF 	reasonable error detection and recovery, returning an "error" status < 	to EXECSYMB only if it really wants the job to be retried.)  F (5)	EXECSYMB allows a queue processor to handle all copies, the first B 	copy only, or the last copy only, for jobs that specify multiple D 	job copies or file copies.  (This is especially important when the F 	queue processor is transferring one copy of the file, and forwarding 8 	the number-of-copies parameter for handling elsewhere.)  H (6)	EXECSYMB allows the queue processor to be started dynamically, when H 	the queue actually has work available.  This option is selectable on a D 	per-queue basis, by specifying a "timeout" interval.  If the queue F 	processor detached process exists but is idle, and no work is queued C 	within the timeout period, EXECSYMB will tell the process to exit  E 	(while keeping the queue in the active state, as far as the VMS job  ( 	controller/queue manager is concerned.)   			       Running EXECSYMB 			       ----------------  I Here's what you need to know to run EXECSYMB.  (Remember that a symbiont  ! image must reside in SYS$SYSTEM.)   K The EXECSYMB process will change its name to "ExecSymb3.0.1_n" where  n  is H a sequence number that starts at 1.  Since each process handles up to 32L queues, you shouldn't see sequence numbers above 1 unless you have more thanL 32 queues processed by EXECSYMB at the same time.  EXECSYMB starts with its N base priority set from the /BASE_PRIORITY=n qualifier on the first queue that K it starts; however, soon after starting it will set its base priority to 7. H This is done so that EXECSYMB's priority will be above that of the queueG processors (which are created with a base priority of DEFPRI, which is  K usually 4) and below that of the job controller (whose base priority is 8.) L EXECSYMB sends important messages, such as startup and shutdown of the main J process, to the OPER12 operator.  Other information is written to the log M file, which is named SYS_EXECSYMB:EXECSYMBn.LOG (where "n" is as described in N the process name above).  If SYS_EXECSYMB is not defined in the system logicalI name table, log files are placed in SYS$MANAGER:.  (The "queue processor" N detached processes also place their SYS$OUTPUT and SYS$ERROR log files there. M As of V3.2.6, it is possible to redirect a particular queue's .OUT/.ERR files M by defining a system logical name, EXECSYMB_OUTDIR_queuename, pointing to the K destination directory.)  EXECSYMB remains active as long as it has at least N one active queue to process; upon stopping the last queue (and waiting for itsI queue processing detached process, if any, to exit), EXECSYMB will exit.    N EXECSYMB can send items to the detached process in ASCII or binary form.  The M ASCII form uses two writes per item, one to send the item name, the other to  K send its value.  The binary form does one write per item, and includes the  I item's binary code number as the first four bytes of the record.  In the  L ASCII form, many item values are converted from their raw form to an edited L ASCII form; e.g. the UIC item will be converted from four binary bytes to a M string of the form [gggggg,mmmmmm].  The binary form does no editing on item  M values.  In addition, EXECSYMB can be told to skip sending items that have a  ; null string as a value.  This can save a lot of processing.   I EXECSYMB terminates the list of items for a particular task with an item  L that it makes up itself.  This item has the name "EXEC_STEP", binary code 0,I and can have one of three ASCII values:  "EXECUTE", which means that the  L task's item list has been completely transferred, and the task is ready for I execution; "RESET", which means that a partial item list was sent, which  J should be discarded, and the detached process should return to its initialJ state; and "EXIT", which means that the detached process should exit.  TheM "EXECUTE" command expects the detached process to return a completion status, ) and then perform a "RESET" automatically.   H EXECSYMB can also send the queue processor another item that it makes upM itself.  This item, named "EXEC_FLAGS", binary code -1, is a character string I containing a list of "task flags", indicating specific characteristics of I the current task which are not directly available otherwise.  This string J consists of a leading slash ("/"), a list of (zero or more) uppercase-onlyH keywords separated by slashes, and a trailing slash.  Thus, to determineJ if a specific keyword is present in the item value, you can search for theJ keyword surrounded by slashes.  At the present time, the only keyword thatK can be passed in this item is "SPOOL", which means that the file associated K with this task is a spool file (i.e. a file created by writing to a spooled  device).  J You can tell EXECSYMB how to process a queue through two queue qualifiers:J the command procedure that is to be used is specified through the /LIBRARYJ qualifier, and the list of processing options is specified as a character F string in the /SEPARATE=RESET qualifier (which corresponds to the itemJ JOB_RESET_MODULES).  Since device control libraries and job reset modules K aren't too meaningful in the context of server symbionts, use of these two    qualifiers works out quite well.  G The /LIBRARY qualifier takes a filename as its value.  Although device  M control libraries are required to reside in SYS$SHARE and have the extension  L .TLB, the /LIBRARY qualifier does not place these restrictions on the value L you specify.  (In fact, the job controller sticks a SYS$SHARE: on the front M of this value, and a .TLB on the end, but EXECSYMB strips those off!)  Thus,  K  /LIBRARY=SYS_PROCS:EXAMINEQUEUE.COM  is a valid specification.  Note that  O this field is restricted to a total of 39 characters (since the job controller  4 thinks this is the filename part of a library name.)  I The /SEPARATE=RESET qualifier takes an arbitrary character string as its  F value.  EXECSYMB requires this string to be a comma-separated list of   options from the following list:  = 	TIME="d hh:mm:ss.cc"	This specifies how long to wait before  . 				retrying aborted jobs.  If not specified, ! 				aborted jobs are not retried.   C 	DYN="d hh:mm:ss.cc"	This specifies the timeout period for a queue  / 				with a dynamically-started queue processor. - 				If not specified, the queue processor is  - 				always active while the queue is started.   = 	ITEMS="itemlist"	This specifies the list of item codes to be - 				passed to the queue processor.  Codes are , 				represented as decimal numbers, and the 4 				syntax  mm:nn  can be used for a range of codes.  > 	SPOOL=[spooldir]	This specifies a directory into which spool 0 				files can be entered, if it is possible for 0 				the queue to include spool files (i.e. files- 				created from output to a spooled device.) 1 				Such a directory MUST exist on all disks that . 				are used as secondary devices for spooled  				devices.  = 	ASCII or BINary		This specifies the format for passing item  # 				values to the detached process.   > 	PRINTer or SERVER	This specifies the queue type, and is only , 				used to set the indicator for SHOW QUEUE1 				(printer queues print, server queues process)   > 	NONULl or NULL		This specifies whether items whose values are. 				the null string are passed to the detached 				process   7 	CHECK or NOCHECK	This specifies whether the queue can  3 				checkpoint jobs, i.e. whether a job consisting  1 				of several tasks in which one task aborts is  1 				restarted from the point of abort (CHECK) or  + 				from the beginning of the job (NOCHECK)   < 	COPY={	ALL,		This specifies which copy of a multi-copy job,7 		First,		and which copy of a multi-copy file in a job, < 	     or Last}		is to be processed by the detached process. 2 				ALL gets every copy, FIRST gets the first file1 				copy in the first job copy, and LAST gets the 4 				last file copy in the last job copy.  (Note that0 				certain flags in the SEPARATION_CONTROL item0 				may be set only on the FIRST or LAST copy.)   ; 	USER=username		If specified, this sets the username under  / 				which the queue processor detached process  2 				will run.  (The default is SYSTEM.)  This can 0 				be useful for accounting, or for processors / 				that use proxies into other DECnet nodes.   3 				Note that the specified username need NOT be a  0 				valid one on the system (i.e. there doesn't + 				have to be an entry in SYSUAF for that   				username)!  . 	FLAG			If specified, indicates that the queue0 				processor wants the "EXEC_FLAGS" pseudo-item. 				to be passed prior to the "EXEC_STEP" item 				for each task.  6 	INIT			If specified, indicates that the dynamic queue0 				processor should be started at queue startup- 				(so that it can do some initializations).   7 Defaults, if a particular option is not specified, are:   N no requeue, non-dynamic queue processor, no ITEMS, no SPOOL directory, ASCII, < SERVER, NULL, CHECK, COPY=ALL, USER=SYSTEM, no FLAG, no INIT  K A little more needs to be said about spool file handling.  EXECSYMB can be  K used to process queues from spooled devices (such as spooled null printers, G used for remote printer support).  When output is written to a spooled  M device, a spool file is created on the device's secondary device (disk), and  L queued to the device's queue.  This file is identified only by file ID, and J has no directory entry.  In some applications (e.g. where the file will beJ copied to another node with a network copy program), the file must have a L full filename to be effective.  EXECSYMB will detect spool files for queues J that specify the SPOOL=directory option, and will enter such files in the J specified directory on their device.  Once such a file has been processed K (and is about to be deleted automatically by the job controller), EXECSYMB   removes the directory entry.  ) 		      Sample queue processing procedure ) 		      ---------------------------------   K The following is a sample queue processing procedure that can be used with  M EXECSYMB.  It is reproduced here to illustrate the required features of such  N a procedure; it can also be found, without comments, in this directory in the G file  EXAMINEQUEUE.COM  (which can be used as-is with EXECSYMB.)  This  M procedure does nothing "useful"; it produces a log file containing the items  M passed for each request it processes, and it indicates successful completion  
 of each task.   I First, you can specify any setup commands you require.  SET NOVERIFY and   SET NOON are recommended.    		$ SET NOON 		$ SET NOVERIFY  F Next, the procedure must locate the mailboxes that it uses to talk to J EXECSYMB.  The input mailbox (written by EXECSYMB, read by the procedure) H has a logical name of  CMD_MBX_pid  where "pid" is the process ID of theM detached process running this procedure.  The output mailbox (written by the  L procedure, read by EXECSYMB) is used for returning status, and has the name O STAT_W_MBX_pid (where "pid", again, is the process ID).  We can also determine  H the name of the queue we are processing by translating the logical name N QUEUE_NAME_pid.  Thus, the procedure must determine its own PID, and then use  it to access this information.   		$ PID=F$GETJPI("","PID")+ 		$ QUEUENAME=F$TRNLNM("QUEUE_NAME_''PID'")   L Before we do any real work, we must open the input and output mailboxes for O talking with EXECSYMB.  (If we decide to reinitialize after detecting a mailbox 2 I/O error, we may want to come back here as well.)   		$INIT:/ 		$ OPEN/WRITE/ERR=NOMBX STAT STAT_W_MBX_'PID': , 		$ OPEN/READ/ERR=NOMBX INPUT CMD_MBX_'PID':  J The items sent by EXECSYMB all have names that can be used as DCL symbols.H That is the technique used here.  (EXECSYMB has an alternate format for I items, in which a fixed-length binary item code precedes the item value;  E that format is intended for use by compiled programs that run in the  J detached process.)  The item "EXEC_STEP" is used by EXECSYMB to guide the O operation of the detached process; EXECSYMB can assign it the values "EXECUTE",  "RESET", and "EXIT".  I Initially, or after an "EXECUTE" operation is complete, or when EXECSYMB  H explicitly requests a "RESET" (such as when a job is deleted while beingO processed), the procedure should reset controlling variables to initial values, L and return to its input processing loop.  This procedure has one controllingN variable, EXEC_STEP.  Here, we initialize the symbol to the value "INPUT", andJ subsequently use the symbol as the destination label of a GOTO.  This is aL rather simple, yet effective, way of implementing the control operation. (WeM also write out a separator line to the log file, to mark the boundary between 
 requests.)  	 		$RESET: ? 		$ WRITE SYS$OUTPUT "========================================"  		$ EXEC_STEP="INPUT"   M Now comes the good part of the procedure.  It starts with the label that was  J initially assigned to EXEC_STEP.  The first command reads the NAME of the K symbol (i.e. the item name) being passed, and the second command reads its  L VALUE.  Thus, EXECSYMB can tell the process which item is being passed, and @ its value, and a symbol of that name with that value is created.  	 		$INPUT:   		$ READ/ERR=ERRMBX INPUT SYMBOL! 		$ READ/ERR=ERRMBX INPUT 'SYMBOL   L For demonstration purposes, we echo the information to SYS$OUTPUT, which is 
 the log file.    		$ WRITE SYS$OUTPUT SYMBOL  		$ WRITE SYS$OUTPUT 'SYMBOL  K Having completed the value assignment, we go to the location pointed to by  H EXEC_STEP.  This was initially INPUT, and will remain so until EXECSYMB J sends the item EXEC_STEP and a new value (EXECUTE, RESET, or EXIT) for it.   		$ GOTO 'EXEC_STEP   K When EXECSYMB says "EXECUTE", it indicates that the item sequence for this  M task is complete, and should be acted upon.  A real symbiont processor would  J do something with the item list at this point (e.g. do something with the M file specified in item FILE_SPECIFICATION).  Once the operation is complete,  H EXECSYMB expects a status to be returned via the mailbox.  This example L always returns a success status.  After it reports completion, the procedureJ loops to the "RESET" label to reset controlling variables and re-enter the input loop.    		$EXECUTE:  		$ WRITE STAT "%X00000001"  		$ GOTO RESET  K If an "EXIT" operation is requested, EXECSYMB wants the detached process to L exit.  One way to do this is to log off; you can also do an EXIT or whateverK else you desire (including, for example, sending operator notification that ! the detached process is exiting.)    		$EXIT:
 		$ LOGOUT  M Finally, we add some error handling for the cases where we failed to open one N of the required mailboxes, or got an I/O error on a mailbox.  If we can't openO a mailbox, we cannot continue, so we exit (logoff).  If we got an I/O error, we O can close and attempt to reopen the mailbox, in which case we'll either succeed + or the open-failure code will terminate us.   	 		$NOMBX: 
 		$ LOGOUT
 		$ERRMBX: 		$ CLOSE STAT 		$ CLOSE INPUT 
 		$ GOTO INIT   7                       Release notes for EXECSYMB V02.32 7                       =================================   ,                                  15-Jun-1989  K    Changes since the previous release (V02.29, 23-Feb-1988) are as follows:   M     1.	Synchronization between AST-level and non-AST-level code was improved. F 	Also, use of hibernation and wakeup calls was improved to cut down on$ 	the number of system service calls.  L     2,	The mailbox message size for the status mailbox was increased from 12D 	to 268 bytes, to allow room for accounting, checkpoint, and device  	status information.  G     3.	The status message format was extended to allow specification of C 	accounting data, checkpoint data, and device status.  The program  @ 	logic was enhanced to recognize "intermediate" status messages H 	containing checkpoint and device status information.  (In other words, D 	instead of only recognizing a status message from a stream at task A 	completion, EXECSYMB will also accept such messages during task  C 	execution, to provide checkpoint data or device status to the job  
 	controller.)   B 	The old status message was required to have the format %XnnnnnnnnC 	where the n's are hex digits.  The new status message can have two : 	formats.  An intermediate status message looks like this:  = 		,{optional device status}{,optional checkpoint data string}   2 	A task completion status message looks like this:  0 		<completion status>{,optional accounting data}  D 	Status values are numeric longwords, represented as either a signedC 	decimal number, or a hex number preceded by "%X".  Accounting data E 	consists of four such numbers, representing the four accounting data A 	fields (pages printed, QIO's to printer, GET's from source, and  B 	hundredths of CPU-seconds used.)  Checkpoint data is an arbitraryE 	character string.  For more details, read the SMB section of the VMS  	Utility Routines manual.   E 	A note about the "device status" field:  this can be used to specify ? 	various queue status or attribute values.  There are also some G 	unsupported bits in the status (at least as of VMS V5.4), which may be C 	quite useful in some applications.  Here is a brief summary of the 0 	bits in the device status field as of VMS V5.4:  ' 	SMBMSG$V_name	       bit#   mask value ' 	=============	       ====   ========== 2 	LOWERCASE		 0	     1	  Sets "Lowercase" attribute. 	PAUSE_TASK		 1	     2	  Initiates pause-queue- 	REMOTE			 2	     4	  Sets "remote" attribute - 	SERVER			 3	     8	  Sets "server" attribute 0 	STALLED			 4	    16	  Indicates queue "stalled". 	STOP_STREAM		 5	    32	  Initiates stop-queue0 	TERMINAL		 6	    64	  Sets "terminal" attribute3 	UNAVAILABLE		 7	   128	  Sets "device unavailable"  	SYM_NOTIFIES		 8	   256	  ?  	SYM_REQUESTS_OPER	 9	   512	  ? 	SYM_COPIES_FILE		10	  1024	  ?  	SYM_COPIES_JOB		11	  2048	  ?= 	SYM_ACCEPTS_ALL_FORMS	12	  4096	  Allows all jobs, any /FORM $ 	SYM_NO_JOB_CHECKPOINT	13	  8192	  ?  G     4.	A feature called "permanent processor support" had been added to H 	EXECSYMB in V02.27.  This was supposed to provide a way for an existingG 	detached process to "register" itself as a queue processor (instead of H 	EXECSYMB creating the process when the queue was started.  The feature F 	wasn't designed too well, and was only added to support one specific C 	application (which, naturally, ended up never using it).  Because  D 	permanent processor support was incompatible with the intermediate A 	status message support described above (which *is* useful), and  C 	because, to my knowledge, nobody ever used it, permanent processor 7 	support *has been removed* from EXECSYMB as of V02.32.  	         ----------------  C 	If you built something using the "permanent processor" feature, it G 	won't work with versions of EXECSYMB beyond V02.29 -- and I would like 9 	to hear from you to discuss alternative implementations.   7                       Release notes for EXECSYMB V3.0.1 7                       =================================   ,                                  12-Jul-1989  K    Changes since the previous release (V02.32, 15-Jun-1989) are as follows:   J     1.	Use (and misuse) of event flags in previous versions was completely@ 	cleaned up.  This may have been at least partly responsible for1 	"strange behavior" in past releases of EXECSYMB.   J     2.	Cosmetic changes to process names were made (EXECSYMB process has aC 	name like "ExecSymb3.0.1_n" instead of "SYMBIONT_EXEC_n" and queue @ 	processors are named "nx=queuename" instead of "nx_queuename".)  G     3.	EXECSYMB determines whether it is running on VMS V4.x or a later E 	version.  If a later version, it uses the new queue manager features C 	that were added in VMS V5.0 (e.g. queue name no longer needs to be : 	specified when changing a particular entry's attributes.)  I     4.	EXECSYMB now explicitly sets its base priority to 7 (one below the E 	current level used by the job controller), instead of using whatever B 	was specified as the /BASE_PRIORITY qualifier on the first queue ? 	started for this symbiont.  Also, EXECSYMB now uses the system H 	parameter DEFPRI to determine the base priority of the queue processorsH 	that it creates.  (Thus, they will typically run with base priority 4.)  I     5.	A bug in the protection attached to the status mailbox was fixed.  F 	Prior to this version, the status mailbox was inadvertently left withH 	full access for all users, when it should have had full access only for 	SYSTEM processes.  J     6.	Some additional stream status information was added, to reduce the C 	amount of time EXECSYMB uses for scanning streams that have never  B 	been active (both in its "main loop" and when a status message is 	received.)   F     7.	Logfile messages (and some operator messages) were shortened toH 	eliminate extraneous text.  (Since debugging symbiont problems requiredG 	finding the message in the source code anyway, having a longer message / 	didn't really provide any useful information.)   N     8.	For several versions prior to this release, it had not been possible toA 	get null items sent to the queue processor (i.e. all queues were F 	effectively "NONULL" whether they specified it or not.)  This bug hasF 	been fixed.  (Most queue processors will still want to specify NONULL 	for efficiency's sake.)  E     9.	Previous versions of EXECSYMB did no validity checking of the  C 	requeue-time or dynamic-time queue parameters; such checks are now 
 	included.  K    10.	This isn't really a change, but should be noted somewhere:  EXECSYMB H 	has always used the LIB$FID_TO_NAME routine to convert a file-ID into aB 	full filespec.  Prior to VMS V5.0, this routine was supplied withF 	EXECSYMB as an object module (and a Bliss-32 source file).  VMS V5.0 F 	added LIB$FID_TO_NAME to the LIBRTL, so EXECSYMB for V5.0 and beyond F 	no longer requires the explicit object module reference in its build  	procedure's LINK command.  L    11.	The (undocumented) "debug" mode was enhanced to allow it to be turnedG 	on and off dynamically, and to display all current status information.   7                       Release notes for EXECSYMB V3.1.1 7                       =================================   ,                                  02-Mar-1990  O Changes since the previous public release (V3.0.1, 12-Jul-1989) are as follows:   M     1.	EXECSYMB now saves the "device name" specified in the "/ON=" qualifier B 	for each queue, and creates a logical name DEVICE_NAME_pid (whereC 	"pid", as usual, is the process ID of the queue processor for that H 	queue.)  This provides a way to pass a queue-dependent parameter of up E 	to 31 characters directly to the queue processor.  Note that the SCS H 	node name portion of "/ON=" is *not* part of this parameter.  Also noteF 	that VMS imposes no syntax restrictions on the "device name", as long% 	as the string is enclosed in quotes.   D 	An example of the use of this feature:  we have several queues thatF 	use an NJE package to send print files to devices on our IBM systems.F 	In the past, we used a separate command procedure to drive each queueH 	processor -- now we use a single procedure, and specify the destinationF 	for each queue through the "/ON=" parameter.  It makes things simplerG 	and more flexible, and it's nice to see the information displayed in a E 	SHOW QUEUE instead of being buried in a command procedure somewhere.   M     2.	A bug that prevented EXECSYMB from stopping some hung queue processors H 	has been fixed.  In past releases, if a queue processor changed its UICD 	to something other than [1,4] and then became hung, EXECSYMB's exitD 	timeout code would fail to stop the process because EXECSYMB didn'tH 	enable WORLD privilege.  As of this release, EXECSYMB correctly enables> 	WORLD privilege, and thus is able to stop any hung processor.G 	(All symbiont processes, such as EXECSYMB, are started with SETPRV and F 	no other privileges enabled -- so fixing this problem simply required? 	adding WORLD to the list of privileges that EXECSYMB enables.)   7                       Release notes for EXECSYMB V3.1.2 7                       =================================   ,                                  21-Jun-1990  O Changes since the previous public release (V3.1.1, 02-Mar-1990) are as follows:   K     1.	One very minor bug fix, to the code that re-converts the "TIME=" and F 	"DYN=" queue parameters to ASCII (to reset the parameter string after7 	the queue is started), to display the hours correctly.   7                       Release notes for EXECSYMB V3.2.4 7                       =================================   ,                                  20-Aug-1990  O Changes since the previous public release (V3.1.2, 21-Jun-1990) are as follows:   O     1.	The ability was added to disable requeue-for-retry (i.e. to force a job  D 	to complete with an error or fatal error status) in a queue that isC 	enabled for retry (i.e. for which a TIME= parameter is specified). A 	This feature is implemented by making the status (written to the < 	EXECSYMB status mailbox) the negative of the actual status.  L     2.	EXECSYMB now defines some additional logical names in the group [1,*]C 	logical name table (LNM$GROUP_000001).  These names may be used to B 	determine the association of queues, streams and queue processor I 	processes related to a particular copy of the EXECSYMB symbiont process. F 	Every time a stream is started by EXECSYMB process number N (i.e. theD 	one whose process name is "ExecSymb3.2.4_N"), a logical name of theH 	form EXECSYMB_Nx is created (where x is the stream number encoded as a F 	"base 32" digit, 0-9 or A-V); its equivalence name is the name of theC 	queue for which that stream was started.  This logical will remain A 	defined for as long as the EXECSYMB process exists (although its H 	equivalence name may change.)  Also, when a queue processor process is H 	actually created, a name of the form EXECSYMB_PID_Nx is defined, whose G 	equivalence name is the process ID of the queue processor.  Thus, for  D 	any EXECSYMB process, you can determine the queues and active queue 	processors that belong to it.  E     3.	The $DEBUG mode "EXIT" command (executed by writing the string G 	"$DEBUGEXIT" to the symbiont's status mailbox) was changed to stop all E 	streams' queue processors.  A "QUIT" command (i.e. "$DEBUGQUIT") was B 	added to do the "immediate exit" that was formerly what EXIT did.E 	This change was made to provide a clean way of stopping the symbiont H 	and its associated processes after a queue manager failure.  (A sample C 	command procedure, EXECUTIL.COM, is supplied with the source code, & 	illustrating some of these features.)  7                       Release notes for EXECSYMB V3.2.6 7                       =================================   ,                                  01-Apr-1991  O Changes since the previous public release (V3.2.4, 20-Aug-1990) are as follows:   H     1.	Added queue-specific locations for the *.OUT and *.ERR log files.B 	If the logical name "EXECSYMB_OUTDIR_queuename" is defined in theE 	system logical name table, its value is used as the device/directory 7 	where the log files for queue "queuename" are created.   7                       Release notes for EXECSYMB V3.2.7 7                       =================================   ,                                  23-Oct-1991  O Changes since the previous public release (V3.2.6, 01-Apr-1991) are as follows:   N     1.	Added a queue parameter "INIT", which is used with the "DYN=" parameterG 	to indicate that the dynamic queue processor is to be started when the D 	queue is first started.  (Ordinarily, when a queue is started and aC 	dynamic queue processor is specified, the processor is not started G 	until a job is available for processing.)  This is useful if the queue F 	processor procedure needs to do some initialization at queue startup,E 	such as sending device status bits to the job controller.  The queue : 	processor will be started with the usual dynamic timeout.  7                       Release notes for EXECSYMB V3.3.1 7                       =================================   ,                                  31-Mar-1992  O Changes since the previous public release (V3.2.7, 23-Oct-1991) are as follows:   I     1.	Initial update to include new items defined by VMS V5.5.  (All new H 	items are presently passed untranslated.)  Note that previous releases F 	of EXECSYMB *will not work* under VMS V5.5; however, this release of 4 	EXECSYMB *will* work with previous releases of VMS.  O     2.	Compiling this version of EXECSYMB with a VMS V5.5-compatible SMBDEF.INC @ 	will produce a symbiont that will work with VMS V5.5 as well as 	previous releases of VMS.  7                       Release notes for EXECSYMB V3.4.1 7                       =================================   ,                                  14-Oct-1992  O Changes since the previous public release (V3.3.1, 31-Mar-1992) are as follows:   M     1.	The code was cleaned up a bit:  an IMPLICIT NONE declaration was added H 	to each routine, and all previously undeclared variables were declared.  L     2.	An occasional problem was noted in V3.3.1 (and prior versions), whichC 	appears to be due to a race condition between EXECSYMB and a queue D 	processor whose exit has been requested.  The queue processor exitsH 	before EXECSYMB flags the fact that the exit is expected.  As a result,@ 	the queue processor exit is treated as an unexpected abort, andF 	EXECSYMB stops the queue.  This problem is evidenced by EXECSYMBx.LOG! 	message sequences like this one:   5 	 17-MAR-92 09:46:34 Exitstat: stream  7 = %X10000001   8 	 17-MAR-92 09:46:34 Exit request for processor 00000703  B 	The "Exitstat" message indicates an unexpected abort on stream 7;C 	the next message is logged by the EXECSYMB routine that requests a E 	queue processor exit (and which caused the exit that resulted in the  	first message).  D 	Although I don't see how this race condition can happen, I have nowC 	changed the exit-request code to set the "exiting" flag before the ? 	exit request message is sent out.  ***NOTE*** If you still see C 	message sequences like the one listed above after installing V3.4,   	please contact me with details!  M     3.	Some additional output code was added to the debugging mode, primarily C 	to dump the contents of messages received from the job controller.   M     4.	This is an important change, especially in light of the instability of B 	the V5.5-x job controller/queue manager (both "classic" and "new"F 	versions).  When the job controller aborts, in its last gasp it killsC 	off all symbiont processes, so that there are no orphan symbionts  G 	sitting around with nobody to talk to them.  EXECSYMB gets zapped this E 	way -- but any active queue processors started by EXECSYMB will just D 	keep running, since nobody will tell them to stop.  The only way toE 	fix this is to add a user rundown routine (which runs in kernel mode @ 	at image/process rundown) and have that routine do the cleanup.D 	(An exit handler won't do the job, since the job controller simply G 	does a $DELPRC on each symbiont process -- thus, an exit handler would  	not be called.)  H 	After several job controller crashes in recent weeks, I finally decidedG 	that it was time to write such a routine, which meant creating a user- H 	written system service.  As long as I was doing that, I took the other H 	EXECSYMB kernel-mode code -- the SETUSER routine -- and created a user-C 	written system service for it.  The combination of SETUSER and the E 	rundown routine are now in a separate image, EXECSYMB_KM.EXE, which  F 	must be installed /SHARE/PROT in order for EXECSYMB to work properly.D 	Since I have no VMS V4.x systems left on which I could test this, ID 	am only including this support in the VMS V5.x-compatible EXECSYMB.  H 	The rundown routine will deassign all logical names created by EXECSYMBH 	and will send an exit request to each active queue processor.  (It doesE 	*not* do a $DELPRC on the queue processors -- instead it allows them  	to do a normal exit.)  J     5.	The "new, improved" VMS V5.5 queue manager behaves differently whenF 	it receives a TASK_STATUS message from a symbiont.  (EXECSYMB sends aE 	TASK_STATUS messages when it receives an intermediate status message G 	from a queue processor.)  In particular, it is no longer legal to send > 	a TASK_STATUS message if there is no job active on the queue.  F 	The INIT feature (added in EXECSYMB V3.2.7) was provided specificallyD 	for the purpose of allowing a queue processor to send device statusF 	information back to the job controller (via an "intermediate status" G 	message to EXECSYMB).  This would be used to set queue characteristics B 	(e.g. ACCEPTS_ALL_FORMS) before any jobs were actually processed.F 	However, there was no *requirement* that the queue processor actuallyA 	send an intermediate status message; the queue would still start ' 	correctly if no such message was sent.   B 	The new queue manager doesn't allow EXECSYMB to use a TASK_STATUSF 	message to forward the device status information; instead, the device. 	status must be sent as part of queue startup.  G 	As a result, effective with V3.4.1, if you specify the INIT flag on an B 	EXECSYMB queue, your queue processor *must* send an "intermediateE 	status" message when it starts up.  Until the message is received by E 	EXECSYMB, the queue will remain in the "starting" state, as EXECSYMB H 	will be waiting to receive the device status information for forwarding 	to the job controller.   L     6.	I fixed a bug in the queue processor exit processing code which wouldH 	return a spurious STOP_STREAM completion message to the job controller.B 	Ordinarily this message would be ignored without any ill effects.H 	However, with the new V5.5 queue manager, the extra message would causeE 	EXECSYMB to abort and produce a process dump in SYS$SYSTEM: *if* the A 	spurious message occurred on the last active queue.  Under those H 	circumstances, the job controller thinks the symbiont has exited (sinceG 	its last active queue reported a STOP_STREAM already) and so the extra C 	message appears to come from a process that isn't a symbiont.  The D 	job controller returns an "invalid message" status which aborts the 	process and triggers the dump.   7                       Release notes for EXECSYMB V3.5.2 7                       =================================   ,                                  13-Jan-1994  O Changes since the previous public release (V3.4.1, 14-Oct-1992) are as follows:   L     1.	AXP support was added.  This involved no code changes to EXECSYMB.FORH 	itself.  The MACRO-32 compiler complained about some of the code in oneH 	of the support modules (ENTREM), so I cleaned that up.  EXECSYMB_KM wasF 	modified to assemble on the VAX or compile on the AXP with a suitableH 	symbol definition; I used the templace user-written system service codeH 	(provided as C code on the AXP) but wrote the equivalent in MACRO-32 toB 	keep the whole thing as one module (and to avoid the need for a C* 	compiler on top of the Fortran compiler!)  @ 	Note: this version of EXECSYMB *should* work with VAX VMS V6.0;F 	apparently there were no changes to the symbiont interface in the newE 	VMS release.  (The $SMBDEF modules are identical for both releases.) D 	I would expect that you'd at least have to relink the images under  	V6.0, though.  N     2.	The new DEC Fortran compilers produce warnings for things like declaredB 	but unused variables.  I cleaned up the code to eliminate all theD 	warnings.  While doing that, I also did some minor cleanup on other@ 	code sequences that I found annoying for one reason or another.  K     3.	The error handling for queue processor process creation was somewhat H 	inadequate.  Since errors in that operation are extremely rare, I neverF 	noticed this deficiency.  While testing the AXP version I managed to H 	cause a process creation failure, and found that EXECSYMB didn't handle3 	it too well.  That problem has now been corrected.   J     4.	I was asked whether queue processor working set parameters could beE 	adjusted, to cut down on page faults.  Since VMS supports use of the F 	/WSDEFAULT, /WSQUOTA, and /WSEXTENT qualifiers on symbiont queues, it? 	seems that EXECSYMB should honor these when creating the queue E 	processor (along with the /BASE_PRIORITY qualifier).  I've now added @ 	the code required to do this.  Since it uses the $GETQUI systemE 	service, this code is certainly VMS version dependent; I've disabled H 	its use if you're running a version prior to V5.0.  Note -- VMS doesn'tB 	display the working set information for non-batch queues, so I'veB 	supplied a short Fortran program (SHOWQUEWS.*) that will do this.  M     5.	During the beta testing of V3.5, we discovered that a STOP/QUEUE/RESET E 	on an EXECSYMB queue would make the queue unstartable.  (Attempts to D 	start the queue would hang in QUEMAN, and the queue would remain inF 	"starting" state forever.)  It turns out that the VMS queue manager'sE 	handling of STOP/QUEUE/RESET changed in some recent release prior to E 	V6.0: what had been a valid symbiont response to the queue manager's H 	RESET request now causes the queue to hang as described above.  To workG 	around this problem, code was added to EXECSYMB to distinguish between + 	a normal STOP request and a RESET request.   N     6.	While I was working on the problem described in (5), I fixed some bugs H 	in the built-in debugging code (DUMP mailbox command) and added a minorA 	enhancement to that code (ability to dump specific stream data).   7                       Release notes for EXECSYMB V3.6.1 7                       =================================   ,                                  14-Jul-1994  O Changes since the previous public release (V3.5.2, 13-Jan-1994) are as follows:   M     1.	Bug fix required for VAX VMS V6.x -- EXECSYMB's version detection code G 	had a really stupid bug in it, which caused a bunch of messages in the F 	EXECSYMB log files showing a status of 00000154 (%SYSTEM-F-IVLOGNAM),) 	and prevented the symbiont from working.   N     2.	Bug fix in EXECSYMB_KM; a line of code was placed in a VAX-only sectionE 	that should have been in the architecture-independent section.  This = 	would have caused problems in the AXP flavor of EXECSYMB_KM.   N     3.	One new feature: a new flag "HOLD" is recognized in the queue parameterH 	string (i.e. the /SEPARATE=RESET string).  Prior to V3.6, if you wantedF 	jobs to be requeued for retry on a failure completion status, you hadE 	to specify a wait time via the "TIME=" queue parameter.  I ran into  H 	many cases where I just wanted the jobs held indefinitely (e.g. if the H 	queue processor modifies and requeues the job for processing elsewhere,F 	and then releases it).  HOLD enables you to do this.  If you specify F 	"HOLD", don't specify "TIME=", and a job reports an error completion = 	status, the job will be requeued and put on indefinite hold. 