Home GEMDOSGEMDOS Directory functionsDirectory functions NetworkNetwork

5.16 Character input/output

• Cauxin  Reads character from serial port.
• Cauxis  Obtains input status of serial port.
• Cauxos  Obtains output status of serial port.
• Cauxout Writes character to serial port.
• Cconin  Reads character from standard input device.
• Cconis  Checks keyboard buffer whether character is waiting.
• Cconos  Checks status of standard output device.
• Cconout Writes character to standard output device.
• Cconrs  Reads string from standard input device.
• Cconws  Outputs string to standard output device.
• Cnecin  Reads character without displaying it on-screen.
• Cprnos  Obtains printer status.
• Cprnout Outputs character to printer.
• Crawcin Reads character without display/interpretation.
• Crawio  Reads character direct from keyboard, or outputs it to screen.

Note: The output routines of the GEMDOS emulate a VT52 terminal.

5.16.1 Cauxin

Name: »Character auxiliary input« - Input via serial port.
 
Opcode: 3
 
Syntax: int32_t Cauxin ( void );
 
Description: The GEMDOS routine Cauxin reads a character byte from the GEMDOS handle 2 - normally the serial port aux:. The function waits until the character arrives.
 
Note: Atari recommends use of the BIOS function Bconin for this, as Cauxin can cause problems when its handle is redirected and end-of-file is encountered.
 
Return value: The function returns the read-in character in the low byte of the returned WORD.
 
Availability: All GEMDOS versions.
 
Group: Character input/output
 
See also: Binding   Cauxout   Bconin
 

5.16.1.1 Bindings for Cauxin

C: int32_t Cauxin ( void );
 
Assembler:
  
move.w    #3,-(sp)     ; Offset 0
trap      #1           ; GEMDOS
addq.l    #2,sp        ; Correct stack

5.16.2 Cauxis

Name: »Character auxiliary input status« - Check the input status of the serial port.
 
Opcode: 18
 
Syntax: int16_t Cauxis ( void );
 
Description: The GEMDOS routine Cauxis checks the status of GEMDOS handle 2 - normally the serial port aux: - to see whether at least one character is waiting to be received.
 
Note: The function works correctly with redirection of input/output only as of GEMDOS Version 0.15. Atari recommends the use of the BIOS function Bconstat instead.
 
Return value: The function can return the following results:
 
Value Meaning
   
-1 At least one character in buffer available
0 No character available
Availability: All GEMDOS versions.
 
Group: Character input/output
 
See also: Binding   Cauxos
 

5.16.2.1 Bindings for Cauxis

C: int16_t Cauxis ( void );
 
Assembler:
  
move.w    #18,-(sp)    ; Offset 0
trap      #1           ; GEMDOS
addq.l    #2,sp        ; Correct stack

5.16.3 Cauxos

Name: »Character auxiliary output status« - Check the ouput status of the serial port.
 
Opcode: 19
 
Syntax: int16_t Cauxos ( void );
 
Description: The GEMDOS routine Cauxos checks the status of GEMDOS handle 2 - normally the serial port aux: - to see whether it is ready to output characters.
 
Note: Atari recommends use of the BIOS function Bcostat for this.
 
Return value: The function can return the following results:
 
Value Meaning
   
-1 Character can be output
0 Character can not be output
Availability: All GEMDOS versions.
 
Group: Character input/output
 
See also: Binding   Cauxis   Bcostat
 

5.16.3.1 Bindings for Cauxos

C: int16_t Cauxos ( void );
 
Assembler:
  
move.w    #19,-(sp)    ; Offset 0
trap      #1           ; GEMDOS
addq.l    #2,sp        ; Correct stack

5.16.4 Cauxout

Name: »Character auxiliary output« - Write a character to the serial port.
 
Opcode: 4
 
Syntax: int32_t Cauxout ( int16_t c );
 
Description: The GEMDOS routine Cauxout writes the character c to GEMDOS handle 2 - normally the serial port aux:.
 
Note: The function works correctly with redirection of input/output only as of GEMDOS Version 0.15. Atari recommends the use of the BIOS function Bconout instead.
 
Return value: The function returns a negative value in case of error.
 
Availability: All GEMDOS versions.
 
Group: Character input/output
 
See also: Binding   Cauxin   Bconout
 

5.16.4.1 Bindings for Cauxout

C: int32_t Cauxout ( int16_t c );
 
Assembler:
  
move.w    c,-(sp)      ; Offset 2
move.w    #4,-(sp)     ; Offset 0
trap      #1           ; GEMDOS
addq.l    #4,sp        ; Correct stack

5.16.5 Cconin

Name: »Character console input« - Read a character from the standard input device.
 
