PDP-10.stacken/files/stacken-tape-backup/dskb:10_7/soupr/parse.rno

.CH NAMING CONVENTIONS
.AP
.NPR
.LC
	^P^A^R^S^E HAS ADOPTED THE FOLLOWING CONVENTIONS
FOR NAMING SUBROUTINES:
.B 1
.LM 5
.TS 5
.I -5
1.	^INPUT ROUTINES END IN THE LETTER "^I". ^E.^G.
^S^I^X^I INPUTS A ^S^I^X^B^I^T WORD, ^O^C^T^I INPUTS
AN OCTAL NUMBER, ETC.
.B 1
.I -5
2.	^OUTPUT ROUTINES END IN THE LETTER "^O".
^E.^G. ^S^I^X^O OUTPUTS A ^S^I^X^B^I^T WORD,
^O^C^T^O OUTPUTS AN OCTAL NUMBER, ETC.
.B 1
.I -5
3.	^PREDICATES END IN THE LETTER "^P". ^MUCH
LIKE THEY DO IN ^L^I^S^P. ^E.^G. ^W^I^L^D^P
TESTS WHETHER A FILE SPEC IS WILD OR NOT. ^W^I^L^D^P
WILL SKIP IF THE SPEC IS FOUND TO BE WILD.
.LM 0
.CH AC'S
.NPR
.AP
.LC
	^P^A^R^S^E USES THE FOLLWING CONVENTIONS
FOR THE NAMING AND USAGE OF ACCUMULATORS:
.B 1
.LM 5
.TS 5
.I -5
1.	^NO ROUTINE IS EXPECTED TO PRESERVE ^T1-^T4.
^HENCE ALL ROUTINES HAVE FAST ACCESS TO TEMPORARY SCRATCH SPACE.
.I -5
2.	^ACCUMULATOR SYMBOLS ARE DEFINED IN THE UNIVERSAL
FILE ^P^R^S.
.I -5
3.	^T1-^T4 ARE GUARANTEED TO BE CONSECUTIVE ^A^C'S IN
THAT ORDER.
.I -5
4.	^ALL ROUTINES ARE EXPECTED TO PRESERVE ^P1-^P4.
.I -5
5.	^P1-^P4 ARE GUARANTEED TO BE CONSECUTIVE ^A^C'S IN
THAT ORDER.
.I -5
6.	^C CONTAINS THE NEXT CHARACTER FOR ^I_/^O.
^ROUTINES THAT PARSE INPUT WILL LEAVE ^C
WITH THE FIRST CHARACTER FOR THE NEXT ROUTINE.
^E.^G. WHEN PARSING "^F^O^O.^M^A^C", ^S^I^X^I LEAVES
"." IN ^C.
^THUS "RE-EAT" AND LOOK AHEAD OPERATIONS ARE UNNECESSARY.
.I -5
7.	^P IS THE STACK POINTER.
.CH ERRORS
.NPR
.AP
.LC
	^MOST ROUTINES IN ^P^A^R^S^E NORMALLY RETURN ^C^P^O^P^J1.
^WHEN AN ERROR OCCURS, AN ERROR MESSAGE IS TYPED, AND THE
ROUTINE RETURNS ^C^P^O^P^J.
^THUS THE MAIN PROGRAM SHOULD NOT TYPE AN ERROR MESSAGE.
^BY THE TIME THE MAIN PROGRAM RECEIVES THE ^C^P^O^P^J RETURN,
THE MESSAGE HAS ALREADY BEEN TYPED.
	^THE FOLLOWING IS A LIST OF ALL THE ERROR MESSAGES
THAT ^P^A^R^S^E MIGHT TYPE:
.B 1
.UC
.FL CAP
.FL IND
?><PRSSYN SYNTAX ERROR
.B 1
?><PRSIN INPUT ERROR FOR \D\E\V
.B 1
?><PRSUKN UNKNOWN OR AMBIGUOUS ABBREVIATION \F\O\O
.B 1
%><WLDNSF NO SUCH FILES AS \F\I\L\E-\S\P\E\C
.B 1
?><PRSLKP LOOKUP ENTER ERROR \N \F\I\L\E-\S\P\E\C
.B 1
?><PRSCOR NOT ENOUGH CORE
.B 1
?><PRSOUT OUTPUT ERROR FOR \D\E\V
.B 1
?><PRSPTH ILLEGAL FORMAT FOR PATH
.B 1
.LC
.NFL CAP
.NFL IND
	^IF HOWEVER, THE USER WISHES TO HANDLE THE ERROR
HIMSELF, THE AUTOMATIC TYPEOUT CAN BE SUPPRESSED.
^THE TYPEOUT IS NORMALLY PERFORMED BY A ROUTINE CALLED <PREFIX>.
^WHERE <PREFIX> IS THE PREFIX THAT APPEARS IN THE
ERROR MESSAGE. ^TO SUPPRESS THE TYPEOUT, THE USER NEED
ONLY WRITE HIS OWN <PREFIX> ROUTINE.
^E.^G. ^TO SUPPRESS THE "OUTPUT ERROR" MESSAGE, THE
USER SHOULD WRITE A ROUTINE CALLED "^P^R^S^O^U^T".
^THE USER SHOULD
SPECIFY THE /^S^E^A^R^C^H SWITCH TO ^L^I^N^K SO THAT THE
NORMAL ROUTINE IS NOT LOADED.
^TO PERFORM ERROR RECOVERY, THE USER MERELY PLACES HIS
RECOVERY CODE INSIDE OF HIS <PREFIX> ROUTINE. ^P^A^R^S^E
DOESN'T NORMALLY ATTEMPT ANY ERROR RECOVERY OF IT'S OWN,
IT MERELY REPORTS THE ERRORS.
	^E^O^F (^END OF ^FILE) IS CONSIDERED TO BE AN
