.FIRST TITLE ########SEMAPHORE DIRECTIVES FOR RSX-11M EXECUTIVE
.LITERAL
	Version 02.3		July 12,1982
	Last modification	Feb. 17,1983
 
	Harry Atherton
	University of Cincinnati Medical Center
	Department of Pediatrics, ML 541
	231 Bethesda Ave.
	Cincinnati, Ohio 45267
	Phone (513) 872-5341
 
.END LITERAL
.NOJUSTIFY
.AUTOPARAGRAPH
	The files in this UIC implement binary semaphore operations
in the RSX-11M executive.  This software has been in use at our
installation since RSX-11M V3.0, and it is believed to be bug free.
If you have any problems, comments, or suggestions I would like
to hear them.
No responsibility is assumed for the
use or reliability of this software.
.TITLE	SEMAPHORE DIRECTIVES FOR RSX-11M EXECUTIVE
.PAGE
	The following files implement the binary semaphore P-operation
and V-operation executive directives:
.LEFT MARGIN 15
.P -15
DRDSP.MOD###-- Adds the directives to the dispatch table.
.P -15
DREIF.MOD###-- Adds call to cleanup routine on task exit.
.P -15
SYSCM.MOD###-- Adds semaphore queues to executive data base.
.P -15
DRSEM.MAC###-- Directive processing and exit cleanup routines.
.P -15
SEMDIR.MAC##-- Macros that can be added to RSXMAC.SML to provide
directive calls SEMP$S AND SEMV$S.
.P -15
SEMCAL.MAC##-- FORTRAN callable subroutines provide directive
calls SEMP and SEMV. Object module should be added to your
FORTRAN object library.
.P -15
SEMTEST.FTN -- Small FORTRAN program to test and demonstrate
use of semaphores. The object module of SEMCAL.MAC must be available
to the task builder.
.P -15
SEMTEST2.FTN-- Small FORTRAN program to test for error return when
SEMP is called twice.
The object module of SEMCAL.MAC must be available
to the task builder.
.STANDARD 60
.AUTOPARAGRAPH
.NOJUSTIFY
.PARAGRAPH 5,1
To add the semaphore directives a system generation must
be done. To prepare for the SYSGEN copy files DRDSP.MOD,
DREIF.MOD, and SYSCM.MOD to [11,40] on the executive source disk.
Also copy DRSEM.MAC
to [11,10] on the executive source disk.
 
	After applying any DEC supplied patches, these modifications
are made.  The SLP correction files DRDSP.MOD, DREIF.MOD,
and SYSCM.MOD use ASCII
string locators to insert the additions to the program logic.
These files
must be applied AFTER any DEC patches. Note that these files are called .MOD
instead of .COR to avoid confusing them with the DEC files.
 
	Also watch out for file version numbers on
the source files if multiple
SYSGENS are done on the same disk. The DEC correction files specify
version 1 for input and version 2 for output. If you are working
with a virgin disk everything will work right since the .MOD files do
not specify version numbers. 
.TEST PAGE 8
  
	To have the module DRSEM assembled with the other executive
modules answer Y to the question: "Do you wish to edit any of the
Executive files ?"  Then edit the file [11,24]RSXASM.CMD.  Locate
the line containing DRSED. It should look like:
.BREAK
.BLANK 1
[11,24]DRSED,listing=[1,1]EXEMC/ML,[11,10]RSXMC,LB:DRSED
.BLANK 1
Add a line exactly like it, except replace DRSED with DRSEM (it
occurrs three times in the line). The module DRSEM will be included
in the executive object module library automatically by SYSGEN.

This is also a good time to edit the executive build command file.
It is file [11,10]RSXBLD.CMD on the baseline disk. 
Two situations must be considered. If you are building the executive
without executive directive commons locate the line
containing DRSED.  Add the following line after it:
.BREAK
.BLANK 1
[1,24]RSX11M/LB:DRSEM
.BLANK 1
If you are building the executive with directive commons the module DRSEM
should be placed in EXCOM2. Find the two lines containing
DRSMG and add :DRSEM to the end of each line.
When finished the following should appear twice in RSXBLD.CMD:
.LITERAL

LB:[1,24]RSX11M/LB:DRASG:DRATP:DRCIN:DREXP:DRGEF:DRGTP
LB:[1,24]RSX11M/LB:DRMAP:DRREG:DRSMG:DRSEM
LB:[1,1]EXELIB/LB

.END LITERAL
.BLANK 1
The SYSGEN can proceed normally from this point.
.AUTOPARAGRAPH 
.NOJUSTIFY
	When the SYSGEN is finished you can add the file SEMDIR.MAC