Opcode: 1
 
Syntax: int32_t Cconin ( void );
 
Description: The GEMDOS routine Cconin reads a character from GEMDOS handle 0 - normally the standard input device con: (the keyboard as a rule), waiting until one is available.
 
Note: By setting bit 3 of the system variable conterm one can have the value of Kbshift returned in bits 24..31. Unfortunately there is no way to recognise input/output redirection or end-of-file. That is why many libraries define the key combination Control-Z (ASCII-code 26) as the character for end-of-file.
 
Return value: The function returns a LONG with the ASCII-code of the character in the lower WORD (bits 0 .. 7). If the read character originates from the keyboard, then the lower 8 bits of the higher WORD (bits 16 .. 23) contain the scancode of the keyboard, with Shift-key status in the upper 8 bits as mentioned above. Note that if a non-ASCII key is pressed, the ASCII-code returned will be 0.
 
Availability: All GEMDOS versions.
 
Group: Character input/output
 
See also: Binding   Cconout   Cconis   Kbshift
 

5.16.5.1 Bindings for Cconin

C: int32_t Cconin ( void );
 
Assembler:
  
move.w    #1,-(sp)     ; Offset 0
trap      #1           ; GEMDOS
addq.l    #2,sp        ; Correct stack

5.16.6 Cconis

Name: »Character console is waiting« - Check whether a character is waiting in the standard input buffer.
 
Opcode: 11
 
Syntax: int32_t Cconis ( void );
 
Description: The GEMDOS routine Cconis checks whether a character is waiting to be read in GEMDOS handle 0 - normally the standard input buffer of con:.
 
Return value: The function can return the following results:
 
Value Meaning
   
-1L Character available
0L Character not available
Availability: All GEMDOS versions.
 
Group: Character input/output
 
See also: Binding   Cconin
 

5.16.6.1 Bindings for Cconis

C: int32_t Cconis ( void );
 
Assembler:
  
move.w    #11,-(sp)    ; Offset 0
trap      #1           ; GEMDOS
addq.l    #2,sp        ; Correct stack

5.16.7 Cconos

Name: »Character console output status« - Check status of standard output device.
 
Opcode: 16
 
Syntax: int16_t Cconos ( void );
 
Description: The GEMDOS routine Cconos checks whether a character may be output to GEMDOS handle 1 - normally the standard output device con:.
 
Note: The function works correctly with redirection of input/output only as of GEMDOS Version 0.15.
 
Return value: The function returns the status of the standard output device, as follows:
 
Value Meaning
   
0 Character can not be output
1 At least one character can be output
Availability: All GEMDOS versions.
 
Group: Character input/output
 
See also: Binding   Cconout
 

5.16.7.1 Bindings for Cconos

C: int16_t Cconos ( void );
 
Assembler:
  
move.w    #16,-(sp)    ; Offset 0
trap      #1           ; GEMDOS
addq.l    #2,sp        ; Correct stack

5.16.8 Cconout

Name: »Character console output« - Write one character to the standard output device.
 
Opcode: 2
 
Syntax: int32_t Cconout ( int16_t c );
 
Description: The GEMDOS routine Cconout writes the character c to GEMDOS handle 1 - normally the standard output device con: - as a rule the screen.
 
Note: The character c contain the associated ASCII-code in bits 0..7 (all other bits have to be 0). No line-feed translation is done at the output, so ASCII 13 and ACII 10 must be sent to start a new line. The function works correctly with redirection of the input/output only as of GEMDOS Version 0.15; with earlier versions, do not redirect this handle to a write-only device since the call tries to read from the output stream to process the 'special' keys.
 
Return value: The return value of the function depends on the operating system. The following apply:
 
Operating system Value
   
TOS No sensible return value
MagiC < 3.00
< 0 = Error
0L = Output device is full
1L = Output was successful
MiNT/MagiC > 3.00
< 0 = Error
0L = Output device is full
1L = Output was successful
4L = Output to the terminal was successful
Availability: All GEMDOS versions.
 
Group: Character input/output
 
See also: BindingCconin   Cconos   VT52 terminal
 

5.16.8.1 Bindings for Cconout

C: int32_t Cconout ( int16_t c );
 
Assembler:
  
move.w    c,-(sp)      ; Offset 2
move.w    #2,-(sp)     ; Offset 0
trap      #1           ; GEMDOS
addq.l    #4,sp        ; Correct stack

5.16.9 Cconrs

Name: »Character console read string« - Read a string from the standard input.
 
Opcode: 10
 
Syntax: int32_t Cconrs ( LINE *buf );
 
Description: The GEMDOS routine Cconrs reads a string from the standard input stream (GEMDOS handle 0) - normally the keyboard - and echoes it to the standard output stream (GEMDOS handle 1) - normally the screen.
 
