.sp 2
.cs 5
.mt 5
.mb 6
.pl 66
.ll 65
.po 10
.hm 2
.fm 2
.ft All Information Presented Here is Proprietary to Digital Research
.tc    4.3 Character I/O Functions
.he CP/M-8000 Programmer's Guide          4.4  Character I/O Functions
.sh
4.4  Character I/O Functions
.qs
.ix character I/O functions
.ix I/O functions, character
.pp 
Character I/O functions read or write characters serially to a 
peripheral device. Character I/O functions supported in CP/M-8000
are described in this section and listed in Table 4-13. 
.sp 2
.sh 
.ce
Table 4-13. Character I/O Functions
.sp 
.nf
                  Function             Function Number
.sp 
            Console Operations
.sp
               Console Input                  1
.sp
               Console Output                 2
.sp
               Direct Console I/O             6
.sp
               Print String                   9
.sp
               Read Console Buffer            10
.sp
               Get Console Status             11
.bp
.pn 63
.sh
.ce
Table 4-13.  (continued)
.sp 
.nf
                  Function             Function Number
.sp 
            Additional Serial I/O
.sp
               Auxiliary Input                3
.sp
               Auxiliary Output               4
.sp 
               List Output                    5
.sp 2
            I/O Byte 
.sp 2
               Get I/O Byte                   7
.sp
               Set I/O Byte                   8
.ix functions, console
.fi
.in 0
.ll 65
.bp
.tc         4.4.1  Console I/O Functions
.sh
4.4.1  Console I/O Functions
.qs
.ix console I/O functions
.pp
This section describes functions that read from, write to, and
report the status of the logical device CONSOLE.
.sp 2
.tc                Console Input Function
.ul
Console Input Function
.qu
.sp 3
.nf
                   FUNCTION 1:  CONSOLE INPUT

               Entry Parameters:
                  Register   R5:  01H

               Returned  Values:
                  Register   R7:  ASCII Character
.sp 2
.fi
.ix logical console device
.ix tab characters
.pp
The Console Input function reads the next character from the
logical console device (CONSOLE) to register   R7.  Printable
characters, along with carriage return, line feed, and backspace
(CTRL-H), are echoed to the console. Tab characters (CTRL-I)
are expanded into columns of eight characters. Other CONTROL
characters, such as CTRL-C, are processed.  The BDOS does not
return to the calling program until a character has been typed.
Thus, execution of the program is suspended until a character is ready. 
.ix console input
.bp
.tc                Console Output Function
.ul
Console Output Function
.qu
.ix console output function
.sp 3
.nf
                   FUNCTION 2:  CONSOLE OUTPUT

               Entry Parameters:
                  Register   R5:  02H
                  Register   R7:  ASCII Character

               Returned  Values:
                  Register   R7:  00H
.sp 2
.fi
.pp
The ASCII character from   R7 is sent to the logical console.
Tab characters expand into columns of eight characters.  In addition, a 
check is made for stop scroll (CTRL-S), start scroll (CTRL-Q), 
and the printer switch (CTRL-P). This function also processes
CTRL-C, which aborts the operation and warm boots the system.  If the console 
is busy, 
execution of the calling program is suspended until the console 
accepts the character.
.ix console output
.ix stop scroll
.ix start scroll
.ix printer switch
.bp
.tc                Direct Console I/O Function
.ul  
Direct Console I/O Function
.qu
.ix direct console I/O function
.sp 3
.nf
                 FUNCTION 6:  DIRECT CONSOLE I/O

             Entry Parameters: 
                Register   R5:  06H
                Register   R7:  0FFH (input)
                                0FEH (status)
                                     or
                                Character (output)

             Returned  Values:
                Register   R7:  Character or Status
