{ ----------------------------------------------------------------------------- NOTICE: THESE MATERIALS are UNSUPPORTED by OSS! If you do not understand how to use them do not contact OSS for help! We will not teach you how to program in Pascal. If you find an error in these materials, feel free to SEND US A LETTER explaining the error, and how to fix it. THE BOTTOM LINE: Use it, enjoy it, but you are on your own when using these materials! DISCLAIMER: OSS makes no representations or warranties with respect to the contents hereof and specifically disclaim all warranties of merchantability or fitness for any particular purpose. This document is subject to change without notice. OSS provides these materials for use with Personal Pascal. Use them in any way you wish. -------------------------------------------------------------------------- } Character I/O Page 1 Character Input and Output The ST supports five character oriented devices. Of these five, you will probably only use four, the printer port, the RS232 port, the MIDI port, and the keyboard/console. The other device is the internal data path to the intelligent keyboard unit (which handles the mouse and joysticks, as well as the keyboard); you will seldom, if ever, need to access that device directly! One of the most common operations on character oriented devices is reading a single character. The following few routines perform that function: Read character from standard input. FUNCTION conin : Long_Integer ; GEMDOS( 1 ) ; This call waits for a character to be typed from the standard input device (normally the keyboard), echoes it to the standard output (normally the screen), and returns the character thus read in the same manner as the bconin BIOS call. This call should only be used from a TOS application. You can also get a character from the standard input by Reading characters from the standard file Input, which is equivalent to using this routine. In fact, unless you have a real need to use the routines described here, it is usually better to use built-in Pascal methods. Get a character from the auxilliary (RS232) device. FUNCTION auxin : Integer ; GEMDOS( 3 ) ; If you want characters from the RS232 device, use this routine. Since the characters returned by this call are only 8 bits, the return value is only an Integer. Get character from character-oriented device. This next routine is the underlying BIOS call which can be used to perform input from any of the five devices. You should normally use one of the above GEMDOS calls whenever possible, but if you need to get input from the MIDI port, for example, you will need this routine: FUNCTION bconin( device : Integer ) : Long_Integer ; BIOS( 2 ) ; This function returns a character from the specified character-oriented device. The valid values for the device parameter are as follows: 0 printer port (not used for input) 1 RS232 port 2 keyboard 3 MIDI port 4 intelligent keyboard (don't use!) If no character was waiting when bconin was called, it waits until a character is available. If you don't want to wait for characters, you should call bconstat first, to determine that a character is available. The bconin function returns the character value in the low byte of the returned Character I/O Page 2 Long_Integer. If the specified device is the console (device 2), however, the return value is more complex. In that case, the keyboard scancode is returned in the upper word, and the ASCII equivalent (if any) is returned in the lower word. If you only want the Integer return value, and you want to assign it to an Integer variable, remember that you must use the built-in function Int to convert from a Long_Integer to an Integer. You may wish to find out whether a character is available before calling one of the character input routines. Just as we saw above, there are several calls designed to get that status: Get status of standard input. Don't use this one!!! FUNCTION c_conis : boolean ; GEMDOS( 11 ) ; This routine is supposed to return True if at least one character is available on the standard input device (normally the keyboard). If the keyboard buffer ever gets full, however, this routine ceases to work properly, always returning True. For this reason, we recommend you use the bconstat BIOS call, instead. Get status of auxilliary (RS232) port. FUNCTION auxstat : Boolean ; GEMDOS( 18 ) ; This call returns True, if at least one character is ready for input from the RS232 port, and False, otherwise. If you need to get the input status of the MIDI port or the keyboard (because of the bug in constat, above), you will have to use the following routine which is the underlying BIOS call: Character-oriented device input status FUNCTION bconstat( device : Integer ) : Boolean ; BIOS( 1 ) ; This function expects the number of a character oriented device, as described above (0-4). It returns a True value if at least one character is waiting for input and False otherwise. If the device is the printer, however, there is one situation where the returned status will not be correct. You might want to define your own special-purpose status routine as follows, so you don't have to insert the device except in one place: (* Return True, if there is a keyboard character waiting. *) FUNCTION Char_Waiting : Boolean ; CONST keyboard = 2 ; (* Device number of the keyboard. *) Character I/O Page 3 FUNCTION bconstat( device : Integer ) : Boolean ; BIOS( 1 ) ; BEGIN Char_Waiting := bconstat( keyboard ) ; END ; Besides character input and input status, you also need to be able to put characters to character devices. The following routines allow those actions: Write a character to the standard output. PROCEDURE conout( c : Integer ) ; GEMDOS( 2 ) ; This call puts a character to the standard output device (normally the screen). The effect is identical to Writeing characters to the standard file Output. You should only use this call from a TOS application. Put character to character-oriented device. PROCEDURE bconout( device, c : integer ) ; BIOS( 3 ) ; This routine writes a single character to the specified device. If the device's output buffer is full, the routine will wait until the character is actually placed in the buffer. If you don't want to wait for output, you should call bcostat first, to determine that the device is ready to receive the next character. Character-oriented device output status. FUNCTION bcostat( device : Integer ) : Boolean ; BIOS( 8 ) ; This routine checks to see whether the specified device is ready to accept another character. It returns True, if the device is ready to receive, and False otherwise. If the ST is powered up while the printer is off-line, the hardware does not detect the off-line condition. The bcostat call will return True, in this case, even though the printer is not ready to accept data. As soon as the printer is turned on-line again, the status is correct. Get status of standard print device. FUNCTION c_prnos : Boolean ; GEMDOS( 17 ) ; This call returns True if the printer is available to accept characters, False otherwise. However, as mentioned in the section about the bcostat BIOS call, the ST hardware cannot detect an off-line condition if the ST is powered up while the printer is off-line. In this situation, the c_prnos function will erroneously return True. Character I/O Page 4 Check output status of auxilliary device (RS232). FUNCTION c_auxos : Boolean ; GEMDOS( 19 ) ; This routine returns True, if the standard auxilliary device (normally the RS232 port) is ready to accept data, and False, otherwise. If the auxilliary device is the RS232 port, this call will only return False if the RTS/CTS flow control method is used, and CTS goes to a false condition.