)EXECSYMB, SYSTEM_MGMT, Executive Symbiont+ EXECSYMB* V3.6.1, John Osudar5 Chemical Technology Division4 Argonne National Laboratory+ 205 L-2132 9700 South Cass Avenue2 Argonne, IL 60439-48371 Phone: (708) 252-75050 FAX: (708) 252-59124 Electronic mail addresses:5 Internet: OSUDAR@CMT.ANL.GOV0 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 ------------GEXECSYMB is a VMS server symbiont that feeds queue entry information toNdetached processes that are designed to execute specific operations (hence theHname, Executive Symbiont). It is multi-threaded (it can handle up to 32Nqueues at the same time); it requires one detached process and one mailbox forJeach queue, plus one mailbox for status information and one for detecting Gprocess exit status for each copy of EXECSYMB (i.e. one per 32 queues).DEXECSYMB can be used to implement a wide variety of VMS queue-based 0operations. 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 operations3 on files queued to MFENET inbound-file symbionts)8 (3) Queued file transfer for DECnet and other networksGThis program was written with one major goal in mind: to simplify the Isystem's interface to a user-written queue processor, eliminating (or at Kleast hiding) the quirks that are present in the job controller-to-symbiontinterface supplied by Digital. LUnder VMS V4 and later, symbionts operate in a rather strange environment. NA symbiont is a detached process (unlike VMS V3, where it was a subprocess of Hthe job controller). However, it lacks several useful things that most Jprocesses have: symbionts have no CLI, which means that they can't spawn Ncommands; symbionts are always created with username SYSTEM and one privilege M(SETPRV); and symbionts cannot access process-permanent logicals (SYS$INPUT, LSYS$OUTPUT, SYS$ERROR) the way other processes can. A symbiont's SYS$INPUT Mpoints to a mailbox to which the job controller writes its request messages, Mand SYS$OUTPUT points to another mailbox from which the job controller reads Kstatus messages from the symbiont. (Incidentally, the latter has been the Ojob controller's "achilles heel"; if your symbiont accidentally writes a bunch Iof stuff to SYS$OUTPUT, the job controller will respond with a series of Lconsole error messages about "invalid mailbox message received". Under someMversions of VMS, this is immediately followed by a fatal "end-of-file on job Ocontroller mailbox" that aborts the queue manager, stopping ALL queues on your Osystem and leaving active batch jobs in VMS limbo. VMS V4.4 and beyond allows Nthe queue manager to restart after such an abort, but this usually leads to a Nrecurrence of the problem, and a hard abort on the part of the queue manager.)JEXECSYMB was designed to make the symbiont environment easier to use. Of Icourse, EXECSYMB itself has to deal with the restrictions listed above. JHowever, a queue handled by EXECSYMB is processed by an EXECSYMB detached Gprocess, which is created with the DCL CLI, a real command procedure asKSYS$INPUT, a log file as SYS$OUTPUT, and a pair of mailboxes for talking toMEXECSYMB. The protocol for passing information between the executive symbiontMand the detached process involves transferring "items", which EXECSYMB parsesIfrom the job controller's request message, through a mailbox. One of theM"items" is created by EXECSYMB itself -- it's called "EXEC_STEP", which is anJ"execute trigger", telling the detached process that a string of items hasLbeen completely transferred and an operation (execute, reset, exit) is to beNperformed. The detached process returns a completion status through the otherHmailbox, which provides EXECSYMB with a task status to return to the jobFcontroller. As a result, it is relatively easy to write a DCL commandKprocedure to process a queue. There are just a few requirements for such aLprocedure, which are outlined below, in the section "sample queue processing procedure".  Features of EXECSYMB --------------------HIn addition to providing a safer and less hostile environment for queue Jprocessing, EXECSYMB adds some features that aren't available to ordinary 1user-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 ----------------IHere's what you need to know to run EXECSYMB. (Remember that a symbiont !image must reside in SYS$SYSTEM.)KThe EXECSYMB process will change its name to "ExecSymb3.0.1_n" where n isHa sequence number that starts at 1. Since each process handles up to 32Lqueues, you shouldn't see sequence numbers above 1 unless you have more thanL32 queues processed by EXECSYMB at the same time. EXECSYMB starts with its Nbase priority set from the /BASE_PRIORITY=n qualifier on the first queue that Kit starts; however, soon after starting it will set its base priority to 7.HThis is done so that EXECSYMB's priority will be above that of the queueGprocessors (which are created with a base priority of DEFPRI, which is Kusually 4) and below that of the job controller (whose base priority is 8.)LEXECSYMB sends important messages, such as startup and shutdown of the main Jprocess, to the OPER12 operator. Other information is written to the log Mfile, which is named SYS_EXECSYMB:EXECSYMBn.LOG (where "n" is as described inNthe process name above). If SYS_EXECSYMB is not defined in the system logicalIname table, log files are placed in SYS$MANAGER:. (The "queue processor"Ndetached processes also place their SYS$OUTPUT and SYS$ERROR log files there. MAs of V3.2.6, it is possible to redirect a particular queue's .OUT/.ERR filesMby defining a system logical name, EXECSYMB_OUTDIR_queuename, pointing to theKdestination directory.) EXECSYMB remains active as long as it has at leastNone active queue to process; upon stopping the last queue (and waiting for itsIqueue processing detached process, if any, to exit), EXECSYMB will exit. NEXECSYMB can send items to the detached process in ASCII or binary form. The MASCII form uses two writes per item, one to send the item name, the other to Ksend its value. The binary form does one write per item, and includes the Iitem's binary code number as the first four bytes of the record. In the LASCII form, many item values are converted from their raw form to an edited LASCII form; e.g. the UIC item will be converted from four binary bytes to a Mstring of the form [gggggg,mmmmmm]. The binary form does no editing on item Mvalues. 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.IEXECSYMB terminates the list of items for a particular task with an item Lthat it makes up itself. This item has the name "EXEC_STEP", binary code 0,Iand can have one of three ASCII values: "EXECUTE", which means that the Ltask's item list has been completely transferred, and the task is ready for Iexecution; "RESET", which means that a partial item list was sent, which Jshould be discarded, and the detached process should return to its initialJstate; 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.HEXECSYMB can also send the queue processor another item that it makes upMitself. This item, named "EXEC_FLAGS", binary code -1, is a character stringIcontaining a list of "task flags", indicating specific characteristics ofIthe current task which are not directly available otherwise. This stringJconsists of a leading slash ("/"), a list of (zero or more) uppercase-onlyHkeywords separated by slashes, and a trailing slash. Thus, to determineJif a specific keyword is present in the item value, you can search for theJkeyword surrounded by slashes. At the present time, the only keyword thatKcan be passed in this item is "SPOOL", which means that the file associatedKwith this task is a spool file (i.e. a file created by writing to a spooleddevice).JYou can tell EXECSYMB how to process a queue through two queue qualifiers:Jthe command procedure that is to be used is specified through the /LIBRARYJqualifier, and the list of processing options is specified as a character Fstring in the /SEPARATE=RESET qualifier (which corresponds to the itemJJOB_RESET_MODULES). Since device control libraries and job reset modules Karen't too meaningful in the context of server symbionts, use of these two qualifiers works out quite well.GThe /LIBRARY qualifier takes a filename as its value. Although device Mcontrol 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 Lyou specify. (In fact, the job controller sticks a SYS$SHARE: on the front Mof 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 Othis field is restricted to a total of 39 characters (since the job controller 4thinks this is the filename part of a library name.)IThe /SEPARATE=RESET qualifier takes an arbitrary character string as its Fvalue. 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 the4 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).7Defaults, if a particular option is not specified, are:Nno requeue, non-dynamic queue processor, no ITEMS, no SPOOL directory, ASCII, <SERVER, NULL, CHECK, COPY=ALL, USER=SYSTEM, no FLAG, no INITKA little more needs to be said about spool file handling. EXECSYMB can be Kused to process queues from spooled devices (such as spooled null printers,Gused for remote printer support). When output is written to a spooled Mdevice, a spool file is created on the device's secondary device (disk), and Lqueued to the device's queue. This file is identified only by file ID, and Jhas no directory entry. In some applications (e.g. where the file will beJcopied to another node with a network copy program), the file must have a Lfull filename to be effective. EXECSYMB will detect spool files for queues Jthat specify the SPOOL=directory option, and will enter such files in the Jspecified 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) ---------------------------------KThe following is a sample queue processing procedure that can be used with MEXECSYMB. It is reproduced here to illustrate the required features of such Na procedure; it can also be found, without comments, in this directory in the Gfile EXAMINEQUEUE.COM (which can be used as-is with EXECSYMB.) This Mprocedure does nothing "useful"; it produces a log file containing the items Mpassed for each request it processes, and it indicates successful completion of each task.IFirst, you can specify any setup commands you require. SET NOVERIFY and SET NOON are recommended. $ SET NOON $ SET NOVERIFYFNext, the procedure must locate the mailboxes that it uses to talk to JEXECSYMB. The input mailbox (written by EXECSYMB, read by the procedure) Hhas a logical name of CMD_MBX_pid where "pid" is the process ID of theMdetached process running this procedure. The output mailbox (written by the Lprocedure, read by EXECSYMB) is used for returning status, and has the name OSTAT_W_MBX_pid (where "pid", again, is the process ID). We can also determine Hthe name of the queue we are processing by translating the logical name NQUEUE_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'")LBefore we do any real work, we must open the input and output mailboxes for Otalking with EXECSYMB. (If we decide to reinitialize after detecting a mailbox2I/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':JThe items sent by EXECSYMB all have names that can be used as DCL symbols.HThat is the technique used here. (EXECSYMB has an alternate format for Iitems, in which a fixed-length binary item code precedes the item value; Ethat format is intended for use by compiled programs that run in the Jdetached process.) The item "EXEC_STEP" is used by EXECSYMB to guide the Ooperation of the detached process; EXECSYMB can assign it the values "EXECUTE","RESET", and "EXIT". IInitially, or after an "EXECUTE" operation is complete, or when EXECSYMB Hexplicitly requests a "RESET" (such as when a job is deleted while beingOprocessed), the procedure should reset controlling variables to initial values,Land return to its input processing loop. This procedure has one controllingNvariable, EXEC_STEP. Here, we initialize the symbol to the value "INPUT", andJsubsequently use the symbol as the destination label of a GOTO. This is aLrather simple, yet effective, way of implementing the control operation. (WeMalso write out a separator line to the log file, to mark the boundary between requests.) $RESET:? $ WRITE SYS$OUTPUT "========================================" $ EXEC_STEP="INPUT"MNow comes the good part of the procedure. It starts with the label that was Jinitially assigned to EXEC_STEP. The first command reads the NAME of the Ksymbol (i.e. the item name) being passed, and the second command reads its LVALUE. 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 'SYMBOLLFor demonstration purposes, we echo the information to SYS$OUTPUT, which is the log file. $ WRITE SYS$OUTPUT SYMBOL $ WRITE SYS$OUTPUT 'SYMBOLKHaving completed the value assignment, we go to the location pointed to by HEXEC_STEP. This was initially INPUT, and will remain so until EXECSYMB Jsends the item EXEC_STEP and a new value (EXECUTE, RESET, or EXIT) for it. $ GOTO 'EXEC_STEPKWhen EXECSYMB says "EXECUTE", it indicates that the item sequence for this Mtask is complete, and should be acted upon. A real symbiont processor would Jdo something with the item list at this point (e.g. do something with the Mfile specified in item FILE_SPECIFICATION). Once the operation is complete, HEXECSYMB expects a status to be returned via the mailbox. This example Lalways returns a success status. After it reports completion, the procedureJloops to the "RESET" label to reset controlling variables and re-enter the input loop. $EXECUTE: $ WRITE STAT "%X00000001" $ GOTO RESETKIf an "EXIT" operation is requested, EXECSYMB wants the detached process toLexit. One way to do this is to log off; you can also do an EXIT or whateverKelse you desire (including, for example, sending operator notification that!the detached process is exiting.) $EXIT: $ LOGOUTMFinally, we add some error handling for the cases where we failed to open oneNof the required mailboxes, or got an I/O error on a mailbox. If we can't openOa mailbox, we cannot continue, so we exit (logoff). If we got an I/O error, weOcan 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.327 =================================, 15-Jun-1989K 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 ofC 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 {,optional accounting data}D Status values are numeric longwords, represented as either a signedC decimal number, or a hex number preceded by "%X". Accounting dataE consists of four such numbers, representing the four accounting dataA 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 someG unsupported bits in the status (at least as of VMS V5.4), which may beC quite useful in some applications. Here is a brief summary of the0 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" attribute0 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 toH EXECSYMB in V02.27. This was supposed to provide a way for an existingG detached process to "register" itself as a queue processor (instead ofH 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 processor7 support *has been removed* from EXECSYMB as of V02.32. ----------------C If you built something using the "permanent processor" feature, itG won't work with versions of EXECSYMB beyond V02.29 -- and I would like9 to hear from you to discuss alternative implementations. 7 Release notes for EXECSYMB V3.0.17 =================================, 12-Jul-1989K 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 laterE version. If a later version, it uses the new queue manager featuresC 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 theE current level used by the job controller), instead of using whateverB was specified as the /BASE_PRIORITY qualifier on the first queue ? started for this symbiont. Also, EXECSYMB now uses the systemH 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 wereF 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: EXECSYMBH 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.17 =================================, 02-Mar-1990OChanges 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=" qualifierB for each queue, and creates a logical name DEVICE_NAME_pid (whereC "pid", as usual, is the process ID of the queue processor for thatH 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 SCSH 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 aE SHOW QUEUE instead of being buried in a command procedure somewhere.M 2. A bug that prevented EXECSYMB from stopping some hung queue processorsH 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 andF 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.27 =================================, 21-Jun-1990OChanges 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=" andF "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.47 =================================, 20-Aug-1990OChanges 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 toB 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 remainA defined for as long as the EXECSYMB process exists (although itsH 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 stringG "$DEBUGEXIT" to the symbiont's status mailbox) was changed to stop allE streams' queue processors. A "QUIT" command (i.e. "$DEBUGQUIT") wasB 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 symbiontH 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.67 =================================, 01-Apr-1991OChanges 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/directory7 where the log files for queue "queuename" are created. 7 Release notes for EXECSYMB V3.2.77 =================================, 23-Oct-1991OChanges 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 theD queue is first started. (Ordinarily, when a queue is started and aC dynamic queue processor is specified, the processor is not startedG until a job is available for processing.) This is useful if the queueF 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.17 =================================, 31-Mar-1992OChanges 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 newH 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.17 =================================, 14-Oct-1992OChanges 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 addedH 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 queueD 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 = %X100000018 17-MAR-92 09:46:34 Exit request for processor 00000703B The "Exitstat" message indicates an unexpected abort on stream 7;C the next message is logged by the EXECSYMB routine that requests aE 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 seeC 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, primarilyC to dump the contents of messages received from the job controller.M 4. This is an important change, especially in light of the instability ofB 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 thisE way -- but any active queue processors started by EXECSYMB will justD 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 theE 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 messageG 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 characteristicsB (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 anB EXECSYMB queue, your queue processor *must* send an "intermediateE status" message when it starts up. Until the message is received byE EXECSYMB, the queue will remain in the "starting" state, as EXECSYMBH 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* theA spurious message occurred on the last active queue. Under thoseH circumstances, the job controller thinks the symbiont has exited (sinceG its last active queue reported a STOP_STREAM already) and so the extraC message appears to come from a process that isn't a symbiont. TheD job controller returns an "invalid message" status which aborts the process and triggers the dump. 7 Release notes for EXECSYMB V3.5.27 =================================, 13-Jan-1994OChanges 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 somewhatH 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 theF /WSDEFAULT, /WSQUOTA, and /WSEXTENT qualifiers on symbiont queues, it? seems that EXECSYMB should honor these when creating the queueE 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 disabledH 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/RESETE on an EXECSYMB queue would make the queue unstartable. (Attempts toD 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 toE V6.0: what had been a valid symbiont response to the queue manager'sH 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.17 =================================, 14-Jul-1994OChanges 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 codeG had a really stupid bug in it, which caused a bunch of messages in theF 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.