ERROR, BUT NO MESSAGE IS TYPED. ^WHEN A USER
GETS A ^C^P^O^P^J RETURN FROM AN INPUT ROUTINE, HE
SHOULD CHECK WHETHER THE ERROR WAS ^E^O^F. ^THIS
IS EASILY DETERMINED. ^ALL INPUT ERRORS LOAD THE
ACCUMULATOR ^C WITH A ^G^E^T^S^T^S. ^MERELY TEST
IF THE ^I^O.^E^O^F BIT IS ON IN THE ^R^H OF ^C.
.CH FILE SPECS
.AP
.NPR
.LC
.FL CAP
^SEVERAL ROUTINES IN <PARSE TAKE FILE SPECS AS ARGUMENTS.
^THE FILE SPECS ARE PASSED IN A SPECIAL ARGUMENT BLOCK
DEFINED IN THE UNIVERSAL FILE <PRS.
^THE BLOCK INCLUDES:
.B 1
.NF
<.SBSIZ	;^L^H=SIZE OF BLOCK (INCLUSIVE)
<.SBNXT	;^R^H=ADDRESS OF NEXT BLOCK (OR 0)
<.SBDEV	;DEVICE
<.SMDEV	;DEVICE MASK
<.SBPPN	;<PPN_&SFDS
<.SMPPN	;<PPN_&SFDS MASKS
<.SBNAM	;FILENAME
<.SMNAM	;FILENAME MASK
<.SBEXT	;^L^H=EXTENSION
<.SMEXT	;^R^H=EXTENSION MASK
<.SBMOD	;MODE
.B 1
.F
^WHERE BITS IN THE MASK ARE ONE IF THE FIELD IS WILD.
<E.G. THE MASK OF '^A?^C?' IS 770077.
	^AS AN EXAMPLE, THE FILE SPEC "^D^S^K?:^A?.*[10,1153,*]"
MIGHT BE CODED AS FOLLOWS. ^THE ACTUAL VALUES OF THE SYMBOLS
DEPEND UPON ASSEMBLY PARAMETERS.
.B 1
.TS 9,17,25
.NF
	<XWD	20,0	;<.SBSIZ,,.SBNXT
	<SIXBIT	</DSK/	;<.SBDEV
	770000		;<.SMDEV
	<XWD	10,1153	;<.SBPPN
	0		;SFDS
	0
	0
	0		;DELIMITER
	0		;<.SMPPN
	-1		;SFDS MASK
	0
	0
	<SIXBIT	</A/	;<.SBNAM
	<XWD	7700,0	;<.SMNAM
	<XWD	0,-1	;<.SBEXT,,.SMEXT
	<.IOASC		;<.SBMOD
.F
.CH ROUTINES
.NFL SPACE
.AP
.LC
.NPR
.FL IND
.TS 9,17,41
.HL 1 ^SAVING ^A^C'S
.HL 2 <SAVE4
	><SAVE4 IS A ROUTINE TO SAVE ^A^C'S ^P1-^P4 ON THE STACK.
^IT IS NOT NECESSARY TO EXPLICITELY CALL A ROUTINE TO RESTORE THEM,
AS <SAVE4 WILL PLACE THE ADDRESS OF SUCH A ROUTINE ON THE
STACK. ^WHEN THE USER ROUTINE ^P^O^P^J'S, THE ^A^C'S WILL
AUTOMATICALLY BE RESTORED. ^SKIP RETURNS ARE ALSO
LEGAL. ^THE CALLING SEQUENCE IS:
.B 1
.NF
	<PUSHJ	<P,SAVE4##
	.
	.
	.
	<POPJ	^P,
.F
.HL 2 <SAVE3
	><SAVE3 IS LIKE <SAVE4, EXCEPT THAT ONLY ^P1-^P3
ARE SAVED.
.HL 2 <SAVE2
	><SAVE2 IS LIKE <SAVE3, EXCEPT
THAT ONLY ^P1-^P2 ARE SAVED.
.HL 2 <SAVE1
	><SAVE1 IS LIKE <SAVE2, EXCEPT THAT ONLY ^P1 IS
SAVED.
.HL 1 ^COMMON RETURNS
.HL 2 <CPOPJ
	><CPOPJ IS A NULL ROUTINE. ^I.^E. IT MERELY DOES A
<POPJ.
.HL 2 <CPOPJ1
	><CPOPJ1 IS LIKE <CPOPJ, EXCEPT THAT IT SKIPS.
.HL 1 ^CORE ^MANAGEMENT
.HL 2 <GETBLK
	^ALL ROUTINES IS <PARSE USE ><GETBLK TO ALLOCATE
CORE DYNAMICALLY. ^FREE CORE IS FASHIONED INTO A LINKAGE LIST.
^EACH ITEM IN THE LIST TAKES THE FORM:
.B 1
.NF
	<XWD	N,_<ADR NEXT BLK_>
	<BLOCK	N-1
.B 1
.F
^THE ADDRESS OF THE FIRST BLOCK IS STORED IN THE LOCATION ><FREMEM.
^THE ERROR MESSAGE ><PRSCOR IS TYPED IF THERE ISN'T ENOUGH
CORE. ^THE CALLING SEQUENCE IS:
.B 1
.NF
	<MOVEI	^T1,_<# WORDS_>	;PRESERVED
	<PUSHJ	<P,GETBLK##
	 ;ERROR RETURN (NOT ENOUGH CORE)
	;NORMAL RETURN (^T2 CONTAINS ADR BLK)
