.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