.TITLE	USERMAC - USER MACROS
	.IDENT	/Y01/
	.SBTTL	PMSGDF - DEFINE I/O BLOCKS

;+
; THE FOLLOWING MACROS ARE UTILITY MACROS FOR TERMINAL I/O.
; TO USE THEM IN A TASK, THE USER PROVIDES THE FOLLOWING WITHIN
; THE ROOT SEGMENT:
;
;  1. AN INVOCATION TO PMSGDF IS REQUIRED TO DEFINE THE QIO$S
;     FOR OUTPUT. THE PMSGDF CALL TAKES THE FOLLOWING FORM:
;
;	PMSGDF	SECT,LUN,FEFLAG,NEFLAG
;
;     WHERE:
;      'SECT' IS THE (OPTIONAL) PROGRAM SECTION WHICH
;       IS REDEFINED AFTER THE P.MSG ROUTINE IS DEFINED IN
;       PSECT $CODE.
;
;       'LUN' IS AN OPTIONAL UNIT NUMBER USED FOR THE OUTPUT.
;       IF NOT SPECIFIED, UNIT 5 IS USED (DEFAULT FOR TI:).
;
;       'FEFLAG' IS THE FIRST EVENT FLAG USED IN THE QIO$ REQUESTS.
;       IF NOT SPECIFIED, EVENT FLAG 1 IS USED.
;
;       'NEFLAG' IS THE NUMBER OF SEQUENTIAL EVENT FLAGS USED FOR
;       ALL QIO$ REQUESTS. THE FIRST QIO$ USES 'FEFLAG', THE NEXT
;       USES 'FEFLAG+1', AND SO ON, UP TO 'FEFLAG+NEFLAG-1', THEREUPON
;       CYCLING BACK TO 'FEFLAG'. IF THIS ARGUMENT IS UNSPECIFIED,
;       A VALUE OF 1 IS USED.
;
;  2. THE USER MAY DISCERN THE EVENT FLAG USED FOR THE LAST QIO$
;     REQUEST BY EXAMINING THE GLOBAL WORD P.CEFN. THIS IS USEFUL IN
;     APPLICATIONS WHERE MULTIPLE QIO$ REQUESTS ARE ISSUED WITH A 
;     SINGLE WAIT PERFORMED ON THE FINAL REQUEST.
;
;  3. THE USER MAY DECIDE IF THE STSE$ DIRECTIVE IS TO BE USED
;     FOR PENDING I/O OVER THE WTSE$ DIRECTIVE. TO USE THE
;     STSE$ DIRECTIVE, DEFINE THE SYMBOL 'P.STP' IN THE PROGRAM.
;-

	.MACRO	PMSGDF	SECT,LUN,FEFLAG,NEFLAG,?B
	.PSECT	$CODE
.IF	NB	<LUN>
$$LUN = LUN
.IFF
$$LUN = 5
.ENDC
.IF	NB	<FEFLAG>
$$EFN = FEFLAG
.IFF
$$EFN = 1
.ENDC
.IF	NB	<NEFLAG>
$$NEF = NEFLAG
.IFF
$$NEF = 1
.ENDC
P.FLAG:	.WORD	0
P.CEFN::.WORD	$$EFN - 1
	.MCALL	QIO$S
P.MSG::
	CLR	P.FLAG		; DON'T WAIT FOR COMPLETION
	BR	.+6
P.MSGW::
	MOV	R0,P.FLAG	; MAKE FLAG NON-ZERO
.IF	GT	<$$NEF-1>
	INC	P.CEFN
	CMP	P.CEFN,#<$$EFN+$$NEF-1>
	BLE	.+10
	MOV	#$$EFN,P.CEFN
.ENDC
	QIO$S	#IO.WLB,#$$LUN,P.CEFN,,,,<R0,R1,R2>
	TST	P.FLAG		; CHECK FLAG POLARITY
	BEQ	B		; DON'T WAIT
.IF	NDF	P.STP
	.MCALL	WTSE$S
	WTSE$S	P.CEFN		; WAIT FOR COMPLETION
