.TITLE UNLOCK
	.IDENT /17JA87/
;
;	File:[22,310]UNLOCK.MAC
;	Author: Philip Hannay.  17-Jan-87.  Derived from Pasutl LOCKER
;	History: Philip Hannay.  17-Jan-87.  Created.
;
;  Phil Hannay  5-Jun-84  Modified UNLOCK procedure to wait 5 ticks after
;  unlocking the file (setting the flag) before exiting.  The reason for
;  this is to give another program waiting for this file a chance to get
;  in and lock the file.  Otherwise, this caller can relock the file
;  right away again if it desires and effectivly monopolize the file
;  until it blocks for some other reason.  Note that we use a WTSE for
;  the mark time so that we will not checkpoint unless absolutely 
;  required.
;
;	Last Edit: 17-JAN-1987 21:57:53 

.rem |

Function UNLOCK ( EFN:Event_Flag): boolean; External;

{*USER*

UNLOCK a resource(s) associated with the global event flag EFN.  
The unlock operation is unconditional (the flag is always set).
However, the function returns a boolean value where TRUE is
"resource was locked and is now unlocked", while FALSE is
"resource was not locked and remains unlocked". 

You should use the boolean value returned to make sure all programs
are following the rules of locking and unlocking, issuing an error
message if you find a resource unlocked when you expected it to be
locked.  This points to a programming error or abnormally ending program.

Be sure group global flags are created before attempting to use them.
If the group globals do not exist, a directive error will occur in the
function, and the value of FALSE will be returned indicating and error.

Note:  This module uses a different locking scheme than normally used.
A set flag denotes an unlocked file, region or port,
while a clear flag denotes a locked file, region or port.
This procedure enables us to use waits triggered by flag
sets to make for instant response to a changed lock state while remaining
inactive during the wait interval.  This allows for the most efficient
interactive file, region and port sharing possible by multiple programs.

}

{*WIZARD*

The UNLOCK procedure to wait 5 ticks after
unlocking the file (setting the flag) before exiting.  The reason for
this is to give another program waiting for this file a chance to get
in and lock the file.  Otherwise, this caller can relock the file
right away again if it desires and effectivly monopolize the file
until it blocks for some other reason.  Note that we use a WTSE for
the mark time so that we will not checkpoint unless absolutely 
required.

There is no provision to automatically reset a locked resource if the
caller fails to unlock it (program error or abnormal end).  If it is
required, the caller should look at an outside method (watchdog program)
that will unlock the resources automatically in the event of an error.
This function does an unconditional unlock, and could be used by
such an outside method.

} 

|

;
; Assemble with PASMAC.MAC as prefix file.
;
;

	.ENABL	LSB
	.MCALL	SETF$S
	.MCALL	MRKT$S
	.MCALL	WTSE$S
	
	FUNC UNLOCK, STAT, BOOLEAN
	PARAM EFN, CHAR
	SAVE <R0>

	BEGIN
	MOVB EFN(SP),R0			;MOVE EFN NUMBER TO R0
	CMP	R0,#33.			;CHECK TO SEE IF RESOURCE LOCK FLAG IS
					;WITHIN THE CORRECT RANGE 33 THRU 96
	BLT	19$			;ERROR IF FLAG IS LESS THAN 34
	CMP	R0,#96.			;CHECK THE UPPER LIMIT
	BGT	19$			;EMULATE ERROR IF FLAG GT 96
	CMP	R0,#57.			;CHECK TO SEE IF LOCK FLAG IS
					;WITHIN RESERVE SYS RANGE 57 THRU 64
	BLT	5$			;BRANCH IF FLAG IS LESS THAN 57
	CMP	R0,#64.			;CHECK THE UPPER LIMIT
	BLE	19$			;EMULATE ERROR IF FLAG IN SYS RANGE
5$:	CMP	R0,#33.			;33 IS NOT A VALID FLAG FOR USE
	BEQ	19$			;EMULATE ERROR IF FLAG IS 33
	CMP	R0,#49.			;49 IS NOT A VALID FLAG FOR USE
	BEQ	19$			;EMULATE ERROR IF FLAG IS 49
	CMP	R0,#65.			;65 IS NOT A VALID FLAG FOR USE
	BEQ	19$			;EMULATE ERROR IF FLAG IS 65
	CMP	R0,#81.			;81 IS NOT A VALID FLAG FOR USE
	BEQ	19$			;EMULATE ERROR IF FLAG IS 81

					;VALID LOCK FLAG
	SETF$S	R0			;CLEAR THE FLAG
	CMP	$DSW,#IS.CLR		;MAKE SURE RESOURCE WAS LOCKED BEFORE
	BEQ	1$			;BRANCH IF ALL OKAY
19$:	CLRB	STAT(SP)		;DIRECTIVE FAILURE OR RESOURCE WAS NOT
					;LOCKED WHEN UNLOCKED OR FLAG NUMBER
					;SUPPLIED NOT VALID.  INDICATE ERROR
					;BY SETTING STATUS TO FALSE
	BR	2$			;GO AROUND SUCCESS STUFF
1$:	MOVB	#1,STAT(SP)		;INDICATE ALL OKAY BY STATUS SET TRUE
2$:	MRKT$S	#24.,#5,#1		;SET FLAG 24 AFTER 5 TICKS
	BCS	3$			;NO WAIT IF DIRECTIVE FAILS
	WTSE$S	#24.			;WAIT FOR FLAG 24 - USE WAIT SINCE
3$:					; WE DONT WANT TO CHECKPOINT
					; IF POSSIBLE.
	ENDPR
	.END