.F
.HL 2 <PUR (PURGE CORE)
	><PUR IS A ROUTINE TO RECLAIM CORE FROM A LINKAGE LIST.
^THE ENTIRE LIST IS LINKED TO ><FREMEM. ^THE CALLING
SEQUENCE IS:
.B 1
.NF
	<MOVEI	^T1,_<ADR OF ADR OF 1ST BLK_>
	<PUSHJ	<P,PUR##
	;ONLY RETURN
.F
.HL 1 <FNDNAM
	><FNDNAM IS A ROUTINE TO SEARCH A TABLE FOR A SIXBIT
NAME. ^UNAMBIGUOUS ABBREVIATIONS ARE LEGAL. ^THE ERROR MESSAGE
<PRSUKN WILL BE TYPED IF THE NAME IS UNRECOGNIZED
OR AMBIGUOUS. ^THE CALLING SEQUENCE IS:
.B 1
.NF
	<MOVE	^T1,NAME
	<MOVE	^T2,[<XWD -LENGTH,TABLE]
	<PUSHJ	<P,FNDNAM##
	 ;ERROR RETURN
	;NORMAL RETURN:
	;^T2 RETURNS INDEX INTO TABLE
.F
.HL 1 ^INPUT ^ROUTINES
.HL 2 <CI
	><CI IS A ROUTINE TO INPUT FROM ANY DEVICE. ^THE
LOCATION ><ICH SELECTS WHERE THE INPUT WILL COME FROM.
^IF <ICH=-1, THE INPUT WILL COME FROM THE <TTY VIA
<INCHWL. ^IF <ICH IS A VALID BYTE POINTER, THE INPUT
WILL COME FROM CORE VIA <ILDB. ^IF <ICH IS A CHANNEL NUMBER, THE
INPUT WILL COME FROM WHATEVER FILE IS OPEN ON THE CHANNEL.
^IF AN INPUT ERROR OCCURS, THE ERROR MESSAGE ><PRSIN
WILL BE TYPED, AND A <GETSTS WILL BE LOADED INTO ^C.
^ALL ROUTINES IN <PARSE USE <CI TO PERFORM THEIR INPUT, SO
<ICH CAN ALWAYS BE USED TO SELECT THE SOURCE. ^ALL ROUTINES
WILL PASS THE <GETSTS TO THEIR CALLER. ^THE CALLING SEQUENCE IS:
.B 1
.NF
	<MOVE	^T1,FOO
	<MOVEM	^T1,<ICH##
	<PUSHJ	<P,CI##
	 ;ERROR RETURN
	;NORMAL RETURN:
	;^C RETURNS THE INPUT BYTE
.F
.HL 2 <GETC
	><GETC IS LIKE <CI EXCEPT THAT THE INPUT MUST BE A CHANNEL.
<TTY AND CORE ARE NOT LEGAL.
.HL 2 <LSNI
	><LSNI IS LIKE <GETC, EXCEPT THAT LINE SEQUENCE
NUMBERS ARE IGNORED. <I.E. IF BIT 35 IS ON, IGNORE THE
ENTIRE WORD PLUS THE FIRST CHARACTER OF THE NEXT WORD.
^NULLS ARE ALSO IGNORED. <CI USES <LSNI TO PERFORM ITS
CHANNEL <I/O.
.HL 1 ^OUTPUT ^ROUTINES
.HL 2 <CO
	><CO IS A ROUTINE TO OUTPUT TO ANY DEVICE.
^THE LOCATION ><OCH SELECTS WHERE THE OUTPUT WILL GO. ^IF
<OCH=-1, THE OUTPUT WILL GO TO THE <TTY VIA <OUTCHR. ^IF
<OCH IS A VALID BYTE POINTER, THE OUTPUT WILL GO TO CORE
VIA <IDPB. ^IF <OCH IS A CHANNEL NUMBER, THE OUTPUT WILL GO
TO WHATEVER FILE IS OPEN ON THE CHANNEL.
^IF AN OUTPUT ERROR OCCURS, THE ERROR MESSAGE ><PRSOUT
WILL BE TYPED. ^ALL ROUTINES IN <PARSE USE <CO TO PERFORM
THEIR OUTPUT, SO <OCH CAN ALWAYS BE USED TO SELECT THE
DESTINATION. ^THE CALLING SEQUENCE IS:
.B 1
.NF
	<MOVE	^T1,FOO
	<MOVEM	^T1,<OCH##
	<MOVE	^C,CHAR
	<PUSHJ	<P,CO##
	 ;ERROR RETURN
	;NORMAL RETURN
.F
.HL 2 <PUTC
	><PUTC IS LIKE <CO EXCEPT THAT THE OUTPUT MUST
BE A CHANNEL. <TTY AND CORE ARE NOT LEGAL.
.HL 1 <VERBO
	><VERBO IS A ROUTINE TO OUTPUT A VERBOSITY CONTROLLED
ERROR MESSAGE. ^THE MESSAGE WILL APPEAR IN THE FORM:
.B 1
<_<CR_>_<LF_>?PREFIX <FIRST
.B 1
^WHERE "?" IS ANY CATCH CHARACTER (<E.G. "?", "%", OR "$").
<BATCON CAN BE MADE TO DETECT ERRORS BY TRAPPING OCCURANCES
OF THE CHARACTER IN COLUMN ONE. ^CONVENTION HAS IT THAT "?"
MEANS A FATAL ERROR, AND "%" MEANS A WARNING. <PREFIX IS A SIXBIT
ABBREVIATION OF THE ERROR MESSAGE. ^CONVENTION HAS
IT THAT THE FIRST THREE CHARACTERS OF
THE PROGRAM NAME ARE USED AS THE FIRST THREE CHARACTERS OF <PREFIX.
<FIRST IS AN <ASCII DESCRIPTION OF THE ERROR.
	^THE USER MAY CHOOSE WHETHER <PREFIX, <FIRST, OR BOTH
