!<BLF/REQUIRE 'USR_LIBRARY:PRETTY'>

!++
!
! FACILITY:	CON - Console non-interrupt I/O interface.
!
! ABSTRACT:	This module contains macro definitions which are used to
!		interface to non-interrupt console I/O routines.  These
!		routines are normally part of the VMS executive, although they
!		are part of paged BUGCHECK code and therefore are not available
!		directly.  The routines provided here superceed those provided
!		with the VMS executive for images linked to them.  These
!		routines provide a convient way for drivers and other executive
!		level code to output messages (typically debug) to the console
!		terminal from evevated IPL.  It should be noted that these
!		routines mimic the corresponding VMS routines with the prefix
!		CON$.
!
! RESTRICTIONS:	All macro calls must be bracketed by calls to _owncty and
!		_releasecty except when running standalone, i.e. bootable code.
!		Failure to do this will result in the console terminal
!		becomming inoperable till the next reboot.  E.G.,
!
!			_owncty (txcs = txcs, rxcs = rxcs);
!			_outzstring (string = 'All is well!');
!			_outcrlf;
!			_releasecty (txcs = .txcs, rxcs = .rxcs);
!
! ENVIRONMENT:	VAX, kernel mode, any IPL, no VMS dependencies.
!
! AUTHOR:	James A. Gray
!
! CREATED:	20 July 1986
!
! MODIFICATION
! HISTORY:
!
!	V01.01	20 July 1986, James A. Gray
!		Original version.
!
!--

%SBTTL 'Declarations'

!+
! SWITCHES:
!-

!	None.

!+
! LINKAGE/GLOBAL REGISTERS:
!-

!	None.

!+
! LINKAGES:
!-

LINKAGE
    consolio_getchar_linkage = JSB,
    consolio_outblank_linkage = JSB : NOPRESERVE (0, 2)
	PRESERVE (1)
	NOTUSED (3, 4, 5, 6, 7, 8, 9, 10, 11),
    consolio_outchar_linkage = JSB (REGISTER = 0) : NOPRESERVE (0, 2)
	PRESERVE (1)
	NOTUSED (3, 4, 5, 6, 7, 8, 9, 10, 11),
    consolio_outcrlf_linkage = JSB : NOPRESERVE (0, 2)
	PRESERVE (1)
	NOTUSED (3, 4, 5, 6, 7, 8, 9, 10, 11),
    consolio_outcstring_linkage = JSB (REGISTER = 1) : NOPRESERVE (0, 1, 2)
	NOTUSED (3, 4, 5, 6, 7, 8, 9, 10, 11),
    consolio_outhex_linkage = JSB (REGISTER = 1, REGISTER = 0) : NOPRESERVE (0, 2)
	PRESERVE (1)
	NOTUSED (3, 4, 5, 6, 7, 8, 9, 10, 11),
    consolio_outzstring_linkage = JSB (REGISTER = 1) : NOPRESERVE (0, 1, 2)
	NOTUSED (3, 4, 5, 6, 7, 8, 9, 10, 11),
    consolio_owncty_linkage = JSB (; REGISTER = 0, REGISTER = 1) : NOPRESERVE (0, 1)
	NOTUSED (2, 3, 4, 5, 6, 7, 8, 9, 10, 11),
    consolio_putchar_linkage = JSB (REGISTER = 0) : PRESERVE (0)
	NOTUSED (1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11),
    consolio_putstring_linkage = JSB (REGISTER = 1, REGISTER = 2) : NOPRESERVE (0, 1, 2)
	NOTUSED (3, 4, 5, 6, 7, 8, 9, 10, 11),
    consolio_releasecty_linkage = JSB (REGISTER = 0, REGISTER = 1) : PRESERVE (0, 1)
	NOTUSED (2, 3, 4, 5, 6, 7, 8, 9, 10, 11);

!+
! TABLE OF CONTENTS:
!-

