.TITLE	LIB_ABS_QUEUES Absolute queue manipulation routines
	.IDENT	/V01.01/

;++LIBABSQUE.MAR
;
; Facility: 
;	Fermilab Accelerator Control System (ACNET) General Routine
;
; Abstract:
;	This package contains routines to allow High Level Languages access
;	to the VAX-11 INSQUE and REMQUE instructions to manipulate absolute
;	queues (similar to the LIB$INSQxI and LIB$REMQxI RTL routines that
;	manipulate self-relative queues).
;
; Environment:
;	Stored in FERMILIB.OLB library, linked into users' programs.
;
;--
;
; Modification History:
;
; Author: A. Waller			Creation date: 15-Jul-82
;
; V01.00  19-Sep-82	FJN	Editted for addition to FERMILIB routines
; V01.01  15-Apr-83	FJN	Changed help text for standardization
;
	.PAGE
	.SUBTITLE	Declarations

;
; Include Files:
;
;	NONE
;
; Library Macros:
;
	.NOCROSS
	$SSDEF				;Define system completion status codes
	$LIBDEF				;Define RTL completion status codes
	.CROSS
;
; Local Macros:
;
;	NONE
;
; Equated Symbols:
;
;	NONE
;
; Program section for code
;
	.PSECT	_LIB_CODE,PIC,USR,CON,REL,LCL,SHR,EXE,NOWRT,RD
	.SHOW	BINARY

	.PAGE
	.SUBTITLE	LIB_INSQUE insert entry into queue

;+0LIB_INSQUE
;
; Functional Description:
;	LIB_INSQUE inserts a queue entry into the specified absolute queue.
;
; Calling Sequence:
;	ret-status = LIB_INSQUE(entry,pred)
;
; Input Parameters:
;	entry - Address of array that must be at least 8 bytes long.  Bytes
;		following the first 8 bytes can be used for any purpose by
;		the calling program (first 8 bytes are reserved for the forward
;		and backward links of the queue).
;	pred  - Address of longword containing the absolute address of the
;		current queue entry after which the new entry is to be
;		inserted.
;
; Implicit Inputs:
;	NONE
;
; Output Parameters:
;	pred  - Queue links are updated to reflect insertion of the new entry.
;
; Implicit Outputs:
;	NONE
;
; Condition Codes:
;	SS$_NORMAL	successful completion
;	LIB$_ONEENTQUE	entry is first entry in the queue
;
; Side Effects:
;	Queue header modified by LIB_INSQUE call if entry inserted 
;	onto head or tail of queue.
;-
;+ LIB_INSQUE
; Insert an entry onto an absolute queue using the VAX-11 INSQUE
; instruction.
;
; ret-status.wlc.v = LIB_INSQUE( entry.mqu.ra, pred.ra.r )
;
;  ret-status   completion status code for routine:
;               SS$_NORMAL      successful completion.
;               LIB$_ONEENTQUE  entry is the first in the queue.
;               Passed by value.
;
;  entry        an array that must be at least 8 bytes long.  Any bytes
;               following the first 8 bytes may be used for any purpose
;               by the calling module (the first 8 bytes are reserved
;               for the forward and backward links of the queue). Passed
;               by reference.
;
;  pred         longword containing the absolute address of the current
;               queue entry before which the new entry is to be inserted.
;               Passed by reference.
;
;2 Header
; An absolute queue is described by a header consisting of two longwords.
; Each entry in the queue also consists of (at least) two longwords which
; contain the forward and backward link pointers of the queue as absolute
; addresses of the predecessor and trailing queue entries.  The link
; pointers of the queue header point to the first and last queue entries.
;
; An empty queue consists of just the queue header in which both the
; forward (first longword) and backward (second longword) link pointers
; point to the queue header itself (addresses of the first longword of
; the queue header).
;2 Examples
; If the queue header has been declared as:
;
;       INTEGER*4 header(2)
;
; then an entry may be inserted at the head of the queue by:
;
;          LIB_INSQUE(new_entry, header)      or
;          LIB_INSQUE(new_entry, header(1))
;
; and at the tail of the queue by either of:
;
;          LIB_INSQUE(new_entry, %VAL(header(2)))  or
;          LIB_INSQUE_TAIL(new_entry, header)
;
; or after an old entry by doing:
;
;	   LIB_INSQUE(new_entry, old_entry)
;
; where new_entry and old_entry are the arrays themselves.  If the
; address of the new queue entry is stored in a longword (entry),
; then to insert onto the head of the queue do:
;
;          LIB_INSQUE(%VAL(entry), header(1))
;
; and so forth.
;-

	.ENTRY	LIB_INSQUE,^M<>
	MOVL	8(AP),R0		;Get address of predecessor/header
	BRB	BOTH_INSQUE

;+ LIB_INSQUE_TAIL
; Insert an entry onto the tail of an absolute queue using the
; VAX-11 INSQUE instruction.
;
; ret-status.wlc.v = LIB_INSQUE_TAIL( entry.mqu.ra, header.mqu.r )
;
;  ret-status   completion status code for routine:
;               SS$_NORMAL      successful completion.
;               LIB$_ONEENTQUE  entry is the first in the queue.
;               Passed by value.
;
;  entry        an array that must be at least 8 bytes long.  Any bytes
;               following the first 8 bytes may be used for any purpose
;               by the calling module (the first 8 bytes are reserved
;               for the forward and backward links of the queue). Passed
;               by reference.
;
;  header       the quadword queue header (an array of two longwords)
;               for the absolute queue.  Passed by reference.
;
; See also LIB_INSQUE.
;-

	.ENTRY	LIB_INSQUE_TAIL,^M<>
	MOVZBL	#1,R0			;Setup index to get backward link ptr
	MOVL	@8(AP)[R0],R0		;Get address of queue's tail entry