.sp 2
.fi
.ix I/O, direct console
.ix BDOS function, direct console I/O
.ix direct console I/O
.pp
Direct Console I/O is supported under CP/M-8000 for those specialized
applications where character-by-character console input and output are
required without the control character functions CP/M-8000 supports.  This
function bypasses all of CP/M-8000's normal CONTROL character functions such
as CTRL-S, CTRL-Q, CTRL-P, and CTRL-C. 
.pp
Upon entry to the Direct Console I/O Function, register   R7
contains one of the values listed below. 
.sp 2
.ce
.sh
Table 4-14.  Direct Console I/O Function Values
.qs
.sp
.in 5
.ll 60
.nf
  Value                     Meaning
.fi
.sp
.in 18
.ti -13
FFH          denotes a CONSOLE input request
.sp
.ti -13
FEH          denotes a CONSOLE status request    
.sp
.ti -13
ASCII 
.sp 0
.ti -13
character    output to CONSOLE where CONSOLE is the logical console device
.in 0
.ll 65
.sp
.pp 
.fi
When the input value is FFH, the Direct Console I/O Function calls the BIOS
Conin Function, which returns the next console input character in   R7 but
does not echo the character on the console screen. The BIOS Conin function
waits until it receives a character. Thus, execution of the calling program
remains suspended until a character is ready. 
.pp
When the input value is FEH, the Direct Console I/O Function returns 
the status of the console input in register   R7. When register   R7 
contains the value zero, no console input exists.  However, when 
the value in   R7 is nozero, console input is ready to be read by 
the BIOS Conin Function.
.pp
When the input value in   R7 is neither FEH nor FFH, the Direct
Console I/O Function assumes that   R7 contains a valid ASCII
character, which is sent to the console. 
.bp
.tc                Print String Function
.ul
Print String Function
.qu
.ix print string function
.sp 3
.nf
                    FUNCTION 9:  PRINT STRING

               Entry Parameters:
                  Register   R5:  09H
                  Register  RR6:  String  Address

               Returned  Values:
                  Register   R7:  00H
.sp 2
.fi
.pp
The Print String function sends the character string stored in
memory at the location given in register  RR6 to the logical
console device (CONSOLE) until a dollar sign ($) is encountered
in the string. Tabs are expanded as in the Console Output
Function (2), and checks are made for stop scroll (CTRL-S), 
start scroll (CTRL-Q), and the printer switch (CTRL-P). 
.ix print string
.bp
.tc                Read Console Buffer Function
.ul
Read Console Buffer Function
.qu
.ix read console buffer function
.ix console buffer
.sp 3
.nf
               FUNCTION 10:  READ CONSOLE BUFFER

               Entry Parameters:
                  Register   R5:  0AH
                  Register  RR6:  Buffer Address

               Returned  Values:
                  Register   R7:  00H
                Register Buffer:  Character Count
                                  and Characters
.sp 2
.fi
.ix logical console device
.pp
The Read Buffer function reads a line of edited console input from the
logical console device (CONSOLE) to a buffer address passed in register
 RR6. Console input is terminated when the input buffer is filled, or, a
RETURN (CTRL-M) or a line feed (CTRL-J) character is entered.  The input
buffer addressed by  RR6 takes the form: 
.sp 2
.nf
         RR6:  +0 +1 +2 +3 +4 +5 +6 +7 +8    . . .    +n
   
               mx nc c1 c2 c3 c4 c5 c6 c7    . . .    ??
   
