.TITLE	SELECT
	.SBTTL	DOCUMENTATION
	.IDENT	/CS1.02/
;
;	(DOCUMENTATION)
;
; SELECT
;
; DESCRIPTION
;	ALLOWS THE USER TO SPECIFY A SET OF "ACCEPTABLE" COMMANDS
;	WHICH A USER COULD SELECT, AND THEN HANDLES ALL THE OVERHEAD
;	OF REJECTING ILLEGAL CHARACTERS AND RESPONSES UNTIL A
;	VALID AND UNIQUE STRING HAS BEEN TYPED BY THE USER.  THE
;	NUMBER OF THE OPTION STRING SELECTED IS THEN RETURNED TO
;	THE CALLING PROGRAM.
; USAGE
;	CALL SELECT(IOPT,IDFLT,'...PROMPT STRING...',
;     +		'...OPTION STRING #1...',
;     +		'...OPTION STRING #2...',
;     +			...
;     +		'...OPTION STRING #N...')
; PARAMETERS
;	IOPT	(RETURNED) THE OPTION STRING # THAT THE USER HAS
;		SELECTED DURING THIS CALL TO SELECT.  THIS NUMBER
;		WILL BE IN THE RANGE 1 (ONE) TO N+1, WHERE THE
;		USER HAS SUPPLIED "N" OPTION STRINGS.  THE "N+1"
;		VALUE OCCURS IF THE USER TYPES A CONTROL-Z (THIS
;		EXIT IS ALWAYS POSSIBLE).
;	IDFLT	(SUPPLIED) THE NUMBER OF THE OPTION STRING THAT IS
;		TO BE CONSIDERED AS THE "DEFAULT" OPTION STRING.
;		THIS NUMBER WOULD BE IN THE RANGE OF 1 (ONE) TO "N"
;		IF A DEFAULT OPTION IS DESIRED, AND EQUAL TO 0 (ZERO)
;		IF A DEFAULT IS NOT DESIRED.  THIS OPTION CAN ALSO
;		BE "NULLED" OUT BY USING TWO CONSECUTIVE COMMAS AT
;		THE APPROPRIATE PLACE IN THE CALLING PARAMETER LIST
;		(EG, CALL SELECT(IOPT,,'...PROMPT STRING...',)
;	STRINGS	(SUPPLIED) THE PROMPT STRING, AND THE OPTION STRINGS,
;		HAVE THE SAME FORMAT--HOLLERITH LITERAL STRINGS IN
;		EITHER THE FORM 
;			NHABCD...
;			'ABCD...'
;			IBUF
;		WHERE THE LAST IS AN ARRAY NAME, WITH THE LAST BYTE
;		OF THE STRING BEING A ZERO (OR A ZERO WORD).  THIS
;		ARGUMENT CAN ALSO BE "NULLED" BY LEAVING IT OUT IF
;		NO PROMPT STRING IS DESIRED.
;		OPTION STRINGS CAN'T BE LEFT OUT, AND ARE NUMBERED IN
;		ORDER OF THEIR APPEARANCE IN THE ARGUMENT LIST (WITH
;		THE FIRST BEING #1).  THE UTILITY OF THE OPTION STRINGS
;		CAN BE ENHANCED BY INCLUDING "NOISE WORDS" IN
;		PARENTHESES FOLLOWING THE ACTUAL CHOICE...THIS WAY, THE
;		NOISE WORDS WILL APPEAR IF THE USER TYPES AN ESCAPE
;		TO TERMINATE A UNIQUELY DEFINED OPTION, TO FURTHER
;		EXPLAIN THE OPTION'S FUNCTION.
; NOTES
;	1) IF THE USER AT ANY POINT ATTEMPTS TO TYPE AN INVALID RESPONSE
;	   GIVEN THE OPTIONS POSSIBLE AT THAT POINT, THE CHARACTER
;	   WILL NEITHER BE ACCEPTED NOR PRINTED, BUT A "BELL" WILL SOUND
;	   AT THE USER'S TERMINAL TO TELL HIM THAT AN INVALID CHARACTER
;	   WAS TYPED.  THIS WILL ALSO HAPPEN IF THE USER THINKS A RESPONSE
;	   HAS BEEN UNIQUELY QUALIFIED FOR THE NUMBER OF CHARACTERS HE
;	   HAS TYPED SO FAR AND HE TYPES A CARRIAGE RETURN...BUT ANOTHER
;	   OPTION EXISTS WHICH IS THE SAME THROUGH THE NUMBER OF CHARS
;	   SO FAR.  THE TERMINAL WILL BEEP AND NOT ACCEPT THE CARRIAGE
;	   RETURN, AND THE USER WILL STILL BE INSIDE THE "SELECT" PACKAGE.
;	2) THE USER CAN TYPE AN "ESCAPE" CHARACTER AT ANY POINT, AT
;	   WHICH POINT THE SELECT PACKAGE WILL ATTEMPT TO "FINISH" THE
;	   STRING IN PROGRESS BY CHECKING WHETHER THE STRING IS UNIQUE
;	   COMPARED TO THE OPTIONS INITIALLY SUPPLIED.  IF IT IS UNIQUE,
;	   THE REMAINING CHARACTERS IN THE OPTION WILL BE TYPED, AND THE
;	   SELECT PACKAGE WILL DO ONE OF THREE THINGS DEPENDING ON WHAT
;	   THE FIRST CHARACTER OF THE ORIGINAL OPTION STRING WAS:
;		1ST CHAR	ACTION AFTER TYPING REMAINING CHARS
;		--- ----	------ ----- ------ --------- -----
;		# (NMBR SIGN)	THE STRING "[CONFIRM]" IS TYPED, AND THE
;				USER MUST EITHER CONFIRM THE OPTION BY
;				TYPING A CARRIAGE RETURN, OR HE CANCELS
;				THE OPTION BY TYPING ANY OTHER CHAR.  IF
;				HE CANCELS THE OPTION SO SELECTED, THE
;				WHOLE LINE IS THROWN AWAY AND THE USER
;				STARTS ON AN OPTION FROM SCRATCH.
;		$ (DLR SIGN)	AFTER THE TRAILING CHARACTERS OF THE OPTION
;				ARE TYPED, NO CARRIAGE RETURN IS TYPED.  THE
;				EFFECT IS TO ALLOW A READ STATEMENT TO READ
;				THE NEXT ITEM ON THE SAME LINE AS THE OPTION
;				CHOSEN.
;		% (PRCNT SIGN	AFTER THE TRAILING CHARACTERS OF THE OPTION
;				ARE TYPED, A CARRIAGE RETURN IS TYPED.  IN
;				THIS WAY, THE USER IS LEFT ON THE NEXT LINE
;				DOWN FOR FURTHER INPUT/OUTPUT.
;	   NOTE THAT THE "#" LEADING CHARACTER REQUIRES ONE FURTHER LEVEL
;	   OF CONFIRMATION, WHILE BOTH THE "$" AND "%" LEADING CHARACTERS
;	   WILL IMMEDIATELY ACCEPT THE STRING IN PROGRESS (IF POSSIBLE)
;	   AND RETURN TO THE CALLER.
;	3) TYPING A "?" (QUESTION MARK) AT ANY POINT DURING AN OPTION WILL
;	   TYPE ON THE USER'S TERMINAL ALL THE OPTIONS STILL VALID AT THAT
;	   POINT FOR WHAT HAS BEEN TYPED SO FAR.  TYPING IT AS THE FIRST
;	   CHARACTER OF THE OPTION RESPONSE WILL ADDITIONALLY INDICATE THAT
;	   "^Z" (CONTROL-Z) IS A VALID RESPONSE TO THE OPTION SELECTION.
;	   TYPING IT IN THE MIDDLE OF A RESPONSE WILL LIST ALL POSSIBLE
;	   RESPONSES VALID AT THAT POINT.
;	4) TYPING A ^Z (CONTROL-Z) AS THE 1ST CHARACTER OF THE LINE WILL
;	   ASK THE USER FOR CONFIRMATION, AND IF CONFIRMED, EXIT FROM
;	   SELECT WITH AN OPTION CODE OF "N+1", IF "N" OPTIONS WERE GIVEN.
;	5) THE STANDARD EDITING CHARACTERS OF "RUBOUT OR DEL", "^U",
;	   AND "^R" ARE SUPPORTED, WITH THE LAST RETYPING THE PROMPT
;	   STRING AS WELL AS THE CHARS TYPED SO FAR.