;
; Common code for LIB_INSQUE routines
;
BOTH_INSQUE:
	INSQUE	@4(AP),(R0)		;First parameter is new entry's address
	BEQL	ONE_ENT			;Z-flag set if first entry in queue

;
; Return particular status codes depending upon conditions
;
SUCCESS:
	MOVZWL	#SS$_NORMAL,R0		;Success
	RET
ONE_ENT:
	MOVL	#LIB$_ONEENTQUE,R0	;Success: queue has/had single entry
	RET
EMPTY:
	MOVL	#LIB$_QUEWASEMP,R0	;Error: queue was empty
	RET

	.PAGE
	.SUBTITLE	LIB_REMQUE remove an entry from queue

;+0LIB_REMQUE
;
; Functional Description:
;	LIB_REMQUE removes a queue entry from the specified absolute queue.
;
; Calling Sequence:
;	ret-status = LIB_REMQUE(link,remque-adr)
;
; Input Parameters:
;	link  - Address of a longword containing the absolute address of
;		the queue entry to be removed from the queue.
;
; Implicit Inputs:
;	NONE
;
; Output Parameters:
;	remque-adr - Address of a longword to receive the address of the
;		     removed queue entry.
;
; Implicit Outputs:
;	NONE
;
; Condition Codes:
;	SS$_NORMAL	successful completion
;	LIB$_ONEENTQUE	entry was the last entry in the queue
;	LIB$_QUEWASEMP	tried to remove an entry from an already empty queue
;
; Side Effects:
;	Header modified on return from LIB_REMQUE call if the entry was
;	inserted or removed from head or tail of queue.
;-
;+ LIB_REMQUE
; Remove an entry from an absolute queue using the VAX-11 REMQUE
; instruction.
;
; ret-status.wlc.v = LIB_REMQUE( link.mqu.ra, remque-adr.wa.r )
;
;  ret-status   completion status code for routine:
;               SS$_NORMAL      successful completion.
;               LIB$_ONEENTQUE  entry was the last entry in the queue.
;               LIB$_QUEWASEMP  queue was already empty (remque-adr is
;                               meaningless).
;               Passed by value.
;
;  link         longword containing the absolute address of the entry
;               to be removed from the queue.  Passed by reference.
;
;  remque-adr   longword in which the address of the removed entry is
;               returned.  Passed by reference.
;
;2 Header
; An absolute queue is described by a header consisting of two longwords.
; Each entry in the queue also consists of (at least) two longwords which
; contain the forward and backward link pointers of the queue as absolute
; addresses of the predecessor and trailing queue entries.  The link
; pointers of the queue header point to the first and last queue entries.
;
; An empty queue consists of just the queue header in which both the
; forward (first longword) and backward (second longword) link pointers
; point to the queue header itself (addresses of the first longword of
; the queue header).
;2 Examples
; If the queue header and an entry pointer have been declared as:
;
;       INTEGER*4 header(2), entry
;
; then the entry at the head of the queue is removed by:
;
;          LIB_REMQUE(header(1), entry)
;
; and the entry at the tail is removed by:
;
;	   LIB_REMQUE(header(2), entry)
;
; If entry contains the address of a particular entry on the queue,
; then that entry can be removed by:
;
;          LIB_REMQUE(entry, entry)
;
;-

	.ENTRY	LIB_REMQUE,^M<>
	MOVL	@4(AP),R0		;Get address of longword entry pointer
	REMQUE	(R0),@8(AP)		;Return address of entry in 2nd arg.
	BVS	EMPTY			;Must check V-flag first before Z-flag
	BEQL	ONE_ENT			;Z-flag set if last queue entry removed
	MOVZWL	#SS$_NORMAL,R0		;Neither set if more than 1 entry
	RET

	.PAGE
	.SUBTITLE	LIB_INIT_QHDR initialize an absolute queue header

;+0LIB_INIT_QHDR
;
; Functional Description:
;	LIB_INIT_QHDR initializes the header for an absolute queue.
;
; Calling Sequence:
;	CALL LIB_INIT_QHDR( header )
;
; Input Parameters:
;	header - address of the quadword queue header
;
; Implicit Inputs:
;	NONE
;
; Output Parameters:
;	header - quadword absolute queue is initialized to empty.
;
; Implicit Outputs:
;	NONE
;
; Condition Codes:
;	NONE
;
; Side Effects:
;	NONE
;-
;+ LIB_INIT_QHDR
; Initialize the queue header of an absolute queue to empty.
;
; CALL LIB_INIT_QHDR( header.mqu.ra )
;
;  header       the quadword queue header (an array of two longwords)
;               for the absolute queue.  Passed by reference.
;
;-

	.ENTRY	LIB_INIT_QHDR,^M<>
	MOVL	4(AP),R0		;Get address of queue header itself
	MOVL	R0,(R0)			;Initialize forward queue link
	MOVL	(R0)+,(R0)		;Initialize backward queue link
	RET

	.END