.TITLE	INCHAR - Single-character terminal input
		.IDENT	/1-001/		; File: IN_CHAR.MAR
					; Edit: CFC1001

        ;++
        ;  FACILITY: Single-character immediate input 
        ;
        ;  ABSTRACT:
        ;
	;      One function that seems to come up fairly often during
	;   programming, is the desire to "get a single character from 
	;   the terminal, without the user having to press RETURN.  Un-
	;   fortunately, with only minor exceptions (Vax BASIC, for one),
	;   such an operation is noticeably missing from the set of "built
	;   in" language facilities under Vax/VMS. 
	;
	;      This routine assigns a channel, if necessary, to the
	;   SYS$INPUT device (assumed to be a terminal), and obtains a
	;   single character this device each time it (the routine) is 
	;   called.
	;
	;      The character obtained from the terminal is returned to the
	;   calling program as a single byte ASCII code.
        ;
	;  ENVIRONMENT:   User mode, callable from any higher-level Vax
	;                 programming language.
        ;
        ; AUTHOR:  Christopher F. Chiesa,   CREATION DATE: 10-FEB-1988, approx.
        ;
        ; MODIFIED BY: (Christopher F. Chiesa)
        ;
        ; 1-001 -- original.                CFC 10-FEB-1988
	; 1-002 -- edited text of ABSTRACT, CFC 18-MAR-1988
        ;--

		.SBTTL	DECLARATIONS
        ;
        ; EQUATED SYMBOLS:
        ;
			buffer_length = 1	; Length of buffer

        ;
        ; OWN STORAGE:
        ;

			.PSECT	DATA	NOEXE,WRT

; GCE mod...use sys$command instead, so it will be a terminal even if
; the program is run from a command file.
    DEVNAM:		.ASCID	/SYS$COMMAND/	; device to read from
    CHAN:		.LONG	0		; channel to use (init'd to 0)

        ;
        ; EXECUTABLE CODE BEGINS:
        ;
			.PSECT	CODE	EXE,NOWRT
    
			.ENTRY	INCHAR,^M<r2,r3,r4,r5>

			CMPL	CHAN,#0		; Channel already assigned?

			BNEQ	GET_INPUT	; Yes - don't assign again

	CHAN_ASGN:	$ASSIGN_S -		; Assign channel for input
			DEVNAM=DEVNAM,-
			CHAN=CHAN
			BLBC	R0,OOPS		; Exit with error status


	GET_INPUT:	$QIOW_S	CHAN=CHAN,-	; Perform input on channel
				FUNC=#<IO$_READVBLK!IO$M_NOECHO!IO$M_NOFILTR>,-
				P1=@4(AP),-
				P2=#<buffer_length>
			BLBC	R0,OOPS		; Exit with QIO error

	RETURN:		RET			; Return when successful

	OOPS:		$EXIT_S	R0		; Exit with status code

			.END