To do this one writes in the component maxlen of LINE the number of bytes to be read in - 1. The input will be terminated by the function when the Return key is pressed or the maximum input length has been exceeded.
 
'Special' key combinations cause various actions. In detail:
 
Input Meaning
   
Return End of input; don't place Return in buffer
Control-J End of line; don't place Ctrl-J in buffer
Control-H Kill last character (= Delete)
Backspace Delete last character
Control-U/X Delete whole line and start over
Control-R Echo input line and start over
Control-C Terminate program (!)

Note: Umlauts are handled correctly by the function only as of GEMDOS Version 0.15. On earlier versions a possible end-of-file will not be recognised, and read characters will be output to the screen even if the standard output has been redirected.
 
In MagiC the function has been greatly extended; here the following apply:
 
Input Meaning
   
Cursor up/down Get back last input
Cursor left/right Move cursor by one character L/R
ditto with Shift Cursor to start/end of line
ClrHome Cursor to start of line
Insert Insert mode
Shift-Insert Overwrite mode
Shift-Clear Delete input
Tabulator Alternate line-start/-end
Undo Undo last input
Delete/Backspace Delete char. under/before cursor
F1..F10 Call environmental variables F1..F10

With normal files MagiC will read up to the first LF, while CR is skipped. The environmental variables can be assigned with any desired command interpreter (e.g. the Mupfel).
 
Return value: The function returns the value 0L on successful conclusion, or a negative number in case of error.
 
Availability: All GEMDOS versions.
 
Group: Character input/output
 
See also: Binding   Cconws   MagiC
 

5.16.9.1 Bindings for Cconrs

C: int32_t Cconrs ( LINE *buf );
 
Assembler:
  
pea       buf          ; Offset 2
move.w    #10,-(sp)    ; Offset 0
trap      #1           ; GEMDOS
addq.l    #6,sp        ; Correct stack

5.16.10 Cconws

Name: »Character console write string« - Write a string to the standard output device.
 
Opcode: 9
 
Syntax: int32_t Cconws ( CONST BYTE *buf );
 
Description: The GEMDOS routine Cconws writes the string buf to GEMDOS handle 1 - normally the standard output device con:. The string must be NULL-terminated (with the ASCII character 0). With GEMDOS versions below 0.15, do not redirect this handle to a write-only device since the call tries to read from the output stream to process the 'special' keys.
 
Return value: Under TOS 1.04 the function returns the value 0L on successful execution, or the value -1L in case of error.
Since MagiC 3.00 is there no return value respectively is it the value form Fwrite.
 
Availability: All GEMDOS versions.
 
Group: Character input/output
 
See also: Binding   Cconrs   VT-52 terminal   ASCII table
 

5.16.10.1 Bindings for Cconws

C: int32_t Cconws ( CONST BYTE *buf );
 
Assembler:
  
pea       buf          ; Offset 2
move.w    #9,-(sp)     ; Offset 0
trap      #1           ; GEMDOS
addq.l    #6,sp        ; Correct stack

5.16.11 Cnecin

Name: »Character no echo input« - Read character from the standard input device without displaying it on-screen.
 
Opcode: 8
 
Syntax: int32_t Cnecin ( void );
 
Description: The GEMDOS routine Cnecin reads a character from GEMDOS handle 0 - normally the standard input device con: (the keyboard as a rule), without outputting it to the standard output device (normally the screen).
 
Note: Flow control can be achieved with the key combinations Control-S (stop output) or Control-Q (continue output). With GEMDOS versions prior to 0.30, if the function's handle is redirected an end-of-file condition will cause the system to hang.
 
Return value: The function returns a LONG with the ASCII-code of the character in the lower WORD (bits 0 .. 7). If the read character originates from the keyboard, then the lower 8 bits of the higher WORD (bits 16 .. 23) will contain the scancode of the keyboard, with Shift-key status in the upper 8 bits provided bit 3 of the system variable conterm is set. Note that if a non-ASCII key is pressed, the ASCII-code returned will be 0.
 
Availability: All GEMDOS versions.
 
Group: Character input/output
 
See also: Binding   Cconin   Crawcin   Crawio
 

5.16.11.1 Bindings for Cnecin

C: int32_t Cnecin ( void );
 
Assembler:
  
move.w    #8,-(sp)     ; Offset 0
trap      #1           ; GEMDOS
addq.l    #2,sp        ; Correct stack

5.16.12 Cprnos

Name: »Character printer output status« - Check the status of the printer port.
 
Opcode: 17
 
Syntax: int16_t Cprnos ( void );
 
