Console I/O

Reference Section

_adapter_init
adapter_type
_afill_eol
_afill_line
_afill_n
_afill_region
attr_tbl
_bkbold_off
_bkbold_on
_blink_off
_blink_on
_bold_off
_bold_on
_ccheck_key
_cflush_keys
_cget_chr
_cget_chra
_cget_chrae
_cget_chre
_cget_s
_cget_str
_chk_dimens
_clr_eol
_clr_line
_clr_n
_clr_region
_console_init
_cput_attr
_cput_beep
_cput_chr
_cput_chri
_cput_linefeed
_cput_nattr
_cput_nchr
_cput_nchri
_cput_newline
_cput_return
_cput_str
_cput_strci
_cput_stri
_cput_strji
_cursor_off
_cursor_on
_del_line
_direc_down
_direc_left
_direc_right
direct_video
_direc_up
_fill_eol
_fill_line
_fill_n
_fill_region
_get_adapter
_get_adapters
_get_adaptinfo
_get_attr
_get_attrflags
_get_cursor
_get_dattr
_get_dimens
_get_direction
_get_dmode
_get_keyflags
_get_region
_get_tblattr
_get_vborder
_get_vmode
_get_vpage
_get_vpagecnt
_get_vstate
_goto_bottom
_goto_end
_goto_home
_goto_left
_goto_right
_goto_top
_goto_x
_goto_xy
_goto_y
_hread_textattr
_hrestore_screen
_hsave_screen
_hwrite_textattr
_ins_line
_is_cga
_is_ega
_is_enkbd
_is_mcga
_is_mda
_is_textmode
_is_vga
_kbd_init
kbd_type
monitor_type
_move_back
_move_down
_move_left
_move_next
_move_right
_move_textattr
_move_up
_read_textattr
_region_off
_region_on
_rel_xy
_reset_attr
_restore_screen
_restore_vstate
_save_screen
_save_vstate
_screen_bufsize
screen_cols
screen_dimens
screen_rows
_scroll_down
_scroll_up
_set_80cols
_set_adapter
_set_attr
_set_attrflags
_set_attrtbl
_set_biosvideo
_set_bkboldmode
_set_bkcolor
_set_blinkmode
_set_cursor
_set_dattr
_set_dimens
_set_direction
_set_directvideo
_set_fgcolor
_set_region
_set_vbordattr
_set_vborder
_set_vmode
_set_vpage
_set_vstate
_vborder_off
_vborder_on
video_mode
_video_off
_video_on
video_snow
_where_x
_where_xy
_where_y
_write_textattr

_adapter_init


Descrip
Initializes the console I/O system for multiple adapter support.

Syntax
#include <console.h>
void _adapter_init(void);

Returns
None

Notes
This function initializes the console I/O system to support one or two adapters. Specifically, this function determines which adapters are present and saves essential information about each adapter for later use by the console I/O system. Adapter information may be retrieved by calling _get_adapters and/or _get_adaptinfo.

Due to BIOS limitations, this function must make a "best guess" as to the initial state of the secondary adapter (if one is present). This guess is enforced using a BIOS mode change the first time the secondary adapter is selected by _set_adapter or by the virtual screen system.

This function must be called before _get_adaptinfo or _set_adapter may be used and before a virtual screen may be created on the secondary adapter.

C/C++ Example
	   ...
	   _adapter_init(); /* init adapter support by console i/o */
	   ...

Inline Assembly Example
	   ...
	   adapter_init();  /* init adapter support by console i/o */
	   ...

Source file CIOADINT.ASM ASM equiv ADAPTER_INIT
See also
_console_init, _get_adapter, _get_adaptinfo, monitor_type

adapter_type


Descrip
(Variable) Indicates the active display adapter type.

Syntax
#include <console.h>
extern char adapter_type;

Notes
This read-only char variable indicates the active display adapter type. The following symbolic constants (defined in CONSOLE.H) represent the supported adapter types:

MDA (0x00) Monochrome Display Adapter
CGA (0x01) Color Graphics Adapter
EGA (0x02) Enhanced Graphics Adapter
MCGA(0x03) Multi-color Graphics Array
VGA (0x04) Video Graphics Array

Note that these values are the same as those returned by the _get_adapter function.

This variable is initialized by _console_init.

Source file CIOCVAR.ASM ASM equiv ADAPTER_TYPE
See also
_console_init, _get_adapter, _get_adaptinit, _monitor_type

_afill_eol


Descrip
Sets all attributes from the cursor to the end of the current line to a specified attribute.

Syntax
#include <console.h>
void _afill_eol(int attr)

Returns
None

Notes
This function sets all attributes from the current cursor position to the end of the current line to the attribute specified by attr. The cursor position remains unchanged. If an attribute table has been specified (using _set_attrtbl), attr is treated as an attribute table code and the corresponding attribute table value is used as the fill attribute; otherwise, attr is used as the actual fill attribute. Output is restricted to the current clipping region if the clipping region is enabled; otherwise, it is restricted to the screen (or the active window if windowing is in effect). Attributes are written directly to the display through a BIOS call or directly to video memory depending on the state of the direct_video variable.

See the technical notes for an explanation of how attributes are specified.

_console_init must be called before using this function.

C/C++ Example
	   _afill_eol (WHITE+(16*BLUE));/* white on blue */

Inline Assembly Example
	#include <inline.h>
	   ...
	   mov  ah,(WHITE+(16*BLUE))
	   afill_eol();
	   ...

Source file _CIOAFLE.ASM ASM equiv AFILL_EOL
See also
_afill_line, _afill_n, _afill_region, _clr_eol, _fill_eol

_afill_line


Descrip
Sets all attributes on the current line to a specified attribute.

Syntax
#include <console.h>
void _afill_line(int attr)

Returns
None

Notes
This function sets all attributes on the current line to the attribute specified by attr. The cursor position remains unchanged. If an attribute table has been specified (using _set_attrtbl), attr is treated as an attribute table code and the corresponding attribute table value is used as the fill attribute; otherwise, attr is used as the actual fill attribute. Output is restricted to the current clipping region if the clipping region is enabled; otherwise, it is restricted to the screen (or the active window if windowing is in effect). Attributes are written directly to the display through a BIOS call or directly to video memory depending on the state of the direct_video variable.

See the technical notes for an explanation of how attributes are specified.

_console_init must be called before using this function.

C/C++ Example
	   ...
	   _afill_line(WHITE+(16*BLUE));
	   ...

Inline Assembly Example
	#include <inline.h>
	   ...
	   mov ah,(WHITE+(16*BLUE))
	   afill_line();
	   ...

Source file _CIOAFLL.ASM ASM equiv AFILL_LINE
See also
_afill_eol, _afill_n, _afill_region, _clr_line, _fill_line

_afill_n


Descrip
Sets a specified number of attributes on the current line to a specified attribute.

Syntax
#include <console.h>
void _afill_n(int attr, int num);

Returns
None

Notes
This function sets num attributes on the current line to the attribute specified by attr. Attribute changes take place starting at the current cursor position and continuing to the right. The cursor position remains unchanged. If an attribute table has been specified (using _set_attrtbl), attr is treated as an attribute table code and the corresponding attribute table value is used as the fill attribute; otherwise, attr is used as the actual fill attribute.

Output is restricted to the current clipping region if the clipping region is enabled; otherwise it is restricted to the screen (or the active window if windowing is in effect). Attributes are written directly to the display through a BIOS call or directly to video memory depending on the state of the direct_video variable.

See the technical notes for an explanation of how attributes are specified.

_console_init must be called before using this function.

C/C++ Example
	   ...
	   _afill_n(WHITE+(16*BLUE),10);/* WHITE on BLUE */
	   ...

Inline Assembly Example
	#include <inline.h>
	   ...
	   mov cl,10
	   mov ah,(WHITE+(16*BLUE))
	   afill_n();
	   ...

Source file _CIOAFLN.ASM ASM equiv AFILL_N
See also
_afill_eol, _afill_line, _afill_region, _clr_n, _fill_n

_afill_region


Descrip
Sets all attributes in the current clipping region to a specified attribute.

Syntax
#include <console.h>
void _afill_region(int attr);

Returns
None

Notes
This function sets all attributes in the current clipping region to the attribute specified by attr if the clipping region is enabled; otherwise, all attributes on the screen (or the active window if windowing is in effect) are set to the attribute specified by attr.

The cursor position remains unchanged. If an attribute table has been specified (using _set_attrtbl), attr is treated as an attribute table code and the corresponding attribute table value is used as the fill attribute; otherwise, attr is used as the actual fill attribute.

Attributes are written directly to the display through a BIOS call or directly to video memory depending on the state of the direct_video variable.

See the technical notes for an explanation of how attributes are specified.

_console_init must be called before using this function.

C/C++ Example
	   _afill_region(WHITE+(16*BLUE));/* white on blue */

Inline Assembly Example
	#include <inline.h>
	   mov ah,(WHITE+(16*BLUE))
	   afill_region();
	   ...

Source file _CIOAFLR.ASM ASM equiv AFILL_REGION
See also
_clr_region, _fill_region, _set_region

attr_tbl


Descrip
(Variable) Contains the address of the attribute table currently in use.

Syntax
#include <console.h>
extern char *attr_tbl;

Notes
This near/far pointer contains the address of the currently-installed attribute table. In small data models (TINY, SMALL, MEDIUM), this variable is an near pointer which contains the offset of the attribute table within the default data segment (DGROUP). In large data models (COMPACT, LARGE, HUGE), this variable is a far pointer which contains the segment and offset of the attribute table. The address is -1 if no attribute table is installed.

This variable is initialized to -1 by _console_init. It is modified by _set_attrtbl.

_console_init must be called before accessing this variable.

Source file CIOCVAR.ASM ASM equiv ATTR_TBL
See also
_set_attr

_bkbold_off


Descrip
Turns high intensity background off.

Syntax
#include <console.h>
void _bkbold_off(void);

Returns
None

Notes
This function clears the BKBOLD attribute flag if high intensity background colors are allowed. This causes the _cput_... functions to display text using the current text attribute without forcing the background color to high intensity. This function has no effect if high intensity background attributes are not currently supported by the active display adapter.

Note that this function only affects the attribute which is used for subsequent display of text. It has no effect on text which has already been displayed.

Text displayed using the high intensity background bit appears as blinking text or as text with a high intensity background color, depending on how the active display adapter interprets the bit. The active adapter may be programmed to display high intensity background colors by calling _set_bkboldmode.

_console_init must be called before using this function.

C/C++ Example
	   _bkbold_off();/* turn high intensity background off */

Inline Assembly Example
	   bkbold_off();/* turn high intensity background off */

Source file CIOBKBOF.ASM ASM equiv BKBOLD_OFF
See also
_bkbold_on, _set_bkboldmode

_bkbold_on


Descrip
Turns high intensity background on.

Syntax
#include <console.h>
void _bkbold_on(void);

Returns
None

Notes
This function sets the BKBOLD attribute flag if high intensity background attributes are allowed. This forces the _cput_... functions to display text with the high intensity background bit set. This function has no effect if high intensity background attributes are not currently supported by the active display adapter.

Note that this function only affects the attribute which is used for subsequent display of text. It has no effect on text which has already been displayed.

Text displayed using the high intensity background bit appears as blinking text or as text with a high intensity background color, depending on how the active display adapter interprets the bit. The active adapter may be programmed to display high intensity background colors by calling _set_bkboldmode.

_console_init must be called before using this function.

C/C++ Example
	   _bkbold_on();/* turn high intensity background on */
	   _cput_str("Blink on...");
	   

Inline Assembly Example
	#include <inline.h>
	{
	char str[] = "Blink on...";
	   bkbold_on();
	   lea si,str
	   cput_str();
	  ...
	}   

Source file CIOBKBON.ASM ASM equiv BKBOLD_ON
See also
_bkbold_off, _set_bkboldmode

_blink_off


Descrip
Turns blink off.

Syntax
#include <console.h>
void _blink_off(void);

Returns
None

Notes
This function clears the BLINK attribute flag if blinking text is allowed. This causes the _cput_... and echoed _cget_... functions to display text using the current text attribute without forcing blinking text to be displayed. This function has no effect if blinking text is not currently supported by the active display adapter.

Note that this function only affects the attribute which is used for subsequent display of text. It has no effect on text which has already been displayed.

Text displayed using the blink bit appears as blinking text or as text with a high intensity background color, depending on how the active display adapter interprets the bit. The active adapter may be programmed to display blinking text by calling _set_blinkmode.

_console_init must be called before using this function.

C/C++ Example
	   _blink_off();/* turn blink off */

Inline Assembly Example
	   blink_off();	/* turn blink off */

Source file CIOBLOFF.ASM ASM equiv BLINK_OFF
See also
_blink_on, _set_blinkmode

_blink_on


Descrip
Turns blink on.

Syntax
#include <console.h>
void _blink_on(void);

Returns
None

Notes
This function sets the BLINK attribute flag if blinking text is allowed. This forces the _cput_... and echoed _cget_... functions to display text with the blink bit set. This function has no effect if blinking text is not currently supported by the active display adapter.

Note that this function only affects the attribute byte which is used for subsequent display of text. It has no effect on text which has already been displayed.

Text displayed using the blink bit appears as blinking text or as text with a high intensity background color, depending on how the active display adapter interprets the bit. The active adapter may be programmed to display blinking text by calling _set_blinkmode.

_console_init must be called before using this function.

C/C++ Example
	   _blink_on();	/* turn blink on */

Inline Assembly Example
	   blink_on();	/* turn blink on */

Source file CIOBLON.ASM ASM equiv BLINK_ON
See also
_blink_off, _set_blinkmode

_bold_off


Descrip
Turns bold off.

Syntax
#include <console.h>
void _bold_off(void);

Returns
None

Notes
This function clears the BOLD attribute flag. This causes the _cput_... and echoed _cget_... functions to display text using the current text attribute without forcing the bold bit to be set.

Note that this function only affects the attribute byte which is used for subsequent display of text. It has no effect on text which has already been displayed.

_console_init must be called before using this function.

C/C++ Example
	   _bold_off();	/* turn bold off */

Inline Assembly Example
	   bold_off();	/* turn bold off */

Source file CIOBOFF.ASM ASM equiv BOLD_OFF
See also
_bold_on

_bold_on


Descrip
Turns bold on.

Syntax
#include <console.h>
void _bold_on(void);

Returns
None

Notes
This function sets the BOLD attribute flag. This forces the _cput_... and echoed _cget_... functions to display text with the high intensity foreground (bold) bit set.

Note that this function only affects the attribute byte which is used for subsequent display of text. It has no effect on text which has already been displayed.

_console_init must be called before using this function.

C/C++ Example
	   _bold_on();	 /* turn bold on */
	   _cput_str("Bold on...");

Inline Assembly Example
	#include <inline.h>
	{
	   char str[] = "Bold on...";
	   ...
	   bold_on();
	   lea si,str
	   cput_str();	/* display message */
	   ...
	}

Source file CIOBON.ASM ASM equiv BOLD_ON
See also
_bold_off

_ccheck_key


Descrip
Determines if a keystroke is waiting to be read.

Syntax
#include <console.h>
int _ccheck_key(void);

Returns
1 if a keystroke is waiting to be read.

0 if no keystroke is waiting to be read.

Notes
This function uses BIOS calls to determine if a keystroke is waiting to be read. 1 is returned if a key is waiting to be read; otherwise, 0 is returned.

Enhanced keyboard keystrokes are supported if KBD_INIT has been called and an enhanced keyboard is present.

C/C++ Example
	   _cput_str("Press a key to wake me up: ");
	   while (!_ccheck_key());
	   ...	  	 	/* wait */  
	   _cput_str("\n\rSo soon?!");
	   ...

Inline Assembly Example
	#include <inline.h>
	...
	label_010:
	ccheck_key();
	 jnelabel_010 /* loop while no key press ...*/
		   	 /* fall through on keypress */
	...

Source file _CIOCHKY.ASM ASM equiv CCHECK_KEY
See also
_cflush_keys, _check_key, _get_keyflags

_cflush_keys


Descrip
Flushes pending keystrokes from the keyboard buffer.

Syntax
#include <console.h>
void _cflush_keys(void);

Returns
None

Notes
This function flushes all pending keystrokes from the keyboard buffer. Enhanced keyboard codes are flushed if _kbd_init has been called and an enhanced keyboard is present.

This function uses BIOS calls rather than direct manipulation of keyboard buffer pointers to ensure maximum compatibility with resident applications.

C/C++ Example
	...
	   if (_ccheck_key());
	      _cflush_keys();	 /* clear keyboard buffer */
	   else
	      _cput_str("No keys were waiting");
	...

Inline Assembly Example
	(C Interface Recommended)

Source file CIOFLKEY.ASM ASM equiv CFLUSH_KEYS
See also
_ccheck_key, _flush_keys

_cget_chr


Descrip
Gets a character from the keyboard.

Syntax
int _cget_chr(void);

Returns
Character read from the keyboard.

0 if an extended character was retrieved from the keyboard.

Notes
This function gets a character from the keyboard using BIOS calls. If no keystrokes are waiting when this function is called, it waits until a key is pressed. Enhanced keyboard key codes are supported if _kbd_init has been called and an enhanced keyboard is present.

This function issues an INT 0x28 and yields to the multitasking system (if present) while waiting for a keystroke. This scheme allows background processes (e.g., PRINT.COM or other TSRs) and tasks in the multitasking system to execute while the calling program is idle. If the multitasking system is not initialized, the yield to the multitasking system has no effect. If _tsr_enable, _tsr_resident, or _device_resident has been called, the INT 0x28 is only issued when it is safe to do so.

See Appendices B,C, and D for complete keystroke and keystroke code tables.

This function is similar to C's getch function. It is included to provide similar functionality. Use of _cget_chra is preferable.

C/C++ Example
	{
	   int ch, extended = 0;
	   ch = _cget_chr();	/* get chr from kbd */

	   if (!ch)	 	/* if 0, get next chr */
	      extended = _cget_chr();
	   if (extended)
	      _cput_str("Extended character");
	   else
	      _cput_str("Not an extended character");
	   ...
	}

Inline Assembly Example
	(C Interface Recommended)

Source file _CIOGCHR.ASM ASM equiv CGET_CHR
See also
_ccheck_key, _cget_chr, _cget_chr, _cget_chr, _cget_s, _cput_chr, _get_chr, _hget_chr

_cget_chra


Descrip
Gets a character and type (normal, ALT-keypad, or extended) from the keyboard.

Syntax
#include <console.h>
int _cget_chra(char *chr);

Returns
0 if a normal character was retrieved from the kbd.
chr normal character

1 if an ALT-keypad character was retrieved from the kbd.
chr ALT-keypad character

-1 if an extended character was retrieved from the kbd.
chr extended character

Notes
This function gets a character and its type from the keyboard using BIOS calls. The return value indicates the type (0, 1, and -1 indicate normal, ALT-keypad, and extended, respectively); the character itself is saved in the variable chr. No echoing is performed. If no keystrokes are waiting when this function is called, it waits until a key is pressed.

Enhanced keyboard key codes are supported if _kbd_init has been called and an enhanced keyboard is present.

This function issues an INT 0x28 and yields to the multitasking system (if present) while waiting for a keystroke. This scheme allows background processes (e.g., PRINT.COM or other TSRs) and tasks in the multitasking system to execute while the calling program is idle. If the multitasking system is not initialized, the yield to the multitasking system has no effect. If _tsr_enable, _tsr_resident, or _device_resident has been called, the INT 0x28 is only issued when it is safe to do so.

This function provides an alternative to using two calls to obtain an extended character value. chr always contains the character code regardless of the character type; this allows the programmer to switch on the return value to determine how chr should be processed.

See Appendices B,C, and D for complete keystroke and keystroke code tables.

C/C++ Example
	{
	   int chr;
	   ...
	   switch  (_cget_chra(&chr))/* get chr from kbd */
	   {
	      case  0:_cput_str("Normal character"); break;
	      case  1:_cput_str("ALT-keypad character"); break;
	      case -1:_cput_str("Extended character"); break;
	   }
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	...
	cget_chr();	 /* AL reg = character */
	 ja do_alt_chr/* process ALT-keypad chars */
	 jb do_ext_chr/* go process extended chars */
	to_upper();	 /* AL = uppercase if alpha */
	cput_chr();	 /* output normal characters */
	jmp short done

	do_alt_chr:   	 /* process ALT-keypad chars */
	  ...
	jmp short done

	do_ext_chr:   	 /* process extended chars */
	  ...
	done:
	  ...
	}

Source file _CIOGCHA.ASM ASM equiv CGET_CHR
See also
_cget_chr, _cget_chr, _get_chr, _cget_chr

_cget_chrae


Descrip
Gets a character and type (normal, ALT-keypad, or extended) from the keyboard and echoes the character to the display.

Syntax
#include <console.h>
int _cget_chrae(char *chr);

Returns
0 if a normal character was retrieved from the kbd.
chr normal character

1 if an ALT-keypad character was retrieved from the kbd.
chr ALT-keypad character

-1 if an extended character was retrieved from the kbd.
chr extended character

Notes
This function gets a character and its type from the keyboard using BIOS calls and echoes it to the screen at the current cursor position. The return value indicates the type (0, 1, and -1 indicate normal, ALT-keypad, and extended, respectively); the character itself is saved in the variable chr. The character is echoed only if it is an ALT-keypad character or a normal character in the range 0x20 to 0x7E. Characters are echoed directly to video memory or through BIOS calls depending on the state of the direct_video variable. If no keystrokes are waiting when this function is called, it waits until a key is pressed. Enhanced keyboard key codes are supported if _kbd_init has been called and an enhanced keyboard is present.

This function provides an alternative to using two calls to obtain an extended character value. chr always contains the character code regardless of the character type; this allows the programmer to switch on the return value to determine how chr should be processed.

See Appendices B,C, and D for complete keystroke and keystroke code tables.

C/C++ Example
	{
	   int chr;
	   ...
	   switch  (_cget_chrae(&chr))/* get chr from kbd */
	   {
	      case  0:_cput_str("Normal character"); break;
	      case  1:_cput_str("ALT-keypad character"); break;
	      case -1:_cput_str("Extended character"); break;
	   }
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   cget_chre();	/* AL reg = echoed character */
	    ja do_alt_chr/* process ALT-keypad chars */
	    jb do_ext_chr/* go process extended chars */
	   to_upper();	/* AL = uppercase if alpha */
	     ...	 	/* process normal characters */
	   jmp done

	do_alt_chr:	 	/* process ALT-keypad chars */
	     ...
	   jmp done

	do_ext_chr:	 	/* process extended chars */
	     ...
	done:
	     ...
	}

Source file _CIOGCAE.ASM ASM equiv CGET_CHRE
See also
_cget_chr, _cget_chr, _cget_chr, _get_chr

_cget_chre


Descrip
Gets a character from the keyboard and echoes it to the display.

Syntax
#include <console.h>
int _cget_chre(void);

Returns
Character read from the keyboard.

0 if an extended character was retrieved from the keyboard.

Notes
This function gets a character type from the keyboard using BIOS calls and echoes it to the screen at the current cursor position. The character is echoed only if it is an ALT-keypad character or a normal character in the range 0x20 to 0x7E. Characters are echoed directly to video memory or through BIOS calls depending on the state of the direct_video variable. If no keystrokes are waiting when this function is called, it waits until a key is pressed. Enhanced keyboard key codes are supported if _kbd_init has been called and an enhanced keyboard is present.

This function issues an INT 0x28 and yields to the multitasking system (if present) while waiting for a keystroke. This scheme allows background processes (e.g., PRINT.COM or other TSRs) and tasks in the multitasking system to execute while the calling program is idle. If the multitasking system is not initialized, the yield to the multitasking system has no effect. If _tsr_enable, _tsr_resident, or _device_resident has been called, the INT 0x28 is only issued when it is safe to do so.

See Appendices B,C, and D for complete keystroke and keystroke code tables.

This function is similar to C's getche function. It is included to provide similar functionality. Use of _cget_chrae is preferable.

C/C++ Example
	{
	   int chr, extended=0;
	   ...
	   chr = _cget_chre();/* get chr from kbd */
	   if (!chr)   /* if 0, get next chr */
	      extended = _cget_chre();
	   if (extended)
	      _cput_str(" Extended character");
	   else
	      _cput_str(" Not an extended character");
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   int chr;
	   char *str;
	   ...
	   chr = cget_chre();
	    jnealt_chr /* is it normal? */
	   str = "Normal character"; /*  y: set display string */
	   jmp short done /* go output string */

	alt_chr:
	    jb ext_chr /* is it ALT-keypad? */
	   str = "ALT-keypad character";/* y: set display string */
	   jmp short done /* go output string */

	ext_chr: 	 	/*  n: must be extended */
	   str = "Extended character";
	done:
	   mov si,str	/* SI = offset of "string" */
	   cput_str();	/* display character type */
	   ...
	}