!	_getchar	Gets the next character input at the console terminal.
!
!	_outblank	Outputs a blank character to the console terminal.
!
!	_outchar	Outputs a single character to the console terminal.  If
!			the character is a carriage return then the appropriate
!			number of fill characters will be output after the
!			carriage return has been output.
!
!	_outcrlf	Outputs a carriage return/line feed sequence to the
!			console terminal.
!
!	_outcstring	Outputs a counted string to the console terminal.
!
!	_outhex		Outputs a longword as a hexadecimal value to the
!			console terminal.
!
!	_outzstring	Outputs a zero terminated string (ASCIZ) to the console
!			terminal.
!
!	_owncty		"Allocates" console terminal.
!
!	_putchar	Outputs a character to the console terminal.  No fill
!			characters will be output.
!
!	_putstring	Outputs a string to the console terminal.  If the string
!			contains a null character then output will be terminated
!			with the last character preceeding the null character.
!
!	_read_prompt	Read with prompt a string from the console terminal.
!
!	_releasecty	"Release" console terminal.

!+
! INCLUDE FILES:
!-

!	None.

!+
! MACROS:
!-

MACRO
    _getchar =

	!+
	! FUNCTIONAL DESCRIPTION:
	!
	!	Gets the next character input at the console terminal.
	!
	! ENVIRONMENT:
	!
	!	Kernel access mode, kernel or interrupt stack, any IPL.
	!
	! PARAMETERS:
	!
	!	None.
	!
	! IMPLICIT INPUTS:
	!
	!	None.
	!
	! IMPLICIT OUTPUTS:
	!
	!	None.
	!
	! SIDE EFFECTS:
	!
	!	The value of this macro is the character read from the console
	!	terminal.
	!
	!-

	con_getchar () %;

MACRO
    _outblank =

	!+
	! FUNCTIONAL DESCRIPTION:
	!
	!	Outputs a blank character to the console terminal.
	!
	! ENVIRONMENT:
	!
	!	Kernel access mode, kernel or interrupt stack, any IPL.
	!
	! PARAMETERS:
	!
	!	None.
	!
	! IMPLICIT INPUTS:
	!
	!	None.
	!
	! IMPLICIT OUTPUTS:
	!
	!	None.
	!
	! SIDE EFFECTS:
	!
	!	None.
	!
	!-

	con_outblank () %;

KEYWORDMACRO
    _outchar (
	    char) =

	!+
	! FUNCTIONAL DESCRIPTION:
	!
	!	Outputs a single character to the console terminal.  If the
	!	character is a carriage return then the appropriate number of
	!	fill characters will be output after the carriage return has
	!	been output.
	!
	! ENVIRONMENT:
	!
	!	Kernel access mode, kernel or interrupt stack, any IPL.
	!
	! PARAMETERS:
	!
	!	char
	!		The character to be output.  Only the low order byte
	!		will be output.
	!
	! IMPLICIT INPUTS:
	!
	!	None.
	!
	! IMPLICIT OUTPUTS:
	!
	!	None.
	!
	! SIDE EFFECTS:
	!
	!	None.
	!
	!-

	con_outchar (char) %;

MACRO
    _outcrlf =

	!+
	! FUNCTIONAL DESCRIPTION:
	!
	!	Outputs a carriage return/line feed sequence to the console
	!	terminal.
	!
	! ENVIRONMENT:
	!
	!	Kernel access mode, kernel or interrupt stack, any IPL.
	!
	! PARAMETERS:
	!
	!	None.
	!
	! IMPLICIT INPUTS:
	!
	!	None.
	!
	! IMPLICIT OUTPUTS:
	!
	!	None.
	!
	! SIDE EFFECTS:
	!
	!	None.
	!
	!-

	con_outcrlf () %;

KEYWORDMACRO
    _outcstring (
	    string) =

	!+
	! FUNCTIONAL DESCRIPTION:
	!
	!	Outputs a counted string to the console terminal.
	!
	! ENVIRONMENT:
	!
	!	Kernel access mode, kernel or interrupt stack, any IPL.
	!
	! PARAMETERS:
	!
	!	string
	!		A string or the address of the counted string to be
	!		output.  If a string is specified then it will be
	!		compiled as a UPLIT to a counted string.
	!
	! IMPLICIT INPUTS:
	!
	!	None.
	!
	! IMPLICIT OUTPUTS:
	!
	!	None.
	!
	! SIDE EFFECTS:
	!
	!	None.
	!
	!-

	%IF %ISSTRING (string)
	%THEN
	    con_outcstring (UPLIT BYTE (%CHARCOUNT (string), string))
	%ELSE
	    con_outcstring(string)
	%FI

    %;