.IFF
	.MCALL	STSE$S
	STSE$S	P.CEFN		; STOP FOR COMPLETION
.ENDC
B:	RETURN

.IF	NB	<SECT>
	.PSECT	SECT
.IFF
	.PSECT
.ENDC
	.ENDM	PMSGDF
	.PAGE
	.SBTTL	PRINT MACRO
;+
; MACRO PRINT - PRINT A STATIC STRING ON THE TERMINAL
;
; THE PRINT MACRO CALL TAKES THE FOLLOWING FORM:
;
;	PRINT	<MESSAGE> [,SECT] [,WTFLG]
;
; WHERE 'MESSAGE' IS THE TEXT TO BE PRINTED (NO CONTROL CHARACTERS).
;       THE FIRST CHARACTER IN THE 'MESSAGE' STRING IS USED FOR
;	CARRIAGE CONTROL (FORTRAN STYLE - SEE I/O DRIVERS REFERENCE
;	MANUAL IN THE TERMINAL DRIVERS SECTION). 
;
;	'SECT' IS AN OPTIONAL ARGUMENT SPECIFYING THE PROGRAM
;	SECTION IN WHICH THE PRINT MACRO OCCURS. IF NOT SPECIFIED,
;	THE BLANK .PSECT IS ASSUMED. 
;
;	'WTFLG' IS AN OPTIONAL ARGUMENT SPECIFYING WHETHER A
;	WAITFOR OR STOPFOR IS TO BE INVOKED ON THE QIO REQUEST. IF THE
;	ARGUMENT EQUALS ZERO, THEN NO WAIT IS PERFORMED. IF
;	THE ARGUMENT IS NONZERO OR MISSING, THEN A WTSE$S OR STSE$S IS
;	EXECUTED TO WAIT FOR THE I/O COMPLETION BEFORE RETURN
;
; THE MESSAGE TEXT IS STORED IN .PSECT MSGTXT. AFTER PRINTING
; THE MESSAGE, PROGRAM CONTROL FALLS TO THE NEXT ADDRESS IN
; .PSECT 'SECT', AND THUS THE 'SECT' PARAMETER MUST BE SET CORRECTLY.
;
; NOTE: IF LOCAL SYMBOLS WILL BE USED IN THE USER PROGRAM, AND
;	ANY OF THE LOCAL SYMBOLS ARE REFERENCED ACROSS THE CALL
;	TO PRINT, THEN AN ".ENABL LSB" DIRECTIVE MUST BE INVOKED
;	BEFORE THE CALL TO PRINT. NOTE THAT THE .ENABL LSB
;	MUST OCCUR BEFORE A .PSECT DIRECTIVE IF THE LOCAL SYMBOL
;	BLOCK IS TO APPLY TO THAT .PSECT.
;-
	.MACRO	PRINT	MESSAGE,SECT,WTFLG
	.PSECT	MSGTXT,RO
	.NCHR	MSGLEN,<MESSAGE>
MSGADR = .
	.ASCII	\MESSAGE\

.IF	NB	<SECT>
	.PSECT	SECT
.IFF
	.PSECT
.ENDC
	.MCALL	PMSG
.IF	NB	<WTFLG>
	PMSG	<#<MSGADR+1>>,<#<MSGLEN-1>>,MSGADR,<WTFLG>
.IFF
	PMSG	<#<MSGADR+1>>,<#<MSGLEN-1>>,MSGADR
.ENDC

	.ENDM	PRINT
	.PAGE
	.SBTTL	ERROR - PRINT ERROR MACRO