Source file _CIOGCHE.ASM ASM equiv CGET_CHRE
See also
_cget_chr, _cget_chr, _cget_chr, _get_chr

_cget_s


Descrip
Gets a string from the keyboard and returns the number of characters entered.

Syntax
#include <console.h>
char *_cget_s(char *strbuf);
/* strbuf[0] indicates number of chars to read (num) */

Returns
A pointer to strbuf.
strbuf[1] number of characters read, excluding terminal NULL
strbuf[2..] ASCIIZ string typed by user

Notes
This function gets characters from the keyboard using BIOS calls and places them in buffer. Each character is echoed as it is read from the keyboard if it is an ALT-keypad character or a normal character in the range 0x20 to 0x7E. Characters are echoed directly to video memory or through BIOS calls depending on the state of the direct_video variable. Non-echoed characters are not placed in buffer. If an attempt is made to enter more than num characters into the buffer, the BEL character is sent to the console and the character is ignored. If the backspace key is pressed, the last character in buffer is removed and the last echoed character is overwritten with a space character on the screen. If the Enter key is pressed, a NULL character is placed after the last character written into buffer, a CR is echoed to the console, and the function returns. This function is not redirectable, so EOF is not returned.

On return, strbuf[1] is set to the number of characters actually read. The returned string starts at strbuf[2] and is NULL terminated. To read more than 255 bytes see _cget_str.

WARNING! Buffer must be at least num+3 bytes in size since the resulting string is NULL terminated and the first two bytes are used for input and output.

This function issues an INT 0x28 and yields to the multitasking system (if present) while waiting for a keystroke. This scheme allows background processes (e.g., PRINT.COM or other TSRs) and tasks in the multitasking system to execute while the calling program is idle. If the multitasking system is not initialized, the yield to the multitasking system has no effect. If _tsr_enable, _tsr_resident, or _device_resident has been called, the INT 0x28 is only issued when it is safe to do so.

See Appendices B,C,and D for complete keystroke and keystroke code tables.

_console_init must be called before using this function.

This function is similar to C's gets function. It is included to provide similar functionality. Use of _cget_str is preferable.

C/C++ Example
	{
	   char strbuf[83], *str;
	   ...
	   _cput_str ("Enter a string: ");
	   strbuf[0] = 81;
	   intbuf[4];
	   str = _cget_s(strbuf);/* get input from keyboard */
	   _put_newline();
	   _cput_str(str);	/* display input */
	   _cput_str("\n_cget_s read ");
	   _cput_str(_i_to_dec(strbuf[1], intbuf));
	   _cput_str("chars.");
	   ...
	}

Inline Assembly Example
	(Not applicable)

Source file _CIOGS.ASM ASM equiv CGET_STR
See also
_cget_s, _cput_str, _get_str

_cget_str


Descrip
Gets a string from the keyboard.

Syntax
#include <console.h>
char *_cget_str(char *strbuf, unsigned int num);

Returns
A pointer to strbuf.
strbuf string typed by user

Notes
This function gets characters from the keyboard using BIOS calls and places them in strbuf. Each character is echoed as it is read from the keyboard if it is an ALT-keypad character or a normal character in the range 0x20 to 0x7E. Characters are echoed directly to video memory or through BIOS calls depending on the state of the direct_video variable. Non-echoed characters are not placed in buffer. If an attempt is made to enter more than num characters into strbuf, the BEL character is sent to the console and the character is ignored. If the backspace key is pressed, the last character in strbuf is removed and the last echoed character is overwritten with a space character on the screen. If the Enter key is pressed, a NULL character is placed after the last character written into strbuf, a CR is echoed to the console, and the function returns. This function is not redirectable, so EOF is not returned.

WARNING! strbuf must be at least num+1 bytes in size since the resulting string is NULL terminated.

This function issues an INT 0x28 and yields to the multitasking system (if present) while waiting for a keystroke. This scheme allows background processes (e.g., PRINT.COM or other TSRs) and tasks in the multitasking system to execute while the calling program is idle. If the multitasking system is not initialized, the yield to the multitasking system has no effect. If _tsr_enable, _tsr_resident, or _device_resident has been called, the INT 0x28 is only issued when it is safe to do so.

See Appendices B,C,and D for complete keystroke and keystroke code tables.

_console_init must be called before using this function.

C/C++ Example
	{
	   char strbuf[81], *sptr;

	   _console_init();
	   _cput_str("Enter a string: ");
	   sptr = _cget_str(strbuf, 80);
	   _cput_str("\n\r The string was: ");
	   _cput_str(sptr);	/* display string */
	   _cput_newline();
	   _cput_str (strbuf);    /* display string */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char strbuf[20001];
	   char prompt[] = "Enter a string: ";
	   ...
	console_init();
	lea si,prompt/* SI = offset of prompt */
	cput_str();	 /* display prompt */
	lea si,strbuf/* DI = offset of strbuf */
	mov cx,20000/* CX = max chars to read */
	cget_str();	 /* get input from keyboard */
	cput_newline();	/* "\n\r" */
	cput_str();	 /* display input string */
	...
	}

Source file _CIOGSTR.ASM ASM equiv CGET_STR
See also
_cget_chr, _cget_s, _cput_str, _cget_s, _get_str, _vcget_script

_chk_dimens


Descrip
Determines if specified screen dimensions are supported by the active display adapter.

Syntax
#include <console.h>
int _chk_dimens(char cols, char rows);

Returns
0 if the screen dimensions are supported.

-1 if the screen dimensions are not supported by the active display adapter.

Notes
This function determines if the specified screen dimensions are supported by _set_dimens on the active display adapter. 0 is returned if the specified number of rows and cols is supported; -1 is returned otherwise. If the virtual screen system is in use, then the test applies to the adapter on which the active screen currently resides.

The adapter type and monitor type of the active display adapter determine which screen dimensions can be supported by _set_dimens. The following table indicates the supported text mode display dimensions as a function of display adapter and monitor type:

MDA/EGA CGA/EGA EGA EGA MCGA VGA
MONO RGB ECD_LO ECD_HI ANY ANY

40x12 or 80x12- - Yes - - Yes
40x14 or 80x14- - Yes - - Yes
40x21 or 80x21- - - Yes - -
40x25 or 80x25Yes Yes Yes Yes Yes Yes
40x28 or 80x28- - - - - Yes
40x43 or 80x43- - - Yes - -
40x50 or 80x50- - - - Yes Yes

Other nonstandard text mode screen dimensions are available on many display adapters via video mode changes. These extended text modes are properly supported by the console I/O system once they have been selected. However, extended text modes cannot be directly selected by _set_dimens because video mode values vary from manufacturer to manufacturer. See the technical notes for information about identifying nonstandard text modes at run time.

_console_init must be called before this function may be used.

C/C++ Example
	{
	   int cols, rows;
	   char intbuf[10];
	   ...
	   _cput_str("\n\rEnter number of columns to display: ");
	   cols = _dec_to_i(_cget_str(intbuf, 5), &strindx);
	   _cput_str("\n\rEnter number of rows to display: ");
	   rows = _dec_to_i(_cget_str(intbuf, 5), &strindx);
	   if(_chk_dimens(cols, rows) == -1);
	   _cput_str("Requested dimens are not supported by adapter.");
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char cols, rows;
	   char intbuf[10], *str;
	   ...
	   str = "Enter number of columns to display: ";
	   mov si,str        /* SI = str pointer */
	   cput_str();
	   mov cl,3          /* CL = maximum chars to get */
	   lea si,intbuf     /* SI = offset of intbuf */
	   cget_str();
	   dec_to_c();           /* display columns selection */
	   mov cols,al       /* save requested columns */
	   str = "Enter number of rows to display: ";
	   mov si,str
	   cput_str();
	   mov cl,3
	   lea si,intbuf
	   cget_str();
	   dec_to_c();
	   mov ah,cols
	   xchgal,ah	/* AL = cols, AH = rows */
	   chk_dimens();	/* determine if dimensions are supported */
	   ...
	}

Source file _CIOCDMS.ASM ASM equivâ
See also
_get_adaptinfo, _get_dimens, _set_dimens

_clr_eol


Descrip
Clears to the end of the current line.

Syntax
#include <console.h>
void _clr_eol(void);

Returns
None

Notes
This function clears all characters and attributes from the current cursor position to the end of the current line. Cleared positions are filled with space characters in the default text attribute. The cursor position remains unchanged. Output is restricted to the current clipping region if the clipping region is enabled; otherwise, it is restricted to the screen (or the active window if windowing is in effect). Characters and attributes are written directly to the display through a BIOS call or directly to video memory depending on the state of the direct_video variable.

_console_init must be called before using this function.

C/C++ Example
	   ...
	   _cput_str("Clear this string");
	   _goto_left();/* goto beginning of string */
	   if (_cget_chr()==0)/* when ready... */
	      _cget_chr();
	   _clr_eol();	 /* clear to end of line */
	   ...

Inline Assembly Example
	#include <inline.h>
	char string[] = "Clear this string";
	   ...
	   leasi,string
	   put_str();
	   goto_left();	/* goto beginning of string */
	   if (_cget_chr()==0)/* when ready... */
	      _cget_chr();
	   clr_eol();	 /* clear to end of line */
	   ...

Source file CIOCLRE.ASM ASM equiv CLR_EOL
See also
_clr_line, _clr_n, _clr_region, _fill_eol

_clr_line


Descrip
Clears the current line.

Syntax
#include <console.h>
void _clr_line(void);

Returns
None

Notes
This function clears all characters and attributes on the current line. Cleared positions are filled with space characters in the default text attribute. The cursor position remains unchanged.

Output is restricted to the current clipping region if the clipping region is enabled; otherwise, it is restricted to the screen (or the active window if windowing is in effect). Characters and attributes are written directly to the display through a BIOS call or directly to video memory depending on the state of the direct_video variable.

_console_init must be called before using this function.

C/C++ Example
	   ...
	   _cput_str("Clear this line");
	   ...
	   _clr_line();	/* clear entire line */
	   ...

Inline Assembly Example
	{
	char string[] = "Clear this line";
	   ...
	   lea si,string
	   put_str();
	   ...
	   clr_line();/* clear entire line */
	   ...
	}

Source file CIOCLRL.ASM ASM equiv CLR_LINE
See also
_clr_eol, _clr_n, _clr_region, _fill_line

_clr_n


Descrip
Clears a specified number of columns on the current line.

Syntax
#include <console.h>
void _clr_n(int num);

Returns
None

Notes
This function clears num characters and attributes on the current line starting at the current cursor position and continuing to the right. Cleared positions are filled with space characters in the default text attribute. The cursor position remains unchanged. Output is restricted to the current clipping region if the clipping region is enabled; otherwise, it is restricted to the screen (or the active window if windowing is in effect). Characters and attributes are written directly to the display through a BIOS call or directly to video memory depending on the state of the direct_video variable.

_console_init must be called before using this function.

C/C++ Example
	   _cput_str(".......Clear first 7 characters of this string");
	   _goto_left();	/* cursor on left most margin */
	   _clr_n (7);	 	/* clear ten spaces */
	   ...

Inline Assembly Example
	#include <inline.h>
	{
	   char str[] = ".......Clear first 7 character of string");
	   ...
	   lea si,str
	   _cput_str();
	   goto_left();	/* cursor on left most margin */
	   mov cl,10	/* CL = num spaces to clr */
	   clr_n();	/* clear up to n spaces */
	   ...
	}

Source file _CIOCLRN.ASM ASM equiv CLR_N
See also
_clr_eol, _clr_line, _clr_region, _fill_n

_clr_region


Descrip
Clears the current clipping region.

Syntax
#include <console.h>
void _clr_region(void);

Returns
None

Notes
This function clears all characters and attributes in the current clipping region. Cleared positions are filled with space characters in the default text attribute. The cursor position remains unchanged.

If the clipping region is currently disabled, these actions take place within the boundaries of the screen (or within the active window if windowing is in effect). Characters and attributes are written directly to the display through a BIOS call or directly to video memory depending on the state of the direct_video variable.

_console_init must be called before using this function.

