.C.H.Y
HOW TO WRITE A SYMBIONT
FOR VAX/VMS
.W





by

Douglass J. Wilson  & Neal Lippman





Joint Computer Facility
Massachusetts Institute of Technology
.S
.C.Y.H
PRINCIPLE SYMBIONT FUNCTIONS

.W.X
1. Synchronize access to shared unit
   record devices

2. Despool and interpret data stored 
   in files

3. Perform device specific functions
.S
.C.Y.H
NEED FOR A USER-WRITTEN SYMBIONT

.W.X
o Perform device specific control
  functions (not supported by DEC)

o Provide a means of coordination of
  access to devices without overhead
  of batch queue processing

o Provide additional control over
  file processing (suspend, resume,
  abort)
.S
.C.Y.H
QUEUEING A JOB - BATCH STREAM APPROACH
.W.X.$(0

lqqqqqqqqqqqk
x  COMMAND  x$SUBMIT/PARA=DATA.PLT
x PROCEDURE tqqqqqqqqqqqqqqqk
x           tqqqqqqqqqqqqqqkx
x(PLOT.COM) x              xx
mqqqqqqqqqqqj              xx
			   xx
	   qqqqqqk        \xx/
   BATCH QUEUE   x         \/
		 mqqq lqqqqqqqqqqqk     
   JOBLIM = 1         x BATCH JOB x
	   qqqqqqqqqq x           x
		    lqu  PLT.COM  x
    lqqqqqqqqk      x x  PLT.EXE  x
    x        x      x mqqqqqqqqqqqj
    x DEVICE x<qqqqqj
    x        x
    mqqqqqqqqj
.$(B
.S
.C.H.Y
QUEUEING A JOB - SYMBIONT APPROACH
.W.X
.$(0
     lqqqqqqqqqqqqqqk
     x USER PROCESS tqqqqqqqqk
     x (PLOT.EXE OR tqqqqqqqkx
     x  PRINT.EXE)  x       xx
     mqqqqqqqqqqqqqqj      \xx/
                            \/
                        lqqqqqqqqqk
   lqqqqqqqqqk /        x $SNDMSG x
   x   JBC   x/qqqqqqqqqu         x
   x MAILBOX x\qqqqqqqqqu SYSTEM  x
   mqqqqwwqqqj \        x SERVICE x
        xx              mqqqqqqqqqj
       \xx/
        \/
 lqqqqqqqqqqqqqqqqk
 x                x
 x JOB CONTROLLER x
 x                x
 mqqqqqqqqqqqqqqqqj
.$(B
.S
.C.H.Y
SYMBIONT-JOB_CONTROLLER
COMMUNICATIONS

.W.X.$(0
	   lqqqqqqqqqk /      
      lqqqqu   JBC   x/qqqqk   
      xlqqqu MAILBOX x\qqqkx    .
     \xx/  mqqqqqqqqqj \  xx   .
      \/             .....xx...
lqqqqqqqqqqqqqqqqk  .lqqqqvvqqqqk
x                x . x          x
x JOBsCONTROLLER x . x SYMBIONT x
x                x . x          x
mqqqqqqqwwqqqqqqqj.  mqqqqqqqqqqj
     ...xx........          /\
    .   xx                 /xx\
   .    xx\ lqqqqqqqqqk     xx
	xmq\x  SMB    tqqqqqjx
	mqq/x MAILBOX tqqqqqqj
	  / mqqqqqqqqqj
.S.$(B
.C.Y.H
SUMMARY of JOB CONTROLLER MESSAGES

.W.X
o Start file processing                  
				 
o Abort processing
  
o Suspend processing

o Resume processing
   Possibly qualified with TOP_OF_FILE

o Exit
.S
.C.Y.H
SUMMARY of SYMBIONT MESSAGES

.W.X
o INIT DONE                              
				 
o FILE DONE
  
.S
.C.Y.H




CODING THE SYMBIONT
.S
.C  
.Y.H
SYMBIONT ROUTINES

.W.X.$(0
lqqqqqqqqqqqqqqqqk
x INITIALIZATION x       lqqqqqqqqqqqk
x     CODE       x       x CONDITION x
mqqqqqqqqwqqqqqqqj       x  HANDLER  x
lqqqqqqq>x               mqqqqqqqqqqqj
x        V                             
x lqqqqqqqqqqqqqk                       
x x  MAIN LOOP  x        lqqqqqqqqqqqk
x x             x        x           x
x x             x        x    AST    x
x x    FILE     tqqqqqqq>x   LEVEL   x
x x PROCESSING  x<qqqqqqqu ROUTINES  x
x mqwqqqqqqqwqqqj        x           x
mqqqj       x ^          mqqqwqqqqqqqj
	    V x              x^
	  lqqqvqqqqqqqqk     xx
	  x  UTILITY   x<qqqqjx
	  x  ROUTINES  tqqqqqqj
	  mqqqqqqqqqqqqj
.S.$(B
.C.Y.H
INITIALIZATION ROUTINE
.W.X.   

o Disable AST delivery

o Enable Condition Handler

o Assign channel to JBC Mailbox

o Create Symbiont Mailbox

o Initialize Data Segment
  (FAB,RAB,NAM,local)

o Set Unsolicited Data AST
  on JBC Mailbox

o Send INIT DONE message to JBC

o Enable AST delivery

o Branch to mainline
.S
.C.Y.H
SYMBIONT MAINLINE

.W.X
o Hibernate until woken by AST routines 
	
o If file opened okay (by AST routines)
  dispatch to file processing routine

o On processing routine completion,
  disable AST's for rundown 

o Close file, delete if necessary

o Select file done modifier
  (Success, aborted, error)
   
o Deassign channel to output device
  (Channel assigned in AST routines)

o Send file done message, enable AST's
  and hibernate until woken by AST
.S
.C.Y.H
AST LEVEL ROUTINES

.W.X
o Read the mailbox 

o Case on message type code

  - start file processing

  - abort processing

  - suspend processing

  - resume processing

  - exit
.S 
.C.Y.H
START FILE MESSAGE PROCESSING

.W.X
o Assign channel to output device

o Open and connect the file

o Wake up the mainline symbiont
.S
.C.Y.H
ABORT MESSAGE PROCESSING

.W.X
o If we are not processing a file,
  message is unexpected (signal)

o If we are done processing current
  file, ignore it

o Set abort flag   

o Cancel I/O on output channel

o If we were not suspended, set state   
  to idle

	
.S
.C.Y.H
SUSPEND MESSAGE PROCESSING

.W.X
o If we are done processing file,
  ignore it (JBC knows not to send
  a new file)

o If we were idle, message is         
  unexpected (signal)

o Save old state, set current state
  to suspended 

o $QIOW to mailbox to wait for another
  message
    
o RSB to CASE on message type 
.S
.C.Y.H
RESUME MESSAGE PROCESSING

.W.X
o If we are done, ignore it

o If we weren't suspended,   
  unexpected (signal)

o If the high order two bytes of
  message equals x8000, rewind file 

  
.S
.C.Y.H
EXIT MESSAGE PROCESSING

.W.X
o If we are not idle, unexpected
  (signal)

o Deassign channels from mailboxes

o $exit_s
.S
.C.Y.H
AST ROUTINES -- NOTES

.W.X
o Control within AST routines is
  performed via CO-ROUTINEs
  
o On reciept of unexpected message,
  error is signalled and mailbox is
  read again

o During processing of start processing
  message, mailbox read lenght is 
  reduced to 4 bytes.
.S
.C.Y.H
UTILITY ROUTINES     

.W.X
o Set/restore uic routines (kernel mode)
  requestor_UIC <-> [001,004]
  
o Send file done message to JBC    
  upon completion of file processing
  (reset mbox read length to full
  message size) 

o Send init done message to JBC upon   
  completion of initialization code    

o Accounting routine - send accounting
  information specific to JCF accounting
  system to JBC ($SNDACC)

  
.S
.C.Y.H
CONDITION HANDLER    

.W.X
o If facility code of signalled 
  condition is 0 (system), symbiont 
  exits
  
o $PUTMSG action routine used to send  
  message to system operators ($SNDOPR)

o Signal arguments vector (minus last 
  two longwords) used as $PUTMSG 
  message vector
  
.S
.C.Y.H
INCORPORATING YOUR SYMBIONT INTO VMS

.W.X
$ INIT/QUE/PROCESS=<yoursymb> <quename>

Yoursymb must be in SYS$SYSTEM:
Full directory specifications are not
recognized.

$ START/QUE <quename>
.S
.C.Y.H
IMPLEMENTATION HISTORY

.W.X
A symbiont was written at the Joint
Computer Facility, M.I.T. during the
summer of 1980. 

Approximately 1 week was spent in
analyzing the source code for the
VAX/VMS Version 1 Job Controller and
Printer Symbiont. 

Actual coding of the symbiont was
completed in 2 days. 

Debugging involved approximately 15
man-hours over a three day period. 
.S
.C.Y.H




THE END
.S