to [1,1]RSXMAC.SML so the macros SEMP$S and SEMV$S will be
available. Also the file SEMCAL.MAC should be assembled and the object
module placed in [1,1]SYSLIB.OLB, [1,1]ANSLIB.OLB, [1,1]F4POTS.OLB,
and/or [1,1]FOROTS.OLB so the FORTRAN
subroutines SEMP and SEMV are available.
 
	To demonstrate the functioning of the semaphores, compile and
build the programs SEMTEST.FTN
and SEMTEST2.FTN. By running multiple copies of SEMTEST from
several terminals you can see how the semaphore functions
allow only one program at a time to execute the "critical region"
between the P-operation and the V-operation.
The program SEMTEST2 works in a similar manner, but it calls
SEMP twice and prints the directive status from each directive call.
List these programs to see what they do.
 
	The following pages describe the executive directives in the
format of the ^&Executive Reference Manual\&. Additional information
about semaphores is given in the paper "Implementation and
Application  of Semaphores in RSX-11M" presented at the Fall 1979
DECUS. This appears in the ^&Proceedings of the Digital Equipment
Computer Users Society USA 1979 Fall\&. Reprints are available from
the author.
.NOHEADER
.PAGE
SEMP$S (only $S form supplied)
.SKIP 1
Semaphore P-operation
 
	The Semaphore P-operation instructs the executive to place
the issuing task on the specified semaphore list. If there is already
a task on the list the issuing task is suspended.
If no other task is on the list the issuing task continues execution.
.SKIP 1
FORTRAN call:
.SKIP 1
CALL SEMP(number[,ids])
.P 5
number#=#Semaphore number
.P 5
ids####=#Directive status
.SKIP 1
Macro call:
.SKIP 1
SEMP$S number[,error]
.P 5
number#=#Semaphore number
.P 5
error##=#Error routine address
.SKIP 1
DSW Return Codes:
.LEFT MARGIN 15
.P -10
IS.SPD -- Successful Completion (task was suspended)
.P
IS.SUC -- Successful completion (task was not suspended)
.P
IE.UPN -- Insufficient dynamic memory
.P
IE.ILU -- Semaphore number outside allowable range (range is 1-20;
upper limit is alterable at system generation time; see module DRSEM.MAC)
.P
IE.ITS -- Program is already on the specified semaphore queue
.P
IE.ADP -- Part of DPB is out of the issuing task's address space
.P
IE.SDP -- DIC or DPB size is invalid
.SKIP 1
.LEFT MARGIN 0
Notes:
.LIST 1
.LE
If the task is suspended the suspend status bit is set; see
description of directive SPND$ for additional notes.
.PAGE
SEMP$S (cont.)
.LE
Since the suspend bit is used the task may be resumed by the MCR command
or the executive directive. If this is done proper operation of the
semaphore will be impossible.
.LE
There are two successful completion codes, IS.SPD = +2 and IS.SUC = +1.
If you are interested in knowing whether or not a program is actually
suspended when it calls SEMP$S, the status returned will tell you.
.END LIST
.PAGE
SEMV$S (only $S form supplied)
.SKIP 1
Semaphore V-operation
.PARAGRAPH 5,1
The Semaphore V-operation instructs the executive to remove the
issuing task from the head of the specified semaphore list.
If any other tasks are on the list the one at the head is resumed.
If the issuing task is not at the head of the specified list
no action is taken and status code IE.ULN is returned.
.SKIP 1
FORTRAN call:
.SKIP 1
CALL SEMV(number[,ids])
.P 5
number#=#Semaphore number
.P 5
ids####=#Directive status
.SKIP 1
Macro call:
.SKIP 1
SEMV$S number[,error]
.P 5
number#=#Semaphore number
.P 5
error##=#Error routine address
.SKIP 1
DSW Return Codes:
.LEFT MARGIN 15
.P -10
IS.SUC -- Successful completion
.P
IE.ULN -- Task was not at head of the specified list (Note 1)
.P
IE.ACT -- Next task on list was not active (Note 2)
.P
IE.ITS -- Next task on list was not suspended (Note 2)
.P
IE.ADP -- Part of DPB is out of issuing task's address space
.P
IE.SDP -- DIC or DPB size is invalid
.SKIP 1
.LEFT MARGIN 0
Notes:
.LIST 1
.LE
This will result if the task calls SEMV$S without having previously
called SEMP$S with the same semaphore number.
.LE
This may be caused if a program using the semaphores is resumed by
the MCR command or executive directive.
.LE
When a task exits the executive cleans up the
semaphore lists. If the exiting task has failed to do any required SEMV$S
directives, they are simulated by the executive.
.END LIST