ARE TO APPEAR. ^THE CHOICE IS NORMALLY MADE ONLY ONCE PER JOB,
WHEN THE USER LOGS IN. ^THE USER SELECTS HIS CHOICE WITH <SETUUO FUNCTION
<.STWTC . ^THE INFORMATION IS STORED IN <GETTAB TABLE <.GTWCH .
^EXPERIENCED USERS TYPICALLLY PERFER <PREFIX ONLY, AS THIS
RESULTS IN FAST TYPE OUT.
	^THE CALLING SEQUENCE IS:
.B 1
.NF
	<MOVEI	^T1,[
		<SIXBIT /PREFIX/
		<ASCIZ /?FIRST/]
	<PUSHJ	<P,VERBO##
.B 1
.F
^BUT THE EASIEST WAY TO CALL <VERBO IS BY USING THE MACROS
DEFINED IN THE UNIVERSAL FILE <PRS. ^EACH MACRO
HAS TWO ARGUMENTS: <PREFIX, AND <FIRST. ^THE FIRST CHARACTER OF
<FIRST IS TAKEN AS THE CATCH CHARACTER. ^THE MACROS ARE:
.B 1
.LM 5
.I -5
><VERB CALLS VERBO EXACTLY AS ABOVE.
.I -5
><ERR IS LIKE <VERB, EXCEPT
THAT IT USES A <JRST INSTEAD OF A <PUSHJ.
.I -5
><WARN DOES A <PUSHJ ^P,[<ERR].
^HENCE <WARN EXPANDS TO ONE INSTRUCTION AND CAN BE PLACED UNDER A SKIP
INSTRUCTION.
.I -5
><FATAL IS LIKE <WARN, EXCEPT THAT IT USES A <JRST
INSTEAD OF A <PUSHJ. <I.E. IT RETURNS <CPOPJ
TO THE CALLER.
.LM 0
.HL 1 ^CHANNEL ^I_/^O
.HL 2 <RST
	><RST IS A ROUTINE TO RESET ALL CHANNELS AND RECLAIM ALL
BUFFERS. ^THE CALLING SEQUENCE IS:
.B 1
.NF
	<PUSHJ	<P,RST##
	;ONLY RETURN
.F
.HL 2 <FNDCH
	><FNDCH IS A ROUTINE TO FIND A FREE (UNUSED) CHANNEL.
<FNDCH WILL RETURN THE HIGHEST CHANNEL NOT IN USE. ^ALL
ROUTINES IN <PARSE USE <FNDCH TO ALLOCATE CHANNELS DYNAMICALLY.
^IF THE MAIN PROGRAM WISHES TO HARD CODE CHANNEL
NUMBERS, IT SHOULD USE THE LOWEST NUMBERS POSSIBLE.
^HENCE CONFLICT WITH <PARSE WILL BE MINIMIZED. ^THE CALLING
SEQUENCE IS:
.NF
.B 1
	<PUSHJ	<P,FNDCH##
	 ;ERROR RETURN
	;NORMAL RETURN:
	;^T1 RETURNS THE CHANNEL NUMBER
.F
.HL 2 <LKP
	><LKP IS A ROUTINE TO PERFORM AN <OPEN/LOOKUP ON
THE INPUT CHANNEL. ^IF THE CHANNEL WAS OPEN TO BEGIN WITH, IT IS
CLOSED VIA ><ICLS. <LKP USES <GETBLK TO ALLOCATE CORE FOR THE BUFFERS.
^THE ERROR MESSAGE ><PRSLKP WILL BE TYPED IF THE <LOOKUP
FAILS. ^THE CALLING SEQUENCE IS:
.B 1
.NF
	<MOVEI	^P1,_<FILE SPEC_>
	<PUSHJ	<P,LKP##
	 ;ERROR RETURN
	;NORMAL RETURN
.F
.HL 2 <SLKP
	><SLKP IS LIKE <LKP EXCEPT THAT NO ERROR
MESSAGE IS TYPED IF THE <LOOKUP FAILS. ^THE ERROR
CODE IS RETURNED IN THE <RH OF LOCATION <FIL+1.
.HL 2 <NTR
	><NTR IS LIKE <LKP EXCEPT THAT IT PERFORMS AN <ENTER
ON THE OUTPUT CHANNEL.
.HL 2 <IREN
	><IREN IS A ROUTINE TO PERFORM A <RENAME ON THE INPUT
CHANNEL. ^THE ERROR MESSAGE ><PRSLKP WILL BE TYPED
IF THE <RENAME FAILS. ^THE INPUT CHANNEL WILL BE CLOSED VIA ><ICLS.
^THE CALLING SEQUENCE IS:
.B 1
.NF
	<MOVEI	^P1,_<FILE SPEC_>
	<PUSHJ	<P,IREN##
	 ;ERROR RETURN
	;NORMAL RETURN
.F
.HL 2 <OREN
	><OREN IS LIKE <IREN, EXCEPT THAT THE <RENAME IS PERFORMED
ON THE OUTPUT CHANNEL.
.HL 2 <ICLS
	><ICLS IS A ROUTINE TO CLOSE THE INPUT CHANNEL AND RECLAIM
THE BUFFER SPACE. ^THE CALLING SEQUENCE IS:
.B 1
.NF
	<PUSHJ	<P,ICLS##
	;ONLY RETURN
.F
.HL 2 <OCL
	><OCL IS LIKE <ICLS EXCEPT THAT IT CLOSES THE OUTPUT