C/C++ Example
	   ...
	   _cput_str("Since no windowing or regions are active, 
	      clr the screen");
	   if (_cget_chr()==0)/* wait for user command! */
	      _cget_chr();
	   _clr_region();/* clear region */
	   ...

Inline Assembly Example
	{
	   char string[] = "Since no windowing or regions are active,\
	      clear the screen";
	   ...
	   if (_cget_chr()==0)/* wait for user command! */
	      _cget_chr();
	   clr_region();
	   ...
	}

Source file CIOCLRR.ASM ASM equiv CLR_REGION
See also
_clr_eol, _clr_line, _clr_region, _fill_n

_console_init


Descrip
Initializes the Console I/O system.

Syntax
#include <console.h>
void _console_init(void);

Returns
None

Notes
This function initializes the Console I/O system to reflect the current text mode display state. This includes screen dimensions, active adapter type, video mode, video refresh state, active display page, cursor position, cursor shape, video RAM segment and starting offset, and video border color and state. This function also sets video_snow to 1 if the active display adapter is a CGA, resets the cursor advance direction to ADV_RIGHT, clears the text attribute flags, sets the clipping region size to full screen, and turns off the clipping region. A test is also performed to determine if direct video access is permissible and the direct_video variable is set to reflect the result. Only the active virtual screen is initialized if the virtual screen system is in use when this function is called.

This function is designed to leave the current screen and display state intact. However, if the active adapter is a VGA, it is programmed to support cursor emulation. The video system is not affected in any other way.

Due to hardware and BIOS limitations, the current video border color cannot be determined unless the active display adapter is a VGA. If the active adapter is not a VGA, the default video border color is always assumed to be BLACK and the border state is set to OFF. If the active adapter is a VGA, the Console I/O variables are set to reflect the current border color and state (if the border color is not BLACK, the border state is set to ON; otherwise, it is set to OFF). Note that the actual border state is not affected by this function in any way.

This function must be called before most Console I/O functions may be used unless the virtual screen system is in use.

WARNING! This function is intended for text-mode use only. It assumes that the screen is currently in a non-graphics video mode. Use of this function under any other circumstances will produce undefined results.

WARNING! This function leaves the Windowing system in an undefined state. To preserve the condition of the windowing system, call _win_suspend just before calling this function. The state of the windowing system may then be restored at a later point by calling _win_resume.

C/C++ Example
	   _console_init();/* initialize SA console I/O */
	   _cput_str("Console I/O initialized");  
	      /* note: use _cput_... _cget_... functions */

Inline Assembly Example
	{
	   char str[] = "Console I/O initialized";
	   ...
	   console_init();
	   lea si,str
	   cput_str();
	   ...
	}

Source file CIOCINIT.ASM ASM equiv CONSOLE_INIT
See also
adapter_type, direct_video, _kbd_init, kbd_type, screen_dimens, video_mode, video_snow

_cput_attr


Descrip
Puts an attribute to the display.

Syntax
#include <console.h>
void _cput_attr(int attr);

Returns
None

Notes
This function writes attr to the display at the current cursor position, without affecting the character at that position. The cursor is then moved just past the displayed attribute in the current cursor advance direction. If an attribute table has been specified (using _set_attrtbl), attr is treated as an attribute table code and the corresponding attribute table value is used as the display attribute; otherwise, attr is used as the actual display attribute.

Output is restricted to the current clipping region if the clipping region is enabled; otherwise, it is restricted to the screen (or the active window if windowing is in effect). The attribute is written to the display through BIOS calls or directly to video memory depending on the state of the direct_video variable.

See the technical notes for detailed information on how to specify attributes.

_console_init must be called before using this function.

C/C++ Example
	   _cput_attr(WHITE+(16*BLUE));/* put white on blue attr */

Inline Assembly Example
	#include <inline.h>
	   mov ah,(WHITE+(16*BLUE));/* AH = white/blue attr */
	   cput_attr();/* put chosen attr to the display */

Source file _CIOPATR.ASM ASM equiv CPUT_ATTR
See also
_cput_chr, _cput_nattr

_cput_beep


Descrip
Sounds a tone on the system speaker.

Syntax
#include <console.h>
void _cput_beep(void);

Returns
None

Notes
This function sounds a tone on the system speaker using a BIOS call. The cursor position does not change.

This function does not depend on _console_init.

C/C++ Example
	   _cput_beep();  /* Sound beep */

Inline Assembly Example
	   cput_beep();   /* Sound beep */

Source file CIOPBEEP.ASM ASM equiv CPUT_BEEP
See also
_put_beep

_cput_chr


Descrip
Puts a character to the display.

Syntax
#include <console.h>
void _cput_chr(int chr);

Returns
None

Notes
This function writes chr to the display at the current cursor position. The cursor is then moved once in the current cursor advance direction. Output is restricted to the current clipping region if the clipping region is enabled; otherwise, it is restricted to the screen (or the active window if windowing is in effect). The character is written to the display through BIOS calls or directly to video memory depending on the state of the direct_video variable.

The special ASCII characters BEL (0x07), BS (0x08), CR (0x0D), and LF (0x0A) are recognized and interpreted; all other characters are written directly to the display. BEL sounds a tone on the system speaker; BS moves the cursor once in the direction opposite the current cursor advance direction; and CR moves the cursor to the left edge of the current clipping region. LF moves the cursor down one row; if the cursor is already on the bottom row of the clipping region, the current clipping region is scrolled up one row and the new row is filled with space characters in the default text attribute.

_console_init must be called before using this function.

C/C++ Example
	{
	   ...
	   _cput_chr(177);	 /* display '±' */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	   mov al,177	/* AL = character to display */
	   cput_chr();	/* display character in AL */

Source file _CIOPCHR.ASM ASM equiv CPUT_CHR
See also
_cget_chr, _cput_chr, _cput_nchr, _cput_str, _hput_chr, _put_chr

_cput_chri


Descrip
Puts a character to the display without interpreting it.

Syntax
#include <console.h>
void _cput_chri(int chr);

Returns
None

Notes
This function writes chr to the display at the current cursor position without interpreting it. The cursor is then moved once in the current cursor advance direction. The character is written to the display through BIOS calls or directly to video memory depending on the state of the direct_video variable. Output is restricted to the current clipping region if the clipping region is enabled; otherwise, it is restricted to the screen (or the active window if windowing is in effect).

_console_init must be called before using this function.

C/C++ Example
	   _cput_chri (0x25);/* display 0x25 character (%) */

Inline Assembly Example
	#include <inline.h>
	   mov al,0x25	    /* AL = character to display */
	   cput_chri();	/* display (%) character */

Source file _CIOPCHI.ASM ASM equiv CPUT_CHRI
See also
_cput_chr, _cput_str

_cput_linefeed


Descrip
Performs the equivalent of a linefeed in the current clipping region.

Syntax
#include <console.h>
void _cput_linefeed(void);

Returns
None

Notes
This function advances the cursor down one line within the current clipping region. If the cursor is already at the bottom line of the clipping region, the clipping region is scrolled up one line and a blank line in the default text attribute is scrolled in at the bottom of the region. Scrolling is performed using BIOS calls or by direct manipulation of video memory depending on the state of the direct_video variable.

_console_init must be called before using this function.

C/C++ Example
	   _cput_linefeed();   /* advance cursor down to next line */

Inline Assembly Example
	   cput_linefeed();  /* advance cursor down to next line */

Source file CIOPLINE.ASM ASM equiv CPUT_LINEFEED
See also
_cput_newline, _cput_return, _move_down

_cput_nattr


Descrip
Puts an attribute to the display a specified number of times.

Syntax
#include <console.h>
void _cput_nattr(int attr, int num);

Returns
None

Notes
This function writes attr to the display num times starting at the current cursor position and continuing in the current cursor advance direction. The characters at those positions are not affected. The cursor is then moved just past the last displayed attribute in the current cursor advance direction. If an attribute table has been specified (using _set_attrtbl), attr is treated as an attribute table code and the corresponding attribute table value is used as the display attribute; otherwise, attr is used as the actual display attribute. Output is restricted to the current clipping region if the clipping region is enabled; otherwise, it is restricted to the screen (or the active window if windowing is in effect). The attributes are written to the display through BIOS calls or directly to video memory depending on the state of the direct_video variable.

See the technical notes for detailed information on how to specify attributes.

_console_init must be called before using this function.

C/C++ Example
	   _cput_nattr (WHITE+(16*RED),10); /* put 10, WHITE/RED attrs */

Inline Assembly Example
	#include <inline.h>
	   mov ah,(WHITE+(16*RED)) /* AH = WHITE on RED attr */
	   mov cl,10	/* CL = times to write attr */
	   cput_nattr();	/* put attr n times to display */

Source file _CIOPNTR.ASM ASM equiv CPUT_NATTR
See also
_cput_attr

_cput_nchr


Descrip
Puts a character to the display a specified number of times.

Syntax
#include <console.h>
void _cput_nchr(int chr, int num)

Returns
None

Notes
This function writes chr to the display num times, starting at the current cursor position and continuing in the current cursor advance direction. The cursor is advanced past the last character written. Output is restricted to the current clipping region if the clipping region is enabled; otherwise, it is restricted to the screen (or the active window if windowing is in effect). The character is written to the display through BIOS calls or directly to video memory depending on the state of the direct_video variable.

The special ASCII characters BEL (0x07), BS (0x08), CR (0x0D), and LF (0x0A) are recognized and interpreted accordingly; all other characters are written to the display. BEL sounds a tone on the system speaker; BS moves the cursor once in the direction opposite the current cursor advance direction; and CR moves the cursor to the left edge of the current clipping region. LF moves the cursor down one row; if the cursor is already on the bottom row of the clipping region, the current clipping region is scrolled up one row and the new row is filled with space characters in the default text attribute.

_console_init must be called before using this function.

C/C++ Example
	   _cput_nchr('±',80);/* output a line of shades */

Inline Assembly Example
	#include <inline.h>
	   mov al,177/* AL = character to write */
	   mov cl,80/* CL = number of times to write char */
	   cput_nchr();/* display a line of ± characters */ 

Source file _CIOPNCH.ASM ASM equiv CPUT_NCHR
See also
_cput_chr, _cput_nchr

_cput_nchri


Descrip
Puts a character to the display a specified number of times without interpreting it.

Syntax
#include <console.h>
void _cput_nchri(int chr, int num)

Returns
None

Notes
This function writes chr to the display num (maximum of 255) times without interpreting it, starting at the current cursor position and continuing in the current cursor advance direction. The cursor is advanced past the last character written. Output is restricted to the current clipping region if the clipping region is enabled; otherwise, it is restricted to the screen (or the active window if windowing is in effect). The character is written to the display through BIOS calls or directly to video memory, depending on the state of the direct_video variable.

_console_init must be called before using this function.

C/C++ Example
	   _cput_nchri(0x07,10); /* 10 BEEP characters w/o interpreting */
	   	  	 /* ... i.e., w/o beeping */

Inline Assembly Example
	#include <inline.h>
	   mov al,0x07	    /* AL = char to display */
	   mov cl,10	/* CL = num of time to display */
	   cput_nchri();	/* BEEP n times */

Source file _CIOPNCI.ASM ASM equiv CPUT_NCHRI
See also
_cput_nchr

_cput_newline


Descrip
Performs the equivalent of a carriage return and linefeed in the current clipping region.

Syntax
#include <console.h>
void _cput_newline(void);

Returns
None

Notes
This function returns the cursor to the left-most column of the current clipping region and advances it down one line. If the cursor is already at the bottom line of the clipping region, the clipping region is scrolled up one line and a blank line in the default text attribute is scrolled in at the bottom of the region. If the clipping region is not active, these actions take place within the boundaries of the screen (or the active window if windowing is in effect).

Scrolling is performed using BIOS calls or by direct manipulation of video memory, depending on the state of the direct_video variable.

_console_init must be called before using this function.

C/C++ Example
	   _cput_newline();
	   _cput_str("begin again");

Inline Assembly Example
	#include <inline.h>
	{
	   char str[] = "begin again";
	   ...
	   cput_newline();
	   lea si,str
	   cput_str();
	   ...
	}

Source file CIOPLINE.ASM ASM equiv CPUT_NEWLINE
See also
_cput_linefeed, _cput_return, _put_newline

_cput_return


Descrip
Performs the equivalent of a carriage return in the current clipping region.

Syntax
#include <console.h>
void _cput_return(void);

Returns
None

Notes
This function returns the cursor to the left-most column of the current line in the current clipping region. If the clipping region is disabled, the cursor is returned to the left-most column of the screen (or the active window if windowing is in effect). The vertical position of the cursor remains unchanged.

This function is actually an alternate name for _goto_left. Both names are provided for convenience.

_console_init must be called before using this function.

C/C++ Example
	   _cput_return();
	   _cput_str ("return to left-most column");

Inline Assembly Example
	#include <inline.h>
	{
	   char *str = "return to left-most column";
	   ...
	   cput_return();
	   mov si,str
	   cput_str();
	   ...
	}

Source file CIOGLEFT.ASM ASM equiv CPUT_RETURN
See also
_cput_linefeed, _cput_newline, _goto_left

_cput_str


Descrip
Puts a string to the display.

Syntax
#include <console.h>
void _cput_str(const char *str);

Returns
None

Notes
This function writes str to the display starting at the current cursor position and continuing in the current cursor advance direction. The cursor is advanced past the last character written. Output is restricted to the current clipping region if the clipping region is enabled; otherwise, it is restricted to the screen (or the active window if windowing is in effect). Characters are written to the display through BIOS calls or directly to video memory depending on the state of the direct_video variable. This function is not redirectable, so EOF is not detected.

The special ASCII characters BEL (0x07), BS (0x08), CR (0x0D), and LF (0x0A) are recognized and interpreted; all other characters are written directly to the display. BEL sounds a tone on the system speaker; BS moves the cursor once in the direction opposite the current cursor advance direction; and CR moves the cursor to the left edge of the current clipping region. LF moves the cursor down one row; if the cursor is already on the bottom row of the clipping region, the current clipping region is scrolled up one row and the new row is filled with space characters in the default text attribute.

_console_init must be called before using this function.

C/C++ Example
	   _cput_str("Display this string.");

Inline Assembly Example
	#include <inline.h>
	{
	char string[] = "Display this string.";
	   ...
	   lea si,string/* SI = offset of string */
	   cput_str();	/* display string */
	   ...
	}

Source file _CIOPSTR.ASM ASM equiv CPUT_STR
See also
_cput_newline, _cput_script, _cput_str, _cput_str, _cput_str, _put_str, _vcput_script

_cput_strci


Descrip
Puts a centered string to the display without interpreting it.

Syntax
#include <console.h>
void _cput_strci(const char *str, int width);

Returns
None

Notes
This function writes str to the display without interpreting any of the characters in the string (except the terminating NULL). The string is centered within the region which starts at the current cursor position and extends width positions in the current cursor advance direction. The cursor is advanced past the last character written. Output is restricted to the current clipping region if the clipping region is enabled; otherwise, it is restricted to the screen (or the active window if windowing is in effect). Characters are written to the display through BIOS calls or directly to video memory depending on the state of the direct_video variable.

Note that the appearance of the resulting string depends on the cursor advance direction. For example, if the cursor advance direction is down, the string is centered vertically with the string being displayed from top to bottom.

_console_init must be called before using this function.

C/C++ Example
	   _cput_strci ("Center this string w/o interpreting...",80);

Inline Assembly Example
	#include <inline.h>
	{
	   char string[] = "Center this string w/o interpreting...";
	   ...
	   lea si,string/* SI = offset of string */
	   mov cl,80	/* CL = width of region */
	   cput_strci();	/* display centered string */
	   ...
	}

Source file _CIOPSCI.ASM ASM equiv CPUT_STRCI
See also
_cput_str, _cput_str

_cput_stri


Descrip
Puts a string to the display without interpreting it.

Syntax
#include <console.h>
void _cput_stri(const char *str);

Returns
None

Notes
This function writes str to the display without interpreting any of the characters in the string (except the terminating NULL). Characters are written starting at the current cursor position and continuing in the current cursor advance direction. The cursor is advanced past the last character written. Output is restricted to the current clipping region if the clipping region is enabled; otherwise, it is restricted to the screen (or the active window if windowing is in effect). Characters are written to the display through BIOS calls or directly to video memory depending on the state of the direct_video variable.

_console_init must be called before using this function.

C/C++ Example
	#define BEEP = "\x07"
	...
	   _cput_stri("Display this string w/o interpreting: BEEP");

Inline Assembly Example
	#include <inline.h>
	{
	char string[] = "Display this string, don't interpret: \n\r";
	...
	lea si,string
	cput_stri();/* display uninterpreted string */
	...
	}

Source file _CIOPSTI.ASM ASM equiv CPUT_STRI
See also
_cput_str, _put_str

_cput_strji


Descrip
Puts a justified string to the display without interpreting it.

Syntax
#include <console.h>
void _cput_strji(const char *str, int width);

Returns
None

Notes
This function writes str to the display without interpreting any of the characters in the string (except the terminating NUL). The string is justified so that the last character of the string appears at the end of the region which lies width cursor positions from the current cursor position in the current cursor advance direction. The cursor is advanced past the last character written. Output is restricted to the current clipping region if the clipping region is enabled; otherwise, it is restricted to the screen (or the active window if windowing is in effect). Characters are written to the display through BIOS calls or directly to video memory depending on the state of the direct_video variable.

_console_init must be called before using this function.

C/C++ Example
	   _cput_strji("Right justify this string...",80);

Inline Assembly Example
	#include <inline.h>
	{
	   char string[] = "Right justify string w/o interpreting...";
	   ...
	   lea si,string/* SI = offset of string */
	   mov cl,80	/* CL = width of region */
	   cput_strji();	/* display right justified str */
	   ...
	}

Source file _CIOPSJI.ASM ASM equiv CPUT_STRJI
See also
_cput_str, _cput_str

_cursor_off


Descrip
Turns the hardware cursor off.

Syntax
#include <console.h>
void _cursor_off(void);

Returns
None

Notes
This function turns the hardware cursor off, making it invisible. The behavior of the cursor remains unchanged in every other respect.

_console_init must be called before using this function.

C/C++ Example
	{
	   _cput_str("Hide cursor ");
	   if (_cget_chr()==0)/* when ready... */
	      _cget_chr();
	   _cursor_off();/* ...turn cursor off */
	   ...
	}

Inline Assembly Example
	{
	   char string[] = "Hide cursor";
	   ...
	   if (_cget_chr()==0)/* when ready... */
	      _cget_chr();
	   cursor_off();/* ...turn cursor off */
	   ...
	}

Source file CIOCOFF.ASM ASM equiv CURSOR_OFF
See also
_cursor_on

_cursor_on


Descrip
Turns the hardware cursor on.

Syntax
#include <console.h>
void _cursor_on(void);

Returns
None

Notes
This function turns the hardware cursor on, making it visible.

The behavior of the cursor remains unchanged in every other respect.

_console_init must be called before using this function.

C/C++ Example
	{
	   _cput_str("Turn hardware cursor on ");
	   if (_cget_chr()==0)    /* when ready... */
	      _cget_chr();
	   _cursor_on();	/* ...turn cursor on */
	   ...
	}

Inline Assembly Example
	(C Interface Recommended)

Source file CIOCON.ASM ASM equiv CURSOR_ON
See also
_cursor_off, _set_cursor

_del_line


Descrip
Removes a line from the current clipping region.

Syntax
#include <console.h>
void _del_line(void);

Returns
None

Notes
This function deletes the line containing the cursor from the current clipping region. All lines below the current line are scrolled up and a blank line in the default text attribute is scrolled in at the bottom of the clipping region. The cursor position remains unchanged. If the line containing the cursor lies below the bottom of the clipping region, this function has no effect. If the clipping region is currently disabled, these actions take place within the boundaries of the screen (or within the boundaries of the active window if windowing is in effect). This function is performed using BIOS calls or by direct manipulation of video memory depending on the state of the direct_video variable.

_console_init must be called before using this function.

C/C++ Example
	   _del_line();

Inline Assembly Example
	   del_line();

Source file CIOINSL.ASM ASM equiv DEL_LINE
See also
_clr_line, _ins_line, _scroll_down, _scroll_up

_direc_down


Descrip
Sets the cursor advance direction to ADV_DOWN (down).

Syntax
#include <console.h>
void _direc_down(void);

Returns
None

Notes
This function sets the cursor advance direction so that the cursor advances down one row after each character is displayed by the _cput_... and echoed _cget_... functions.

_console_init must be called before using this function.

C/C++ Example
	   _direc_down();	/* set cursor advance to down */
	   _cput_str("This is down");/* This is down... */

Inline Assembly Example
	{
	   char str[] = "This is down";
	   ...
	   direct_down();	/* set cursor advance to down */
	   lea si,str
	   cput_str();	/* display str by rows */
	   ... 
	}  

Source file CIODIRD.ASM ASM equiv DIREC_DOWN
See also
_set_direction

_direc_left


Descrip
Sets the cursor advance direction to be ADV_LEFT (left).

Syntax
#include <console.h>
void _direc_left(void);

Returns
None

Notes
This function sets the cursor advance direction so that the cursor advances one column to the left after each character is displayed by the _cput_... and echoed _cget_... functions.

_console_init must be called before using this function.

C/C++ Example
	   _direc_left();	/* set cursor advance to left */
	   _goto_x(10);	    /* go to tenth column */
	   _cput_str("Going left");/* tfel gnioG */

Inline Assembly Example
	{
	   char str[] = "Going left";
	...
	lea si,str
	direc_left();
	mov al,10
	goto_x();
	cput_str();	 /* tfel gnioG */
	...
	}

Source file CIODIRL.ASM ASM equiv DIREC_LEFT
See also
_set_direction

_direc_right


Descrip
Sets the cursor advance direction to ADV_RIGHT (right).

Syntax
#include <console.h>
void _direc_right(void);

Returns
None

Notes
This function sets the cursor advance direction so that the cursor advances one column to the right after each character is displayed by the _cput_... and echoed _cget_... functions.

_console_init must be called before using this function.

C/C++ Example
	   _direct_right();/* set cursor direction going right */
	   _cput_str("Normal cursor advance direction -> ");

Inline Assembly Example
	(Not Applicable)

Source file CIODIRR.ASM ASM equiv DIREC_RIGHT
See also
set_direction

direct_video


Descrip
(Variable) Indicates the current Console I/O output method.

Syntax
#include <console.h>
extern char direct_video;

Returns
None

Notes
This variable determines whether console I/O screen output is performed using BIOS calls or by directly accessing video RAM. A value of 0 indicates BIOS and a value of 1 indicates direct. _console_init may also set this variable to -1 to indicate that BIOS output is being used and that direct output is not allowed on the current system (i.e., it is not fully IBM PC compatible). This variable may be set directly or by calling _set_directvideo and _set_biosvideo.

This variable is initialized by _console_init.

Source file CIOCVAR.ASM ASM equivâ
See also
_set_biosvideo, _set_directvideo

_direc_up


Descrip
Sets the cursor advance direction to ADV_UP (up).

Syntax
#include <console.h>
void _direc_up(void);

Returns
None

Notes
This function sets the cursor advance direction so that the cursor advances up one row after each character is displayed by the _cput_... and echoed _cget_... functions.

_console_init must be called before using this function.

C/C++ Example
	   _direc_up();	/* set cursor advance going up */
	   ...
	   _cput_str("Going up"); /* Direction is vertical */

Inline Assembly Example
	(Not Applicable)

Source file CIODIRU.ASM ASM equiv DIREC_UP
See also
_set_direction

_fill_eol


Descrip
Sets all characters and attributes from the cursor to the end of the current line to a specified character and attribute.

Syntax
#include <console.h>
void _fill_eol(int chr, int attr);

Returns
None

Notes
This function sets all characters and attributes from the current cursor position to the end of the current line to chr and attr. The cursor position remains unchanged. If an attribute table has been specified (using _set_attrtbl), attr is treated as an attribute table code and the corresponding attribute table value is used as the fill attribute; otherwise, attr is used as the actual fill attribute. Output is restricted to the current clipping region if the clipping region is enabled; otherwise, it is restricted to the screen (or the active window if windowing is in effect). Characters and attributes are written directly to the display through a BIOS call or directly to video memory depending on the state of the direct_video variable.

_console_init must be called before using this function.

C/C++ Example
	{
	   unsigned char chr;
	   chr = '±';
	   _fill_eol (chr, (WHITE+(16*BLUE)));
	   	  /* fill using chosen character and attribute */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	   ...
	   mov al,177	    /* AL = fill character */
	   mov ah,(WHITE+(16*BLUE))/* AH = fill attribute */
	   fill_eol();	/* use '±' and white/blue attr */
	   ...

Source file _CIOFLLE.ASM ASM equiv FILL_EOL
See also
_afill_eol, _clr_eol, _fill_line, _fill_n, _fill_region

_fill_line


Descrip
Sets all characters and attributes on the current line to a specified character and attribute.

Syntax
#include <console.h>
void _fill_line(int chr, int attr);

Returns
None

Notes
This function sets all characters and attributes on the current line to chr and attr. The cursor position remains unchanged. If an attribute table has been specified (using _set_attrtbl), attr is treated as an attribute table code and the corresponding attribute table value is used as the fill attribute; otherwise, attr is used as the actual fill attribute. Output is restricted to the current clipping region if the clipping region is enabled; otherwise, it is restricted to the screen (or the active window if windowing is in effect). Characters and attributes are written directly to the display through BIOS calls or directly to video memory depending on the state of the direct_video variable.

_console_init must be called before using this function.

C/C++ Example
	   _fill_line('±',(WHITE+(16*BLUE)));
	   	  /* use '±' chrs and white on blue attrs */

Inline Assembly Example
	#include <inline.h>
	   ...
	   mov ah,(WHITE+(16*BLUE))/* AH = fill attribute */
	   mov al,177	    /* AL = fill character */
	   fill_line();
	   ...

Source file _CIOFILL.ASM ASM equiv FILL_LINE
See also
_afill_line, _clr_line, _del_line, _ins_line, _fill_eol, _fill_n, _fill_region

_fill_n


Descrip
Sets a specified number of characters and attributes on the current line to a specified character and attribute.

Syntax
#include <console.h>
void _fill_n(int chr, int attr, int num);

Returns
None

Notes
This function sets num characters and attributes on the current line to chr and attr. Character/attribute changes take place starting at the current cursor position and continuing to the right. The cursor position remains unchanged. If an attribute table has been specified (using _set_attrtbl), attr is treated as an attribute table code and the corresponding attribute table value is used as the fill attribute; otherwise, attr is used as the actual fill attribute.

Output is restricted to the current clipping region if the clipping region is enabled; otherwise, it is restricted to the screen (or the active window if windowing is in effect). Characters and attributes are written directly to the display through BIOS calls or directly to video memory depending on the state of the direct_video variable.

_console_init must be called before using this function.

C/C++ Example
	   _fill_n('°',(WHITE+(16*BLUE)),10);
	   /* use '±' chr and white on blue for next ten columns 
	      of current line */
	   ...

Inline Assembly Example
	#include <inline.h>
	   ...
	   mov ah,(WHITE+(16*BLUE))/* AH = fill attribute */
	   mov al,177	/* AL = ± fill character */
	   mov cl,10	/* CL = num characters to fill */
	   fill_n();
	   ...

Source file _CIOFILN.ASM ASM equiv FILL_N
See also
_afill_n, _clr_n, _fill_eol, _fill_line, _fill_region

_fill_region


Descrip
Sets all characters and attributes in the current clipping region to a specified character and attribute.

Syntax
#include <console.h>
void _fill_region(int chr, int attr);

Returns
None

Notes
This function sets all characters and attributes in the current clipping region to chr and attr if the clipping region is enabled; otherwise, all characters on the screen (or the active window if windowing is in effect) are set to chr and attr. The cursor position remains unchanged. If an attribute table has been specified (using _set_attrtbl), attr is treated as an attribute table code and the corresponding attribute table value is used as the fill attribute; otherwise, attr is used as the actual fill attribute. Characters and attributes are written directly to the display through BIOS calls or directly to video memory depending on the state of the direct_video variable.

_console_init must be called before using this function.

C/C++ Example
	   _fill_region ('±',(WHITE+(16*BLUE)));
	/* use '±' for chr and white on blue attribute */ 

Inline Assembly Example
	#include <inline.h>
	   ...
	   mov ah,(WHITE+(16*BLUE))/* AH = fill attribute */
	   mov al,177	    /* AL = fill character */
	   fill_region();
	   ...

Source file _CIOFILR.ASM ASM equiv FILL_REGION
See also
_afill_region, _clr_region, _set_region

_get_adapter


Descrip
Returns the active display adapter type.

Syntax
#include <console.h>
char _get_adapter(void);

Returns
The active display adapter type.

Notes
This function returns a code which indicates the active adapter type. If the virtual screen system is in use, the return value indicates the adapter to which the active screen is assigned. The following symbolic constants (defined in CONSOLE.H) represent the adapter codes which may be returned by this function:

MDA (0x00) Monochrome Display Adapter
CGA (0x01) Color Graphics Adapter
EGA (0x02) Enhanced Graphics Adapter
MCGA (0x03) Multi-color Graphics Array
VGA (0x04) Video Graphics Array

Note that this function only indicates the adapter type, not the display mode or video mode. For example, EGA and VGA adapters support color, black-and-white, and monochrome display modes. To determine the display mode or video mode for the active adapter, use _get_dmode or _get_vmode.

This function does not depend on _console_init.

C/C++ Example
	{
	   int adapter;
	   adapter = _get_adapter();
	   switch(adapter)
	   {
	      case MDA: _cput_str("MDA"); break;
	      case CGA: _cput_str("CGA"); break;
	      case EGA: _cput_str("EGA"); break;
	      case MCGA: _cput_str("MCGA"); break;
	      case VGA: _cput_str("VGA"); break;
	      default: break;
	   }
	   ...
	}

Inline Assembly Example
	(C Interface Recommended)

Source file CIOGADP.ASM ASM equiv GET_ADAPTER
See also
adapter_type, _get_adapter, _is_cga, _is_ega, _is_mcga, _is_mda, _is_vga

_get_adapters


Descrip
Returns the active display adapter type(s) and monitor type(s).

Syntax
#include <console.h>
void _get_adapters(char *padapter, char *pmonitor, char *sadapter, char *smonitor);

Returns
No return value.
padapter primary adapter type
pmonitor primary monitor type
sadapter secondary adapter type
smonitor secondary monitor type

Notes
This function returns codes which indicate the primary (active) and secondary (inactive) adapter and monitor types. The following symbolic constants (defined in CONSOLE.H) represent the adapter codes which may be returned in padapter or sadapter:

MDA (0x00) Monochrome Display Adapter
CGA (0x01) Color Graphics Adapter
EGA (0x02) Enhanced Graphics Adapter
MCGA (0x03) Multi-Color Graphics Array
VGA (0x04) Video Graphics Array
ADAPT_NONE(0xFF) No adapter present

In addition, the following symbolic constants (also defined in CONSOLE.H) indicate the monitor types which may be returned in padapter or sadapter:

MONO (0x00) Digital monochrome display
RGB (0x01) RGB color display (200 scan lines)
ECD_LO (0x02) Enhanced color display (200 scan lines)
ECD_HI (0x03) Enhanced color display (350 scan lines)
ACOLOR (0x04) Analog color display (variable scan lines)
AMONO (0x05) Analog monochrome display
ADAPT_NONE(0xFF) No adapter present

The following monitor/adapter combinations may be returned by _get_adapters:

MDA CGA EGA MCGA VGA

MONO Yes - Yes - -
RGB - Yes Yes - -
ECD_LO - - Yes - -
ECD_HI - - Yes - -
ACOLOR - - - Yes Yes
AMONO - - - Yes Yes

C/C++ Example
	{
	   char padapter, pmonitor, sadapter, smonitor, adapter;
	   int i;
	   ...
	   _get_adapters(&padapter, &pmonitor, &sadapter, &smonitor);
	   _cput_str("Primary Adapter type: ");
	   adapter = padapter;
	   for(i = 0; i < 2; i++)
	   {
	      switch(adapter)/* secondary adapter types */
	      {
	         case MDA: _cput_str("Monochrome Display Adapter");
	   	     break;
	         case VGA: _cput_str("Video Graphics Array"); break;
	            ...
	      }
	      _cput_str("\n\rSecondary Adapter type: ");
	      adapter = sadapter;
	      if(padapter = -1)
	      break;
	   }
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char padapter, pmonitor, sadapter, smonitor;
	   char *str;
	   ...
	   get_adapters();
	      str = "Primary Adapter type: ";
	   mov si,str
	   cput_str();
	   adapt_010:
	   cmp al,MDA
	    jneadapt_020
	   str = "Monochrome Display Adapter";
	adapt_020:
	   cmp al,VGA
	    jneadapt_030
	   str = "Video Graphics Array";
	adapt_030:
	   ... 	 	/* test all types */
	adapt_070:
	   cput_str();	/* display adapter type */
	   mov al,dl
	   inc dl	 	/* secondary adapter present? */
	    jnzadapt_080/*  n: type(s) determined */
	   str = "\n\rSecondary Adapter type: ";
	   cput_str();
	   jmp adapt_010/*  y: secondary adapter */
	   ...
	adapt_080
	   ...
	}

Source file _CIOGAPS.ASM ASM equiv GET_ADAPTERS
See also
_get_adapter, _get_adaptinfo, monitor_type, _set_adapter

_get_adaptinfo


Descrip
Returns information about a specified display adapter.

Syntax
#include <console.h>
int _get_adaptinfo(int adapter, saadapt *adaptinfo);

Returns
0 if adapter is present in the system.
adaptinfo information about specified adapter

-1 if adapter is not present in the system.
adaptinfo structure unmodified

Notes
This function returns information about the capabilities and state of a specified display adapter. Specifically, this function indicates the current video mode, active video display page, the current screen dimensions, the number of supported video display pages and all screen dimensions directly supported on adapter by the console I/O and virtual screen systems. (These values are usually required when the virtual screen system is initialized for a specific system at run time.) "Best guess" values are returned if vmode, vpage, pagecnt, cols, and/or rows cannot be exactly determined due to BIOS limitations.

adaptinfo is a structure of type saadapt defined in CONSOLE.H as follows:

typedef struct {
char vmode; /* current video mode */
char vpage; /* active video page */
char cols; /* current number of text mode columns */
char rows; /* current number of text mode rows */
char dflags; /* screen dimension flags */
char pagecnt;/* number of video display pages */
} saadapt;

The following symbolic constants (defined in CONSOLE.H) represent the adapter codes which may be specified for adapter:

MDA (0x00) Monochrome Display Adapter
CGA (0x01) Color Graphics Adapter
EGA (0x02) Enhanced Graphics Adapter
MCGA(0x03) Multi-Color Graphics Array
VGA (0x04) Video Graphics Array
ADAPT_1(0xFF) Primary (active) adapter
ADAPT_2(0xFE) Secondary (inactive) adapter

The following flags (defined in CONSOLE.H) may be returned in dflags to indicate the text mode display dimensions directly supported by _set_dimens:

D_12ROWS(0x01) Supports 40x12 or 80x12 text dimensions
D_14ROWS(0x02) Supports 40x14 or 80x14 text dimensions
D_21ROWS(0x04) Supports 40x21 or 80x21 text dimensions
D_25ROWS(0x08) Supports 40x25 or 80x25 text dimensions
D_28ROWS(0x10) Supports 40x28 or 80x28 text dimensions
D_43ROWS(0x20) Supports 40x43 or 80x43 text dimensions
D_50ROWS(0x40) Supports 40x50 or 80x50 text dimensions

Only some flag combinations are possible. The returned combination depends on the adapter type as well as the type of attached monitor, as follows:

MDA/EGA CGA/EGA EGA EGA MCGA VGA
MONO RGB ECD_LO ECD_HI ANY ANY

D_12ROWS- - Yes - - Yes
D_14ROWS- - Yes - - Yes
D_21ROWS- - - Yes - -
D_25ROWSYes Yes Yes Yes Yes Yes
D_28ROWS- - - - - Yes
D_43ROWS- - - Yes - -
D_50ROWS- - - - Yes Yes

dflags0x08 0x08 0x0B 0x2C 0x48 0x5B

Other nonstandard text modes cannot be directly selected by _set_dimens because video mode values vary from manufacturer to manufacturer. For this reason, extended text modes are not indicated in dflags. See the Console I/O technical notes for instructions on identifying nonstandard text modes at run time.

_adapter_init must be called before this function may be used.

C/C++ Example
	{
	   saadapt adapt1_info, adapt2_info;
	   ...
	   if(_get_adaptinfo(ADAPT_1, &adapt1_info))
	      _cput_str("Primary adapter type and state determined.");
	   else
	      _cput_str("Primary Adapter not present.");
	   if(_get_adaptinfo(ADAPT_2,&adapt2_info))
	      _cput_str("Secondary Adapter type and state determined.");
	   else
	      _cput_str("Secondary Adapter not present.");
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   saadapt adapt1_info, adapt2_info;
	   char *str;
	   ... 	 	/* initialize console i/o */
	   mov     al,ADAPT_1
	   get_adaptinfo();
	    jc adapt_010
	   mov adapt1_info.vmode,al /* save adapter info */
	   mov adapt1_info.vpage,ah
	   mov adapt1_info.cols,dl
	   mov adapt1_info.rows,dh
	   mov adapt1_info.dflags,cl
	   mov adapt1_info.pagecnt,ch
	      str = "Primary adapter type and state determined.";
	   jmp short adapt_020

	adapt_010:
	   str = "Primary Adapter not present.";
	adapt_020:
	   mov si,str
	   cput_str();	/* display adapter 2 status */
	   mov al,ADAPT_2
	   get_adaptinfo();
	    jc adapt_030
	   mov adapt2_info.vmode,al /* save adapter info */
	   mov adapt2_info.vpage,ah
	   mov adapt2_info.cols,dl
	   mov adapt2_info.rows,dh
	   mov adapt2_info.dflags,cl
	   mov adapt2_info.pagecnt,ch
	   str = "Secondary adapter type and state determined.";
	   jmp short adapt_040

	adapt_030:
	   str = "Secondary Adapter not present.";
	adapt_040:
	   mov si,str
	   cput_str();	/* display adapter 1 status */
	   ...
	}

Source file _CIOGADN.ASM ASM equiv GET_ADAPTINFO
See also
_chk_dimens, _get_adapter, _get_dimens, _get_vpage, _get_vmode, _get_vstate, _is_textmode, set_adapter

_get_attr


Descrip
Returns the current text attribute code or value.

Syntax
#include <console.h>
int _get_attr(void);

Returns
Current text attribute code or value.

Notes
This function returns the current text attribute. If an attribute table has been specified (using _set_attrtbl), the returned value is an attribute table code; otherwise, it is an actual attribute value.

The current text attribute is the base attribute used by the _cput_... and echoed _cget_... functions to display text. This is combined with the current BOLD, BLINK, and BKBOLD attribute flags to produce the actual display attribute.

_get_tblattr should be called immediately after calling this function if the text attribute value (not the code) is required. _get_tblattr converts the attribute code to its corresponding attribute if an attribute table has been specified; otherwise, it has no effect.

_console_init must be called before using this function.

C/C++ Example
	{
	   int attr;	 
	   attr = _get_attr();
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   int attr;
	   get_attr();/* AH = current text attribute */
	   xor al,al
	   mov attr,ax
	   ...
	}

Source file _CIOGATR.ASM ASM equiv GET_ATTR
See also
_get_dattr, _set_attr, _get_tblattr

_get_attrflags


Descrip
Returns the current text attribute flags.

Syntax
#include <console.h>
char _get_attrflags(void);

Returns
Attribute flags.

Notes
This function returns the flags which indicate the current bold, blink, and background high intensity states for the current text attribute. These flags determine whether or not the _cput_... functions force displayed text to appear with bold, blinking, or high intensity background attributes.

The following symbolic constants (defined in CONSOLE.H) indicate the various bits which may be set in flags:

BOLD (0x08) bold, foreground intensity
BLINK(0x80) blinking text, bold background if blink disabled
BKBOLD(0x80) bold background, blinking text if blink enabled

Note that the BLINK and BKBOLD values are identical. The actual interpretation of the BLINK or BKBOLD bit depends on how the current display adapter has been programmed. If blink is enabled, the bit represents BLINK; otherwise, it represents BKBOLD. The meaning of this bit may be changed by calling _set_blinkmode or _set_bkboldmode.

_console_init must be called before using this function.

C/C++ Example
	{
	   char attrflag;
	   attrflag = _get_attrflags();
	   switch(attrflag)
	   {
	      case BOLD: _cput_str("Bold bit enabled"); break;
	      case BKBOLD: _cput_str("Blink/Bkbold bit enabled"); break;
	   }
	   ...
	}

Inline Assembly Example
	(C Interface Recommended)

Source file CIOGATRF.ASM ASM equiv GET_ATTRFLAGS
See also
_set_attr

_get_cursor


Descrip
Gets the shape and state of the display cursor.

Syntax
#include <console.h>
unsigned int _get_cursor(int *state);

Returns
The shape of the cursor.
state 1 if the cursor is currently turned on; 0 if the cursor is currently turned off

Notes
This function returns the shape of the display cursor and indicates in state whether or not the cursor is currently turned on. The starting cell position (start) and the ending cell position (end) for the cursor are contained in the high and low bytes of the return value, respectively. The range of each cell position is 0-255, with 0 representing the top of the character cell and 255 representing the bottom of the character cell. These values are independent of the active display adapter or monitor. The display cursor fills the character cell from top to bottom, beginning at the start position and ending at the end position. If end lies above start, the cursor wraps past the bottom of the cell to the top of the cell and continues downward until the end position is encountered.

Note that the actual cursor appearance is ultimately determined by the BIOS and the active display adapter. For example, a wrapping cursor (end < start) appears as a "broken" cursor on MDA adapters but is not visible on many Hercules-compatible adapters. Also, EGA, MCGA, and VGA adapters perform "cursor emulation", which restricts the range of possible cursor shapes.

The following symbolic constants (defined in CONSOLE.H) may be used to check the cursor with a number of predefined shapes:

BLOCK_CURSOR(0x00FF) Full block cursor shape
HALF_CURSOR(0x80FF) Half block cursor shape
DEFAULT_CURSOR(0xD0E0) BIOS default cursor shape
THICK_CURSOR(0xD0FF) Like DEFAULT, but extends to bottom of cell
XTHICK_CURSOR(0xB8FF) Like THICK, but starts one scan line higher

_console_init must be called before using this function.

C/C++ Example
	{
	   unsigned curstype;
	   int state;
	   curstype = _get_cursor(&state);
	   if (state == 1)
	      _set_cursor(curstype); /* if cursor is on, set it; 
	   	  	       otherwise, just save shape */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   unsigned curstype;
	   ...
	   curstype = get_cursor();/* AX = cursor type */
	    jnelabel_100    /* is cursor on? */
	   set_cursor();	    /*   y: set cursor type */
	label_100:
	   ...
	}

Source file _CIOGCUR.ASM ASM equiv GET_CURSOR
See also
_set_cursor

_get_dattr


Descrip
Returns the default text attribute code or value.

Syntax
#include <console.h>
int _get_dattr(void)

Returns
The default text attribute code or value.

Notes
This function returns the "default" text attribute. If an attribute table has been specified (using _set_attrtbl), the returned value is an attribute table code; otherwise, it is an actual attribute value.

The default text attribute is the fill attribute used for clearing, inserting and scrolling. It is also the attribute to which the current attribute is set when _reset_attr is called.

_get_tblattr should be called immediately after calling this function if the text attribute value (not the code) is required. _get_tblattr converts the code to its corresponding attribute if an attribute table has been specified; otherwise, it has no effect.

_console_init must be called before using this function.

C/C++ Example
	{
	   int dattr;
	   dattr = _get_dattr(); /* get default attribute */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   int dattr;
	   ...   
	   get_dattr();	/* AH = default attribute */
	   xor al,al
	   mov dattr,ax/* load C variable */
	   ...
	}

Source file _CIOGDTR.ASM ASM equiv GET_DATTR
See also
_get_attr, _get_tblattr, _set_dattr

_get_dimens


Descrip
Returns the current screen dimensions of the active display adapter.

Syntax
#include <console.h>
void _get_dimens(char *cols, char *rows);

Returns
No return value.
cols number of columns in the current display mode
rows number of rows in the current display mode

Notes
This function indicates the number of text mode columns and rows on the active display adapter in the current video display mode. The indicated number of columns and rows are identical to the values specified in the screen_dimens variable. If the virtual screen system is in use, then the values indicate the dimensions of theactive screen.

_console_init must be called before this function may be used.

C/C++ Example
	{
	   char cols, rows;
	   char intbuf[10];
	   ...
	   _get_dimens(&cols, &rows);
	   _cput_str("Number of columns: ";
	   _cput_str(_c_to_dec(cols, intbuf));
	   _cput_str("Number of rows: ";
	   _cput_str(_c_to_dec(rows, intbuf));
	   ...
	   _cput_str("Number of columns: ";
	   _cput_str(_c_to_dec(cols, intbuf));
	   _cput_str("Number of rows: ";
	   _cput_str(_c_to_dec(rows, intbuf));
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char cols, rows;
	   char intbuf[10], *str;
	   ...
	   get_dimens();	/* AL = cols, AH = rows */
	   mov cols,al
	   mov rows,ah	    /* load variables */
	   str = "Number of columns: ";
	   mov si,str	/* SI = str */
	   cput_str();	/* display string */
	   lea si,intbuf/* SI = offset intbuf */
	   mov al,cols	    /* AL = columns */
	   c_to_dec();
	   cput_str();	/* display number of columns */
	   str = "Number of rows: ";
	   mov si,str	/* SI = str */
	   cput_str();
	   lea si,intbuf
	   mov al,rows	    /* AL = rows */
	   c_to_dec();
	   cput_str();	/* display number of rows */
	   ...
	}

Source file _CIOGDMS.ASM ASM equiv GET_DIMENS
See also
_chk_dimens, _get_adaptinfo, _set_dimens

_get_direction


Descrip
Returns the current cursor advance direction.

Syntax
#include <console.h>
unsigned int _get_direction(void);

Returns
The cursor advance direction.

Notes
This function returns the current cursor advance direction. The cursor advance direction indicates the direction and distance the cursor moves after each character is displayed using the _cput_... and echoed _cget_... functions. The following symbolic constants (defined in CONSOLE.H) represent some of the possible advance directions:

ADV_RIGHT(0x0001) Cursor moves one column to the right
ADV_LEFT (0x00FF) Cursor moves one column to the left
ADV_UP(0xFF00) Cursor moves one row up
ADV_DOWN (0x0100) Cursor moves one row down
ADV_NONE (0x0000) No cursor motion at all

Other values may be returned. The value in the low byte represents the signed number of columns to move; the value in the high byte represents the signed number of rows. Negative values are interpreted as left and upward motion; positive values are interpreted as right and downward motion.

_console_init must be called before this function may be used.

C/C++ Example
	   if(_get_direction() != ADV_RIGHT)
	      _set_direction(ADV_RIGHT);
	   ...

Inline Assembly Example
	#include <inline.h>
	   ...
	   get_direction();/* AX = current direction */
	   cmp ax,ADV_RIGHT/* is it "right"? */
	    jnesdrc_010/*   y: continue */
	   mov ax,ADV_RIGHT
	   set_direction();/*   n: set to "right" */
	sdrc_010:
	   ...

Source file CIOGDIR.ASM ASM equiv GET_DIRECTION
See also
_set_direction

_get_dmode


Descrip
Returns the active display mode.

Syntax
#include <console.h>
char _get_dmode(void);

Returns
The active display mode.

Notes
This function returns a code indicating the active display mode. The display mode indicates how the various text mode attributes are interpreted and displayed on the active monitor in the current video mode. The following symbolic constants (defined in CONSOLE.H) represent the display mode codes which may be returned by this function:
MONO2(0x00) Monochrome, blink enabled
MONO4(0x01) Monochrome, high intensity background, no blink
BW2 (0x02) Black/white, blink enabled
BW4 (0x03) Black/white, high intensity background, no blink
COLOR8(0x04) Color, 8 background colors, blink enabled
COLOR16(0x05) Color, 16 background colors, no blink
GRAY8(0x06) Gray scale, 8 shades, blink enabled
GRAY16(0x07) Gray scale, 16 shades, no blink

The display mode is usually used to select an appropriate attribute table for the Console I/O system at run time.

Note that the display mode is largely independent of the adapter type. For example, the MONO display modes are possible on MDA, EGA, and VGA adapters; and the COLOR and GRAY modes are possible on CGA, EGA, MCGA, and VGA adapters.

This function does not depend on _console_init.

The GRAY display modes can only be detected if the active display adapter is an EGA, MCGA, or VGA. If any other display adapter is active, the GRAY display modes are reported as COLOR modes. CGA adapters which support gray scale display mode must be identified using some other method (i.e., the user must specify it at run time). CGA adapters in COMPAQ computers usually operate in gray scale mode. The example below may be used to enforce this assumption.

C/C++ Example
	{
	   char dmode;
	   ...
	   dmode = _get_dmode();
	   switch (dmode)
	   {
	      case MONO2:_put_str("Monochrome, blink enabled"); break;
	      case MONO4:_put_str("Monochrome, high intensity\ 
	   	  	   background, no blink"); break;
	      case BW2:_put_str("Black/white, blink enabled"); break;
	      case BW4:_put_str("Black/white, high intensity\ 
	   	  	 background, no blink"); break;
	      case COLOR8:_put_str("Color, 8 background colors, blink\ 
	   	  	   enabled"); break;
	      case COLOR16:_put_str("Color, 16 background colors, no\ 
	   	  	    blink"); break;
	      case GRAY8:_put_str("Gray scale, 8 shades, blink\ 
	   	  	   enabled"); break;
	      case GRAY16: _put_str("Gray scale, 16 shades, no blink");
	         break;
	      default: break;
	   };
	   ...
	}

Inline Assembly Example
	(C Interface Recommended)

Source file CIOGDMOD.ASM ASM equiv GET_DMODE

_get_keyflags


Descrip
Returns the current keyboard shift status flags.

Syntax
#include <console.h>
unsigned int _get_keyflags(void);

Returns
The current keyboard shift status flags.

Notes
This function returns the BIOS keyboard flags which describe the current state of various keyboard toggles and shift keys. The following flags are returned in the low byte:

RSHIFT_KEY (0x01) Right Shift key is depressed
LSHIFT_KEY (0x02) Left Shift key is depressed
CTRL_KEY (0x04) Ctrl key is depressed
ALT_KEY (0x08) Alt key is depressed
SCROLL_LOCK(0x10) Scroll Lock is ON
NUM_LOCK (0x20) Num Lock is ON
CAPS_LOCK (0x40) Caps Lock is ON
INSERT_ON (0x80) Insert is ON

The following flags are returned in the high byte if _kbd_init was called previously and an enhanced keyboard was detected (the global kbd_type variable is set to 1):

LCTRL_KEY (0x01) Left Ctrl key is depressed
LALT_KEY (0x02) Left Alt key is depressed
RCTRL_KEY (0x04) Right Ctrl key is depressed
RALT_KEY (0x08) Right Alt key is depressed
SCROLL_KEY(0x10) Scroll Lock key is depressed
NUM_KEY (0x20) Num Lock key is depressed
CAPS_KEY (0x40) Caps Lock key is depressed
SYSREQ_KEY(0x80) System Request key is depressed

0 is returned in the high byte of the result if _kbd_init was not previously called or a standard keyboard was detected (the global kbd_type variable is set to 0).

All symbolic constants listed above are defined in CONSOLE.H.

C/C++ Example
	{
	   int keyf;
	   char buf[5];
	   keyf = _get_keyflags();
	   _cput_str("\nKeyflags: ");
	   _cput_str(_uc_to_dec(keyf, buf));
	   ...
	}

Inline Assembly Example
	(C Interface Recommended)

Source file CIOGKEYF.ASM ASM equiv GET_KEYFLAGS
See also
_kbd_init, kbd_type

_get_region


Descrip
Returns the current clipping region position and dimensions.

Syntax
#include <console.h>
void _get_region(unsigned char *row, unsigned char *col, unsigned char *hght, unsigned char *wdth);

Returns
No return value.
row the starting row coordinate
col the starting column coordinate
hght the height in rows
wdth the width in columns

Notes
This function indicates the height, width, and position of the upper left-hand corner of the current clipping region. The indicated position is relative to the upper left-hand corner of the screen (or the active window, if windowing isin effect). hght and wdth are the actual height and width of the clipping region, whether or not the region extends beyond the boundaries of the screen (or active window). If the clipping region is currently off, the height and width of the current screen (or active window) are indicated, and the indicated position is (0,0).

When the clipping region is active, all cursor positioning is relative to the upper left-hand corner of the region and all output from the _cput_... and echoed _cget_... functions is restricted to the clipping region. The cursor becomes invisible if it is moved outside of this region.

_console_init must be called before using this function.

C/C++ Example
	{
	   char row,col,hght,wdth;
	   _get_region (&row, &col, &hght, &wdth);
	   row++;	 /* inc starting row position */
	   col++;	 /* inc starting column position */
	   _set_region(row,col,hght,wdth);
	   /* smaller region by one row and one column */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char row,col,hght,wdth;
	   ...
	   get_region();
	   mov row,dh/* row = starting row coordinate */
	   mov col,dl/* col = starting column coordinate */
	   mov hght,ah	/* hght = height in rows */
	   mov wdth,al	/* wdth = width in columns */
	   ...
	}

Source file _CIOGREG.ASM ASM equiv GET_REGION
See also
_set_region

_get_tblattr


Descrip
Returns an attribute from the current attribute table.

Syntax
#include <console.h>
int _get_tblattr(int attr);

Returns
Attribute from attribute table (original value of attr is returned if no table has been specified).

Notes
This function returns the attribute table value which corresponds to attr. The currently-selected attribute table is used. If no attribute table has been specified, the attr parameter value is returned unmodified.

_console_init must be called before using this function.

C/C++ Example
	{
	   ...
	   char attrtbl[] = {0x17, 0x47}; /* white/blue, white/red */
	   int attr;
	   _set_attrtbl(attrtbl);
	   ...
	   attr = _get_tblattr(0);/* find first attr in tbl */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char attr;
	   char attrtbl[] = {0x17, 0x47}; /* white/blue, white/red */
	   ...
	   lea ax,attrtbl/* AX = offset of attr tbl */
	   set_attrtbl();
	   mov ah,0	/* AH = attrtbl[0](white/blue) */
	   get_tblattr();	/* AH = attr code from attrtbl */
	   mov attr,ah	    /* load C variable */
	   ...
	}

Source file _CIOGTTR.ASM ASM equiv GET_TBLATTR
See also
_set_attr

_get_vborder


Descrip
Gets the current video border color and state.

Syntax
#include <console.h>
int _get_vborder(char *state);

Returns
The current video border attribute or code.
state 1 if the video border is currently on; 0 if the video border is currently off

Notes
This function returns the current video border color and indicates (via state) whether or not the video border is currently turned on. If an attribute table has been specified (using _set_attrtbl), the return value is an attribute table code; otherwise, the return value is an actual video border color. The results are undefined if the active video mode is MONO.

The border color and state are initialized by _console_init and may be changed using _set_vborder, _set_vbordattr, _vborder_on or _vborder_off.

The range of possible border color values and their interpretations depends on the active display adapter and monitor. CGA monitors support 16 border colors which are identical to the foreground and background colors defined in CONSOLE.H. EGA adapters with standard color monitors support 16 border colors; VGA color and EGA enhanced color monitors support 64 border colors. Colors are mapped differently for each monitor type.

Note that if no attribute table has been installed, this function returns the actual color value used to program the border color on the active display adapter. It does not attempt to interpret that value in terms of the standard 16 foreground and background colors, even if the border color was set using _set_vbordattr.

_console_init must be called before using this function.

C/C++ Example
	{
	   char attr, state;
	   attr=_get_vborder(&state); /* get video border color/state */
	   if (state == 1)     /* is border on? */
	      _cput_str("Border is currently on.");
	   else
	      _cput_str("Border is currently off.");
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char *str;
	   char attr;
	...
	get_vborder();/* get video border color and state */
	mov  attr,ah/* save border attribute */
	 jne  label_100/* is border on? */
	str = "Border is currently on.";
	jmp short label_200

	label_100:   	 	
	str = "Border is currently off.";
	label_200:
	mov si,str
	cput_str();
	...
	}

Source file _CIOGVBD.ASM ASM equiv GET_VBORDER
See also
_set_vborder

_get_vmode


Descrip
Returns the current video mode.

Syntax
#include <console.h>
char _get_vmode(void);

Returns
The current video mode.

Notes
This function returns the current video mode. The following symbolic constants (defined in CONSOLE.H) represent the standard video mode values which may be returned:

BW40 (0x00) 40x25 text mode, color burst off
CO40 (0x01) 40x25 text mode
BW80 (0x02) 80x25 text mode, color burst off
CO80 (0x03) 80x25 text mode
CG320X200X4(0x04) 320x200 graphics mode, 4 color
BW320X200X4(0x05) 320x200 graphics mode, 4 color
CG640X200X2(0x06) 640x200 graphics mode, 2 color
MONO80 (0x07) 80x25 text mode, monochrome
CG160X200X16jr(0x08) 160x200 graphics mode, 16 color, PCjr
CG320X200X16jr(0x09) 320x200 graphics mode, 16 color, PCjr
CG640X200X4jr(0x0A) 640x200 graphics mode, 4 color, PCjr
CG320X200X16(0x0D) 320x200 graphics mode, 16 color
CG640X200X16(0x0E) 640x200 graphics mode, 16 color
MG640X350 (0x0F) 640X350 graphics mode, monochrome
CG640X350X16(0x10) 640x350 graphics mode, 16 color
CG640X480X2(0x11) 640x480 graphics mode, 2 color
CG640X480X16(0x12) 640x480 graphics mode, 16 color
CG320X200X256(0x13) 320x200 graphics mode, 256 color

In addition, many non-IBM display adapters support enhanced modes which are not listed above.

This function does not depend on _console_init.

C/C++ Example
	   ...
	   switch (_get_vmode())
	   {
	      case BW40:_put_str("40X25 text mode, color burst off");
	         break;
	      case CO40:_put_str("40X25 text mode"); break;
	      case BW80:_put_str("80X25 text mode, color burst off");
	         break;
	      case CO80:_put_str("80X25 text mode"); break;
	         ...
	      default: break;
	   };
	   ...

Inline Assembly Example
	(C Interface Recommended)

Source file CIOGVMOD.ASM ASM equiv GET_VMODE
See also
_get_adaptinfo, _is_textmode, _set_vmode

_get_vpage


Descrip
Returns the active video display page.

Syntax
#include <console.h>
char _get_vpage(void);

Returns
The active video display page number.

Notes
This function returns the active video display page of the active display adapter. The return value is an origin 0 page number (the first video page is page 0, the second is page 1, and so on). If the virtual screen system is active,the return value is the video display page to which the active screen is assigned on its adapter.

_console_init must be called before this function may be used.

Source file CIOGVPG.ASM ASM equiv GET_VPAGE
See also
_get_adaptinfo, _get_vpage, _set_vpage

_get_vpagecnt


Descrip
Returns the number of available video display pages on the active display adapter.

Syntax
#include <console.h>
char _get_vpagecnt(void);

Returns
The number of available video display pages on the active adapter.

Notes
This function returns the number of available video display pages in the current text video mode on the active display adapter. The return value is an origin 1 number. A "best guess" page count is returned if the number of available video pages cannot be exactly determined due to BIOS limitations. If the virtual screen system is in use, then the return value is the number of video pages available on the adapter to which the active screen is assigned.

_console_init must be called before this function may be used.

C/C++ Example
	#include<console.h>
	{
	   char intbuf[10];
	   ...
	   _cput_str("Active video page: ");
	   _cput_str(_i_to_dec(_get_vpagecnt(), intbuf));
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char intbuf[10];
	   char *str = "Active video page: ";
	   ...
	   mov si,str	/* SI = offset of str */
	   cput_str();
	   get_vpagecnt();    /* AL = active video page */
	   lea si,intbuf/* SI = offset of intbuf */
	   c_to_dec();	/* convert page to ASCII */
	   cput_str();	/* display page number */
	   ...
	}

Source file CIOGVPGC.ASM ASM equiv GET_VPAGECNT
See also
_get_adaptinfo, _get_vpage, _set_vpage

_get_vstate


Descrip
Returns the current video state.

Syntax
#include <console.h>
vstat *_get_vstate(const vstat far *buffer);

Returns
A pointer to buffer.
buffer the current video state information

Notes
This function saves the current video state in buffer. The state of the active screen is saved if the virtual screen system is in use. The video state information is saved in the following format (defined in CONSOLE.H):

typedef struct {
char vst_adapter; /* active display adapter */
char vst_vmode; /* active video display mode */
char vst_vpage; /* active video display page */
char vst_refresh; /* refresh state (1-on, 0=off) */
unsigned int vst_dimens;/* screen dimensions (cols, rows) */
char vst_attr; /* current text attribute */
char vst_dattr; /* default text attribute */
char vst_vbon; /* video border state (1=on, 0=off) */
char vst_vbcolor; /* video border color */
char vst_bkbold; /* bkbold/blink mode (1=bkbold, 0=blink) */
char vst_curon; /* cursor state (1=on, 0=off) */
unsigned int vst_curtype;/* cursor type (0-255, 0-255) */
unsigned int vst_curpos;/* cursor position (forced to 0,0) */
} vstat;

This is the same format required by _set_vstate. By using _get_vstate in combination with _set_vstate, video states may be saved, manipulated, and restored at will.

Note that the returned cursor position is always the upper left corner of the screen (0,0). This is usually the preferred cursor placement position when video states are restored. If the actual cursor position is required, _where_xy may be called immediately after calling _get_vstate and the returned position information may be stored in the vst_curpos field.

_console_init must be called before this function may be used.

C/C++ Example
	{
	   vstat v1;
	   ...
	   _get_vstate(&v1); /* save state of active display adapter */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   vstat v1;
	   ...
	   pushss
	   pop es
	   lea di,v1  /* ES:DI -> buffer */
	   get_vstate();  /* save state of active display adapter */
	   ...
	}

Source file _CIOGVST.ASM ASM equiv GET_VSTATE
See also
_get_adaptinfo, _set_vstate

_goto_bottom


Descrip
Moves the cursor to the bottom row of the current clipping region.

Syntax
#include <console.h>
void _goto_bottom(void);

Returns
None

Notes
This function moves the cursor to the bottom row of the current clipping region. If the clipping region is currently disabled, the cursor is moved to the bottom row of the screen (or the active window if windowing is in effect). The horizontal position of the cursor remains unchanged.

_console_init must be called before using this function.

C/C++ Example
	   ...
	   _goto_bottom();/* go to bottom of screen or 
	   	  	    clipping region */
	   _goto_left();
	   _cput_str("<- Lower left corner");
	   ...

Inline Assembly Example
	(C Interface Recommended)

Source file CIOGBOT.ASM ASM equiv GOTO_BOTTOM

_goto_end


Descrip
Moves the cursor to the lower right-hand corner of the current clipping region.

Syntax
#include <console.h>
void _goto_end(void);

Returns
None

Notes
This function moves the cursor to the lower right-hand corner of the current clipping region. If the clipping region is currently disabled, the cursor is moved to the lower right-hand corner of the screen (or the active window if windowing is in effect).

_console_init must be called before using this function.

C/C++ Example
	   ...
	   _goto_end();
	   _cput_str("Bottom, right, corner...");
	   ...

Inline Assembly Example
	(C Interface Recommended)

Source file CIOGEND.ASM ASM equiv GOTO_END

_goto_home


Descrip
Moves the cursor to the upper left-hand corner of the current clipping region.

Syntax
#include <console.h>
void _goto_home(void);

Returns
None

Notes
This function moves the cursor to the upper left-hand corner of the current clipping region. If the clipping region is currently disabled, the cursor is moved to the upper left-hand corner of the screen (or the active window if windowing is in effect).

_console_init must be called before using this function.

C/C++ Example
	   ...
	   _goto_home();
	   _cput_str ("in upper left-hand corner");
	   ...

Inline Assembly Example
	(C Interface Recommended)

Source file CIOGHOME.ASM ASM equiv GOTO_HOME

_goto_left


Descrip
Moves the cursor to the left-most column of the current clipping region.

Syntax
#include <console.h>
void _goto_left(void);

Returns
None

Notes
This function moves the cursor to the left-most column of the current clipping region. If the clipping region is currently disabled, the cursor is moved to the left-most column of the screen (or the active window if windowing is in effect). The vertical position of the cursor remains unchanged.

_console_init must be called before using this function.

C/C++ Example
	   ...
	   _goto_left();
	   _cput_str ("left-most column");
	   ...

Inline Assembly Example
	(C Interface Recommended)

Source file CIOGLEFT.ASM ASM equiv GOTO_LEFT

_goto_right


Descrip
Moves the cursor to the right-most column of the current clipping region.

Syntax
#include <console.h>
void _goto_right(void);

Returns
None

Notes
This function moves the cursor to the right-most column of the current clipping region. If the clipping region is currently disabled, the cursor is moved to the right-most column of the screen (or the active window if windowing is in effect). The vertical position of the cursor remains unchanged.

_console_init must be called before using this function.

C/C++ Example
	   ...
	   _goto_right();
	   ...

Inline Assembly Example
	(C Interface Recommended)

Source file CIOGRGHT.ASM ASM equiv GOTO_RIGHT

_goto_top


Descrip
Moves the cursor to the top row of the current clipping region.

Syntax
#include <console.h>
void _goto_top(void);

Returns
None

Notes
This function moves the cursor to the top row of the current clipping region. If the clipping region is currently disabled, the cursor is moved to the top row of the screen (or the active window if windowing is in effect). The horizontal position of the cursor remains unchanged.

_console_init must be called before using this function.

C/C++ Example
	   ...
	   _goto_top();
	   _cput_str("top row");
	...

Inline Assembly Example
	(C Interface Recommended)

Source file CIOGTOP.ASM ASM equiv GOTO_TOP

_goto_x


Descrip
Moves the cursor to a specified column.

Syntax
#include <console.h>
void _goto_x(int xpos);

Returns
None

Notes
This function moves the cursor to xpos in the current clipping region. xpos is specified as a number of columns from the left-most column in the clipping region (the left-most column is column zero).

If the clipping region is not active, the cursor is positioned relative to the left-most column on the screen (or within the active window if windowing is in effect). The row remains unchanged. If the cursor is positioned beyond the boundaries of the current clipping region or screen (or window if windowing is in effect), the cursor becomes invisible.

_console_init must be called before using this function.

C/C++ Example
	   ...
	   _goto_x (5);	 /* move cursor to column 5 */
	   ...

Inline Assembly Example
	#include <inline.h>
	   ...
	   mov al,5	/* AL = xpos */
	   goto_x();	/* move cursor to column 5 */
	   ...

Source file _CIOGX.ASM ASM equiv GOTO_X
See also
_goto_x, _goto_y

_goto_xy


Descrip
Moves the cursor to a specified column and row.

Syntax
#include <console.h>
void _goto_xy(int xpos, int ypos);

Returns
None

Notes
This function moves the cursor to xpos and ypos in the current clipping region. This position is specified as a number of rows and columns from the upper left-hand corner of the current clipping region (the top row is row zero and the left-most column is column zero). If the clipping region is not active, the cursor is positioned relative to the upper left-hand corner of the screen (or the active window if windowing is in effect). If the cursor is positioned beyond the boundaries of the current clipping region or screen (or window if windowing is in effect), the cursor becomes invisible.

_console_init must be called before using this function.

C/C++ Example
	   ...
	   _goto_xy(5,10);/* goto column 5, row 10 */
	   ...

Inline Assembly Example
	#include <inline.h>
	...
	   mov al,5	/* AL = xpos */
	   mov ah,10	/* AH = ypos */
	   goto_xy();	/* got column 5, row 10 */
	   ...

Source file _CIOGXY.ASM ASM equiv GOTO_XY
See also
_goto_x, _goto_y, _rel_xy, _where_x

_goto_y


Descrip
Moves the cursor to a specified row.

Syntax
#include <console.h>
void _goto_y(int ypos);

Returns
None

Notes
This function moves the cursor to ypos in the current clipping region. ypos is specified as a number of rows from the top row in the clipping region (the top row is row zero). If the clipping region is not active, the cursor is positioned relative to the top row on the screen (or within the active window if windowing is in effect). The column remains unchanged. If the cursor is positioned beyond the boundaries of the current clipping region or screen (or window if windowing is in effect), the cursor becomes invisible.

_console_init must be called before using this function.

C/C++ Example
	   ...
	   _goto_y (5);	/* place cursor on row five */
	   ...

Inline Assembly Example
	#include <inline.h>
	   ...
	   mov ah,5	/* AH = new ypos */
	   goto_y();	/* place cursor on row five */
	   ...

Source file _CIOGY.ASM ASM equiv GOTO_Y
See also
_goto_x, _goto_x

_hread_textattr


Descrip
Copies text and attributes from a specified display region to a disk buffer.

Syntax
#include <console.h>
int _hread_textattr(int handle, void *workbuf, unsigned int wsize, char top, char left, char height, char width, int *nbytes);

Returns
0 if the text and attributes were successfully read from the display region and saved in the disk buffer.
nbytes the number of bytes written to handle
workbuf undefined

1 if end-of-file was encountered.
nbytes the number of bytes written to handle
workbuf undefined

-1 if an error occurred.
nbytes the number of bytes written to handle
workbuf undefined
e_code error code

Notes
This function reads text and attributes from the display region located at top and left, where top and left are origin 0 positions relative to the upper left corner of the active window (or the screen if windowing is not in effect). The text and attributes are written to the file associated with handle at the current file pointer position; the file pointer is advanced past the written information. workbuf is used to buffer the writes and is left in an undefined state. nbytes returns the actual number of bytes written to handle. 0 is returned if the operation was successful. 1 is returned if a disk full condition was encountered. If an error occurred, -1 is returned and an error code is returned in e_code. Text and attributes are read from the active screen if the virtual screen system is active.

A maximum of height rows and width characters per row are copied. If the source region extends beyond the boundaries of the screen or window, then only those characters are read which are actually on the screen or within the active window. Character/attribute pairs are read from the display using BIOS calls or directly from video memory depending on the state of the direct_video variable.

The size of the work buffer (wsize) must be at least equal to twice the value of width. If this requirement is not satisfied, -1 is returned and e_code is set to E_INSMEM.

The text and attributes are written to the disk buffer as character/attribute pairs (character followed by attribute). These character/attribute pairs are preceded by the actual size of the display region from which they were read, as follows:

char buf_width; /* width of each row */
char buf_height;/* number of rows */
int buf_charattr[];/* character/attribute pairs, attr in high (2nd) byte,
size = buf_height x buf_width */

Note that the size of the display region stored in the disk buffer will differ from the specified height and width if the source display region extends beyond the boundaries of the window or screen.

_console_init must be called before this function may be used.

C/C++ Example
	{
	   char top, left, height, width;
	   char *workbuf;
	   int nbytes, handle;
	   ...
	   workbuf = (char *)malloc(260);
	   _lseekbof(handle);
	   if(_hread_textattr(handle, workbuf, 260, 0, 0,
	       	   10, 80, &nbytes) != 0)
	   _cput_str("Text and attrs not successfully saved!");
	   ...
	}

Inline Assembly Example
	#include <console.h>
	{
	   char *workbuf, *str;
	   int handle;
	   	  ... /* open up a file for saving screen */
	   	  workbuf = (char *)malloc(4000);
	   	  mov bx,handle
	   	  mov si,workbuf
	   	  mov cx,256
	   	  lseekbof();
	   	  xor dx,dx    /* origin 0,0 */
	   	  mov ah,10    /* AH = number of rows */
	   	  mov al,80    /* AL = number of cols */
	   	  hread_textattr();
	   	   je hrdtxt_010
	   	  str = "Text and attrs not successfully saved!";
	   	  mov si,str
	   	  cput_str();
	hrdtxt_010:
	   	  ...
	}

Source file _CIOHRTX.ASM ASM equiv HREAD_TEXTATTR
See also
_hsave_screen, _hwrite_textattr, _read_textattr

_hrestore_screen


Descrip
Restores a previously saved screen and video state from a specified disk buffer.

Syntax
#include <console.h>
int _hrestore_screen(int handle, void *workbuf, unsigned int wsize, int *nbytes);

Returns
0 if the screen and video state information was successfully.
nbytes the number of bytes successfully read from handle
workbuf undefined

1 if end-of-file was encountered.
nbytes the number of bytes successfully read from handle
workbuf undefined
-1 if an error occurred.
nbytes the number of bytes successfully read from handle
workbuf undefined
e_code error code

Notes
This function restores the current screen and video state. The restored information is read from the file associated with handle at the current file pointer position. nbytes is returned with the actual number of bytes read and restored from handle; the file pointer is advanced past the restored information. workbuf is used to buffer the reads and is left in an undefined state. 0 is returned if the operation was successful. 1 is returned if end-of-file was encountered. If an error occurred, -1 is returned and the error code is returned in e_code. Only the state and contents of the active screen are affected if the virtual screen system is active.

The size of the work buffer (wsize) must be at least equal to twice the number of screen columns in the new video state. The -1 condition is returned and e_code is set to E_INSMEM if this requirement is not satisfied. Because 132 column text modes are common, the recommended minimum value for wsize is 264 bytes (2x132=264).

Only the specified display adapter and screen dimensions in the saved video state are checked before the video state is restored. If either of these values is invalid, -1 is returned and e_code is set to E_INVDATA. All other values are assumed to be legal. The results are undefined if the specified video mode or video display page is not supported by the indicated display adapter.

The restored video state includes the current display adapter, video refresh state, video mode, active video page, screen dimensions, cursor shape and state, cursor position, blink/high-intensity mode, border color and state, and current and default text attributes. This information is usually saved by a prior call to _hsave_screen. See the _hsave_screen reference section entry for a description of the required format for the saved video state and screen information.

The video state can never be "partially" restored, though the screen contents can be if an error occurs. If the return value is non-zero, nbytes may be checked to determine if the video state was successfully restored or not. A non-zero nbytes indicates that the video state was restored; if nbytes is zero then the state was not restored. If the return value is non-zero and nbytes is non-zero, _clr_region should probably be called to blank the screen before continuing.

This function automatically calls _console_init to re-initialize the console I/O system when the screen state is restored.

_console_init must be called before this function may be used.

WARNING! This function leaves the windowing system in an undefined state. To preserve the condition of the windowing system, call _win_suspend just before calling this function. The state of the windowing system may then be restored at a later point by calling _win_resume.

C/C++ Example
	{
	   char *workbuf;
	   int nbytes, handle;
	   ...
	   workbuf = (char *)malloc(256);
	   _lseekbof(handle);
	   if (_hrestore_screen(handle, workbuf, 256, &nbytes) != 0)
	   _cput_str("Error restoring screen and video state!");
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char *workbuf, *str;
	   int handle;
	   ... 	 /* open up a file for saving screen */
	   workbuf = (char *)malloc(256);
	   mov bx,handle
	   mov si,workbuf
	   mov cx,256
	   lseekbof();
	   hrestore_screen();
	    je hrsscr_010
	   str = "Error restoring screen and video!";
	   mov si,str
	   cput_str();
	hrsscr_010:
	   ...
	}

Source file _CIOHRSC.ASM ASM equiv HRESTORE_SCREEN
See also
_hsave_screen, _hwrite_textattr, _restore_screen, _restore_vstate

_hsave_screen


Descrip
Saves the current screen and video state to a specified disk buffer.

Syntax
#include <console.h>
int _hsave_screen(int handle, void *workbuf, unsigned int wsize, int *nbytes);

Returns
0 if the screen and video state information was successfully saved.
nbytes the number of bytes written to handle
workbuf undefined

1 if end-of-file was encountered.
nbytes the number of bytes written to handle
workbuf undefined

-1 if an error occurred.
nbytes the number of bytes written to handle
workbuf undefined
e_code error code

Notes
This function saves the current screen and video state. The saved information is written to the file associated with handle at the current file pointer position. nbytes is returned with the actual number of bytes written to handle; the file pointer is advanced past the written information. workbuf is used to buffer the writes and is left in an undefined state. 0 is returned if the operation was successful. 1 is returned if a disk full condition was encountered. If any other error occurred, -1 is returned and an error code is returned in e_code. Only the active screen is saved if the virtual screen system is active.

The size of the work buffer (wsize) must be at least equal to twice the number of screen columns in the current text display mode. -1 is returned and e_code is set to E_INSMEM if this requirement is not satisfied. Because 132 column text modes are common, the recommended minimum value for wsize is 264 bytes (2x132=264).

The saved video state includes the current display adapter, video refresh state, video mode, active video page, screen dimensions, cursor shape and state, cursor position, blink/high-intensity mode, border color and state, and current and default text attributes. The video border is assumed to be off if the border color and state cannot be determined due to the display adapter type (e.g., CGA).

The video state is the first information saved (it is written as a structure of type vstat, defined in CONSOLE.H). The screen information is then written (as character, attribute pairs) starting at the first even offset within the buffer after the vstat structure.

The size of the required disk buffer depends on the current screen dimensions and may be obtained by calling the _screen_bufsize function. However, disk buffers are usually allocated at a fixed size of 16K to accommodate 132-column text video modes (132x60x2=15840 bytes). Standard 80x25 screens can easily be saved in 4K buffers.

_console_init must be called before this function may be used.

WARNING! This function is intended for text-mode use only. It assumes that the screen is currently in a non-graphics video mode. The results are undefined if this function is used under any other circumstances.
WARNING! If the windowing system is active when this function is called, the active window must be STDWIN or the results are undefined.

C/C++ Example
	#include<console.h>
	{
	   char *workbuf;
	   int nbytes, handle;
	   ...
	   workbuf = (char *)malloc(256);
	   _lseekbof(handle);
	   if(_hsave_screen(handle, workbuf, 256, &nbytes) != 0)
	   _cput_str("Screen and video state not successfully saved!");
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char *workbuf, *str;
	   int handle;
	   ... 	 	/* open up a file */
	   workbuf = (char *)malloc(256);
	   mov bx,handle
	   mov si,workbuf
	   mov cx,256
	   lseekbof();
	   hsave_screen();
	    je hsvscr_010
	   str = "Screen and video state not successfully saved!";
	   mov si,str
	   cput_str();
	hsvscr_010:
	   ...
	}

Source file _CIOHSSC.ASM ASM equiv HSAVE_SCREEN
See also
_hread_textattr, _hrestore_screen, _save_screen, _save_vstate

_hwrite_textattr


Descrip
Copies text and attributes to a specified display region from a disk buffer.

Syntax
#include <console.h>
int _hwrite_textattr(int handle, void *workbuf, unsigned int wsize, char top, char left, char height, char width, int *nbytes);

Returns
0 if the text and attributes were successfully written to the display region from the disk buffer.
nbytes the number of bytes read from handle
workbuf undefined

1 if end-of-file was encountered.
nbytes the number of bytes read from handle
workbuf undefined

-1 if an error occurred.
nbytes the number of bytes read from handle
workbuf undefined
e_code error code

Notes
This function writes text and attributes to the display region located at top and left, where top and left are origin 0 positions relative to the upper left corner of the active window (or the screen if windowing is not in effect). The text and attributes are read from the file associated with handle at the current file pointer position; the file pointer is advanced past any information which is read. workbuf is used to buffer the file I/O and is left in an undefined state. nbytes is returned with the actual number of bytes read from handle. 0 is returned if the operation was successful. 1 is returned if end-of-file was encountered. If an error occurred, -1 is returned and an error code is returned in e_code. Text and attributes are written to the active screen if the virtual screen system is active.

A maximum of height rows and width characters per row are written to the display. If the destination region extends beyond the boundaries of the screen or window, then only those characters are copied which fit on the screen or the active window. Only the data is copied which is actually present in the disk buffer if it contains fewer than height rows or width columns of data. Character/attribute pairs are written to the display using BIOS calls or directly from video memory depending on the state of the direct_video variable.

The size of the work buffer (wsize) must be at least equal to twice the value of width. -1 is returned and e_code is set to E_INSMEM if this requirement is not satisfied.

The display region may be partially written or not written at all if an error occurs. If the return value is non-
zero, nbytes may be checked to determine if the display region has been modified. A non-zero nbytes indicates that the region was partially written; if nbytes is zero then the display region is unchanged. If the return value is non-
zero and nbytes is non-zero, _set_region should probably be called followed by _region_on and _clr_region to blank the partially updated display region before continuing.

Text and attributes in the disk buffer must be stored as character/attribute pairs (character followed by attribute). In addition, these character/attribute pairs must be preceded by the actual size of the display region from which they were read. This is the same format supported by _hread_textattr, as follows:

char buf_width; /* width of each row */
char buf_height;/* number of rows */
int buf_charattr[];/* character/attribute pairs, attr in high (2nd) byte,
size = buf_height x buf_width */

_console_init must be called before this function may be used.

C/C++ Example
	#include<console.h>
	{
	   char top, left, height, width;
	   char *workbuf;
	   int nbytes, handle;
	   ...
	   workbuf = (char *)malloc(260);
	   _lseekbof(handle);
	   if(_hwrite_textattr(handle, workbuf, 260, 0, 0, 10,
	      80, &nbytes) != 0)
	      _cput_str("Text and attrs not successfully\
	   	     written to display!");
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char *workbuf, *str;
	   int handle;
	   ...   /* open up a file for saving screen */
	   workbuf = (char *)malloc(4000);
	   mov bx,handle
	   mov si,workbuf
	   mov cx,256
	   lseekbof();
	   xor dx,dx	/* origin 0,0 */
	   mov ah,10	/* AH = number of rows */
	   mov al,80	/* AL = number of cols */
	   hwrite_textattr();
	    je hwrtxt_010
	   str = "Text and attrs not written to display!";
	   mov si,str
	   cput_str();
	hwrtxt_010:
	   ...
	}

Source file _CIOHWTX.ASM ASM equiv HWRITE_TEXTATTR
See also
_hread_textattr, _hrestore_screen, _write_textattr

_ins_line


Descrip
Inserts a blank line in the current clipping region.

Syntax
#include <console.h>
void _ins_line(void);
Returns
None

Notes
This function inserts a blank line into the current clipping region at the current cursor position. All lines below the new blank line are scrolled down and the bottom line in the clipping region is scrolled out of the region and disappears. The new line is filled with space characters in the default attribute. The cursor position remains unchanged. If the line containing the cursor lies below the bottom of the clipping region, this function has no effect. If the clipping region is currently disabled, these actions take place within the boundaries of the screen (or within the active window if windowing is in effect). This function is performed using BIOS calls or by direct manipulation of video memory depending on the state of the direct_video variable.

_console_init must be called before using this function.

C/C++ Example
	   _ins_line();

Inline Assembly Example
	(C Interface Recommended)

Source file CIOINSL.ASM ASM equiv INS_LINE
See also
_del_line, _scroll_down, _scroll_up

_is_cga


Descrip
Indicates whether or not the active display adapter is CGA compatible.

Syntax
#include <console.h>
int _is_cga(void);

Returns
1 if the active display adapter is CGA compatible.

0 if the active display adapter is not CGA compatible.

Notes
This function determines whether or not the active display adapter is a Color Graphics Adapter or a compatible adapter. 1 is returned if the active adapter is a CGA, EGA, MCGA, or VGA adapter. 0 is returned if the active adapter is a MDA.

_console_init must be called before using this function. To determine adapter type without calling _console_init, use _get_adapter.

C/C++ Example
	   if (_is_cga)	/* is this a CGA compatible? */
	      _cput_str("Adapter is CGA compatible");
	   else
	      _cput_str("Adapter is not CGA compatible");
	   ...

Inline Assembly Example
	#include <inline.h>
	{
	   char yes_cga[] = "Adapter is CGA compatible";
	   char not_cga[] = "Adapter is not CGA compatible";
	   ...
	   is_cga();	/* is adapter CGA compatible? */
	    jnecga_100	    /*   n: display "not" string */
	   lea si,yes_cga/* SI = offset of is_cga */
	   jmp short cga_200/* continue w/o exiting */

	cga_100:
	   lea si,not_cga/* SI = offset of not_cga */
	cga_200:
	cput_str();	 /* display message string */
	...
	}

Source file _CIOICGA.ASM ASM equiv IS_CGA
See also
adapter_type, _get_adapter, _get_adapter, _get_adaptinfo

_is_ega


Descrip
Indicates whether or not the active display adapter is EGA compatible.

Syntax
#include <console.h>
int _is_ega(void);

Returns
1 if the active display adapter is EGA compatible.

0 if the active display adapter is not EGA compatible.

Notes
This function determines whether or not the active display adapter is an Enhanced Graphics Adapter or a compatible adapter. 1 is returned if the active display adapter is an EGA or VGA. 0 is returned if the active display adapter is a MDA, CGA, or MCGA.

_console_init must be called before using this function. To determine adapter type without calling _console_init, use _get_adapter.

C/C++ Example
	{
	   if (_is_ega)/* is adapter EGA or VGA? */
	      _cput_str("Adapter is EGA compatible");
	   else
	      _cput_str("Adapter is not EGA compatible");
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char yes_ega[] = "Adapter is EGA compatible";
	   char not_ega[] = "Adapter is not EGA compatible";
	   ...
	   is_ega();	/* is adapter EGA or VGA? */
	    jnelabel_100/*   n: display "not" string */
	   lea si,yes_ega/* SI = offset of is_ega */
	   cput_str();	/* display string */
	   jmp short label_200/* continue (compatible) */

	label_100:
	   lea si,not_ega/* SI = offset of not_ega */
	   cput_str();	/* display string */
	   exit(0);	/* exit (incompatible) */
	label_200:
	   ...
	}

Source file _CIOIEGA.ASM ASM equiv IS_EGA
See also
adapter_type, _get_adapter, _get_adapter, _get_adaptinfo

_is_enkbd


Descrip
Determines whether or not the attached keyboard is an enhanced keyboard.

Syntax
#include <console.h>
int _is_enkbd(void);

Returns
1 if the attached keyboard is an enhanced keyboard.

0 if the attached keyboard is not an enhanced keyboard.

Notes
This function determines whether or not the attached keyboard is an enhanced keyboard. Enhanced keyboards return additional key codes for key combinations which are not available on non-enhanced keyboards.

C/C++ Example
	   ...
	   if (_is_enkbd)/* enhanced keyboard? */
	      _cput_str("Keyboard is an enhanced keyboard");
	   else
	      _cput_str("Keyboard is not an enhanced keyboard");
	   ...

Inline Assembly Example
	#include <inline.h>
	{
	   ...
	   is_enkbd();	/* enhanced keyboard? */
	    jnelabel_100/*   n: normal keyboard */
	   /* ... enhanced keyboard routines ...*/
	   jmp short label_200/* when done jump to label_200 */

	label_100:
	   	  /* ... normal keyboard routines ...*/
	label_200:
	   ... /* continue execution here... */
	}

Source file _CIOINKB.ASM ASM equiv IS_ENKBD
See also
_kbd_init, kbd_type

_is_mcga


Descrip
Indicates whether or not the active display adapter is MCGA compatible.

Syntax
#include <console.h>
int _is_mcga(void);

Returns
1 if the active display adapter is MCGA compatible.

0 if the active display adapter is not MCGA compatible.

Notes
This function determines whether or not the active display adapter is a Multi-color Graphics Array or a compatible adapter. 1 is returned if the active display adapter is a MCGA. 0 is returned if the active display adapter is a MDA, CGA, EGA, or VGA.

_console_init must be called before using this function. To determine adapter type without calling _console_init, use _get_adapter.

C/C++ Example
	   if (_is_mcga())/* is adapter MCGA? */
	      _cput_str("Adapter is MCGA compatible");
	   else
	      _cput_str("Adapter is not MCGA compatible");
	   ...

Inline Assembly Example
	#include <inline.h>
	{
	   char *str;
	   ...
	   is_mcga();	/* is adapter MCGA? */
	    jnelabel_100/*   y: display next string */
	   str = "Adapter is MCGA compatible";
	   mov si,str	/* DS:SI -> str */
	   cput_str();
	   jmp short label_out/* continue (compatible) */

	label_100:	 	/* if jumped here, not MCGA? */
	   str = "Adapter is not MCGA compatible";
	   mov si,str	/* DS:SI -> str */
	   cput_str();	/* display string */
	   exit(0);	/* exit (incompatible) */
	label_out:
	   ...
	}

Source file _CIOIMCG.ASM ASM equiv IS_MCGA
See also
adapter_type, _get_adapter, _get_adapter, _get_adaptinfo

_is_mda


Descrip
Indicates whether or not the active display adapter is MDA compatible.

Syntax
#include <console.h>
int _is_mda(void);

Returns
1 if the active display adapter is MDA compatible.

0 if the active display adapter is not MDA compatible.

Notes
This function determines whether or not the active display adapter is a Monochrome Display Adapter or a compatible adapter. 1 is returned if the active display adapter is a MDA. 0 is returned if the active display adapter is a CGA, EGA, MCGA, or VGA.

_console_init must be called before using this function. To determine adapter type without calling _console_init, use _get_adapter.

C/C++ Example
	   if (_is_mda)	/* is adapter MDA? */
	      _cput_str("Adapter is MDA compatible");
	   else
	      _cput_str("Adapter is not MDA compatible");
	   ...

Inline Assembly Example
	#include <inline.h>
	{
	   char *str;
	   ...
	   is_mda();	/* is adapter MDA? */
	    jne label_100	/*   n: display "not" string */
	   str = "Adapter is MDA compatible";
	   mov si,str	/* DS:SI -> str */
	   cput_str();
	   jmp short label_200/* continue (compatible) */

	label_100:
	   str = "Adapter is not MDA compatible";
	   mov si,str	/* DS:SI -> str */
	   cput_str();
	   exit(0);	/* exit (incompatible) */

	label_200:	 	/* continue execution here... */
	   ...
	}

Source file _CIOIMDA.ASM ASM equiv IS_MDA
See also
adapter_type, _get_adapter, _get_adapter, _get_adaptinfo

_is_textmode


Descrip
Determines if the current video mode is a text (non-graphics) mode.

Syntax
#include <console.h>
int _is_textmode(void);

Returns
1 if the current video mode is a text mode.

0 if the current video mode is a graphics mode.

Notes
This function determines if the current video display mode on the physically active system adapter is an alphanumeric text mode. All text modes are successfully identified on most adapters, including nonstandard, extended text modes (e.g., mode 0x54 on a Paradise VGA adapter is correctly identified as a text mode).
This function does not depend on _console_init or _adapter_init and is not virtual screen aware. It is intended primarily for use within TSRs to determine if the console I/O system is safe to use.

C/C++ Example
	{
	   ...
	   if(textmode())
	   _cput_str("Display mode is in text mode.");
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char str[] = "Display mode is in text mode.";
	   ...
	   textmode();	/* in textmode? */
	    jnetxtmode_010/*   n: non-text mode */
	      leasi,str
	   cput_str();	/* display string */
	txtmode_010:
	   ...
	}

Source file _CIOISTX.ASM ASM equiv IS_TEXTMODE
See also
_get_adaptinfo, _get_vmode

_is_vga


Descrip
Indicates whether or not the active display adapter is VGA compatible.

Syntax
#include <console.h>
int _is_vga(void);

Returns
1 if the active display adapter is VGA compatible.

0 if the active display adapter is not VGA compatible.

Notes
This function determines whether or not the active display adapter is a Video Graphics Array or a compatible adapter. 1 is returned if the active display adapter is a VGA. 0 is returned if the active display adapter is a MDA, CGA, EGA, or MCGA.

_console_init must be called before using this function. To determine adapter type without calling _console_init, use _get_adapter.

C/C++ Example
	   if (_is_vga)
	      _cput_str("Adapter is VGA compatible");
	   else
	      _cput_str("Adapter is not VGA compatible");
	   ...

Inline Assembly Example
	#include <inline.h>
	{
	   char *str;
	   ...
	   is_vga();	/* is adapter VGA? */
	    jnelabel_err/*   n: exit with errmsg */
	     ... continue with program ...
	   jmp label_ok/* jump to quit when finished */

	label_err:
	   str = "Incompatible adapter, requires VGA adapter.";
	   mov si,str	/* SI = offset of message */
	   cput_str();	/* display err message */
	label_ok:
	   exit(0);

	}

Source file _CIOIVGA.ASM ASM equiv IS_VGA
See also
adapter_type, _get_adapter, _get_adapter, _get_adaptinfo

_kbd_init


Descrip
Initializes the Console I/O system for enhanced keyboard support if an enhanced keyboard is present.

Syntax
#include <console.h>
void _kbd_init(void);

Returns
None

Notes
This function determines the type of keyboard present and initializes the kbd_type variable so Console I/O keyboard functions will support an enhanced keyboard if one is present.

The following symbolic constants (defined in CONSOLE.H) represent the possible values of kbd_type:

ENHANCED_KBD (0x10) Enhanced keyboard is present
STANDARD_KBD (0x00) Standard (non-enhanced) keyboard is present

The use of this function is optional. If it is not called, the Console I/O keyboard functions assume that a standard (non-enhanced) keyboard is present and enhanced key codes will not be supported. This same effect may be achieved after _kbd_init has been called by setting kbd_type to 0x00.

C/C++ Example
	   _console_init();/* initialize SA console I/O */
	   _kbd_init();
	   if (kbd_type == ENHANCED_KBD)
	      _cput_str("Enhanced keyboard present.");
	   else 
	      _cput_str("Normal keyboard detected.");
	   ...

Inline Assembly Example
	#include <inline.h>
	{
	   char *str;
	   console_init();
	   kbd_init();
	   cmp 	 kbd_type,ENHANCED_KBD
	    jne
	   str = "Enhanced keyboard present.";
	   jmp 	 label_020

	label_010:
	   str = "Normal keyboard detected.";
	label_020:
	   mov 	 si,str
	   put_str();
	   ...
	}

Source file CIOKINIT.ASM ASM equiv KBD_INIT
See also
kbd_type

kbd_type


Descrip
(Variable) Indicates the type of keyboard detected by _kbd_init.

Syntax
#include <console.h>
extern char kbd_type;

Notes
This char variable indicates whether or not an enhanced keyboard is present. It is initialized when _kbd_init is called. If this variable indicates that an enhanced keyboard is present, the Console I/O keyboard functions will support the enhanced keyboard. Enhanced keyboard support can be disabled or enabled any time after _kbd_init has been called by changing the value of this variable.

The following symbolic constants (defined in CONSOLE.H) represent the possible values of kbd_type:

ENHANCED_KBD(0x10) Enhanced keyboard is present
STANDARD_KBD(0x00) Standard (non-enhanced) keyboard is present

Source file CIOKVAR.ASM ASM equivâ
See also
_is_enkbd, _kbd_init

monitor_type


Descrip
(Variable) Indicates the type of monitor attached to the active display adapter.

Syntax
#include <console.h>
extern char monitor_type

Notes
This char variable indicates the type of physical display attached to the active display adapter. If the virtual screen system is in use, monitor_type indicates the type of monitor attached to the display adapter of the active screen.

monitor_type may be equal to any of the following values (these symbolic constants are defined in CONSOLE.H):

MONO(0x00) Digital monochrome display
RGB (0x01) RGB color display (200 scan lines)
ECD_LO(0x02) Enhanced color display (200 scan lines)
ECD_HI(0x03) Enhanced color display (350 scan lines)
ACOLOR(0x04) Analog color display (variable scan lines)
AMONO(0x05) Analog monochrome display

This variable is initialized by _console_init.

Source file CIOCVAR.ASM ASM equivâ
See also
_adapter_init, _get_adapter

_move_back


Descrip
Moves the cursor once in the direction opposite the current cursor advance direction.

Syntax
#include <console.h>
void _move_back(void);

Returns
None

Notes
This function moves the cursor once in the direction opposite the direction last specified by _set_direction or any of the _direc_... functions. For example, if the current cursor advance direction were ADV_RIGHT, this function would move the cursor one column to the left. If the cursor is positioned beyond the boundaries of the current clipping region or screen (or window if windowing is in effect), the cursor becomes invisible.

_console_init must be called before using this function.

C/C++ Example
	{
	   int i;
	   char ch;
	   ch = 'a';

	   for(i=0; i < 26; i++)/* do alphabet in same space */
	   {
	      _cput_chr(ch);
	      _sleep_sec(5);/* sleep between letters */
	      _move_back();
	      _sleep_sec(100);
	   }
	   ...
	}

Inline Assembly Example
	(C Interface Recommended)

Source file CIOMBACK.ASM ASM equiv MOVE_BACK

_move_down


Descrip
Moves the cursor down one row.

Syntax
#include <console.h>
void _move_down(void);
Returns
None

Notes
This function moves the cursor down one row. If the cursor is positioned beyond the boundaries of the current clipping region or screen (or window if windowing is in effect), the cursor becomes invisible.

_console_init must be called before using this function.

C/C++ Example
	   _move_down();

Inline Assembly Example
	(C Interface Recommended)

Source file CIOMDOWN.ASM ASM equiv MOVE_DOWN

_move_left


Descrip
Moves the cursor left one column.

Syntax
#include <console.h>
void _move_left(void);

Returns
None

Notes
This function moves the cursor one column to the left. If the cursor is positioned beyond the boundaries of the current clipping region or screen (or window if windowing is in effect), the cursor becomes invisible.

_console_init must be called before using this function.

C/C++ Example
	   _move_left();

Inline Assembly Example
	   move_left();

Source file CIOMLEFT.ASM ASM equiv MOVE_LEFT

_move_next


Descrip
Moves the cursor once in the current cursor advance direction.

Syntax
#include <console.h>
void _move_next(void);

Returns
None

Notes
This function moves the cursor once in the direction last specified by _set_direction or any of the _direc_... functions. For example, if the current cursor advance direction were ADV_RIGHT, this function would move the cursor one column to the right. If the cursor is positioned beyond the boundaries of the current clipping region or screen (or window if windowing is in effect), the cursor becomes invisible.

_console_init must be called before using this function.

C/C++ Example
	   _move_next();

Inline Assembly Example
	   move_next();

Source file CIOMNEXT.ASM ASM equiv MOVE_NEXT

_move_right


Descrip
Moves the cursor right one column.

Syntax
#include <console.h>
void _move_right(void);

Returns
None

Notes
This function moves the cursor one column to the right. If the cursor is positioned beyond the boundaries of the current clipping region or screen (or window if windowing is in effect), the cursor becomes invisible.

_console_init must be called before using this function.

C/C++ Example
	   _move_right();

Inline Assembly Example
	   move_right();

Source file CIOMRGHT.ASM ASM equiv MOVE_RIGHT

_move_textattr


Descrip
Moves text and attributes from one display region to another display region.

Syntax
#include <console.h>
void _move_textattr(int srcleft, int srctop, int wdth, int hght, int dstleft, int dsttop);

Returns
None

Notes
This function copies text and attributes from the display region located at srctop and srcleft to the display region located at dsttop and dstleft, where srctop and dsttop are origin 0 row numbers and srcleft and dstleft are origin 0 column numbers relative to the upper left-hand corner of the active window (or the screen if windowing is not in effect). A maximum of hght rows and wdth characters per row are copied. If the source or destination region extends beyond the boundaries of the screen (or the active window if windowing is in effect), only those characters are copied which are actually on the screen (or within the window). Character/attribute pairs are written to the display through BIOS calls or directly to video memory depending on the state of the direct_video variable.

_console_init must be called before using this function.

C/C++ Example
	   _move_textattr(0,0,40,25,40,0);
	   /* move left half of screen to right half */

Inline Assembly Example
	#include <inline.h>
	   ...
	   mov dl,0	/* DL = srcleft */
	mov dh,0	 /* DH = srctop */
	    mov al,40	 /* AL = width */
	    mov ah,25	 /* AH = height */
	    mov bl,40	 /* BL = dstleft */
	    mov bh,0	 /* BH = dsttop */
	    move_textattr();
	    ...

Source file _CIOMTXT.ASM ASM equiv MOVE_TEXTATTR
See also
direct_video, _read_textattr, _write_textattr

_move_up


Descrip
Moves the cursor up one row.

Syntax
#include <console.h>
void _move_up(void);

Returns
None

Notes
This function moves the cursor up one row. If the cursor is positioned beyond the boundaries of the current clipping region or screen (or window if windowing is in effect), the cursor becomes invisible.

_console_init must be called before using this function.

C/C++ Example
	   _move_up();

Inline Assembly Example
	#include <inline.h>
	   move_up();

Source file CIOMUP.ASM ASM equiv MOVE_UP

_read_textattr


Descrip
Copies text and attributes from a specified display region to a specified buffer.

Syntax
#include <console.h>
void _read_textattr(int srcleft, int srctop, int wdth, int hght, void far *buffer);

Returns
No return value.
buffer text and attributes read from the screen

Notes
This function reads text and attributes from the display region located at srctop and srcleft and places them in buffer, where srctop and srcleft are origin 0 positions relative to the upper left-hand corner of the active window (or the screen if windowing is not in effect). A maximum of hght rows and wdth characters per row are copied. If the source region extends beyond the boundaries of the screen (or the active window if windowing is in effect), only those characters are copied which are actually on the screen (or within the window). Character/attribute pairs are read from the display through BIOS calls or directly from video memory depending on the state of the direct_video variable.

On return, buffer contains the width of the region, the height of the region, and character/attribute pairs (character followed by attribute), in the following format:

char buf_width; /* width of each row */
char buf_height;/* number of rows */
int buf_charattr[];/* character/attribute pairs, attr in high (2nd) byte,
size = buf_height x buf_width */

The number of char/attribute pairs stored in buffer may be calculated by multiplying the width and height values returned in buffer. Note that these values may not be the same as wdth and hght; if the source region extends beyond the edge of the window (or screen), the returned width and height only indicate the extent of the clipped region. buffer must be large enough to hold all of the transferred data (at least wdth*hght+2 bytes in size) or information following buffer will be overwritten.

_console_init must be called before using this function.

C/C++ Example
	{
	   void *buffer;
	   if ((buffer = (char *) malloc(2100)) == NULL)
	      exit(1);/* allocate 2*(width * height) */
	   _read_textattr(0,0,40,25,buffer);/* read left half of 
	   	  	 	    screen to buffer */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   void *buffer;
	   ...
	   if ((buffer = (char *) malloc(2100)) == NULL)
	       exit(1);
	   mov di,buffer/* DI = offset of dest buffer */
	   mov dl,0	/* DL = srcleft */
	   mov dh,0	/* DH = srctop */
	   mov al,40	/* AL = width */
	   mov ah,25	/* AH = height */
	   read_textattr();
	   ...
	}

Source file _CIORTXT.ASM ASM equiv READ_TEXTATTR
See also
_hread_textattr, _move_textattr, _save_screen, _write_textattr

_region_off


Descrip
Disables the current clipping region.

Syntax
#include <console.h>
void _region_off(void);

Returns
None

Notes
This function disables the current clipping region. If the clipping region is currently enabled, the region is disabled and the cursor returns to the position it occupied at the time the region was originally enabled. The cursor position remains unchanged if the clipping region is currently disabled. The display always remains unchanged.
When the clipping region is disabled, all cursor positioning is relative to the upper left-hand corner of the screen (or the active window if windowing is in effect), and output from the _cput_... and echoed _cget_... functions is allowed anywhere within the boundaries of the screen (or window).

_console_init must be called before using this function.

C/C++ Example
	   _region_off();

Inline Assembly Example
	   region_off();

Source file CIOREG.ASM ASM equiv REGION_OFF
See also
_region_on

_region_on


Descrip
Enables the current clipping region.

Syntax
#include <console.h>
void _region_on(void);

Returns
None

Notes
This function activates the most recently-defined clipping region and moves the cursor to the upper left-hand corner of the region. The display is not affected in any other way. When the clipping region is active, all cursor positioning is relative to the upper left-hand corner of the region, and all output from the _cput_... and echoed _cget_... functions is restricted to the clipping region. The cursor becomes invisible if it is moved outside of this region.

_console_init must be called before using this function.

C/C++ Example
	   _region_on();

Inline Assembly Example
	   region_on();

Source file CIOREG.ASM ASM equiv REGION_ON
See also
_get_region, _region_off, _set_region

_rel_xy


Descrip
Moves the cursor a specified distance relative to its current position.

Syntax
#include <console.h>
void _rel_xy(int xdist, int ydist);

Returns
None

Notes
This function adjusts the position of the cursor on the horizontal axis by xdist and on the vertical axis by ydist. The movement takes place relative to the original cursor position. Negative values are interpreted as left and upward motion; positive values are interpreted as right and downward motion. If the cursor is positioned beyond the boundaries of the current clipping region or screen (or window if windowing is in effect), the cursor becomes invisible.

_console_init must be called before using this function.

C/C++ Example
	   _rel_xy(15,15); /* move cursor 15 rows and 15 cols
	   	  	  from current position */

Inline Assembly Example
	#include <inline.h>
	{
	   int xdist = ydist = 15;
	   ...
	   mov al,xdist/* AL = xdist */
	   mov ah,ydist/* AH = ydist */
	   rel_xy();	/* 15 rows and 15 cols relative
	   	  	 	   to current position */
	   ...
	}

Source file _CIORXY.ASM ASM equiv REL_XY
See also
_goto_x

_reset_attr


Descrip
Resets the current text attribute and attribute flags.

Syntax
#include <console.h>
void _reset_attr(void);

Returns
None

Notes
This function resets the current text attribute to the default text attribute. It also turns bold, blink, and high intensity background (BKBOLD) off by resetting all of the attribute flags.

The current text attribute is the base attribute used by the _cput_... functions when displaying characters; this value is bitwise ORed with the current attribute flags to produce the actual display attribute used to display all characters.

_console_init must be called before using this function.

C/C++ Example
	   _reset_attr();

Inline Assembly Example
	   reset_attr();

Source file CIORATR.ASM ASM equiv RESET_ATTR
See also
_set_attr

_restore_screen


Descrip
Restores a previously saved screen and video state.

Syntax
#include <console.h>
int _restore_screen(void far *buffer);

Returns
0 if the screen was successfully restored.

-1 if the saved video state is invalid.

Notes
This function restores the last screen and video state saved in buffer by _save_screen. The restored information includes the entire contents of the screen (characters and attributes), current display adapter, video refresh state, video mode, active video page, screen dimensions, cursor shape and state, cursor position, blink/high-intensity mode, border color and state, and current and default text attributes. The video border is turned off if the border color and state could not be determined due to the display adapter type (e.g., CGA).

0 is returned if the function was successful; -1 is returned only if the adapter type in the saved video state is invalid. The results are undefined if the specific video display page is not supported by the indicated display adapter.

_console_init and _save_screen must be called before using this function. This function calls _console_init.

WARNING! This function leaves the windowing system in an undefined state. To preserve the condition of the windowing system, call _win_suspend just before calling this function. The state of the windowing system may then be restored at a later point by calling _win_resume.

C/C++ Example
	{
	   void *buffer;
	   scrbuf_addr = malloc(_screen_bufsize());
	   _save_screen(buffer);
	   _restore_screen (buffer);
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   void *scrbuf_addr;	/* global near/far pointer */
	   ...
	   scrbuf_addr = malloc (_screen_bufsize());
	   mov di,scrbuf_addr /* DI = offset of buffer */
	IF __LARGE_DATA__
	   mov es,word ptr scrbuf_addr+2
	ENDIF
	   save_screen():	
	   ...
	IF __LARGE_DATA__
	   mov es,word ptr scrbuf_addr+2
	ENDIF
	   mov di,scrbuf_addr /* DI = offset of buffer */
	   restore_screen();
	   ...
	}

Source file _CIOSCR.ASM ASM equiv RESTORE_SCREEN
See also
_hrestore_screen, _save_screen, _save_vstate, _write_textattr

_restore_vstate


Descrip
Restores a previously-saved video state.

Syntax
#include <console.h>
void _restore_vstate(void);

Returns
None

Notes
This function restores the last video state saved by _save_vstate, fills the screen with space characters in the original attribute, and moves the cursor to the upper left-hand corner of the screen. The restored video state includes the current display adapter, video refresh state, video mode, active video page, screen dimensions, cursor shape and state, blink/high-intensity mode, border color and state, and current and default text attributes. The video border is turned off if the border color and state could not be determined due to the display adapter type (e.g., CGA).

_console_init and _save_vstate must be called before using this function. This function calls _console_init.

WARNING! This function leaves the windowing system in an undefined state. To preserve the condition of the windowing system, call _win_suspend just before calling this function. The state of the windowing system may then be restored at a later point by calling _win_resume.

C/C++ Example
	   _restore_vstate(); /* restore previously saved video state */

Inline Assembly Example
	   restore_vstate(); /* restore previously saved vstate */

Source file CIOVST.ASM ASM equiv RESTORE_VSTATE
See also
_get_vstate, _save_screen, _save_vstate

_save_screen


Descrip
Saves the current screen and video state.

Syntax
#include <console.h>
void _save_screen(void far *buffer);

Returns
No return value.
buffer video state and screen contents information

Notes
This function saves the current screen and video state in buffer for later restoration by _restore_screen. The saved video state includes the current display adapter, video refresh state, video mode, active video page, screen dimensions, cursor shape and state, cursor position, blink/high-intensity mode, border color and state, and current and default text attributes. The video border is assumed to be off if the border color and state cannot be determined due to the display adapter type (e.g., CGA).

Since the contents of the screen are saved in buffer, the required size of buffer varies. For example, 80x25 mode requires just over 4000 bytes of buffer space, and 80x43 mode requires almost twice as much buffer space. _screen_bufsize should be called prior to calling this function to determine the exact buffer requirements.

_console_init must be called before using this function.

WARNING! This function is intended for text-mode use only. It assumes that the screen is currently in a non-graphics video mode. Use of this function under any other circumstances will produce undefined results.

WARNING! If the windowing system is active when this function is called, the active window must be STDWIN or the results are undefined.

C/C++ Example
	{
	   void *scrbuf_addr;
	   scrbuf_addr = malloc(_screen_bufsize());
	   _save_screen(scrbuf_addr);
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   void *scrbuf_addr;
	   ...
	   scrbuf_addr = malloc(screen_bufsize());
	#if __LARGE_DATA__
	   les di,scrbuf_addr/* ES:DI -> scr buffer */
	#else
	   pushds	 	
	   pop es	 	/* DS=SS (for small models) */ 
	   mov di,scrbuf_addr/* DI = offset of scr buffer */
	#endif
	   save_screen();
	   ...
	}

Source file _CIOSCR.ASM ASM equiv SAVE_SCREEN
See also
_get_vstate, _hsave_screen, _read_textattr, _restore_screen, _save_vstate, _screen_bufsize

_save_vstate


Descrip
Saves the current video state.

Syntax
#include <console.h>
void _save_vstate(void);

Returns
None

Notes
This function saves the current video state for later restoration by _restore_vstate. The saved video state includes the current display adapter, video refresh state, video mode, active video page, screen dimensions, cursor shape and state, blink/high-intensity mode, border color and state, and current and default text attributes. The video border is assumed to be off if the border color and state cannot be determined due to the display adapter type (e.g., CGA).

Note that this function only saves the video state. The screen itself is not saved. If the screen must be saved, use _save_screen.

_console_init must be called before using this function.

WARNING! This function is intended for text-mode use only. It assumes that the screen is currently in a non-graphics video mode. Use of this function under any other circumstances will produce undefined results.

WARNING! If the windowing system is active when this function is called, the active window must be STDWIN or the results are undefined.

C/C++ Example
	   _save_vstate();/* save video state */

Inline Assembly Example
	   save_vstate();	/* save video state */

Source file CIOVST.ASM ASM equiv SAVE_VSTATE
See also
_get_vstate, _restore_vstate, _save_screen, _set_vstate

_screen_bufsize


Descrip
Returns the size of the buffer required by _save_screen.

Syntax
#include <console.h>
unsigned int _screen_bufsize(void);

Returns
The number of bytes required by _save_screen to save the screen.

Notes
This function determines the size of the buffer required by _save_screen to save the current screen and video state. The required buffer size is returned.

This function should be used to determine the buffer size requirements of _save_screen any time the exact screen size is not predefined. Note that even if the program is executed from the DOS command line, the system may be operating in a text mode with a nonstandard number of rows or columns (e.g., 80x43 and 132x43 modes are common). Buffer space may be allocated dynamically using _dos_malloc, _near_malloc, _far_malloc, malloc, _dos_allocmem, farmalloc, etc.

_console_init must be called before using this function.

C/C++ Example
	{
	   void *scrbuf_addr;
	   if((scrbuf_addr = malloc(_screen_bufsize())) == NULL)
	      _cput_str("Error allocating screen buffer heap.");
	   /* use heap space to save screen */
	   else
	      _save_screen (scrbuf_addr); /* save the screen */
	   ...
	}

Inline Assembly Example
	(C Interface Recommended)

Source file CIOSCRSZ.ASM ASM equiv SCREEN_BUFSIZE
See also
_hsave_screen, _save_screen

screen_cols


Descrip
(Variable) Indicates the number of columns on the screen.

Syntax
#include <console.h>
extern unsigned char screen_cols;

Notes
This read-only unsigned char variable indicates the width of the screen in the current video mode. The width is specified in columns.

This variable is initialized by _console_init.

Source file CIOCVAR.ASM ASM equivâ
See also
_get_dimens, screen_dimens, _set_dimens

screen_dimens


Descrip
(Variable) Indicates the number of rows and columns on the screen.

Syntax
#include <console.h>
extern unsigned int screen_dimens;

Notes
This read-only unsigned int variable indicates the width and height of the screen in the current video mode. The low byte indicates the width in columns; the high byte indicates the height in rows.

Source file CIOCVAR.ASM ASM equivâ
See also
_get_dimens, screen_cols, screen_rows, _set_dimens

screen_rows


Descrip
(Variable) Indicates the number of rows on the screen.

Syntax
#include <console.h>
extern unsigned char screen_rows;

Notes
This read-only unsigned char variable indicates the height of the screen in the current video mode. The height is specified in rows.

This variable is initialized by _console_init.

Source file CIOCVAR.ASM ASM equivâ
See also
_get_dimens, screen_dimens, _set_dimens

_scroll_down


Descrip
Scrolls the current clipping region down a specified number of lines.

Syntax
#include <console.h>
void _scroll_down(int num);

Returns
None

Notes
This function scrolls all characters and attributes in the current clipping region down num lines. An equal number of lines are scrolled out the top of the clipping region and disappear, and the same number of blank lines in the default attribute are scrolled in at the bottom of the region. The cursor position remains unchanged. If the clipping region is currently disabled, these actions take place within the boundaries of the screen (or within the boundaries of the active window if windowing is in effect). Characters and attributes are written directly to the display through BIOS calls or directly to video memory depending on the state of the direct_video variable.

_console_init must be called before using this function.

C/C++ Example
	   _scroll_down(10);/* scroll down 10 */

Inline Assembly Example
	}
	#include <inline.h>

	   mov al,10/* AL = number of lines to scroll */
	   scroll_down();/* scroll down 10 lines */
	   ...

Source file _CIOSCDN.ASM ASM equiv SCROLL_DOWN
See also
_ins_line, _scroll_up

_scroll_up


Descrip
Scrolls up a specified number of lines.

Syntax
#include <console.h>
void _scroll_up(int num);

Returns
None

Notes
This function scrolls all characters and attributes in the current clipping region up num lines. An equal number of lines are scrolled out the top of the clipping region and disappear, and the same number of blank lines in the default attribute are scrolled in at the bottom of the region. The cursor position remains unchanged. If the clipping region is currently disabled, these actions take place within the boundaries of the screen (or within the boundaries of the active window if windowing is in effect). Characters and attributes are written directly to the display through BIOS calls or directly to video memory depending on the state of the direct_video variable.

_console_init must be called before using this function.

C/C++ Example
	   _scroll_up(10);/* scroll up ten rows */

Inline Assembly Example
	#include <inline.h>

	mov al,10/* AL = number of lines to scroll */
	scroll_up();/* scroll up ten rows */
	...

Source file _CIOSCUP.ASM ASM equiv SCROLL_UP
See also
_ins_line, _scroll_down

_set_80cols


Descrip
Ensures that the display is in an 80+ column text video mode.

Syntax
#include <console.h>
int _set_80cols(void);

Returns
0 if the display was already in an 80+ column mode.

-1 if the display was changed to an 80 column text mode (the screen has been blanked).

Notes
This function analyzes the current video mode and changes it to an appropriate 80 column text mode if the current mode is not an 80 column or better text mode. If a mode change must take place, the screen is blanked, the cursor is moved to the upper left-hand corner, and -1 is returned. Otherwise, the display remains unaffected and 0 is returned. If the current video mode is a black-and-white mode, BW80 is the final mode; if the current video mode is a monochrome mode, MONO is the final mode; otherwise, CO80 is the final mode.

If a mode change is necessary, then this function automatically initializes the console I/O system by calling _console_init.

C/C++ Example
	   if (_set_80cols() == 0)
	      _cput_str("Display was already in 80 column text mode");
	   else
	      _cput_str("Display was changed to 80 column text mode");
	   ...

Inline Assembly Example
	#include <inline.h>
	{
	   char *str;
	   ...
	   set_80cols();	/* ensure 80 col text mode */
	    je label_100/* necessary to change modes? */
	   	  	 	/*   y: display this string */
	   str = "Display was changed to 80 column text mode";
	   mov si,str	/* SI = offset of str */
	   cput_str();	/* display message */

	label_100:
	   ...
	}

Source file _CIOS80.ASM ASM equiv SET_80COLS
See also
_set_vmode

_set_adapter


Descrip
Selects the active display adapter.

Syntax
#include <console.h>
int _set_adapter(int adapter);

Returns
0 if adapter was successfully selected.

-1 if adapter is not present in the system.

Notes
This function manually selects adapter as the active display adapter and re-initializes the console I/O system accordingly. If the indicated adapter type is present in the system, then: 1) it is selected as the active display adapter; 2) page 0 is selected as the active video display page; 3) _console_init is called to re-initialize the console I/O system; and 4) 1 is returned. 0 is returned only if the indicated adapter type is not present. If the virtual screen system is active, this function reassigns the active screen to video display page 0 of the specified adapter without transferring the contents of the screen.

The following symbolic constants (defined in CONSOLE.H) represent the adapter codes which may be specified for adapter:

MDA (0x00) Monochrome Display Adapter
CGA (0x01) Color Graphics Adapter
EGA (0x02) Enhanced Graphics Adapter
MCGA(0x03) Multi-Color Graphics Array
VGA (0x04) Video Graphics Array
ADAPT_2 (0xFE) Secondary (inactive) adapter

Where possible, this function performs adapter switching without issuing BIOS calls. This eliminates the undesirable side effects of BIOS mode changes (including screen blanking, flickering, and color register reprogramming). However, because the initial state of the secondary adapter cannot be determined directly, the console I/O system must make a "best guess" as to the initial state of the secondary adapter. This guess is enforced using a BIOS mode change the first time the secondary adapter is selected by _set_adapter or by the virtual screen system.

_adapter_init must be called before this function may be used.

C/C++ Example
	   ...
	   if(_set_adapter(ADAPT_2) == -1)
	      _cput_str("\n\rUnable to select secondary adapter.");
	   ...

Inline Assembly Example
	#include <inline.h>
	{
	   char str[] = "\n\rUnable to select secondary adapter.";
	   ...
	   mov al,ADAPT_2
	   set_adapter();
	    jncadapt_010
	   lea si,str
	   cput_str();
	adapt_010:
	   ...
	}

Source file _CIOSADP.ASM ASM equiv SET_ADAPTER
See also
adapter_type, _get_adapter, _get_adapter, _get_adaptinfo

_set_attr


Descrip
Sets the current text attribute.

Syntax
#include <console.h>
void _set_attr(int attr);

Returns
None

Notes
This function sets the "current" text attribute to attr. If an attribute table has been specified (using _set_attrtbl), attr is interpreted as an attribute table code and the current attribute is set to the attribute in the table which corresponds to attr. Otherwise, the current attribute is set to attr.

The current text attribute is the base attribute used by the _cput_... and echoed _cget_... functions to display text. It is combined with the current BOLD, BLINK, and BKBOLD attribute flags to produce the actual display attribute.

See the technical notes for detailed information on how to specify attributes.

_console_init must be called before using this function.

C/C++ Example
	   _set_attr(WHITE+(16*BLUE));/* use WHITE on BLUE attr */

Inline Assembly Example
	#include <inline.h>
	   ...
	   mov ah,(WHITE+(16*BLUE))
	   set_attr();	/* select white/blue attr */
	   ...

Source file _CIOSATR.ASM ASM equiv SET_ATTR
See also
_get_attr, _reset_attr, _set_dattr

_set_attrflags


Descrip
Sets the current text attribute flags.

Syntax
#include <console.h>
void _set_attrflags(int flags);

Returns
None

Notes
This function sets the flags which indicate the current bold, blink, and background high intensity states for the current text attribute. These flags determine whether or not the _cput_... functions force displayed text to appear with bold, blinking, or high intensity background attributes.

The following symbolic constants (defined in CONSOLE.H) indicate the various bits which may be set in flags:

BOLD (0x08) bold foreground intensity
BLINK (0x80) blinking text; bold background if blink disabled
BKBOLD (0x80) bold background; blinking text if blink enabled

All other bits in flags are ignored. Note that the BLINK and BKBOLD values are identical. The actual interpretation of the BLINK or BKBOLD bit depends on how the active display adapter has been programmed. If blink is enabled, thebit represents BLINK; otherwise, it represents BKBOLD. The meaning of this bit may be changed by calling _set_blinkmode or _set_bkboldmode.

_console_init must be called before using this function.

C/C++ Example
	   _set_attrflags (BLINK);/* blinking text */
	   _cput_str("Blinking bit set");
	   ...

Inline Assembly Example
	#include <inline.h>
	{
	   char str[] = "Bold bit set";
	   ...
	   mov al,BOLD	    /* AL = BOLD(def in console.h) */
	   set_attrflags();/* set current attr flags */
	   lea si,str	/* SI = offset of str */
	   cput_str();	/* display str */
	   ...
	}

Source file _CIOSATF.ASM ASM equiv SET_ATTRFLAGS
See also
_get_attr

_set_attrtbl


Descrip
Sets the attribute table address.

Syntax
#include <console.h>
void _set_attrtbl(char *table);

Returns
None

Notes
This function sets the attribute table address to table. This immediately affects which attributes are selected or returned by functions which accept attribute values or codes. If -1 is specified for table, the current attribute table address is discarded and no attribute table is used; otherwise, the indicated attribute table is used and all attribute values are treated as attribute codes.

WARNING! When this function is called, the current and default attributes are left in an undefined state. _set_attr and _set_dattr should be used to establish initial values for these attributes after calling this function.

See the technical notes for detailed information on how to specify attributes in attribute tables.

_console_init must be called before using this function.

C/C++ Example
	{
	   char table[] = {0x17, 0x47, 0};
	   	  /* white/blue, white/red, blue/white */ 
	   _set_attrtbl(table);
	   _set_attr(0);/* select white/blue attr */
	   _cput_str("White on Blue characters ");	 
	   
	   ...
	   _set_attrtbl((char *)-1);/* discard this attr table */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char *str;
	   char table[] = {0x17, 0x47, 0x31};/* white/blue, white/red,
	   	  	 	    blue/white */
	   ...
	#if __LARGE_DATA__
	   mov dx,ss
	#endif
	   lea ax,table /* AX = offset of attr table */
	   set_attrtbl();	/* set custom attr table */
	   mov ah,1	/* AH = attr code (table[1]) */
	   set_attr();	/* set attr using table */
	   str = "White on Red characters";
	   mov si,str	/* SI = offset of str */
	   put_str();	/* display string */
	   mov ax,-1
	   set_attrtbl();	/* discard custom attr table */
	   ...
	}

Source file _CIOSATB.ASM ASM equiv SET_ATTRTBL
See also
attr_tbl, _get_dmode, _get_tblattr

_set_biosvideo


Descrip
Selects BIOS output for the console I/O system.

Syntax
#include <console.h>
void _set_biosvideo(void);

Returns
None

Notes
This function selects the BIOS output method for the console I/O system by setting the direct_video flag to 0. Console I/O functions support both direct and BIOS output. This allows applications to select the output method at run time, making it possible to run applications in environments which are not compatible with direct video I/O.

_console_init must be called before using this function.

C/C++ Example
	   _set_biosvideo();/* use BIOS for display */

Inline Assembly Example
	   set_biosvideo();/* use BIOS for display */

Source file CIOSBVID.ASM ASM equiv SET_BIOSVIDEO
See also
direct_video, _set_directvideo

_set_bkboldmode


Descrip
Reprograms the active display adapter to support high-intensity background attributes.

Syntax
#include <console.h>
void _set_bkboldmode(void);

Returns
None

Notes
This function reprograms the active display adapter to interpret the blink/intensity attribute bit as a high intensity background bit rather than as a blinking text bit. This function works with all display adapters. Note that this function immediately affects the way the display adapter interprets on-screen attributes. It does not affect the display attributes or attribute flags used by the _cput_... functions to display text. If the BLINK or BKBOLD attribute flag is currently set (using _set_attrflags, _blink_on or _bkbold_on), it remains set and it is interpreted as BKBOLD instead of BLINK.

_console_init must be called before using this function.

C/C++ Example
	   _set_bkboldmode();

Inline Assembly Example
	   set_bkboldmode();

Source file CIOSBKB.ASM ASM equiv SET_BKBOLDMODE
See also
_set_blinkmode

_set_bkcolor


Descrip
Sets the background color for the current text attribute.

Syntax
#include <console.h>
void _set_bkcolor(int bkcolor);

Returns
None

Notes
This function sets the background color of the current text attribute to the color specified by bkcolor. If an attribute table has been specified (using _set_attrtbl), bkcolor is treated as an attribute table code and the corresponding attribute table value is used as the background color; otherwise, bkcolor is used as the actual background color. The following symbolic constants (defined in CONSOLE.H) may be used to specify background colors:

BLACK(0x00) Black
BLUE (0x01) Blue
GREEN(0x02) Green
CYAN (0x03) Cyan
RED (0x04) Red
MAGENTA (0x05) Magenta
BROWN(0x06) Brown (low intensity yellow)
LTGRAY(0x07) Light gray (low intensity white)
DARKGRAY (0x08) High intensity black
LTBLUE(0x09) High intensity blue
LTGREEN (0x0A) High intensity green
LTCYAN(0x0B) High intensity cyan
LTRED(0x0C) High intensity red
LTMAGENTA(0x0D) High intensity magenta
YELLOW(0x0E) Yellow
WHITE(0x0F) High intensity white

If the requested background color is any other value, only the low 4 bits of the requested value are used.

Note that colors DARKGRAY through WHITE set the background high intensity (BKBOLD) attribute bit. If high intensity background colors are not currently supported (i.e., _set_blinkmode has been called) and a high intensity color is specified, the corresponding low intensity background color is used.

_console_init must be called before using this function.

C/C++ Example
	   _set_bkcolor(BLUE);/* set background color to BLUE */
	   _set_fgcolor(WHITE);/* output now white/blue */
	   ...

Inline Assembly Example
	#include <inline.h>
	   ...
	   mov ah,BLUE	    /* AH = background color */
	   set_bkcolor();
	   mov ah,WHITE/* AH = foreground color */
	   set_fgcolor();	/* output now white/blue */
	   ...
	}

Source file _CIOSBKC.ASM ASM equiv SET_BKCOLOR
See also
_set_attr, _set_fgcolor

_set_blinkmode


Descrip
Reprograms the active video display adapter to support blinking characters.

Syntax
#include <console.h>
void _set_blinkmode(void);

Returns
None

Notes
This function reprograms the active display adapter to interpret the blink/intensity attribute bit as a blinking text bit rather than as a high intensity background bit. This function works with all display adapters.

Note that this function immediately affects the way the display adapter interprets on-screen attributes. It does not affect the display attributes or attribute flags used by the _cput_... functions to display text. If the BLINK or BKBOLD attribute flag is currently set (using _set_attrflags, _blink_on or _bkbold_on), it remains set and it is interpreted as BLINK instead of BKBOLD.

_console_init must be called before using this function.

C/C++ Example
	   _set_blinkmode();/* support blinking characters */

Inline Assembly Example
	   set_blinkmode();/* support blinking characters */

Source file CIOSBLNK.ASM ASM equiv SET_BLINKMODE
See also
_set_bkboldmode

_set_cursor


Descrip
Sets the shape of the display cursor.

Syntax
#include <console.h>
void _set_cursor(unsigned int curtype);

Returns
None

Notes
This function sets the shape of the display cursor to the shape indicated by curtype. The specified shape is independent of the active display adapter or monitor. The display cursor fills the character cell from top to bottom, beginning at the character cell position specified in the high byte of curtype and ending at the cell position specified in the low byte of curtype. Character cell positions (in either the high byte or low byte of curtype) must be in the range 0 to 255, with 0 representing the top of the cell and 255 representing the bottom. If the ending position lies above the starting position, the cursor wraps past the bottom of the cell to the top of the cell and continues downward until the ending position is encountered.

The following symbolic constants (defined in CONSOLE.H) may be used as parameters to set the cursor to a number of predefined shapes:

BLOCK_CURSOR(0x00FF) Full block cursor shape
HALF_CURSOR(0x80FF) Half block cursor shape
DEFAULT_CURSOR(0xD0E0) BIOS default cursor shape
THICK_CURSOR(0xD0FF) Like DEFAULT, but extends to bottom of cell
XTHICK_CURSOR(0xB8FF) Like THICK, but starts one scan line higher

The shapes defined by DEFAULT_CURSOR and THICK_CURSOR appear identical on CGA and MCGA adapters as well as EGA and VGA adapters in 200 scan line mode.

Note that the actual cursor appearance is ultimately determined by the BIOS and the active display adapter. For example, a wrapping cursor appears as a "broken" cursor on MDA adapters but is not visible on many Hercules-compatible adapters. Also, EGA, MCGA, and VGA adapters perform "cursor emulation," which restricts the range of possible cursor shapes.
This function only sets the shape of the display cursor. The display cursor may be turned on and off by calling _cursor_on and _cursor_off.

_console_init must be called before using this function.

C/C++ Example
	   _set_cursor(BLOCK_CURSOR);/* BLOCK CURSOR */
	   ...

Inline Assembly Example
	#include <inline.h>
	   ...
	   mov ax,BLOCK_CURSOR	  /* BLOCK CURSOR */
	   set_cursor();	    /* set cursor shape */
	   ...

Source file _CIOSCUR.ASM ASM equiv SET_CURSOR
See also
_cursor_off, _cursor_on, _get_cursor

_set_dattr


Descrip
Sets the default text attribute.

Syntax
#include <console.h>
void _set_dattr(int dattr);

Returns
None

Notes
This function sets the "default" text attribute to dattr. If an attribute table has been specified (using _set_attrtbl), dattr is interpreted as an attribute table code and the default attribute is set to the attribute in the table which corresponds to dattr; otherwise, the default attribute is set to dattr.

The default text attribute is the fill attribute used by the console I/O system for clearing, inserting, and scrolling. It is also the attribute to which the current attribute is set when _reset_attr is called.

See the technical notes for detailed information on how to specify attributes.

_console_init must be called before using this function.

C/C++ Example
	   _set_dattr(WHITE+(16*BLUE)); /* white/blue */
	   ...

Inline Assembly Example
	#include <inline.h>
	   ...
	   mov ah,(WHITE+(16*BLUE));/* AX = default attr */
	   set_dattr();	    /* set to white/blue */
	   ...

Source file _CIOSDTR.ASM ASM equiv SET_DATTR
See also
_get_dattr, _reset_attr, _set_attr

_set_dimens


Descrip
Sets the screen dimensions of the active display adapter.

Syntax
#include <console.h>
int _set_dimens(char cols, char rows);

Returns
0 if the screen dimensions were successfully set.

-1 if the requested screen dimensions are not supported by the active display adapter.

Notes
This function reprograms the active display adapter to display a specified number of text mode rows and columns. -1 is returned and no change takes place if the specified number of rows and cols are not directly supported by the active display adapter. Otherwise: 1) the active adapter is reprogrammed to support the indicated screen dimensions; 2) page 0 is selected as the active video display page; 3) _console_init is called to re-initialize the console I/O system; and 4) 0 is returned. Only the screen dimensions of the active screen are affected if the virtual screen system is in use.

The adapter type and monitor type of the active display adapter determine which screen dimensions can be supported by this function. The following table indicates the supported text mode display dimensions as a function of display adapter and monitor type:

MDA/EGA CGA/EGA EGA EGA MCGA VGA
MONO RGB ECD_LO ECD_HI ANY ANY

40x12 or 80x12- - Yes - - Yes
40x14 or 80x14- - Yes - - Yes
40x21 or 80x21- - - Yes - -
40x25 or 80x25Yes Yes Yes Yes Yes Yes
40x28 or 80x28- - - - - Yes
40x43 or 80x43- - - Yes - -
40x50 or 80x50- - - - Yes Yes

Other nonstandard text modes cannot be directly selected by _set_dimens because video mode values vary from manufacturer to manufacturer. However, extended text modes are properly supported by the console I/O system once they have been established. See the Console I/O technical notes for instructions on identifying and selecting nonstandard text modes at run time.

This function automatically calls _console_init to re-initialize the console I/O system when the screen dimensions are changed.

_console_init must be called before this function may be used.

WARNING! This function leaves the windowing system in an undefined state. To preserve the condition of the windowing system, call _win_suspend just before calling this function. The state of the windowing system may then be restored at a later point by calling _win_resume.

C/C++ Example
	{
	   int cols, rows;
	   char intbuf[10], *strindx;
	   ...
	   _cput_str("\n\rEnter number of columns to display: ");
	   cols = _dec_to_i(_cget_str(intbuf, 5), &strindx);
	   _cput_str("\n\rEnter number of rows to display: ");
	   rows = _dec_to_i(_cget_str(intbuf, 5), &strindx);
	   if(_set_dimens(cols, rows) == -1);
	      _cput_str("Requested dimensions are not\
	         supported by adapter.");
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char cols, rows;
	   char intbuf[10], *str;
	   ...
	   str = "Enter number of columns to display: ";
	   mov si,str
	   cput_str();
	   mov cl,3
	   lea si,intbuf
	   cget_str();
	   dec_to_c();
	   mov cols,al
	   str = "Enter number of rows to display: ";
	   mov si,str
	   cput_str();
	   mov cl,3
	   lea si,intbuf
	   get_str();
	   dec_to_c();
	   mov ah,cols
	   xchgal,ah	/* AL = cols, AH = rows */
	   set_dimens();
	   ...
	}

Source file _CIOSDMS.ASM ASM equiv SET_DIMENS
See also
_chk_dimens, _get_dimens

_set_direction


Descrip
Sets the cursor advance direction.

Syntax
#include <console.h>
void _set_direction(int direction);

Returns
None

Notes
This function sets the current cursor advance direction. This determines the direction and distance which the cursor moves after each character is displayed using the _cput_... and the echoed _cget_... functions. The following symbolic constants (defined in CONSOLE.H) represent some of the possible advance directions:

ADV_RIGHT(0x0001) Cursor moves one column to the right
ADV_LEFT (0x00FF) Cursor moves one column to the left
ADV_UP(0xFF00) Cursor moves one row up
ADV_DOWN (0x0100) Cursor moves one row down
ADV_NONE (0x0000) No cursor motion at all

Other values may be specified by placing a signed number of columns in the low byte and a signed number of rows in the high byte. Negative values are interpreted as left and upward motion; positive values are interpreted as right and downward motion.

_console_init must be called before using this function.

C/C++ Example
	   _set_direction (ADV_RIGHT);/* direction to the right */
	   ...

Inline Assembly Example
	#include <inline.h>
	   ...
	   mov ax,ADV_LEFT/* AX=direction */
	   set_direction();  /* set cursor advance direction */
	   ...

Source file _CIOSDIR.ASM ASM equiv SET_DIRECTION
See also
_direc_down, _direc_left, _direc_right, _direc_up, _get_direction

_set_directvideo


Descrip
Selects direct video output for the Console I/O system.

Syntax
#include <console.h>
int _set_directvideo(void);

Returns
0 if direct video output was selected.

-1 if direct access could not be selected.

Notes
This function selects the direct output method for the Console I/O system by setting the direct_video flag to 1. If _console_init previously determined that direct video output is not supported by the current environment, -1 is returned and no change takes place; otherwise, 0 is returned.

Console I/O functions support both direct and BIOS output. This allows applications to select the output method at run time, making it possible to run applications in environments which are not compatible with direct video I/O.

_console_init must be called before using this function.

C/C++ Example
	{
	   ...
	   if (_set_directvideo() == 0)
	      _cput_str("Direct video output was selected.");
	   else
	      _cput_str("Direct video access could not be selected.");
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   set_directvideo();/* use direct video? */
	    jnclabel_ok/*   y: continue */
	   set_biosvideo();/*   n: use bios */
	label_ok:
	   ...
	}

Source file _CIOSDVD.ASM ASM equiv SET_DIRECTVIDEO
See also
direct_video, _set_biosvideo

_set_fgcolor


Descrip
Sets the foreground color for the current text attribute.

Syntax
#include <console.h>
void _set_fgcolor(int fgcolor);

Returns
None

Notes
This function sets the foreground color of the current text attribute to fgcolor. If an attribute table has been specified (using _set_attrtbl), fgcolor is treated as an attribute table code and the corresponding attribute table value is used as the foreground color; otherwise, fgcolor is used as the actual foreground color. The following symbolic constants (defined in CONSOLE.H) may be used to specify foreground colors:

BLACK (0x00) Black
BLUE (0x01) Blue
GREEN (0x02) Green
CYAN (0x03) Cyan
RED (0x04) Red
MAGENTA (0x05) Magenta
BROWN (0x06) Brown (low intensity yellow)
LTGRAY (0x07) Light gray (low intensity white)
DARKGRAY (0x08) High intensity black
LTBLUE (0x09) High intensity blue
LTGREEN (0x0A) High intensity green
LTCYAN (0x0B) High intensity cyan
LTRED (0x0C) High intensity red
LTMAGENTA(0x0D) High intensity magenta
YELLOW (0x0E) Yellow
WHITE (0x0F) High intensity white

If the requested foreground color is any other value, only the low 4 bits of the requested value are used. This makes it possible to change the foreground color of the current text attribute to match the foreground color of a second attribute by passing the second attribute to this function.

Note that colors DARKGRAY through WHITE set the high intensity (BOLD) attribute bit.

_console_init must be called before using this function.

C/C++ Example
	   _set_fgcolor (BLUE); /* use BLUE as foreground color */
	   ...

Inline Assembly Example
	#include <inline.h>
	...
	mov ah,LTMAGENTA/* AH = color for foreground */
	set_fgcolor();	 /* set foreground color */
	...

Source file _CIOSFGC.ASM ASM equiv SET_FGCOLOR
See also
_set_attr, _set_bkcolor

_set_region


Descrip
Sets new clipping region coordinates.

Syntax
#include <console.h>
void _set_region(int row, int col, int hght, int wdth);

Returns
None

Notes
This function sets the upper left-hand corner of the current clipping region to (col,row) and the width and height of the region to wdth and hght. row and col must be origin 0 positions relative to the upper left-hand corner of the screen (or the active window if windowing is in effect). If wdth and/or hght extend beyond the boundaries of the screen (or the active window if windowing is in effect), the effective clipping region extends only as far as the screen (or window). If the clipping region is currently off, the new position and dimensions do not take effect until_region_on is called; otherwise, they take effect immediately and the cursor is moved to the upper left-hand corner of the new clipping region. Changing the clipping region has no other effect on the display. When the clipping region is active, all cursor positioning is relative to the upper left-hand corner of the region and all output from the _cput_... and echoed _cget_... functions is restricted to the clipping region. The cursor becomes invisible if it is moved outside of this region.

_console_init must be called before using this function.

C/C++ Example
	   _set_region (0,0,5,10); /* five rows and ten cols */
	   ...

Inline Assembly Example
	#include <inline.h>
	   ...
	   mov dh,0	/* DH = row */
	   mov dl,0	/* DL = col */
	   mov ah,5	/* AH = hght */
	   mov al,10	/* AL = wdth */
	   set_region();	/* set new clipping region */
	   ...

Source file _CIOSREG.ASM ASM equiv SET_REGION
See also
_get_region, _region_off, _region_on

_set_vbordattr


Descrip
Sets the video border color to match the background color of a given text attribute.

Syntax
#include <console.h>
void _set_vbordattr(int attr);

Returns
None

Notes
This function sets the video border color to the hardware-specific color which best matches the background color in attr. If an attribute table has been specified (using _set_attrtbl), attr is treated as an attribute table code and the corresponding attribute table value is used as the attribute; otherwise, attr is used as the actual attribute. If high intensity background colors are currently enabled, one of 16 border colors is selected; otherwise, one of 8 border colors is selected. The new border color takes effect immediately only if the border has been turned on using _vborder_on. If the current video mode is MONO, this function has no effect.

This function sets the border color in a monitor-independent manner. However, it can only select one of 16 different colors (64 or more border colors are normally available on VGA color and EGA enhanced color monitors). _set_vborder may be used to select from the full range of available border colors if this is required.

See the technical notes for detailed information on how to specify attributes.

_console_init must be called before using this function.

C/C++ Example
	   _set_vbordattr(BLUE);/* set video border attr */
	   ...

Inline Assembly Example
	#include <inline.h>
	   ...
	   mov ah,RED	/* AH = attribute code */
	   set_vbordattr();/* set video border color */
	   ...

Source file _CIOSVBA.ASM ASM equiv SET_VBORDATTR
See also
_set_vborder

_set_vborder


Descrip
Sets the video border color.

Syntax
#include <console.h>
void _set_vborder(int attr);

Returns
None

Notes
This function sets the video border color to attr. If an attribute table has been specified (using set_attrtbl), attr is treated as an attribute table code and the corresponding attribute table value is used as the border color; otherwise, attr is used as the actual border color. The new color takes effect immediately only if the border has been turned on using _vborder_on. This function has no effect if the current video mode is MONO (see _get_vmode).

The range of allowable border color values and their interpretations depends on the active display adapter and monitor. CGA monitors support 16 border colors which are identical to the foreground and background colors defined in CONSOLE.H. EGA adapters with standard color monitors support 16 border colors; VGA color and EGA enhanced color monitors support 64 border colors. Colors are mapped differently for each monitor type.

To set the video border color in a monitor-independent (but more limited) fashion, use the _set_vbordattr function instead.

_console_init must be called before using this function.

C/C++ Example
	   _set_vborder(BLUE);
	   ...

Inline Assembly Example
	#include <inline.h>
	   ...
	   mov ah,RED	/* AH = video border color */
	   set_vborder();	/* set video border color */
	   ...

Source file _CIOSVBR.ASM ASM equiv SET_VBORDER
See also
_get_vborder, _set_vbordattr, _vborder_off, _vborder_on

_set_vmode


Descrip
Sets the video mode.

Syntax
#include <console.h>
void _set_vmode(int mode);

Returns
None

Notes
This function sets the current video mode to mode. The screen is blanked and the cursor is moved to the upper left-hand corner of the screen (unless the NOCLEAR option is specified as shown below). The following symbolic constants (defined in CONSOLE.H) represent the standard values of mode:

BW40 (0x00) 40x25 text mode, color burst off
CO40 (0x01) 40x25 text mode
BW80 (0x02) 80x25 text mode, color burst off
CO80 (0x03) 80x25 text mode
CG320X200X4(0x04) 320x200 graphics mode, 4 color
BW320X200X4(0x05) 320x200 graphics mode, 4 color
CG640X200X2(0x06) 640x200 graphics mode, 2 color
MONO80 (0x07) 80x25 text mode, monochrome
CG160X200X16jr(0x08) 160x200 graphics mode, 16 color, PCjr
CG320X200X16jr(0x09) 320x200 graphics mode, 16 color, PCjr
CG640X200X4jr(0x0A) 640x200 graphics mode, 4 color, PCjr
CG320X200X16(0x0D) 320x200 graphics mode, 16 color
CG640X200X16(0x0E) 640x200 graphics mode, 16 color
MG640X350 (0x0F) 640X350 graphics mode, monochrome
CG640X350X16(0x10) 640x350 graphics mode, 16 color
CG640X480X2(0x11) 640x480 graphics mode, 2 color
CG640X480X16(0x12) 640x480 graphics mode, 16 color
CG320X200X256(0x13) 320x200 graphics mode, 256 color
NOCLEAR (0x80) (Option) Don't clear screen when changing mode

Other nonstandard text modes are available on many video adapters. See the Console I/O technical notes for an explanation of nonstandard text video modes and how they may be detected and selected using Spontaneous Assembly console I/O functions.

The NOCLEAR option causes the mode change to take place without clearing the screen in the new mode. It is specified by bitwise ORing the NOCLEAR constant together with the new video mode. For example, if mode were MONO+NOCLEAR, the mode would be changed to MONO and the monochrome screen would not be cleared. This option is ignored on XT-class machines unless an EGA-compatible adapter is present.

This function automatically initializes the console I/O system by calling _console_init.

C/C++ Example
	   _set_vmode (CO40);/* 40x25 text mode */
	   ...

Inline Assembly Example
	#include <inline.h>
	   ...
	   mov al,CG320X200X256/* AL = new video mode */
	   set_vmode();	    /* set the video mode */
	   ...

Source file _CIOSVMD.ASM ASM equiv SET_VMODE
See also
_get_vmode, _set_80cols, _video_mode

_set_vpage


Descrip
Sets the active video display page.

Syntax
#include <console.h>
void _set_vpage(int vpage);

Returns
None

Notes
This changes the active video display page to vpage. vpage must be an origin 0 page number (the first page is page 0, the second page is page 1, and so on). If the virtual screen system is in use, the active screen is reassigned to the specified video page on its adapter; the screen contents are transferred only if the screen is buffered or windowed.

vpage is assumed to be a legal value. The results are undefined if the specified video display page is not available. _get_vpagecnt or _get_adaptinfo may be used to determine the number of allowed video display pages.

_console_init must be called before this function may be used.

WARNING! This function leaves the windowing system in an undefined state. To preserve the condition of the windowing system, call _win_suspend just before calling this function. The state of the windowing system may then be restored at a later point by calling _win_resume.

C/C++ Example
	{
	   int vp;
	   ...
	   vp = _get_vpage();/* get current video page */
	   vp++;	 /* adjust page identifier */
	   _set_vpage(vp);/* select next page */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   ...
	   get_vpage();	/* get current video page */
	   inc al	 	/* adjust page */
	   set_vpage();	/* select next page */
	   ...
	}

Source file _CIOSVP.ASM ASM equiv SET_VPAGE
See also
_get_adaptinfo, _get_vpage, _get_vpage, _set_vstate, _vscreen_create

_set_vstate


Descrip
Sets the video state to a specified state.

Syntax
#include <console.h>
int _set_vstate(const vstat far *buffer);

Returns
0 if the video state was successfully set.

-1 if the specified video state could not be set.

Notes
This function sets the current video state to the state specified in buffer, calls _console_init, and blanks the screen in the default text attribute. 0 is returned if the operation was successful. -1 is returned if the requested display adapter is not present in the system or the specified screen dimensions are not supported by the specified adapter. Only the active screen is affected if the virtual screen system is in use.

Only the specified display adapter and screen dimensions are checked by this function. All other values are assumed to be legal. The results are undefined if the specified video mode or video display page is not supported by the indicated display adapter.

The video state information in buffer is specified as a structure of type vstat, which is defined in CONSOLE.H as follows:

typedef struct {
char vst_adapter; /* active display adapter */
char vst_vmode; /* active video display mode */
char vst_vpage; /* active video display page */
char vst_refresh; /* refresh state (1-on, 0=off) */
unsigned int vst_dimens;/* screen dimensions (cols, rows) */
char vst_attr; /* current text attribute */
char vst_dattr; /* default text attribute */
char vst_vbon; /* video border state (1=on, 0=off) */
char vst_vbcolor; /* video border color */
char vst_bkbold; /* bkbold/blink mode (1=bkbold, 0=blink) */
char vst_curon; /* cursor state (1=on, 0=off) */
unsigned int vst_curtype;/* cursor type (0-255, 0-255) */
unsigned int vst_curpos;/* cursor position (forced to 0,0) */
} vstat;

This is the format returned by _get_vstate. By using _get_vstate in combination with _set_vstate, video states may be saved, manipulated, and restored at will.

Note that _get_vstate always forces the cursor position to the upper left corner of the screen (0,0) when it returns a video state. This is usually the preferred cursor placement position when video states are restored by _set_vstate. This may be circumvented, if necessary, by calling _where_xy immediately after calling _get_vstate and then storing the returned cursor position in the vst_curpos field of buffer.

To minimize undesirable side effects, _set_vstate only performs essential changes to the video state. For example, no video mode change is performed if the current display adapter is already in the required video mode.

_console_init must be called before this function may be used. In addition, _adapter_init must be called first if the restored video state might include a change to a secondary display adapter.

WARNING! This function leaves the windowing system in an undefined state. To preserve the condition of the windowing system, call _win_suspend just before calling this function. The state of the windowing system may then be restored at a later point by calling _win_resume.

C/C++ Example
	{
	   vstat v1;
	   .../* set up structure for adapter */
	   if(_set_vstate(&v1) == -1)
	      _put_str("Specified video state could not be set.");
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   vstat v1;
	   char *str;
	   ... 	 /* set up structure buffer for adapter */
	   pushss
	   pop es
	   lea di,v1/* ES:DI -> v1 */
	   set_vstate();/* save state of active display adapter*/
	    jnclabel_010
	   str = "Specified video state could not be set.";
	   mov si,str
	   put_str();/* display error message */
	label_010:
	   ...
	}

Source file _CIOSVST.ASM ASM equiv SET_VSTATE
See also
_get_vstate, _restore_vstate, _save_screen, _save_vstate, _vscreen_create

_vborder_off


Descrip
Turns the video border off.

Syntax
#include <console.h>
void _vborder_off(void)

Returns
None

Notes
This function turns the video border (overscan region) off. This is done by changing the video border color to BLACK. The current video border color may be restored by calling _vborder_on. If the current video mode is MONO, this function has no effect.

_console_init must be called before using this function.

C/C++ Example
	   ...
	   _vborder_off();/* turn video border off */
	   ...

Inline Assembly Example
	#include <inline.h>
	   ...
	   vborder_off();
	   ...

Source file CIOVBOFF.ASM ASM equiv VBORDER_OFF
See also
_vborder_on

_vborder_on


Descrip
Turns the video border on.

Syntax
#include <console.h>
void _vborder_on(void);

Returns
None

Notes
This function turns the video border (overscan region) on. This is done by changing the video border color to the color set using _set_vborder. If the current video mode is MONO, this function has no effect.

_console_init must be called before using this function.

C/C++ Example
	   ...
	   _vborder_on();/* turn video border on */
	   ...

Inline Assembly Example
	#include <inline.h>
	   ... 
	   vborder_on();
	   ...

Source file CIOVBON.ASM ASM equiv VBORDER_ON
See also
_set_vborder, _vborder_off

video_mode


Descrip
(Variable) Indicates the current video mode.

Syntax
#include <console.h>
extern char video_mode;

Notes
This read-only char variable indicates the current video display mode. The mode may be changed by calling _set_vmode or _set_80cols.

The following symbolic constants (defined in CONSOLE.H) represent the standard video modes:

BW40 (0x00) 40x25 text mode, color burst off
CO40 (0x01) 40x25 text mode
BW80 (0x02) 80x25 text mode, color burst off
CO80 (0x03) 80x25 text mode
CG320X200X4(0x04) 320x200 graphics mode, 4 color
BW320X200X4(0x05) 320x200 graphics mode, 4 color
CG640X200X2(0x06) 640x200 graphics mode, 2 color
MONO(0x07) 80x25 text mode, monochrome
CG160X200X16jr(0x08) 160x200 graphics mode, 16 color, PCjr
CG320X200X16jr(0x09) 320x200 graphics mode, 16 color, PCjr
CG640X200X4jr(0x0A) 640x200 graphics mode, 4 color, PCjr
CG320X200X16(0x0D) 320x200 graphics mode, 16 color
CG640X200X16(0x0E) 640x200 graphics mode, 16 color
MG640X350(0x0F) 640X350 graphics mode, monochrome
CG640X350X16(0x10) 640x350 graphics mode, 16 color
CG640X480X2(0x11) 640x480 graphics mode, 2 color
CG640X480X16(0x12) 640x480 graphics mode, 16 color
CG320X200X256(0x13) 320x200 graphics mode, 256 color

In addition, many non-IBM display adapters support enhanced modes which are not listed above. See the Console I/O technical notes for an explanation of nonstandard text video modes and how they may be detected using Spontaneous Assembly console I/O functions.

This variable is initialized by _console_init.

Source file CIOCVAR.ASM ASM equivâ
See also
_console_init, _set_80cols, _set_vmode

_video_off


Descrip
Disables video refresh on the current display adapter.

Syntax
#include <vscreen.h>
void _video_off(void);

Returns
None

Notes
This function turns off video refresh on the active display adapter. This blanks the screen (without any loss of data) until _video_on is called. Only the active screen is affected if the virtual screen system is in use.

When video refresh is disabled, multiple screen state changes can be performed smoothly, with little or no screen flickering, including changes to the video mode, video page, video border, screen dimensions, and the contents of the screen itself. _video_off does not work on VGA adapters.

_console_init must be called before this function may be used.

C/C++ Example
	{
	   ...
	   _video_off();/* disable video refresh */
	   ...
	}

Inline Assembly Example
	{
	   ...
	   video_off();/* disable video refresh */
	   ...
	}

Source file CIOVID.ASM ASM equiv VIDEO_OFF
See also
_video_on

_video_on


Descrip
Enables video refresh on the current display adapter.

Syntax
void _video_on(void);

Returns
None

Notes
This function enables video refresh on the active display adapter. Only the active screen is affected if the virtual screen system is in use.

This function is a companion function to _video_off, which disables video refresh on the active adapter. When video refresh is disabled, multiple screen state changes can be performed smoothly, with little or no screenflickering, including changes to the video mode, video page, video border, screen dimensions, and the contents of the screen itself. _video_on does not work on VGA adapters.

_console_init must be called before this function may be used.

C/C++ Example
	{
	   ...
	   _video_on();/* enable video refresh */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	      ...
	        video_on();/* enable video refresh */
	   ...
	}

Source file CIOVID.ASM ASM equivâ
See also
_video_off

video_snow


Descrip
(Variable) Indicates whether or not direct video output should compensate for "snow".

Syntax
#include <console.h>
extern char video_snow;

Notes
This char size variable indicates whether or not Console I/O functions which directly access video memory should take measures to prevent display interference ("snow"). If this variable is 0, snow control is not performed; if it is 1, snow control is performed and the display speed is reduced. If direct video access has been disabled (i.e., direct_video is not set to 1), this variable has no effect.

_console_init initializes this variable to 1 if the active display adapter is a CGA; otherwise, it is initialized to 0.

Source file CIOCVAR.ASM ASM equivâ

_where_x


Descrip
Returns the current cursor column coordinate.

Syntax
#include <console.h>
int _where_x(void);

Returns
The current cursor column.

Notes
This function returns the current cursor column position. The returned coordinate is relative to the left margin of the current clipping region if the clipping region is enabled; otherwise, it is relative to the left margin of the screen (or the active window if windowing is in effect). 0 represents the left-most column of the clipping region or screen.

This binder is included to provide functionality similar to C's wherex.

_console_init must be called before using this function.

C/C++ Example
	{
	   int xpos;
	   xpos = _where_x();
	   goto_xy (xpos+5,0); /* get current x pos, add five more */ 
	   ...
	}

Inline Assembly Example
	   ...
	   where_x();
	   add al,5
	   goto_xy();
	   ...

Source file _CIOWX.ASM ASM equiv WHERE_X
See also
_where_x, _where_y

_where_xy


Descrip
Returns the current cursor coordinates.

Syntax
#include <console.h>
void _where_xy(char *xpos, char *ypos);

Returns
No return value.
xpos the current cursor column
ypos the current cursor row

Notes
This function modifies xpos and ypos to reflect the current cursor coordinates. These coordinates are relative to the upper left-hand corner of the current clipping region if the clipping region is enabled; otherwise, they are relative to the upper left-hand corner of screen (or the active window if windowing is in effect). (0,0) represents the upper left-hand corner position.

_console_init must be called before using this function.

C/C++ Example
	{
	   int xpos, ypos;
	   _where_y(&xpos, &ypos);
	   ...
	}

Inline Assembly Example
	{
	#include <inline.h>
	{
	   int xpos, ypos;

	   where_xy();
	   mov xpos,al
	   mov ypos,ah
	   ...
	}

Source file _CIOWXY.ASM ASM equiv WHERE_XY
See also
_goto_x, _where_x, _where_y

_where_y


Descrip
Returns the current cursor row coordinate.

Syntax
#include <console.h>
int _where_y(void);

Returns
The current cursor row.

Notes
This function returns the current cursor row position. The returned coordinate is relative to the top margin of the current clipping region if the clipping region is enabled; otherwise, it is relative to the top margin of the screen (or the active window if windowing is in effect). 0 represents the top column of the clipping region or screen.

This binder is included to provide functionality similar to C's wherey.

_console_init must be called before using this function.

C/C++ Example
	{
	   int ypos;
	   ypos = _where_y();
	   ...
	}

Inline Assembly Example
	{
	   int ypos;
	   where_xy();
	   mov ypos,ah
	   ...
	}

Source file _CIOWY.ASM ASM equiv WHERE_Y
See also
_where_x, _where_x

_write_textattr


Descrip
Copies text and attributes from a specified buffer to a specified display region.

Syntax
#include <console.h>
void _write_textattr(int dstleft, int dsttop, int wdth, int hght, void far *buffer);

Returns
None

Notes
This function writes the text and attributes in buffer to the display region located at dsttop and dstleft, where dsttop and dstleft are origin 0 positions relative to the upper left-hand corner of the current window (or the screen if windowing is not in effect). A maximum of hght rows and wdth characters per row are copied. If the destination region extends beyond the boundaries of the screen (or the active window if windowing is in effect), only those characters are copied which will fit on the screen (or within the window). If buffer contains fewer than hght rows or wdth columns of data, only the data which is actually present in buffer is copied.

Character/attribute pairs are written to the display through BIOS calls or directly to video memory depending on the state of the direct_video variable.

buffer contains the width of the region, the height of the region, and character/attribute pairs (character followed by attribute), in the following format:

char buf_width; /* width of each row */
char buf_height;/* number of rows */
int buf_charattr[];/* character/attribute pairs, attr in high (2nd) byte,
size = buf_height x buf_width */

The number of char/attribute pairs (words) present in buffer must be equal to the indicated width multiplied by the indicated height. Note that this is the buffer format supported by _read_textattr.

_console_init must be called before using this function.

C/C++ Example
	{
	   void *txtbuf;
	   txtbuf = malloc(1010);
	   _read_textattr(0,0,40,25,txtbuf);/* read half scr */
	   _write_textattr(0,0,40,25,txtbuf);/* replace scr half */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   void *txtbuf;
	   if ((txtbuf = malloc(2100)) == NULL)
	      exit(1);
	...
	    mov di,txtbuf/* DI = offset of dest buffer */
	    mov dl,0	 /* DL = srcleft */
	    mov dh,0	 /* DH = srctop */
	    mov al,40	 /* AL = width */
	    mov ah,25	 /* AH = height */
	    read_textattr();/* read text */
	    ...
	    write_textattr();/* write text */
	    ...
	}

Source file _CIOWTXT.ASM ASM equiv WRITE_TEXTATTR
See also
_hwrite_textattr, _move_textattr, _read_textattr, _restore_screen