Description: The GEMDOS routine Cprnos checks whether handle 3 - normally the parallel port prn: - is ready to accept characters.
 
Note: It is strongly recommended to use this function before starting a printout, since it takes around 30 seconds to recognize a printer timeout if the printer is not ready (perhaps not switched on?).
 
Return value: The function can return the following results:
 
Value Meaning
   
-1 Printer is ready
0 Printer is not ready
Availability: All GEMDOS versions.
 
Group: Character input/output
 
See also: Binding   Cconos
 

5.16.12.1 Bindings for Cprnos

C: int16_t Cprnos ( void );
 
Assembler:
  
move.w    #17,-(sp)    ; Offset 0
trap      #1           ; GEMDOS
addq.l    #2,sp        ; Correct stack

5.16.13 Cprnout

Name: »Character printer output« - Write a character to the printer port.
 
Opcode: 5
 
Syntax: int32_t Cprnout ( int16_t c );
 
Description: The GEMDOS routine Cprnout writes the character c to GEMDOS handle 3 - normally the printer port prn:.
 
c is a WORD value, with the character to be output occupying bits 0..7; all other bits must be 0.
 
Note: Before print output one should check with Cprnos whether the printer is ready. Settings made with the aid of the Setprt function are ignored for printing by almost all TOS versions. With redirection of input/output, the function works correctly only as of GEMDOS Version 0.15.
 
Return value: The function returns 0 in case of error, else non-zero if it wrote the character to the printer successfully.
 
Availability: All GEMDOS versions.
 
Group: Character input/output
 
See also: Binding   Cprnos   Setprt
 

5.16.13.1 Bindings for Cprnout

C: int32_t Cprnout ( int16_t c );
 
Assembler:
  
move.w    c,-(sp)      ; Offset 2
move.w    #5,-(sp)     ; Offset 0
trap      #1           ; GEMDOS
addq.l    #4,sp        ; Correct stack

5.16.14 Crawcin

Name: »Character raw input« - Read a character unbuffered from standard input device.
 
Opcode: 7
 
Syntax: int32_t Crawcin ( void );
 
Description: The GEMDOS routine Crawcin reads a character from GEMDOS handle 1 - normally the standard input con: (the keyboard) - without echoing it immediately to the screen or processing any of the 'special' keys.
 
Note: The function works correctly with input/output redirection only as of GEMDOS Version 0.15.
 
Return value: The function returns a LONG with the ASCII-code of the character in the lower WORD (bits 0 .. 7). If the read character originates from the keyboard, then the lower 8 bits of the higher WORD (bits 16 .. 23) will contain the scancode of the keyboard, with Shift-key status in the upper 8 bits provided bit 3 of the system variable conterm is set. Note that if a non-ASCII key is pressed, the ASCII-code returned will be 0.
 
Availability: All GEMDOS versions.
 
Group: Character input/output
 
See also: Binding   Cconin   Cconout   Crawio
 

5.16.14.1 Bindings for Crawcin

C: int32_t Crawcin ( void );
 
Assembler:
  
move.w    #7,-(sp)     ; Offset 0
trap      #1           ; GEMDOS
addq.l    #2,sp        ; Correct stack

5.16.15 Crawio

Name: »Character raw input output« - Permit unbuffered input/output.
 
Opcode: 6
 
Syntax: int32_t Crawio ( int16_t w );
 
Description: The GEMDOS routine Crawio combines unbuffered console input and output in one function. The following applies for the parameter w, of which only the lower 8 bits are significant (others should be 0):
 
Value Meaning
   
0xff Read character from standard input
else Output character to standard output

Note: The function works correctly with input/output redirection only as of GEMDOS Version 0.15.
 
Return value: If the parameter w has the value 0xff, the function returns a bit-array LONG with the ASCII-code of the character in the lower WORD (bits 0 .. 7). If the read character originates from the keyboard, then the lower 8 bits of the higher WORD (bits 16 .. 23) will contain the scancode of the keyboard, with Shift-key status in the upper 8 bits provided bit 3 of the system variable conterm is set. Note that if a non-ASCII key is pressed, the ASCII-code returned will be 0. A return value of 0 means that no character is available.
 
Availability: All GEMDOS versions.
 
Group: Character input/output
 
See also: Binding   Cconin   Cconout   VT-52 terminal
 

5.16.15.1 Bindings for Crawio

C: int32_t Crawio ( int16_t w );
 
Assembler:
  
move.w    w,-(sp)      ; Offset 2
move.w    #6,-(sp)     ; Offset 0
trap      #1           ; GEMDOS
addq.l    #4,sp        ; Correct stack
Home GEMDOSGEMDOS Directory functionsDirectory functions NetworkNetwork