CHANNEL INSTEAD OF THE INPUT CHANNEL.
.HL 2 <OCLS
	><OCLS IS LIKE <OCL EXCEPT THAT IT OUTPUTS THE LAST
BUFFER BEFORE CLOSING THE CHANNEL. ^IF THERE IS AN ERROR
DURING THIS OUTPUT, THE ERROR MESSAGE ><PRSOUT IS TYPED.
^THE CALLING SEQUENCE IS:
.B 1
.NF
	<PUSHJ	<P,OCLS##
	 ;ERROR RETURN
	;NORMAL RETURN
.F
.HL 1 ^UTILITY ^INPUT
.HL 2 <OCTI
	><OCTI IS A ROUTINE TO INPUT AN OCTAL NUMBER.
^LEADING SPACES ARE IGNORED. ^THE CALLING SEQUENCE IS:
.B 1
.NF
	<PUSHJ	<P,OCTI##
	 ;ERROR RETURN
	;NORMAL RETURN:
	;^T1 RETURNS THE NUMBER
.F
.HL 2 <WOCTI
	><WOCTI IS LIKE <OCTI EXCEPT THAT WILDCARDS
ARE LEGAL. ^THE CALLING SEQUENCE IS:
.B 1
.NF
	<PUSHJ	<P,WOCTI##
	 ;ERROR RETURN
	;NORMAL RETURN:
	;^T1 RETURNS THE NUMBER
	;^T2 RETURNS THE WILDCARD MASK
.F
.HL 2 <DECI
	><DECI IS LIKE <OCTI, EXCEPT THAT THE NUMBER IS DECIMAL.
.HL 2 <NUMI
	><NUMI IS A ROUTINE TO INPUT A NUMBER IN ANY RADIX.
^LEADING SPACES ARE IGNORED. ^THE CALLING SEQUENCE IS:
.B 1
.NF
	<MOVEI	^T3,RADIX
	<PUSHJ	<P,NUMI##
	 ;ERROR RETURN
	;NORMAL RETURN:
	;^T1 RETURNS THE NUMBER
.F
.HL 2 <SIXI
	><SIXI IS A ROUTINE TO INPUT A SIXBIT WORD. ^WHERE
"^A"-"Z^" AND "0"-"9" ARE CONSIDERED TO BE VALID SIXBIT CHARACTERS.
^ONLY THE FIRST SIX CHARACTERS ARE SIGNIFICANT. ^LOWER CASE IS
CONVERTED TO UPPER CASE. ^LEADING SPACES ARE IGNORED. ^THE
CALLING SEQUENCE IS:
.B 1
.NF
	<PUSHJ	<P,SIXI##
	 ;ERROR RETURN
	;NORMAL RETURN:
	;^T1 RETURNS THE WORD
.F
.HL 2 <WSIXI
	><WSIXI IS LIKE <SIXI EXCEPT THAT WILDCARDS ARE LEGAL.
^THE CALLING SEQUENCE IS:
.B 1
.NF
	<PUSHJ	<P,WSIXI##
	 ;ERROR RETURN
	;NORMAL RETURN:
	;^T1 RETURNS THE WORD
	;^T2 RETURNS THE WILDCARD MASK
.F
.HL 1 ^UTILITY ^OUTPUT
.HL 2 <OCTO
	><OCTO IS A ROUTINE TO OUTPUT AN OCTAL NUMBER.
^THE CALLING SEQUENCE IS:
.B 1
.NF
	<MOVE	^T1,NUMBER
	<PUSHJ	<P,OCTO##
	 ;ERROR RETURN
	;NORMAL RETURN
.F
.HL 2 <DECO
	><DECO IS LIKE <OCTO, EXCEPT THAT THE NUMBER IS
DECIMAL.
.HL 2 <NUMO
	><NUMO IS A ROUTINE TO OUTPUT A NUMBER IN ANY RADIX. ^THE
CALLING SEQUENCE IS:
.B 1
.NF
	<MOVE	^T1,NUMBER
	<MOVEI	^T3,RADIX
	<PUSHJ	<P,NUMO##
	 ;ERROR RETURN
	;NORMAL RETURN
.F
.HL 2 <SIXO
	><SIXO IS A ROUTINE TO OUTPUT A SIXBIT WORD.
^THE CALLING SEQUENCE IS:
.B 1
.NF
	<MOVE	^T1,WORD
	<PUSHJ	<P,SIXO##
	 ;ERROR RETURN
	;NORMAL RETURN
.F
.HL 2 <STRO
	><STRO IS A ROUTINE TO OUTPUT AN <ASCIZ STRING. ^THE
CALLING SEQUENCE IS:
.B 1
.NF
	<MOVEI	^T1,STRING
	<PUSHJ	<P,STRO##
	 ;ERROR RETURN
	;NORMAL RETURN
.F
.HL 2 <BPO
	><BPO IS A ROUTINE TO OUTPUT AN <ASCIZ
STRING. <BPO DIFFERS FROM <STRO IN THAT THE STRING DOESN'T HAVE TO
BEGIN ON A WORD BOUNDARY. ^THE CALLING SEQUENCE IS:
.B 1
.NF
	<MOVE	^T1,[<POINT 7,ADR,BIT]
	<PUSHJ	<P,BPO##
	 ;ERROR RETURN
	;NORMAL RETURN
.F
.HL 2 <CRLF
	><CRLF CONTAINS AN <ASCIZ CARRIAGE RETURN LINE FEED.
.HL 2 <CRLFO
	><CRLFO IS A ROUTINE TO OUTPUT A CARRIAGE