KEYWORDMACRO
    _outhex (
	    value,
	    zero_sup = 0 ) =

	!+
	! FUNCTIONAL DESCRIPTION:
	!
	!	Outputs a longword as a hexadecimal value to the console
	!	terminal. If the zero suppression flag is true then leading
	!	zeros are suppressed.
	!
	! ENVIRONMENT:
	!
	!	Kernel access mode, kernel or interrupt stack, any IPL.
	!
	! PARAMETERS:
	!
	!	value
	!		The value to be output.
	!
	!	zero_sup
	!		Flag, true => suppress leading zeros.
	!
	! IMPLICIT INPUTS:
	!
	!	None.
	!
	! IMPLICIT OUTPUTS:
	!
	!	None.
	!
	! SIDE EFFECTS:
	!
	!	None.
	!
	!-

	con_outhex (value, zero_sup) %;

KEYWORDMACRO
    _outzstring (
	    string) =

	!+
	! FUNCTIONAL DESCRIPTION:
	!
	!	Outputs a zero terminated string (ASCIZ) to the console
	!	terminal.
	!
	! ENVIRONMENT:
	!
	!	Kernel access mode, kernel or interrupt stack, any IPL.
	!
	! PARAMETERS:
	!
	!	string
	!		A string or the address of the zero terminatted string
	!		to be output.  If a string is specified then it will be
	!		compiled as a UPLIT to a zero terminated string.
	!
	! IMPLICIT INPUTS:
	!
	!	None.
	!
	! IMPLICIT OUTPUTS:
	!
	!	None.
	!
	! SIDE EFFECTS:
	!
	!	None.
	!
	!-

	%IF %ISSTRING (string)
	%THEN
	    con_outzstring (UPLIT BYTE (string, 0))
	%ELSE
	    con_outzstring(string)
	%FI

    %;

KEYWORDMACRO
    _owncty (
	    txcs,
	    rxcs) =

	!+
	! FUNCTIONAL DESCRIPTION:
	!
	!	"Allocate" the console terminal.
	!
	! ENVIRONMENT:
	!
	!	Kernel access mode, kernel or interrupt stack, any IPL.
	!
	! PARAMETERS:
	!
	!	txcs
	!		Address of a longword in which the current console
	!		terminal transmitter status register contents will be
	!		saved.
	!
	!	rxcs
	!		Address of a longword in which the current console
	!		terminal receiver status register contents will be
	!		saved.
	!
	! IMPLICIT INPUTS:
	!
	!	None.
	!
	! IMPLICIT OUTPUTS:
	!
	!	None.
	!
	! SIDE EFFECTS:
	!
	!	Normal output to the console terminal is suspended, control of
	!	output is assumed by the caller.  Normal output will be resumed
	!	by a call to _releasecty.
	!
	!-

	con_owncty (; txcs, rxcs) %;

KEYWORDMACRO
    _putchar (
	    char) =

	!+
	! FUNCTIONAL DESCRIPTION:
	!
	!	Outputs a character to the console terminal.  No fill
	!	characters will be output.
	!
	! ENVIRONMENT:
	!
	!	Kernel access mode, kernel or interrupt stack, any IPL.
	!
	! PARAMETERS:
	!
	!	char
	!		The character to be output.  Only the low order byte
	!		will be output.
	!
	! IMPLICIT INPUTS:
	!
	!	None.
	!
	! IMPLICIT OUTPUTS:
	!
	!	None.
	!
	! SIDE EFFECTS:
	!
	!	None.
	!
	!-

	con_putchar (char) %;

KEYWORDMACRO
    _putstring (
	    string,
	    len) =

	!+
	! FUNCTIONAL DESCRIPTION:
	!
	!	Outputs a string to the console terminal.  If the string
	!	contains a null character then output will be terminated
	!	with the last character preceeding the null character.
	!
	! ENVIRONMENT:
	!
	!	Kernel access mode, kernel or interrupt stack, any IPL.
	!
	! PARAMETERS:
	!
	!	string
	!		A string or the address of the string to be output.
	!		If a string is specified then it will be compiled
	!		as a UPLIT to a string.
	!
	!	len
	!		The length of the string to be output.
	!
	! IMPLICIT INPUTS:
	!
	!	None.
	!
	! IMPLICIT OUTPUTS:
	!
	!	None.
	!
	! SIDE EFFECTS:
	!
	!	None.
	!
	!-

	%IF %ISSTRING (string)
	%THEN
	    con_putstring (UPLIT BYTE (string), len)
	%ELSE
	    con_putstring(string, len)
	%FI

    %;