.fi
.sp
The variable mx is the maximum number of characters the buffer holds. The
variable nc is the total number of characters placed in the buffer. Your
program must set the mx value prior to invoking this function. The mx value
can range in value from 1 through 255 (decimal).  The characters entered
from the keyboard follow the nc value.  The value nc is returned to the
buffer.  It can range from 0 to the value of mx.  If the nc value is less
than the mx value, uninitialized characters follow the last character.  
Uninitialized
characters are denoted by the double question marks (??) in the above
figure.  A terminating RETURN or line feed character is not placed in the
buffer and is not included in the total character count nc. 
.ix read buffer
.pp
This function supports several editing control functions, which 
are briefly described in Table 4-15. 
.ix editing control functions
.bp
.ce
.sh
Table 4-15.  Line Editing Controls
.ix line editing controls
.sp
.in 5 
.nf
Keystroke                      Result
.sp
.ll 60
.fi
.in 19
.ti -14
RUB/DEL       removes and echoes the last character
.sp 
.ti -14
CONTROL-C     reboots when it is the first character on a line
.sp 
.ti -14
CONTROL-E     causes physical end-of-line
.sp 
.ti -14
CONTROL-H     backspaces one character position
.sp 
.ti -14
CONTROL-J     (line feed) terminates input line
.sp 
.ti -14
CONTROL-M     (return) terminates input line
.sp 
.ti -14
CONTROL-P     starts and stops the echoing of console output to the logical 
LIST device 
.sp 
.ti -14
CONTROL-Q     restarts console I/O after CTRL-S halts it
.sp 
.ti -14
CONTROL-R     retypes the current line on the next line
.sp 
.ti -14
CONTROL-S     halts console I/O and waits for CTRL-Q to restart it
.sp 
.ti -14
CONTROL-U     echoes a pound sign (#) indicating ignore characters previously 
input on the current line before it positions the cursor on the next line 
.sp 
.ti -14
CONTROL-X     backspaces to beginning of current line
.fi
.ll 65
.in 0
.sp 2
Certain functions that position the cursor to the leftmost position 
(for example, CONTROL-X) move the cursor to the column position where the 
cursor 
was prior to invoking the Read Console Buffer Function.  This convention 
makes your data 
input and line correction more legible.
.bp
.tc                Get Console Status Function
.ul
Get Console Status Function 
.qu
.ix get console status function
.sp 3
.nf 
                FUNCTION 11:  GET CONSOLE STATUS

                Entry Parameters:
                   Register   R5:  0BH

                Returned  Values:
                   Register   R7:  Console Status
.sp 2
.fi
.ix console status
.pp
The Get Console Status Function checks whether a character has been
typed at the logical console device (CONSOLE). If a character is
ready, a nonzero value is returned in register   R7; otherwise the 
value 00H is returned in   R7. 
.ix console status
.bp
.tc         4.4.2 Additional Serial I/O Functions
.sh
4.4.2  Additional Serial I/O Functions
.qs
.ix additional serial I/O functions
.ix serial I/O functions
.pp
This section describes additional serial I/O functions that read and 
write data to devices defined by I/O Byte Functions (7,8). 
.sp 2
.tc                Auxiliary Input Function
.ul
Auxiliary Input Function
.qu
.ix auxiliary input function
.ix auxiliary input device
.sp 3
.nf
                  FUNCTION 3:  AUXILIARY INPUT

               Entry Parameters:
                  Register   R5:  03H

               Returned  Values:
                  Register   R7:  ASCII Character
.sp 2
.fi
.pp
The Auxiliary Input function reads the next character from the
auxiliary input device into register   R7.  Execution of the 
calling program remains suspended until the character is read. 
This function assumes the BIOS 
implements its Auxiliary Input Function. When more than one 
auxiliary input port exists, the BIOS should implement the 
I/O Byte Function. For details on the 
BIOS Auxiliary Input and I/O Byte Functions, refer
to the \c
.ul
CP/M-8000 Operating System System Guide.
.qu
.ix auxiliary input
.bp
.tc                Auxiliary Output Function
.ul
Auxiliary Output Function
.qu
.sp 3
.ix auxiliary output function
.nf
                  FUNCTION 4:  AUXILIARY OUTPUT

               Entry Parameters:
                  Register   R5:  04H
                  Register   R7:  ASCII Character

               Returned  Values:
                  Register   R7:  00H
.sp 2
.fi
.ix auxiliary output device
.pp
The Auxiliary Output function sends a character from register
  R7 to the auxiliary output device. Execution of the calling 
program remains suspended until the hardware buffer receives the
output character. This function assumes the BIOS 
implements its Auxiliary Output Function. When more than one 
auxiliary output port exists, the BIOS should implement the 
I/O Byte Function. For details on the 
BIOS Auxiliary Output and I/O Byte Functions, refer
to the \c
.ul
CP/M-8000 Operating System System Guide.
.qu
.ix auxiliary output
.bp
.tc                List Output Function
.ul
List Output Function
.qu
.ix list output function
.sp 3
.nf
                    FUNCTION 5:  LIST OUTPUT

               Entry Parameters:
                  Register   R5:  05H
                  Register   R7:  ASCII Character

               Returned  Values:
                  Register   R7:  00H
.sp 2
.ix logical list device (LIST)
.fi
.pp
The List Output function sends the ASCII character in register
  R7 to the logical list device (LIST).
.ix list output
.sp 2
.tc         4.4.3  I/O Byte Functions
.sh
4.4.3  I/O Byte Functions
.qs
.ix I/O byte functions
.pp
This section describes the I/O Byte Functions.  The I/O Byte is
an 8-bit value that assigns physical devices, represented by 2-bit 
fields, to each of the logical
devices: CONSOLE, AUXILIARY INPUT, AUXILIARY OUTPUT, and LIST as
shown in Figure 4-3. The I/O Byte functions allow programs to
access the I/O byte to determine its current value (Get I/O Byte)
or to modify it (Set I/O Byte).  These functions are valid only
if the BIOS implements its I/O Byte Function.  Refer to the \c
.ul
CP/M-8000 Operating System System Guide 
.qu
for details on implementing the I/O Byte Function. 
.sp 3
.nf
                 most significant        least significant

I/O Byte     LIST  AUXILIARY OUTPUT   AUXILIARY INPUT CONSOLE

bits          7,6           5,4           3,2           1,0         
.ix IOBYTE
.fi
.sp 2
.ce
.sh
Figure 4-3.  I/O Byte
.qs
.sp 2 
.pp
The value in each field ranges from 0-3. The value defines the
assigned source or destination of each logical device, as shown in Table 
4-16.
.bp
.ce
.sh
Table 4-16.  I/O Byte Field Definitions
.qs
.sp
.in 14
.ll 60
.li
.ti -9
CONSOLE field (bits 1,0)
.ti -5
0  - console is assigned to the console printer (TTY:)
.ti -5
1  - console is assigned to the CRT device (CRT:)
.ti -5
2  - batch mode: use the AUXILIARY INPUT as the CONSOLE input, and the 
LIST device as the CONSOLE output (BAT:)
.ti -5
3  - user defined console device (UC1:)
.sp
.ti -9
AUXILIARY INPUT field (bits 3,2)
.ti -5
0  - AUXILIARY INPUT is the Teletype device (TTY:)
.ti -5
1  - AUXILIARY INPUT is the high-speed reader device (PTR:)
.ti -5
2  - user defined reader # 1 (UR1:)
.ti -5
3  - user defined reader # 2 (UR2:)
.sp
.ti -9
AUXILIARY OUTPUT field (bits 5,4)
.ti -5
0  - AUXILIARY OUTPUT is the Teletype device (TTY:)
.ti -5
1  - AUXILIARY OUTPUT is the high-speed punch device (PTP:)
.ti -5
2  - user defined punch # 1 (UP1:)
.ti -5
3  - user defined punch # 2 (UP2:)
.sp
.ti -9
LIST field (bits 7,6)
.ti -5
0  - LIST is the Teletype device (TTY:)
.ti -5
1  - LIST is the CRT device (CRT:)
.ti -5
2  - LIST is the line printer device (LPT:)
.ti -5
3  - user defined list device (UL1:)
.in 0
.ll 65
.sp
.pp
The implementation of the BIOS I/O Byte Function is optional. PIP
and STAT are the only CP/M-8000 utilities that use the I/O Byte.
PIP accesses physical devices. STAT designates and displays
logical to physical device assignments. For details on implementing
the I/O Byte Function, refer to the \c
.ul
CP/M-8000 Operating System System Guide. 
.qu
.nx fourf