RETURN LINE FEED. ^THE CALLING SEQUENCE IS:
.B 1
.NF
	<PUSHJ	<P,CRLFO##
	 ;ERROR RETURN
	;NORMAL RETURN
.F
.HL 1 ^SWITCHES
.HL 2 <SWTCH
	><SWTCH IS A ROUTINE TO PARSE SWITCHES. ^THE CALLING
SEQUENCE IS:
.B 1
.NF
	<MOVE	^P2,[<XWD -_<# SWITCHES_>,_<TABLE OF NAMES_>]
	<MOVEI	^P3,_<TABLE OF ROUTINES_>
	<PUSHJ	<P,SWTCH##
	 ;ERROR RETURN
	;NORMAL RETURN
.B 1
.F
^WHERE ^P2 PASSES AN <AOBJN POINTER TO A TABLE OF SWITCH NAMES.
<SWTCH WILL ALLOW THE USER TO TYPE ANY UNAMBIGUOUS
ABBREVIATION OF THE SWITCH. ^P3 PASSES THE ADDRESS OF A TABLE
OF ONE INSTRUCTION ROUTINES. <SWTCH WILL <XCT THE INSTRUCTION
CORRESPONDING TO THE SWITCH NAME. ^THE INSTRUCTIONS ARE
TYPICALLY THINGS LIKE:
.B 1
.NF
	<TRZ	^F,FLAG
	<TRO	^F,FLAG
	<SETZM	FLAG
	<SETOM	FLAG
.F
.B 1
^BUT IF ONE INSTRUCTION ISN'T ENOUGH, YOU CAN USE A
<PUSHJ TO A SUBROUTINE. ^IF THE SWITCH HAS AN ARGUMENT
(<E.G. /^M^A^T^C^H:N) IT IS THE RESPONSIBILITY OF
THE SUBROUTINE TO PARSE THE ARGUMENT AND STORE THE RESULT.
^THE SUBROUTINE IS EXPECTED TO PRESERVE ^P1-^P4,
BUT MAY DESTROY ^T1-^T4. ^THE SUBROUTINE IS
EXPECTED TO RETURN <CPOPJ. <CPOPJ1 WILL BE REGARDED
AS AN ERROR RETURN, AND <SWTCH WILL PASS THE ERROR
TO ITS CALLER BY RETURNING <CPOPJ. <SWTCH NORMALLY RETURNS
<CPOPJ1. <SWTCH WILL PARSE ALL SWITCHES UNTIL A SLASH CANNOT BE
FOUND. ^EXAMPLE:
.B 1
.NF
.UC
.NFL CAP
.NFL IND
	MOVEI	P1,<FILE SPEC>
	MOVE	P2,[XWD -SWL,SWN]
	MOVEI	P3,SWX
	PUSHJ	P,SWTCH##
	 HALT
.B 1
	DEFINE	SW,<
	X	LOG,<TRO F,F.LOG>
	X	NOLOG,<TRZ F,F.LOG>
	X	MATCH,<PUSHJ P,MTCH>
	X	HELP,<PUSHJ P,HELPER##>
_>
.B 1
	DEFINE	X(A,B),<
	SIXBIT	/A/
_>
.B 1
SWN:	SW
	SWL=.-SWN
.B 1
	DEFINE	X(A,B),<
	EXP	B
_>
.B 1
SWX:	SW
.B 1
MTCH:	PUSHJ	P,COLON##	;EAT COLON
	 JRST	CPOPJ1##	;ERROR
	PUSHJ	P,DECI##	;GET NUMBER
	 JRST	CPOPJ1##	;ERROR
	MOVEM	T1,.SBMY(P1)	;STORE IN SPEC
	POPJ	P,	;WIN
.FL CAP
.FL IND
.LC
.F
.HL 2 <EXT
	><EXT IS A ROUTINE TO PERFORM AN /<EXIT SWITCH. <I.E.
IT EATS THE REST OF THE COMMAND LINE THEN EXITS TO THE MONITOR.
^THE CALLING SEQUENCE IS:
.B 1
.NF
	<JRST	<EXT##
.F
.HL 2 <HELPER
	><HELPER IS A ROUTINE TO PERFORM A /<HELP SWITCH.
<I.E. IT COPIES ^H^L^P:PGM.^H^L^P TO THE OUTPUT CHANNEL. ^WHERE
PGM IS THE PROGRAM'S NAME. ^THE CALLING SEQUENCE IS:
.B 1
.NF
	<PUSHJ	<P,HELPER##
	 ;NORMAL RETURN
	;ERROR RETURN
.B 1
.F
<HELPER USES THE ROUTINE ><FNDCH TO ALLOCATE A CHANNEL FOR READING
THE HELP FILE.
.HL 2 <COLON
	><COLON IS A ROUTINE TO REMOVE A COLON FROM THE INPUT
STREAM. <I.E. IF ^C IS A COLON, THEN INPUT THE NEXT CHARACTER.
^IF ^C IS NOT A COLON, THE ERROR MESSAGE ><PRSSYN IS TYPED. ^LEADING
SPACES ARE IGNORED. <COLON IS USED TO PARSE SWITCH ARGUMENTS
(<E.G. /^M^A^T^C^H:N). ^THE CALLING SEQUENCE IS:
.B 1
.NF
	<PUSHJ	<P,COLON##
	 ;ERROR RETURN
	;NORMAL RETURN
.F
.HL 2 <LSTI
	><LSTI IS A ROUTINE TO PARSE A LIST OF KEYWORDS. ^THE
ROUTINE IS USEFUL FOR PARSING SWITCHES THAT USE KEYWORDS
AS ARGUMENTS. ^TWO FORMATS ARE ALLOWED:
.B 1
/SWITCH:X
.BR
/SWITCH:(X,Y,Z)
.B 1
^THE ERROR MESSAGE ><PRSSYN WILL BE TYPED IF THE INPUT
IS NEITHER OF THESE FORMS. <COLON SHOULD BE CALLED BEFORE
CALLING <LSTI. <LSTI WILL RETURN THE ADDRESS OF A LINKAGE LIST
OF KEYWORDS. ^THE FORMAT OF A LINKAGE ELEMENT IS:
.B 1
.NF
	<XWD	3,_<ADR NEXT BLK_>
	<SIXBIT	/X/
	MASK
.B 1
.F
^THE CALLING SEQUENCE IS:
.B 1
.NF
	<PUSHJ	<P,LSTI##
	 ;ERROR RETURN
	;NORMAL RETURN:
	;^P1 RETURNS ADR LIST
.F
.HL 1 ^FILE ^SPECS
.HL 2 <SPCI
	><SPCI IS A ROUTINE TO PARSE A FILE SPEC. ^THE SPEC
IS RETURNED IN A SPECIAL ARGUMENT BLOCK DEFINED
IN THE UNIVERSAL FILE <PRS.
^THE CALLING SEQUENCE IS:
.B 1
.NF
	<MOVEI	^P1,_<FILE SPEC_>
	<PUSHJ	<P,SPCI##
	 ;ERROR RETURN
	;NORMAL RETURN
.F
.B 1
^WHERE _<FILE SPEC_> MUST BE PRE-LOADED WITH THE DEFAULT FILESPEC.
<SPCI WILL NOT ALTER ANY FIELD THAT THE USER DOES NOT EXPLICITELY
SPECIFY. ^HENCE THE DEFAULT REMAINS.
	^THE ERROR MESSAGE ><PRSPTH IS TYPED IF <SFDS'S
ARE NESTED TOO DEEPLY.
	^LEADING SPACES ARE IGNORED.
.HL 2 <SPCSI
	><SPCSI IS A ROUTINE TO PARSE A LIST OF FILE SPECS. ^EACH
SPEC MAY BE FOLLOWED BY SWITCHES. ^FILE SPECS ARE STICKY (<I.E.
THE DEFAULT FOR EACH SPEC IS THE PREVIOUS SPEC). ^THE USER PRE-LOADS
THE ARGUMENT BLOCK WITH THE INITIAL DEFAULT. <SPCSI WILL ALLOCATE
ADDITIONAL BLOCKS AND LINK THEM TO THE USER'S. ^LEADING
SPACES ARE IGNORED. ^THE CALLING SEQUENCE IS:
.B 1
.NF
	<MOVEI	^P1,_<FILE SPEC_>
	<MOVE	^P2,[<XWD -_<# SWITCHES_>,_<TABLE OF NAMES_>]
	<MOVEI	^P3,_<TABLE OF ROUTINES_>
	<PUSHJ	<P,SPCSI##
	 ;ERROR RETURN
	;NORMAL RETURN
.F
.HL 2 <SPCO
	><SPCO IS A ROUTINE TO OUTPUT A FILE SPEC. ^THE
CALLING SEQUENCE IS:
.B 1
.NF
	<MOVEI	^P1,_<FILE SPEC_>
	<PUSHJ	<P,SPCO##
	 ;ERROR RETURN
	;NORMAL RETURN
.F
.HL 1 ^WILDCARDS
.HL 2 <WILD
	><WILD IS A ROUTINE TO PERFORM A WILDCARD
LOOKUP. ^THE CALLING SEQUENCE IS:
.NF
.B 1
	<MOVEI	^P1,_<FILE SPEC_>
	<MOVEI	^P2,_<USER ROUTINE_>
	<PUSHJ	<P,WILD##
	 <JFCL
.F
.B 1
^WHERE _<FILE SPEC_> IS DEFINED IN THE UNIVERSAL FILE <PRS.
<WILD WILL <PUSHJ TO _<USER ROUTINE_> FOR EACH FILE SPECIFIED
BY THE WILDCARD. ^A DESCRIPTION OF EACH FILE WILL
BE PASSED TO _<USER ROUTINE_> IN A BLOCK POINTED TO BY
^P1. _<^USER ROUTINE_> MAY RETURN <CPOPJ OR <CPOPJ1,
BUT <WILD WILL IGNORE ERROR RETURNS AND CONTINUE PROCESSING
OTHER FILES. <WILD WILL RETURN <CPOPJ OR <CPOPJ1 DEPENDING
ON HOW _<USER ROUTINE_> RETURNS ON THE FINAL CALL. ^HENCE
<WILD'S <CPOPJ RETURN SHOULD NORMALLY BE IGNORED.
	<WILD USES THE ROUTINE ><FNDCH TO ALLOCATE CHANNELS FOR
READING DIRECTORIES.
	<WILD MAY BE CALLED RECURSIVELY. ^IN FACT, <WILD CALLS ITSELF
RECURSIVELY.
.HL 2 <WILDER
	><WILDER IS LIKE <WILD EXCEPT THAT
<WILDER TYPES THE ERROR MESSAGE ><WLDNSF IF THERE ARE NO
FILES THAT MATCH THE WILDCARD. ^BUT EVEN IF <WILDER DOES FIND SOME
FILES, THE MESSAGE MAY STILL APPEAR. <E.G. THE PROGRAM HAS
A /<SINCE SWITCH, AND _<USER ROUTINE_> DETERMINES THAT NONE
OF THE FILES HAVE THE CORRECT DATES. ^TO DISABLE
THE MESSAGE, _<USER ROUTINE_> MUST SET THE LOCATION ><WLDCNT
NON-ZERO.
.HL 2 <WILDP
	><WILDP IS A PREDICATE TO DETERMINE IF A FILE SPEC IS WILD. ^THE
CALLING SEQUENCE IS:
.B 1
.NF
	<MOVEI	^P1,_<FILE SPEC_>
	<PUSHJ	<P,WILD##
	 ;RETURN HERE IF NOT WILD
	;RETURN HERE IF WILD
.F
.HL 2 <WLDMAT
	><WLDMAT IS A ROUTINE TO MATCH WILDCARDS. <E.G. IF THE
COMMAND STRING WAS:
.B 1
<*C?.MAC=A?.*
.B 1
<WILD WOULD BE USED TO LOOKUP ^A?.* . ^SUPPOSE <WILD
FOUND A FILE <A1.BAK . <WLDMAT WOULD BE USED TO
TRANSPLANT THE "1" INTO THE OUTPUT SPEC. ^HENCE THE
RESULT WOULD BE <C1.MAC . ^THE CALLING SEQUENCE IS:
.B 1
.NF
	<MOVEI	^P1,_<LOOKUP SPEC_>	;<E.G. <A1.BAK
	<MOVEI	^P2,_<WILD SPEC_>	;<E.G. <C?.MAC
	<MOVEI	^P3,_<NEW SPEC_>	;<E.G. <C1.MAC
	<PUSHJ	<P,WLDMAT##
	;ONLY RETURN
.F
.HL 1 ^MISCELLANEOUS
.HL 2 <PROMPT
	><PROMPT IS A ROUTINE TO TYPE A PROMPT CHARACTER
TO THE USER. ^IT WILL THEN SET ><ICH TO -1 AND INPUT
THE FIRST CHARACTER OF HIS COMMAND STRING. ^IF THE COMMAND
BEGINS WITH A SWITCH, THE SWITCH WILL BE PARSED. ^IF
THE LINE CONTAINS NOTHING ELSE, ANOTHER LINE WILL BE
PARSED IN THE SAME MANNER. <PROMPT IGNORES LEADING SPACES.
<PROMPT DOES A <SKPINC TO STOP <CTRL-O BEFORE TYPING
THE PROMPT CHARACTER.
^IF THE USER TYPES CONTROL ^Z, <PROMPT WILL DO AN
<EXIT <UUO.
^THE CALLING SEQUENCE IS:
.NF
.B 1
	<MOVE	^P2,[<XWD -_<# SWITCHES_>,_<TABLE OF NAMES_>]
	<MOVEI	^P3,_<TABLE OF ROUTINES_>
	<PUSHJ	<P,PROMPT##
	 ;ERROR RETURN
	;NORMAL RETURN
.F
.HL 2 <PRMPT
	><PRMPT IS LIKE <PROMPT EXCEPT THAT SWITCHES ARE NOT
PARSED. ^THE CALLING SEQUENCE IS:
.NF
.B 1
	<PUSHJ	<P,PRMPT##
	 ;ERROR RETURN
	;NORMAL RETURN
.F
.HL 2 <EATS
	><EATS IS A ROUTINE TO REMOVE LEADING SPACES
AND TABS FROM THE INPUT STREAM. <I.E. IF ^C IS A SPACE OR A TAB,
THEN INPUT THE NEXT CHARACTER AND TRY AGAIN. <EATS
WILL RETURN <CPOPJ1 WHEN A NON BLANK CHARACTER IS LOCATED. ^THE
CALLING SEQUENCE IS:
.NF
.B 1
	<PUSHJ	<P,EATS##
	 ;ERROR RETURN
	;NORMAL RETURN
.B 1
.F
	^MOST OF THE INPUT ROUTINES IN <PARSE BEGIN
BY CALLING <EATS. ^HENCE LEADING SPACES ARE IGNORED.
.HL 2 <BP
	><BP IS A PREDICATE ROUTINE FOR BREAK CHARS. ^THE
CALLING SEQUENCE IS:
.B 1
.NF
	<MOVE	^C,CHAR
	<PUSHJ	<P,BP##
	 ;RETURN HERE IF NOT BREAK
	;RETURN HERE IF BREAK
.F
.B 1
^THE FOLLOWING ARE CONSIDERED TO BE BREAK CHARACTERS:
.B 1
.NF
12	<LF	^LINE ^FEED
13	<VT	^VERTICAL ^TAB
14	<FF	^FORM ^FEED
32	_^^Z	CONTROL ^Z
13	<ESC	^E^S^CAPE
.F
.HL 2 <EATCR
	><EATCR IS A ROUTINE TO REMOVE A CARRIAGE RETURN FROM THE
INPUT STREAM. <I.E. IF ^C IS A CARRIAGE RETURN THEN INPUT THE
NEXT CHARACTER. ^LEADING SPACES ARE ALSO
REMOVED. ^IT WOULD BE A GOOD IDEA TO CALL <EATCR BEFORE
CALLING <BP SO THAT CARRIAGE RETURN LINE FEED BEHAVES PROPERLY.
_<^C^R_> IS NOT A BREAK CHAR, BUT _<^L^F_> IS. ^THE CALLING
SEQUENCE IS:
.B 1
.NF
	<PUSHJ	<P,EATCR##
	 ;ERROR RETURN
	;NORMAL RETURN
.F
.HL 2 <EATEOL
	><EATEOL IS A ROUTINE TO IGNORE ALL INPUT UNTIL
A BREAK CHARACTER IS ENCOUNTERED. ^THE CALLING
SEQUENCE IS:
.NF
.B 1
	<PUSHJ	<P,EATEOL##
	 ;ERROR RETURN
	;NORMAL RETURN
.DX INDEX