KEYWORDMACRO
    _read_prompt (
	    prompt,
	    len,
	    string) =

	!+
	! FUNCTIONAL DESCRIPTION:
	!
	!	Read with prompt a string from the console terminal.  All
	!	characters read will be forced to uppercase before echoing; no
	!	lowercase characters will be returned.
	!
	! ENVIRONMENT:
	!
	!	Kernel access mode, kernel or interrupt stack, any IPL.
	!
	! PARAMETERS:
	!
	!	prompt
	!		A string or the address of the zero terminatted string
	!		to be output.  If a string is specified then it will be
	!		compiled as a UPLIT to a zero terminated string.
	!
	!	len
	!		Size of the buffer in which to store the string read
	!		from the console terminal.
	!
	!	string
	!		Address of the buffer in which to store the string read
	!		from the console terminal.
	!
	! IMPLICIT INPUTS:
	!
	!	None.
	!
	! IMPLICIT OUTPUTS:
	!
	!	None.
	!
	! SIDE EFFECTS:
	!
	!	None.
	!
	!-

	%IF %ISSTRING (prompt)
	%THEN
	    con_read_prompt (UPLIT BYTE (prompt, 0), len, string)
	%ELSE
	    con_read_prompt(prompt, len, string)
	%FI

    %;

KEYWORDMACRO
    _releasecty (
	    txcs,
	    rxcs) =

	!+
	! FUNCTIONAL DESCRIPTION:
	!
	!	"Release" the console terminal.  Control is returned to the
	!	previous "owner".
	!
	! ENVIRONMENT:
	!
	!	Kernel access mode, kernel or interrupt stack, any IPL.
	!
	! PARAMETERS:
	!
	!	txcs
	!		Value of the longword in which the console terminal
	!		transmitter status register contents was saved by a
	!		call to _owncty.
	!
	!	rxcs
	!		Value of the longword in which the console terminal
	!		receiver status register contents was saved by a call
	!		to _owncty.
	!
	! IMPLICIT INPUTS:
	!
	!	None.
	!
	! IMPLICIT OUTPUTS:
	!
	!	None.
	!
	! SIDE EFFECTS:
	!
	!	Normal output to the console terminal is resumed.  Any pending
	!	output may be resumed immediately.
	!
	!-

	con_releasecty (txcs, rxcs) %;

!+
! FIELDS:
!-

!	None.

!+
! STRUCTURES:
!-

!	None.

!+
! PROGRAM SECTION DECLARATIONS:
!-

!	None.

!+
! EQUATED SYMBOLS:
!-

!	None.

!+
! OWN (R/O) STORAGE:
!-

!	None.

!+
! OWN (R/W) STORAGE:
!-

!	None.

!+
! BUILTIN DECLARATIONS:
!-

!	None.

!+
! EXTERNAL ROUTINES:
!-

EXTERNAL ROUTINE
    con_getchar : 				! Get next character from console.
	consolio_getchar_linkage,
    con_outblank : 				! Output an ASCII blank character to console.
	NOVALUE consolio_outblank_linkage,
    con_outchar : 				! Output an ASCII character to console.
	NOVALUE consolio_outchar_linkage,
    con_outcrlf : 				! Output a CR/LF sequence to console.
	NOVALUE consolio_outcrlf_linkage,
    con_outcstring : 				! Output a ASCIC string to console.
	NOVALUE consolio_outcstring_linkage,
    con_outhex : 				! Output a value in hexadecimal to console.
	NOVALUE consolio_outhex_linkage,
    con_outzstring : 				! Output a ASCIZ string to console.
	NOVALUE consolio_outzstring_linkage,
    con_owncty : 				! "Allocate" console terminal.
	NOVALUE consolio_owncty_linkage,
    con_putchar : 				! Output character to console.
	NOVALUE consolio_putchar_linkage,
    con_putstring : 				! Output character string to console.
	NOVALUE consolio_putstring_linkage,
    con_read_prompt,				! Read string with prompt from console.
    con_releasecty : 				! "Deallocate" console terminal.
	NOVALUE consolio_releasecty_linkage;

!+
! EXTERNAL REFERENCES:
!-

!	None.