;+
; ERROR - PRINT STATIC ERROR MESSAGE AND JUMP TO LABEL OR EXIT
;
; ERROR IS A NICE WAY OF PRINTING A DIAGNOSTIC AND BAILING OUT
; OF A TASK. THE FORM OF THE MACRO CALL IS:
;
;	ERROR	<MESSAGE>, [LABEL] [,SECT] [,WTFLG]
;
; WHERE 'MESSAGE', 'SECT', AND 'WTFLG' ARE EXACTLY THE SAME
;	FOR THE PRINT MACRO.
;
;	'LABEL', IF SPECIFIED, CAUSES A 'JMP' TO BE EXECUTED
;	TO THE LABEL UPON COMPLETION OF THE QIO; OTHERWISE, AN
;	EXIT$S IS GENERATED AND EXECUTED.
;
; NOTE: SINCE THE ERROR MACRO CALLS THE PRINT MACRO, THE SAME
;	PROCEDURE FOR THE USE OF LOCAL SYMBOLS IN THE PROGRAMMER'S
;	CODE MUST BE FOLLOWED AS PER THE NOTE IN THE DESCRIPTION
;	OF THE PRINT MACRO.
;-
	.MACRO	ERROR	MESSAGE,LABEL,SECT,WTFLG
	.MCALL	PRINT
.IF	NB	<WTFLG>
	PRINT	<MESSAGE>,<SECT>,<WTFLG>
.IFF
	PRINT	<MESSAGE>,<SECT>
.ENDC
.IF	NB	<LABEL>
	JMP	LABEL
.IFF
	.MCALL	EXIT$S
	EXIT$S
.ENDC
	.ENDM	ERROR
	.PAGE
	.SBTTL	PMSG - PRINT ARBITRARY MESSAGE

;+
; PMSG - PRINT ARBITRARY MESSAGE
;
; PMSG IS A MACRO IDEAL FOR PRINTING A DYNAMIC STRING. THE CALL IS:
;
;	PMSG	[BUF] [,[BUFLEN] [,[CC] [,[WTFLG]]]]
;
; WHERE	'BUF' IS THE STARTING ADDRESS OF THE STRING. IF NOT
;	SPECIFIED, R0 IS ASSUMED TO CONTAIN THIS ADDRESS.
;
;	'BUFLEN' IS THE LENGTH, IN BYTES, OF THE STRING IN 'BUF'.
;	IF UNSPECIFIED, R1 IS ASSUMED TO CONTAIN THE BYTE COUNT.
;
;	'CC' IS THE CARRIAGE CONTROL CHARACTER TO BE USED FOR
;	THE I/O OPERATION. IF UNSPECIFIED, THE CONTENTS OF R2 IS
;	INTERPRETED TO CONTAIN THE CARRIAGE CONTROL CHARACTER.
;
;	NOTE WELL! THE ABOVE ARGUMENTS MUST BE VALID OPERANDS
;	FOR MOV INSTRUCTIONS. IN ADDITION, IF REGISTERS ARE TO
;	BE USED AS ARGUMENTS TO PMSG, IT IS RECOMMENDED THAT
;	THE DEFAULT REGISTER ASSIGNMENTS INDICATED ABOVE ARE
;	ADHERED TO, BECAUSE IMPROPER USAGE MAY CAUSE REGISTERS
;	TO BE MASHED. IN PARTICULAR, THE CALL
;
;		PMSG	#BUF,#BFLN,R0
;
;	WILL CAUSE THE WRONG VALUE TO BE USED FOR CARRIAGE CONTROL.
;
;	'WTFLG' IS THE SAME AS FOR THE PRINT MACRO ABOVE.
;-
	.MACRO	PMSG	BUFADR,BUFLEN,CC,WTFLG

.IF	NB,<BUFADR>
	MOV	R0,-(SP)
	MOV	BUFADR,R0
.ENDC
.IF	NB,<BUFLEN>
	MOV	R1,-(SP)
	MOV	BUFLEN,R1
.ENDC
.IF	NB,<CC>
	MOV	R2,-(SP)
	MOVB	CC,R2
.ENDC

.IF	NB	<WTFLG>
.IF	EQ	<WTFLG>
	CALL	P.MSG
.IFF
	CALL	P.MSGW
.ENDC
.IFF
	CALL	P.MSGW
.ENDC

.IF	NB,<CC>
	MOV	(SP)+,R2
.ENDC
.IF	NB,<BUFLEN>
	MOV	(SP)+,R1
.ENDC
.IF	NB,<BUFADR>
	MOV	(SP)+,R0
.ENDC
	.ENDM	PMSG