Miscellaneous DOS

Reference Section

_cbrk_check
_cbrk_disable
_cbrk_enable
_cbrk_install
cbrk_pending
_cbrk_remove
_cbrk_restore
_cbrk_save
_ce_install
_cem_install
_ce_remove
_chk_version
_chk_version2
_cmp_version
_dos_errmsg
_dos_errmsge
_dos_malloc
_dos_mavail
_dos_mfree
_dos_mset
_dos_msize
_dta_restore
_dta_save
e_code
_get_cbrk
_get_cdfree
_get_cdinfo
_get_cdsize
_get_countryinfo
_get_dfree
_get_dinfo
_get_dsize
_get_dta
_get_ecode
_get_lastdrive
_get_vect
_get_verify
_get_version
_set_cbrk
_set_country
_set_dta
_set_vect
_set_verify
_verify_off
_verify_on
_verify_restore
_verify_save

_cbrk_check


Descrip
Allows a ctrl-break event to be processed if one is pending and the DOS ctrl-break flag is set.

Syntax
#include <miscdos.h>
void _cbrk_check(void);

Returns
None

Notes
This function causes control to pass to the current ctrl-break handler if a ctrl-break event is pending and the DOS ctrl-break flag is set.

Nothing happens if no event is pending, the DOS ctrl-break flag is not set, or ctrl-break events have been disabled using _cbrk_disable. DOS ctrl-break checking is only performed when DOS function calls are processed. Therefore, unless a program issues DOS calls frequently, it will be unresponsive to ctrl-break events. _cbrk_check may be called within unresponsive sections of code to alleviate this problem.

C/C++ Example
	   _cbrk_check();/* pass control if ctrl-break pending */

Inline Assembly Example
	   cbrk_check();/* pass control if ctrl-break pending */

Source file MDCBKCHK.ASM ASM equiv CBRK_CHECK

_cbrk_disable


Descrip
Disables all DOS ctrl-break checking

Syntax
#include <miscdos.h>
void _cbrk_disable(void);

Returns
No return value.
cbrk_pending cleared (0)

Notes
This function completely disables DOS ctrl-break checking by deactivating the current ctrl-break handlers. Temporary ctrl-break handlers are installed to keep track of unprocessed ctrl-break events via the cbrk_pending variable. Ctrl-break checking remains disabled until _cbrk_enable is called. This function has no effect on the DOS ctrl-break flag.

WARNING! If this function is called, _cbrk_enable must be called before the program terminates or a system crash may result.

Note that DOS function calls 0x09 and 0x0A may be affected by ctrl-C events (^C and a newline are displayed). This occurs even if _cbrk_disable is called. However, calling _cbrk_disable will prevent the ctrl-break handler from receiving control.

C/C++ Example
	   _cbrk_disable();/* disable DOS ctrl-break checking */

Inline Assembly Example
	#include <inline.h> 
	   cbrk_disable();/* disable DOS ctrl-break checking */

Source file MDCBKDIS.ASM ASM equiv CBRK_DISABLE
See also
_cbrk_enable, cbrk_pending

_cbrk_enable


Descrip
Enables DOS ctrl-break after _cbrk_disable has been called.

Syntax
#include <miscdos.h>
void _cbrk_enable(void);

Returns
No return value.
cbrk_pending cleared (0)

Notes
This function re-enables DOS ctrl-break checking after it has been disabled by _cbrk_disable. It does this by re-installing the ctrl-break handlers which were deactivated by _cbrk_disable. If cbrk_pending is non-zero on entry, a ctrl-break event is then forced. This immediately passes control to the re-installed DOS ctrl-break handler if the DOS ctrl-break flag is set; otherwise, the event is queued by DOS for processing when the state of the DOS ctrl-break flag is changed. If _cbrk_disable was never called, this function has no effect. This function has no effect on the DOS ctrl-break flag.

Note that if cbrk_pending is set to zero immediately prior to calling this function, all ctrl-break events which occurred while _cbrk_disable was in effect will be ignored.

WARNING! If _cbrk_disable is called then this function must be called before the program terminates or a system crash may result.

C/C++ Example
	   _cbrk_enable();/* enable DOS ctrl-break checking */

Inline Assembly Example
	#include <inline.h>
	   cbrk_enable();/* enable DOS ctrl-break checking */

Source file MDCBKDIS.ASM ASM equiv CBRK_ENABLE
See also
_cbrk_disable, cbrk_pending

_cbrk_install


Descrip
Installs a DOS ctrl-break handler.

Syntax
#include <miscdos.h>
void _cbrk_install(int (*func)(void));

Returns
None

Notes
This function installs func in place of the current DOS ctrl-break handler. Once installed, func receives control whenever DOS detects a ctrl-break event which should be processed.

The ctrl-break handler may perform any action, including DOS calls and/or termination of the program. If the ctrl-break handler return to the calling program, the return value is used to indicate whether or not the program should continue execution or be terminated (if the return value is 0 then the program continues where execution left off; otherwise the program terminates).

_cbrk_remove does not need to be called prior to exiting the program. If a ctrl-break handler has been installed, DOS will automatically remove it when the program terminates.

C/C++ Example
	int control_break (void)/* simple cbrk handler */
	{
	   _put_str ("\n\rControl-Break pressed");
	   return (0);   	 /* continue execution */
	}

	{
	   ...
	   _cbrk_install (control_break); /* install it */
	   ...
	}

Inline Assembly Example
	#include <inline.h>

	{
	   ...
	#if __TINY__
	   mov  dx,cs
	#else
	   mov  dx,seg control_break
	#endif
	   mov  ax,offset control_break/* DX;AX -> new handler */
	   cbrk_install ();    /* install it */
	   ...
	}

	int control_break (void)    /* simple cbrk handler */
	{
	   _put_str ("\n\rControl-Break pressed");
	   return (0);	 	    /* continue execution */
	}

Source file _MDCBINS.ASM ASM equiv CBRK_INSTALL
See also
_cbrk_remove

cbrk_pending


Descrip
(Variable) Indicates whether or not ctrl-break events occurred while cbrk_disable was in effect.

Syntax
#include <miscdos.h>
extern char cbrk_pending;

Notes
This char variable is used to keep track of ctrl-break events which occur while cbrk_disable is in effect. When cbrk_enable is called, the re-installed ctrl-break handler (the handler which was active when _cbrk_disable was called) receives control immediately if cbrk_pending is non-zero.

Note that if cbrk_pending is set to zero immediately prior to calling _cbrk_enable, all ctrl-break events which occurred while cbrk_disable was in effect will be ignored.

Source file MDPEND.ASM ASM equivâ
See also
_cbrk_disable, _cbrk_enable

_cbrk_remove


Descrip
Removes an installed DOS ctrl-break handler.

Syntax
#include <miscdos.h>
void _cbrk_remove(void);

Returns
None

Notes
This function resets the DOS ctrl-break address to the initial ctrl-break address stored in the PSP. This disables any ctrl-break handler installed after the program began execution.

_cbrk_remove does not need to be called prior to exiting the program. If a ctrl-break handler has been installed, DOS will automatically remove it when the program terminates.

WARNING! This function uses the _psp global variable. When using Spontaneous Assembly for C/C++, this variable is supplied and initialized by the compiler instead of the Spontaneous Assembly Library.

C/C++ Example
	   _cbrk_remove();   /* reset ctrl-break handler address */

Inline Assembly Example
	#include <inline.h>
	   cbrk_remove();   /* reset ctrl-break handler address */

Source file MDCBKREM.ASM ASM equiv CBRK_REMOVE
See also
_cbrk_install

_cbrk_restore


Descrip
Restores the original state of the DOS ctrl-break flag.

Syntax
#include <miscdos.h>
void _cbrk_restore(void);

Returns
None

Notes
This function restores the DOS ctrl-break flag to the state which was in effect when _cbrk_save was called. If _cbrk_save was not previously called, the resulting state of the DOS ctrl-break flag is undefined.

_cbrk_save is usually called soon after the program begins executing to save the state of the DOS ctrl-break flag before it is changed by _set_cbrk. _cbrk_restore is then called just before the program terminates to restore the DOS break flag to its original state. If this is not done, the program may alter the DOS break status for subsequent programs.

C/C++ Example
	   _cbrk_save ();  /* save DOS ctrl-break status flag */
	   ...
	   _cbrk_restore ();

Inline Assembly Example
	#include <inline.h>
	   cbrk_save ();  /* save DOS ctrl-break status flag */
	   ...
	   cbrk_restore ();

Source file MDCBKSAV.ASM ASM equiv CBRK_RESTORE
See also
_cbrk_save

_cbrk_save


Descrip
Saves the current state of the DOS ctrl-break flag.

Syntax
#include <miscdos.h>
void _cbrk_save(void);

Returns
None

Notes
This function determines the current state of the DOS ctrl-break flag and saves it for later restoration by _cbrk_restore.

_cbrk_save is usually called soon after the program begins execution to save the state of the DOS ctrl-break flag before it is changed by _set_cbrk. _cbrk_restore is then called just before the program terminates to restore the DOS break flag to its original state. If this is not done, the program may alter the DOS break status for subsequent programs.

C/C++ Example
	   _cbrk_save ();  /* save DOS ctrl-break status flag */
	   ...
	   _cbrk_restore ();  /* restore DOS ctrl-break status flag */

Inline Assembly Example
	#include <inline.h>
	   cbrk_save ();  /* save DOS ctrl-break status flag */
	   ...
	   cbrk_restore (); /* restore DOS ctrl-break status flag */

Source file MDCBKSAV.ASM ASM equiv CBRK_SAVE
See also
_cbrk_restore

_ce_install


Descrip
Installs a critical error handler.

Syntax
#include <miscdos.h>
void _ce_install(intaddr ce_handler);

Returns
None

Notes
This function installs ce_handler in place of the current critical error handler address. Once installed, the function at ce_handler receives control whenever a critical error occurs within DOS.

See a DOS Technical Reference Manual or another DOS reference manual for detailed information about writing custom critical error handlers.

The _ce_remove function may be used to uninstall the installed critical error handler. Alternatively, _ce_install may be called to install an alternate critical error handler. _ce_remove does not need to be called prior to exiting the program. If any critical error handler has been installed (including the Critical Error Manager), DOS will automatically uninstall it when the program terminates.

In most cases, it is advisable to use _cem_install instead of _ce_install. The _cem_install function installs the Critical Error Manager, a predefined critical error handler which greatly simplifies processing of critical errors.

ce_handler should be cast as intaddr when calling this function. This prevents the compiler from generating assembly language SEG instructions, which preclude the use of .COM format in the TINY memory model. Some compilers also require type casting of interrupt functions in parameter lists to eliminate spurious compiler errors.

WARNING! The predefined ISRs from the TSR unit install a different critical error handler prior to passing control to a TSR entry point. This means that ce_handler is inactive when a TSR entry point is active. See the TSRs and Device Drivers technical notes for more information.

C/C++ Example
	void interrupt far ce_handler (int bp, int di, int si, int ds,
		          int es, int dx, int cx, int bx,
		          int ax, int ip, int cs,
		          int flags);
	/* set up critical error handler
	{
	   /* handle the critical error here */
	}
	...
	_ce_install ((intaddr) ce_handler);
		   /* install critical error handler */
	...

Inline Assembly Example
	#include <inline.h>
	#ifdef __cplusplus
	extern "C" void interrupt far ce_handler (int bp, int di,
	   int si, int ds, int es, int dx, int cx, int bx, int ax,
	   int ip, int cs, int flags);
	#else
	void interrupt far ce_handler (int bp, int di, int si, int ds,
	   int es, int dx, int cx, int bx, int ax, int ip, int cs,
	   int flags);
	#endif

	/* setup critical error handler
	{
	   ... 	 /* handle the critical error here */
	}
	   ...
	#if __TINY__
	   mov  dx,cs /* setup to install critical error handler */
	#else
	   mov  dx,seg ce_handler
	#endif
	   mov  ax,offset ce_handler
	   ce_install ();/* install critical error handler
	   ...

Source file _MDCEINS.ASM ASM equiv CE_INSTALL
See also
_cem_install, _ce_remove, _tsr_init

_cem_install


Descrip
Installs the Critical Error Manager.

Syntax
#include <miscdos.h>
void _cem_install(char (*user)(char error, char func_num, char err_inf, char drive, void far * far *addr));

Returns
None

Notes
This function installs the Critical Error Manager as the current critical error handler. It also installs user as the address of a user function to be called by the Critical Error Manager whenever a critical error occurs. In large code models, user is a far function; in small code models, user is a near function.

_cem_install may be called repeatedly. Each time it is called, a new user function address may be specified.

The _ce_remove function may be used to uninstall the Critical Error Manager. Alternatively, _ce_install may be called to install an alternate critical error handler. _ce_remove does not need to be called prior to exiting the program. If any critical error handler has been installed (including the Critical Error Manager), DOS will automatically uninstall it when the program terminates.

The Critical Error Manager simplifies processing of critical errors, eliminates "Abort, Retry, Ignore?" messages and allows user-defined functions to be called whenever critical errors occur.

Once installed, the Critical Error Manager receives control whenever a critical error occurs within DOS. If a user function has been specified, that function is called. When the user function returns, the Critical Error Manager performs the action specified by the user function. If no user function is specified, the Critical Error Manager always "fails" the DOS function call which caused the error.

The user function is passed a variety of error information each time a critical error takes place. The user function must support the following syntax:

char user(char error, char func_num, char err_inf, char drive, void far * far *addr);

This function may not issue any DOS function calls except functions 0x00 to 0x0C and 0x59. If any other calls are issued, DOS may crash. When the user function receives control, the following inputs apply (note that these inputs are different than the inputs provided by DOS to a critical error handler):

error default error code corresponding to this critical error (E_WRPROTECT through E_WRONGDISK, as defined in ECODES.H)

func_num function call number of the original DOS function call which caused the critical error

err_inf critical error information (bits 0-2 are defined only if the error occurred on a disk drive):

bit 0 0=reading, 1=writing
bits 1-2 00=DOS area (system files), 01=FAT, 10=directory, 11=data area
bit 3 0=fail not recommended, 1=fail OK
bit 4 0=retry not allowed, 1=retry allowed
bit 5 0=ignore not allowed, 1=ignore allowed
bit 6 (unused)
bit 7 0=disk drive (drive has drive letter), 1=other device type

drive uppercase drive letter of drive on which error occurred (if err_inf bit 7 = 0); otherwise, 0=FAT, 1=standard input device, 2=standard output device, 3=NULL device, 4=clock device, -1=unknown character device

addr address of a pointer to an 8-byte device name if bit 7 of err_inf = 1, undefined otherwise

Note that this error information is organized in such a way as to simplify the construction of an error message describing the problem (i.e., "Drive not ready error reading drive A:" or "Unknown command error on device $CLOCK"). Note also that if DOS 3.0 or later is running, then DOS function call 0x59 can be executed by the user function to obtain information and a recommendation on how to deal with the error.

When the user function has finished its work, it must specify the action to be taken as follows:

CE_IGNORE (00) "Ignore"
CE_RETRY (01) "Retry"
CE_ABORT (02) "Abort"
CE_FAIL (03) "Fail"
CE_QUIT (0xFF) "Quit"

If an invalid action code is returned, the "fail" option is performed.

The "abort" option (CE_ABORT) is directly supported by all DOS versions 2.0 and greater. If "abort" is requested, DOS is instructed to attempt to abort program execution by issuing an INT 23h (control-break). It is advisable to use the "quit" option instead of "abort." This is especially true if ctrl-break handling has been disabled using _cbrk_disable or its equivalent, if interrupt handlers have been installed, or if other functions have been performed which must be cleaned up prior to program termination. If this rule is not followed, the "abort" may be ignored or a system crash may result.

The "retry" option (CE_RETRY) is directly supported by all DOS versions 2.0 and greater. If "retry" is requested, DOS is instructed to retry the operation which caused the critical error. If the critical error occurs again, control is again passed to the Critical Error Manager.

The "ignore" option (CE_IGNORE) is directly supported by all DOS versions 2.0 and greater. If "ignore" is requested, DOS is instructed to ignore the critical error. Note that when an "ignore" is performed, the values returned by the function call are unpredictable (some versions of DOS even modify registers which would not normally be modified by that particular function call).

Use of the "fail" option is preferred where possible since the return values for "fail" are well-defined and predictable for all versions of DOS.

The "fail" option (CE_FAIL) is similar to the "fail" option supported by DOS versions 3.0 and greater. If "fail" is requested, the Critical Error Manager places an error code in an appropriate register and sets the carry flag; control is then passed to the instruction immediately following the DOS function call which caused the critical error. The Critical Error Manager always supports the "fail" option, regardless of the version of DOS being used.

The "quit" option (CE_QUIT) allows program execution to continue at a specified exit address. This is often used to pass control to a routine which performs some kind of cleanup (i.e., restoring interrupt vectors) before terminating the program. When control is passed to this exit point, registers and flags are set to the values which were in effect when the DOS function call was issued. Care must be exercised when using this option. If the critical error occurred on a device which will be accessed by the cleanup routine, another critical error is likely to occur and the program could end up in an infinite loop. If CE_QUIT is returned, the exit address must be placed in addr.

The "abort", "fail", and "quit" options are always allowed. The "retry" and "ignore" options are always allowed under DOS versions 2.0 and 2.1; DOS 3.0 or greater may not allow them (as indicated in bits 4 and 5 of err_inf when the user function is called). If the user function requests either "retry" or "ignore" when it is not allowed, then the Critical Error Manager performs a "fail" instead. Note that even though the "fail" option is always supported by the Critical Error Manager, there are situations where DOS 3.0 or greater would not support "fail" if the Critical Error Manager were not installed. Bit 3 of err_inf is used to indicate these situations.

WARNING! Before installing the Critical Error Manager, _osmajor must be initialized to contain the major DOS version number. When using Spontaneous Assembly for C/C++, this variable is supplied and initialized by the compiler instead of the Spontaneous Assembly library.

WARNING! The predefined ISRs from the TSR unit install a different user function or critical error handler prior to passing control to a TSR entry point. This means that user is inactive when a TSR entry point is active unless _tsr_initc is called with user specified as the user function address. See the TSRs and Device Drivers technical notes for more information.

C/C++ Example
	   char ce_manager (char error, char func_num,
	      char err_inf, char drive, void far * far *device);
	   ...
	/* new critical error manager */
	{
	   ...
	   return (3);
	}
	   _cem_install (ce_manager);/* install it */
	   ...

Inline Assembly Example
	#include <inline.h>
	   char ce_manager (char error, char func_num, 
	      char err_inf, char drive, void far * far *device);

	/* new critical error manager */
	   {
	   ...
	   return (3);
	   }
	#if __TINY__
	   mov  dx,cs
	#else
	   mov  dx,seg ce_manager
	#endif
	   mov  ax,offset ce_manager
	      /* DX:AX -> new critical error manager */
	   cem_install ();    /* install it */
	   ...

Source file _MDCEMNS.ASM ASM equiv CEM_INSTALL
See also
_ce_install, _ce_remove, _tsr_init, _tsr_init

_ce_remove


Descrip
Removes an installed DOS critical error handler.

Syntax
#include <miscdos.h>
void _ce_remove(void);

Returns
None

Notes
This function resets the DOS critical error handler address to the initial critical error handler address stored in the PSP. This disables any critical error handler installed after the program began execution.

This function does not need to be called prior to exiting the program.

If any critical error handler has been installed (including the Critical Error Manager), DOS will automatically uninstall it when the program terminates.

WARNING! This function depends on the _psp global variable. When using Spontaneous Assembly for C/C++, this variable is supplied and initialized by the compiler instead of the Spontaneous Assembly library.

C/C++ Example
	   _ce_remove();

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

Source file MDCEREM.ASM ASM equiv CE_REMOVE
See also
_ce_install, _cem_install

_chk_version


Descrip
Terminates program execution immediately if the current DOS version is unacceptable.

Syntax
#include <miscdos.h>
void _chk_version(int minor, int major);

Returns
No return value.
_osmajor major DOS version number
_osminor minor DOS version number

Notes
This function compares the current DOS version number with the required version number in major;minor. The required version number must be 2.0 or greater. If the current version number is greater than or equal to the required version, _osmajor and _osminor are initialized using the current DOS version number. If the current version is less than the required version, a DOS-like error message is displayed ("Requires DOS version 2.1 or greater") and the program exits to DOS immediately (with ERRORLEVEL set to 1 if DOS 2.0 or greater is running).

The global variable _psp must be initialized prior to calling this function and assumes _psp is in the same segment as all other Spontaneous Assembly library data.

_psp, _osmajor, and _osminor are supplied and initialized by the compiler instead of the Spontaneous Assembly library.

C/C++ Example
	   _chk_version (0, 3);    /* DOS 3.0 required */

Inline Assembly Example
	#include <inline.h>
	   ...
	   mov dx,_psp
	   mov al,0
	   mov ah,3
	   chk_version();  /* DOS 3.0 required */
	   ...

Source file _MDCHKVR.ASM ASM equiv CHK_VERSION
See also
_chk_version, _cmp_version, _get_version

_chk_version2


Descrip
Terminates program execution immediately if the current DOS version is 1.0 or 1.1.

Syntax
#include <miscdos.h>
void _chk_version2(void);

Returns
No return value.
_osmajor major DOS version number
_osminor minor DOS version number

Notes
This function checks the current DOS version number. If the current version number is 2.0 or greater, _osmajor and _osminor are initialized using the current DOS version number. If the current version is less than 2.0, a DOS-like error message is displayed (such as "Requires DOS version 2.0 or later") and the program exits to DOS immediately using DOS 1.x function calls.

The global variable _psp must be initialized prior to calling this function and assumes _psp is in the same segment as all other Spontaneous Assembly library data.

_psp, _osmajor, and _osminor are supplied and initialized by the compiler instead of the Spontaneous Assembly library.

C/C++ Example
	   _chk_version2 ();	/* terminate if DOS 1x */

Inline Assembly Example
	#include <inline.h>
	   mov dx,_psp
	   chk_version2 (); /* terminate if DOS 1x */

Source file _MDCKVR2.ASM ASM equiv CHK_VERSION2
See also
_chk_version, _cmp_version, _get_version, _version

_cmp_version


Descrip
Compares the required DOS version number with the current version.

Syntax
#include <miscdos.h>
int _cmp_version(int minor, int major);

Returns
1 if the DOS version is greater than required version.

0 if the DOS version is equal to required version.

-1 if the DOS version is less than required version.

Notes
This function compares the required DOS version number with the global version variables _osmajor and _osminor. The return value reflects the result of the comparison.

WARNING! Before this function is called, the version variables _osmajor and _osminor must be initialized with the current DOS version number. When using Spontaneous Assembly for C/C++, these variables are supplied and initialized by the compiler instead of the Spontaneous Assembly library.

C/C++ Example
	   switch (_cmp_version (0, 4))
	   {
	   case 1:/* Handle the dos version being later than 4.0 */
	      break;
	   case 0:/* Handle the dos version being 4.0 */
	      break;
	   case -1:/* Handle the DOS ver being earlier than 4.0 */
	      break;
	   }

Inline Assembly Example
	#include <inline.h>
	{
	   ...
	   mov al,0
	   mov ah,4
	   cmp_version ();
	    ja _main_010/* if DOS later than 4.0 */
	    jb _main_020/* if DOS earlier than 4.0 */
	   ... 	 	/* if DOS is 4.0 */
	   jmp short _main_030

	_main_010:
	   ... 	 	/* DOS version later than 4.0 */
	   jmp short _main_030

	_main_020:
	   ... 	 	/* DOS version earlier than 4.0 */
	_main_030:
	   ...
	}

Source file _MDCMPVR.ASM ASM equiv CMP_VERSION
See also
_chk_version, _chk_version, _get_version

_dos_errmsg


Descrip
Returns the offset of a DOS error message string.

Syntax
#include <miscdos.h>
char *_dos_errmsg(int e_code);

Returns
A pointer to the error message if e_code was found in the table.

NULL if e_code is invalid.

Notes
This function returns a pointer to the ASCIIZ error message string associated with the specified DOS error code (e_code). See Appendix A for a complete listing of DOS error codes and error messages.

C/C++ Example
	{
	   char *message;
	   _dos_errmsg (8);
	   ...
	}

Inline Assembly Example
	#include <inline.h>

	   mov ax,8
	   dos_errmsg ();/* DS:SI -> error message */
	   ...

Source file _MDDOSEM.ASM ASM equiv DOS_ERRMSG
See also
_dos_errmsg, _get_ecode

_dos_errmsge


Descrip
Returns the offset of the DOS error message string describing the most recent DOS error.

Syntax
#include <miscdos.h>
char *_dos_errmsge(void);

Returns
A pointer to the error message if e_code was found in the table.

NULL if e_code is invalid.

Notes
This function returns a pointer to the ASCIIZ error message string associated with the DOS error code in e_code. See Appendix A for a complete listing of DOS error codes and error messages.

C/C++ Example
	{
	   char *message;
	   _dos_errmsge ();
	   ...
	}

Inline Assembly Example
	#include <inline.h>

	   dos_errmsge ();    /* DS:SI -> error message */
	   ...

Source file _MDDSEME.ASM ASM equiv DOS_ERRMSGE
See also
_dos_errmsg, e_code

_dos_malloc


Descrip
Allocates a block of DOS memory.

Syntax
#include <miscdos.h>
segaddr _dos_malloc(unsigned int num);

Returns
Segment address (segaddr) of allocated block if successful.

NULL if an error occurred.
e_code error code

Notes
This function attempts to allocate a DOS memory block which is num paragraphs in size. If the allocation is successful, the segment address of the block is returned.

DOS memory blocks always start on paragraph boundaries and have one paragraph overhead.

e_code may be obtained using the _get_ecode function. Symbolic constants for e_code values are defined in Appendix A.

C/C++ Example
	{
	   segaddr heapseg = 0;
	   int newsize, reqsize = 100, blocksize;
	   heapseg = _dos_malloc (200);
	   ...
	   newsize = _dos_mset (heapseg, reqsize);
	   if (newsize != 0)
	   {
	      /* Handle DOS memory control block error */
	      if (newsize == reqsize)
	      {
	         /* insufficient memory to resize block to reqsize */
	      }
	   }
	   ...
	   blocksize = _dos_msize (heapseg);
	   ...
	   if (_dos_mfree (heapseg))
	   {
	      /* Handle error in freeing up memory */
	   }
	}

Inline Assembly Example
	#include <inline.h>
	{
	   ...
	   mov  ax,100
	   dos_malloc ();	/* DX -> allocated block */
	    jc main_030/* if an error occurred */
	   ...
	   mov  ax,200
	   dos_mset ();	/* AX = size of block */
	    jnc  main_020	/* if no error, continue */
	   ... 	 	/* not enough memory to resize */
	   jmp  short main_020
	main_020:
	   ...
	   dos_msize ();	/* AX = size of block at DX */
	   ...
	   dos_mfree ();	/* was block freed? */
	    jnc  main_030	/* y: continue */
	   ... 	 	/* n: error in freeing block */
	main_030:
	   ...
	}

Source file _MDDSMAL.ASM ASM equiv DOS_MALLOC
See also
_dos_mavail, _dos_mfree, _far_malloc

_dos_mavail


Descrip
Returns the size of the largest block of allocable memory.

Syntax
#include <miscdos.h>
unsigned int _dos_mavail(void);

Returns
Size of largest available DOS memory block, in paragraphs.

Notes
This function returns the size of the largest block of memory available to DOS for allocation. DOS memory blocks are allocated by calling _dos_malloc.

C/C++ Example
	{
	   unsigned int avail = _dos_mavail ();
	}

Inline Assembly Example
	#include <inline.h>
	   dos_mavail ();/* AX = # of free paragraphs */

Source file MDDOSMAV.ASM ASM equiv DOS_MAVAIL
See also
_dos_mfree, _far_max

_dos_mfree


Descrip
Frees a block of allocated memory.

Syntax
#include <miscdos.h>
int _dos_mfree(segaddr dosblk);

Returns
0 if dosblk was successfully freed.

-1 if dosblk couldn't be freed.
e_code error code

Notes
This function frees the DOS memory block at dosblk, making its memory available for subsequent allocation by _dos_malloc.

e_code may be obtained using the _get_ecode function. Symbolic constants for e_code values are defined in Appendix A.

C/C++ Example
	{
	   segaddr heapseg = 0;
	   int newsize, reqsize = 100, blocksize;
	   heapseg = _dos_malloc (200);
	   ...
	   newsize = _dos_mset (heapseg, reqsize);
	   if (newsize != 0)
	   {
	      /* Handle DOS memory control block error */
	      if (newsize == reqsize)
	      {
	         /* insufficient memory to resize block to reqsize */
	      }
	   }
	   ...
	   blocksize = _dos_msize (heapseg);
	   ...
	   if (_dos_mfree (heapseg))
	   {
	      /* Handle error in freeing up memory */
	   }
	}

Inline Assembly Example
	#include <inline.h>
	{
	   mov  ax,100
	   dos_malloc ();	/* DX -> allocated block */
	    jc main_030/* if an error occurred */
	   ...
	   mov  ax,200
	   dos_mset ();	/* AX = size of block */
	    jnc  main_020	/* if no error, continue */
	   ... 	 	/* not enough memory to resize */
	   jmp  short main_020
	main_020:
	   ...
	   dos_msize ();	/* AX = size of block at DX */
	   ...
	   dos_mfree ();	/* was bloc freed? */
	    jnc  main_030	/* y: continue */
	   ... 	 	/* n: error in freeing block */
	main_030:
	   ...
	}

Source file _MDDSMFR.ASM ASM equiv DOS_MFREE
See also
_dos_malloc, _far_free

_dos_mset


Descrip
Modifies the size of a block of memory.

Syntax
#include <miscdos.h>
unsigned int _dos_mset(segaddr dosblk, unsigned int new_size);

Returns
0 if the size of dosblk was modified successfully.

Maximum allowed size of dosblk (in paragraphs) if an error occurred.
e_code error code

Notes
This function modifies the size of the allocated DOS memory block at dosblk. 0 is returned if the block size is successfully modified. If the block size cannot be adjusted to the requested size, the new size of the block (in paragraphs) is returned and an error code is returned in e_code.

WARNING! Due to DOS limitations, this function modifies the size of the memory block even if an insufficient memory error occurs while growing the block ( e_code = E_INSMEM).

e_code may be obtained using the _get_ecode function. Symbolic constants for e_code values are defined in Appendix A.

C/C++ Example
	{
	   segaddr heapseg = 0;
	   int newsize, reqsize = 200, blocksize;
	   heapseg = _dos_malloc (100);
	   ...
	   newsize = _dos_mset (heapseg, reqsize);
	   if (newsize != 0)
	   {
	      /* insufficient enough memory to resize block to reqsize */
	   }
	   ...
	   blocksize = _dos_msize (heapseg);
	   ...
	   if (_dos_mfree (heapseg))
	   {
	      /* error in freeing up memory */
	   }
	}

Inline Assembly Example
	#include <inline.h>
	{
	   mov  ax,100
	   dos_malloc ();	/* DX -> allocated block */
	    jc main_030/* if an error occurred */
	   ...
	   mov  ax,200
	   dos_mset ();	/* AX = size of block */
	    jnc  main_020	/* if no error, continue */
	   ... /* insufficient memory to resize block to reqsize */
	   jmp  short main_020
	main_020:
	...
	dos_msize ();	 /* AX = size of block at DX */
	...
	dos_mfree ();	 /* was block freed? */
	 jnc  main_030	 /* y: continue */
	...    	 /* n: error in freeing block */
	main_030:
	...
	}

Source file _MDDSMST.ASM ASM equiv DOS_MSET
See also
_far_realloc

_dos_msize


Descrip
Gets the size of a block of memory.

Syntax
#include <miscdos.h>
unsigned int _dos_msize(segaddr dosblk);

Returns
The size (in paragraphs) of the memory block at dosblk.

Notes
This function returns the size, in paragraphs, of the DOS memory block at dosblk. The returned size is undefined if dosblk is an invalid DOS memory block address.

_dos_msize examines DOS memory blocks directly since no DOS function call is provided to determine the size of a memory block.

C/C++ Example
	{
	   segaddr heapseg = 0;
	   int newsize, reqsize = 100, blocksize;
	   heapseg = _dos_malloc (200);
	   ...
	   newsize = _dos_mset (heapseg, reqsize);
	   if (newsize == 0)
	   {
	      /* Handle DOS memory control block error */
	   }
	   if (newsize != reqsize)
	   {
	      /* insufficient memory to resize block to reqsize */
	   }
	   ...
	   blocksize = _dos_msize (heapseg);
	   ...
	   if (_dos_mfree (heapseg))
	   {
	      /* Handle error in freeing up memory */
	   }
	}

Inline Assembly Example
	#include <inline.h>
	{
	   mov  ax,100
	   dos_malloc ();	/* DX -> allocated block */
	    jc main_030/* if an error occurred */
	   ...
	mov  ax,200
	dos_mset ();	 /* AX = size of block */
	 jnc  main_020	 /* if no error, continue */
	... /* insufficient memory to resize block to reqsize */
	jmp  short main_020
	main_020:
	...
	dos_msize ();	 /* AX = size of block at DX */
	...
	dos_mfree ();	 /* was block freed? */
	 jnc  main_030	 /* y: continue */
	...    	 /* n: error in freeing block */
	main_030:
	...
	}

Source file _MDDSMSZ.ASM ASM equiv DOS_MSIZE

_dta_restore


Descrip
Restores the Disk Transfer Address (DTA).

Syntax
#include <miscdos.h>
void _dta_restore(void);

Returns
None

Notes
This function restores the Disk Transfer Address to the address which was in effect when _dta_save was called. If _dta_save was not previously called, the resulting Disk Transfer Address is undefined.

C/C++ Example
	{
	   void far *dta;
	   ...
	   _dta_save ();
	   _set_dta (dta);
	   ...
	   _dta_restore ();
	}

Inline Assembly Example
	#include <inline.h>
	{
	void far *dta;
	   ...
	   dta_save ();
	   les di,dta
	   set_dta ();
	   ...
	   dta_restore ();
	}

Source file MDDTASAV.ASM ASM equiv DTA_RESTORE
See also
_dta_save, _get_dta, _set_dta

_dta_save


Descrip
Saves the current Disk Transfer Address (DTA).

Syntax
#include <miscdos.h>
void _dta_save(void);

Returns
None

Notes
This function determines the current Disk Transfer Address and saves it for later restoration using _dta_restore.

C/C++ Example
	{
	   void far *dta;
	   ...
	   _dta_save ();
	   _set_dta (dta);
	   ...
	   _dta_restore ();
	}

Inline Assembly Example
	#include <inline.h>
	{
	   void far *dta;
	   ...
	   dta_save ();
	   les di,dta
	   set_dta ();
	   ...
	   dta_restore ();
	}

Source file MDDTASAV.ASM ASM equiv DTA_SAVE
See also
_dta_restore, _get_dta, _set_dta

e_code


Descrip
(Variable) Contains the most recent error code.

Syntax
#include <miscdos.h>
extern int e_code;

Notes
This int variable contains the error code which resulted from the last DOS function call error. It is defined in DGROUP (global or static non-far data) and can be accessed directly or via the _get_ecode function.

e_code is initialized to -1.

Source file MDECODE.ASM ASM equiv E_CODE
See also
_dos_errmsg, _get_ecode

_get_cbrk


Descrip
Returns the state of the DOS ctrl-break flag.

Syntax
#include <miscdos.h>
char _get_cbrk(void);

Returns
The state of the dos control-break flag.

Notes
This function returns the state of the DOS ctrl-break flag.

Constants which describe the state of the ctrl-break flag are defined in MISCDOS.H, as follows:

BRK_OFF (0x00) Ctrl-break checking OFF
BRK_ON (0x01) Ctrl-break checking ON

WARNING! DOS always checks for ctrl-break events whenever I/O is performed using a standard input or output function, even if the ctrl-break flag is clear. The DOS ctrl-break flag only indicates whether or not ctrl-break checking is performed during any DOS function call. If ctrl-break checking must be completely disabled, _cbrk_disable must be used.

This occurs even if _cbrk_disable is called. Calling _cbrk_disable, however, will prevent the ctrl-break handler from receiving control.

C/C++ Example
	   if (_get_cbrk ())
	   {
	      /* handle control break checking ON */
	   } else
	   {
	      /* handle control break checking OFF */
	   }

Inline Assembly Example
	#include <inline.h>
	   get_cbrk ();	/* AL=cbrk status */
	   cmp al,0
	    je get_cbrk_010/* if cbrk checking OFF */
	   ... 	 	/* if cbrk checking ON */
	   jmp short get_cbrk_020

	get_cbrk_010:
	   ... 	 	/* control break checking OFF */
	get_cbrk_020:
	   ...
	}

Source file MDCBKGET.ASM ASM equiv GET_CBRK
See also
_cbrk_save, _set_cbrk

_get_cdfree


Descrip
Gets the amount of free disk space on the current drive.

Syntax
#include <miscdos.h>
long int _get_cdfree(void);

Returns
The amount of free disk space on the current drive, in bytes.

-1 if the function was unsuccessful.

Notes
This function calculates the free disk space on the current drive from the drive's File Allocation Table information. The free disk space is calculated in bytes. -1 is returned if the current drive is invalid or if a critical error occurred.

C/C++ Example
	{
	   long int disk_free = _get_cdfree ();
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	   get_cdfree ();	/* DX;AX = free space */
	    jncget_cdfree_010/* if successful */
	   ... 	 	/* if an error occurred */
	   jmp short get_cdfree_020

	get_cdfree_010:
	   ...
	get_cdfree_020:
	   ...

Source file _MDCDFRE.ASM ASM equiv GET_CDFREE
See also
_get_cdinfo, _get_dfree

_get_cdinfo


Descrip
Gets File Allocation Table (FAT) information for the current drive.

Syntax
#include <miscdos.h>
int _get_cdinfo(disk_info *buffer);

Returns
0 if the function was successful.
buffer information about the current drive

-1 if the function was unsuccessful.

Notes
This function returns File Allocation Table information about the current drive in buffer. -1 is returned if a critical error occurred.

The disk_info structure is defined in MISCDOS.H as follows:

typedef struct {
unsigned char s_clus;/* sectors per cluster */
unsigned char media; /* media type (see below) */
unsigned int b_sec; /* bytes per sector */
unsigned int clusters;/* number of clusters */
} disk_info;

The following symbolic constants (defined in MISCDOS.H) represent the various media ID values that may be returned:

HARD_DISK (0xF8) Hard/fixed disk
FLOPPY_3D18(0xF0) Floppy 3.5 double sided 18 sector
FLOPPY_3D9 (0xF9) Floppy 3.5 double sided 9 sector
FLOPPY_5D15(0xF9) Floppy 5.25 double sided 15 sector
FLOPPY_5S9 (0xFC) Floppy 5.25 single sided 9 sector
FLOPPY_5D9 (0xFD) Floppy 5.25 double sided 9 sector
FLOPPY_5S8 (0xFE) Floppy 5.25 single sided 8 sector
FLOPPY_5D8 (0xFF) Floppy 5.25 double sided 8 sector
FLOPPY_OTHER(0xF0) Floppy disk other

A media ID value of 0xF8 indicates that the current drive is a hard disk; any other number indicates that the current drive is a removable media device.

C/C++ Example
	{
	   disk_info dinfo;
	   if (_get_cdinfo (&dinfo))
	   {
	      /* Handle error obtaining information on current drive */
	   } else
	   {
	      ...
	   }
	}

Inline Assembly Example
	#include <inline.h>
	   ...
	   get_cdinfo ();	/* AX,CX,DX contains info */
	    jncmain_010/* if successful */
	   ... 	 	/* if an error occurred */
	   jmp short main_020

	main_010:
	   ... 	 	/* process disk info */
	main_020:
	   ...

Source file _MDCDINF.ASM ASM equiv GET_CDINFO
See also
_get_dinfo

_get_cdsize


Descrip
Gets the disk size for the current drive.

Syntax
#include <miscdos.h>
long int _get_cdsize(void);

Returns
The size of the current drive, in bytes, if the disk size was obtained.

-1 if the function was unsuccessful.

Notes
This function returns the total disk size for the current drive. The disk size is calculated in bytes. -1 is returned if the current drive is invalid or if a critical error occurred.

C/C++ Example
	{
	   long int disk_size = _get_cdsize ();
	   ...
	}

Inline Assembly Example
	#include <inline.h>

	   get_cdsize ();	/* DX;AX = disk size */
	    jncmain_010/* if successful */
	   ... 	 	/* if an error occurred */
	   jmp short main_020

	main_010:
	   ... 	 	/* process disk size */
	main_020:
	   ...

Source file _MDCDSIZ.ASM ASM equiv GET_CDSIZE
See also
_get_dsize

_get_countryinfo


Descrip
Gets the current DOS country information.

Syntax
#include <miscdos.h>
country *_get_countryinfo(unsigned int cntrycode, country *buffer, unsigned int *rcode);

Returns
A pointer to buffer if the country information was successfully determined.
buffer country information
rcode country code for the retrieved country information

NULL if the function was unsuccessful.
rcode undefined
ecode DOS error code

Notes
This function returns a pointer to buffer, which contains the current DOS country information for cntrycode. A country code of zero returns information for the current country. The information is returned in buffer in the form of a dcountry structure. If the country information is available, the country code is returned in rcode and a pointer is returned to buffer. Otherwise, NULL is returned and the contents of rcode are undefined.

Valid cntrycode values are found in DOS user manuals for DOS 4.x and above and in many programming reference manuals.

The dcountry structure is defined in MISCDOS.H as follows:

typedef struct {
int cntry_dtformat; /* date format */
char cntry_curstr[5];/* currency symbol (ASCIIZ) */
char cntry_thdelim[2];/* thousand delimiter (ASCIIZ) */
char cntry_decdelim[2];/* decimal delimiter (ASCIIZ) */
char cntry_dtdelim[2];/* date delimiter (ASCIIZ) */
char cntry_tmdelim[2];/* time delimiter (ASCIIZ) */
char cntry_curloc; /* currency symbol location */
char cntry_cdigits; /* digits after decimal point */
/* for currency */
char cntry_tmformat; /* time format 12/24 hour */
long cntry_case; /* case map */
char cntry_datadelim[2];/* data delimiter (ASCIIZ) */
char cntry_reserved[10];/* DOS (reserved) */
} dcountry;

The following symbolic constants may be used to check or modify the information in the cntry_dtformat field (these equates are defined in MISCDOS.H):

CDATE_MDY (0x0000) For USA (MONTH/DAY/YEAR)
CDATE_DMY(0x0001) For European (DAY/MONTH/YEAR)
CDATE_YMD(0x0002) For Japanese (YEAR/MONTH/DAY)

The following symbolic constants may be used to check or modify the information in the cntry_curloc field (these equates are defined in MISCDOS.H):

CURR_PN (0x00) Currency symbol precedes the value. There are no spaces between the currency symbol and the value.
CURR_FN (0x01) Currency symbol follows the value. There are no spaces between the currency symbol and the value.
CURR_P1 (0x02) Currency symbol precedes the value. There is one space between the currency symbol and the value.
CURR_F1 (0x03) Currency symbol follows the value. There is one space between the currency symbol and the value.
CURR_R (0x04) Currency symbol replaces the decimal delimiter.

The following symbolic constants may be used to check or modify the information in the cntry_tmformat field (these equates are defined in MISCDOS.INC):

CTIME_12HR (0x00) For 12-hour clock.
CTIME_24HR (0x01) For 24-hour clock.

Spontaneous Assembly functions do not depend on the data in the dcountry structure. Instead, Spontaneous Assembly formatting functions use the global dcopts and dtcopts structures, which may be initialized to country-specific settings by calling _dtc_init and _dc_init, respectively.

e_code may be obtained using the _get_ecode function. Symbolic constants for e_code values are defined in Appendix A.

DOS version 2.x returns the country information in a different format than DOS version 3.0 and above. The conversion to dcountry format is handled internally by this function.

WARNING! Before using this function, _osmajor must be properly initialized or the structure will not be correctly initialized. When using Spontaneous Assembly For C/C++, this variable is supplied and initialized by the compiler instead of the Spontaneous Assembly library.

C/C++ Example
	{
	   unsigned int rcode;
	   char buffer[sizeof(dcountry)], decbuf[20];
	   dcountry *cntry;
	   ...
	   if((cntry = _get_countryinfo(0, buffer, &rcode)) == NULL)
	      _put_str("Unable to retrieve country information");
	   else
	      _put_str(_ui_to_dec(rcode, decbuf)); /* display code */
	   ...

	}

Inline Assembly Example
	#include <inline.h>
	{
	   char buffer[sizeof(dcountry)], decbuf[20];
	   ...
	   xor ax,ax	/* specify current cntry */
	   lea si,buffer/* SI -> country info buf */
	   get_countryinfo();/* get current cntry info */
	    jc label_010
	   lea si,decbuf/* SI -> conversion buf */
	   ui_to_dec();	/* int -> ASCII */
	   put_str();	/* display code */
	label_010:
	   ...
	}

Source file _MDGCTRY.ASM ASM equiv GET_COUNTRYINFO
See also
_set_country

_get_dfree


Descrip
Gets the free disk space on a specified drive.

Syntax
#include <miscdos.h>
long int _get_dfree(int drive);

Returns
The number of free bytes on drive.

-1 if an error occurred.

Notes
This function calculates the free disk space on the specified drive using drive's File Allocation Table information. drive must be a valid drive letter ('A' through 'z'). The free disk space is calculated in bytes. -1 is returned if drive is invalid or if a critical error occurred.

C/C++ Example
	{
	   long int disk_free;
	   disk_free = _get_dfree ('C');
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	   ...
	   mov al,'C'
	   get_dfree ();	/* DX;AX = free space */
	    jncmain_010/* if successful */
	   ... 	 	/* if an error occurred */
	   jmp short main_020
	main_010:
	   ...
	main_020:
	   ...

Source file _MDDFREE.ASM ASM equiv GET_DFREE
See also
_get_cdfree, _get_dinfo

_get_dinfo


Descrip
Gets File Allocation Table (FAT) information about the specified drive.

Syntax
#include <miscdos.h>
int _get_dinfo(int drive, disk_info *buffer);

Returns
0 if the function was successful.
buffer information about drive

-1 if an error occurred.

Notes
This function places File Allocation Table information about drive in buffer. drive must be a drive letter ('A' through 'z'). -1 is returned if drive is an invalid drive letter or if a critical error occurred.

The disk_info structure is defined in MISCDOS.H as follows:

typedef struct {
unsigned char s_clus;/* sectors per cluster */
unsigned char media; /* media type (see below) */
unsigned int b_sec; /* bytes per sector */
unsigned int clusters;/* number of clusters */
} disk_info;

The following symbolic constants (defined in MISCDOS.H) represent the various media ID values that may be returned:

HARD_DISK (0xF8) Hard/fixed disk
FLOPPY_3D18(0xF0) Floppy 3.5 double sided 18 sector
FLOPPY_3D9 (0xF9) Floppy 3.5 double sided 9 sector
FLOPPY_5D15(0xF9) Floppy 5.25 double sided 15 sector
FLOPPY_5S9 (0xFC) Floppy 5.25 single sided 9 sector
FLOPPY_5D9 (0xFD) Floppy 5.25 double sided 9 sector
FLOPPY_5S8 (0xFE) Floppy 5.25 single sided 8 sector
FLOPPY_5D8 (0xFF) Floppy 5.25 double sided 8 sector
FLOPPY_OTHER(0xF0) Floppy disk other

C/C++ Example
	{
	   disk_info dinfo;
	   if (_get_dinfo ('C', &dinfo) == -1)
	   {
	      .../* error obtaining information on drive C */
	   } else
	   {
	      .../* drive info return successfully */
	   }
	}

Inline Assembly Example
	#include <inline.h>
	   ...
	   mov al,'C'
	   get_dinfo ();	/* AX,CX,DX contains info */
	    jncget_dinfo_010/* if successful */
	   ... 	 	/* if an error occurred */
	   jmp short get_dinfo_020

	get_dinfo_010:
	   ... 	 	/* process disk info */
	get_dinfo_020:
	   ...

Source file _MDDINFO.ASM ASM equiv GET_DINFO
See also
_get_cdinfo

_get_dsize


Descrip
Gets the disk size for a specified drive.

Syntax
#include <miscdos.h>
long int _get_dsize(int drive);

Returns
The size of drive, in bytes.

-1 if the function was unsuccessful.

Notes
This function returns the total disk size, in bytes, for the specified drive. drive must be a valid drive letter ('A' through 'z'). -1 is returned if drive is an invalid drive letter or if a critical error occurred.

C/C++ Example
	{
	   long int disk_size;
	   ...
	   disk_size = _get_dsize ('C');
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	   ...
	   mov al,'C'
	   get_dsize ();	/* DX;AX = disk size */
	    jncmain_010/* if successful */
	   ... 	 	/* if an error occurred */
	   jmp short main_020
	main_010:
	   ...
	main_020:
	   ...

Source file _MDDSIZE.ASM ASM equiv GET_DSIZE
See also
_get_cdsize

_get_dta


Descrip
Gets the disk transfer address (DTA).

Syntax
#include <miscdos.h>
void far *_get_dta(void);

Returns
A pointer to the current DTA.

Notes
This function returns the current Disk Transfer Address from DOS.

The DTA is also stored in an internal variable for use by _find_first and _find_next.

C/C++ Example
	{
	   void far *dta;
	   dta = _get_dta();
	}

Inline Assembly Example
	#include <inline.h>
	   ...
	   get_dta ();/* ES:DI = addr of DTA */
	   ...

Source file _MDDTGET.ASM ASM equiv GET_DTA
See also
_dta_restore, _dta_save, _set_dta

_get_ecode


Descrip
Returns the value of e_code.

Syntax
#include <miscdos.h>
int _get_ecode(void);

Returns
The current value of the e_code global variable.

Notes
This function returns the current value of e_code. This value represents the error code returned by the last failed DOS function call in a Spontaneous Assembly function.

C/C++ Example
	{
	   int error_code = _get_ecode ();
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	   ...
	   get_ecode ();/* AX = error code */
	   ...

Source file MDGECODE.ASM ASM equiv GET_ECODE
See also
_dos_errmsg, e_code

_get_lastdrive


Descrip
Gets the total number of logical drives.

Syntax
#include <miscdos.h>
char _get_lastdrive(void);

Returns
The number of logical drives.

Notes
This function returns the total number of logical drives in the system or the value of LASTDRIVE from the CONFIG.SYS file, whichever is greater.

This function returns a number instead of a letter because many networks support more than 26 logical drives.

C/C++ Example
	{
	   char lastdrive;
	   lastdrive = _get_lastdrive ();
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	   ...
	   get_lastdrive ();
	   	  /* AL = number of logical drives */
	   ...

Source file MDGLSTDR.ASM ASM equiv GET_LASTDRIVE
See also
_get_drive

_get_vect


Descrip
Gets an interrupt handler address.

Syntax
#include <miscdos.h>
void (interrupt far * _get_vect (int intnum))();

Returns
Address of the interrupt routine.

Notes
This function returns the address of the interrupt handler which is currently servicing intnum. The interrupt handler address is obtained by issuing a DOS function call.

C/C++ Example
	{
	   void (interrupt far *int_handler)();
	   int_handler = _get_vect(0x24);
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	   ...
	   mov bl,0x24
	   get_vect ();/* DX:AX -> interrupt routine */
	   ...

Source file _MDGVECT.ASM ASM equiv GET_VECT
See also
_get_vec, _set_vec

_get_verify


Descrip
Gets the state of the DOS verify flag.

Syntax
#include <miscdos.h>
char _get_verify(void);

Returns
The current verify flag state.

Notes
This function returns the current state of the DOS verify flag. When verify is off, disk writes are not verified; when verify is on, all disk writes are verified to ensure that data is properly written.

The following symbolic constants (defined in MISCDOS.H) describe the state of the verify flag:

VER_OFF (0x00) Disk writes are not verified
VER_ON (0x01) Disk writes are verified

C/C++ Example
	{
	   if (_get_verify ())
	   {
	      /* Verify is ON */
	   } else
	   {
	      /* Verify is OFF */
	   }
	}

Inline Assembly Example
	#include <inline.h>
	   ...
	   get_verify ();/* AL = state of verify flag */
	   ...

Source file MDGVERIF.ASM ASM equiv GET_VERIFY
See also
_set_verify, _verify_save

_get_version


Descrip
Gets the current DOS version number.

Syntax
#include <miscdos.h>
void _get_version(char *minor, char *major);

Returns
No return value.
minor minor DOS version number
major major DOS version number
_osminor minor DOS version number
_osmajor major DOS version number

Notes
This function determines which version of DOS is currently active and indicates the major version number in major and the minor version number in minor. The version number is then used to initialize _osmajor and _osminor. The major and minor version numbers are returned as origin zero values. The minor version number is treated as a two digit number (i.e., DOS version 3.31 would be indicated with a major version of 0x03 and a minor version of 0x1F).

When using Spontaneous Assembly For C/C++, the _osmajor and _osminor variables are supplied and initialized by the compiler instead of the Spontaneous Assembly library.

C/C++ Example
	{
	   char major, minor;
	   _get_version (&minor, &major);
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	   ...
	   get_version (); /* AL=minor version number, 
	   	  	   AH=major version number */
	   ...

Source file _MDGVERS.ASM ASM equiv GET_VERSION
See also
_chk_version, _chk_version, _cmp_version

_set_cbrk


Descrip
Sets or clears the DOS ctrl-break flag.

Syntax
#include <miscdos.h>
void _set_cbrk(int state);

Returns
None

Notes
This function sets the DOS ctrl-break flag to the indicated state. The results are undefined if state is invalid.

Constants which describe the state of the ctrl-break flag are defined in MISCDOS.H as follows:

BRK_OFF (0x00) Ctrl-break checking OFF
BRK_ON (0x01) Ctrl-break checking ON

WARNING! DOS always checks for ctrl-break events whenever I/O is performed using a standard input or output function, even if the ctrl-break flag is clear. The DOS ctrl-break flag only indicates whether or not ctrl-break checking is performed during any DOS function call. If ctrl-break checking must be completely disabled, _cbrk_disable must be used. Note that functions which use DOS function calls 0x09 and 0x0A may be affected by ctrl-C events (^C and a newline are displayed). This occurs even if _cbrk_disable is called. Calling _cbrk_disable, however, will prevent the ctrl-break handler from receiving control.

C/C++ Example
	   _set_cbrk (BRK_OFF);/* Turn control-break checking off */
	   ...
	   _set_cbrk (BRK_ON);/* Turn control-break checking back on */

Inline Assembly Example
	#include <inline.h>
	mov al,0
	set_cbrk ();/* Turn control-break checking off */
	...
	mov al,1
	set_cbrk ();/* Turn control-break checking back on */
	...

Source file _MDCBSET.ASM ASM equiv SET_CBRK
See also
_cbrk_restore, _get_cbrk

_set_country


Descrip
Sets the current DOS country code (DOS 3.0 or above).

Syntax
#include <miscdos.h>
int _set_country(unsigned int cntrycode);

Returns
0 if the country was successfully selected.

-1 if the function was unsuccessful.
e_code error code

Notes
This function selects the country assigned to cntrycode as the new "current DOS country." 0 is returned if the specified country was successfully selected as the current country. If an invalid country code is used, or if the DOS version is less than 3.0, -1 is returned and an error code is returned in e_code.

Valid cntrycode values are found in DOS user manuals for DOS 4.x and above and in many programming reference manuals.

This function does NOT affect the Spontaneous Assembly data conversion or date/time formatting functions. Instead, _dtc_init and _dc_init should be used for this purpose. Current country information may be retrieved into a specified dcountry structure by calling _get_countryinfo.

e_code may be obtained using the _get_ecode function. Symbolic constants for e_code values are defined in Appendix A.

WARNING! Before using this function, _osmajor must be properly initialized or cntrycode will not be set correctly. When using Spontaneous Assembly For C/C++, this variable is supplied and initialized by the compiler instead of the Spontaneous Assembly library.

C/C++ Example
	   ...
	   if(_set_country(31) == -1)
	      _put_str("Unable to select Netherlands country info");
	   ...

Inline Assembly Example
	#include <inline.h>
	{
	   char *sptr;
	   ...
	   mov ax,3
	   set_country();
	    jc label_100
	   sptr = "Unable to select Latin America country info";
	   mov si,sptr
	   put_str();	/* display error message */
	label_100:
	   ...
	}

Source file _MDSCTRY.ASM ASM equiv SET_COUNTRY
See also
_dc_init, _dtc_init, _get_countryinfo

_set_dta


Descrip
Sets the disk transfer address (DTA).

Syntax
#include <miscdos.h>
void _set_dta(void far *dtaddr);

Returns
None

Notes
This function sets the Disk Transfer Address to dtaddr. dtaddr is also saved in an internal variable for use by _find_first and _find_next.

C/C++ Example
	{
	   void far *dta;
	   ...
	   _dta_save ();
	   _set_dta (dta);
	   ...
	   _dta_restore ();
	}

Inline Assembly Example
	#include <inline.h>
	{
	   void far *dta;
	   ...
	   dta_save ();
	   les di,dta
	   set_dta ();
	   ...
	   dta_restore ();
	   }

Source file _MDDTSET.ASM ASM equiv SET_DTA
See also
_dta_restore, _dta_save, _get_dta

_set_vect


Descrip
Sets an interrupt handler address.

Syntax
#include <miscdos.h>
void _set_vect(int intnum, intaddr new_int);

Returns
None

Notes
This function sets the address of the interrupt handler for intnum to new_int. The interrupt handler address is set by issuing a DOS function call.

See the _isr_... functions for flexible, high-level alternatives to the use of this function.

new_int should be cast as intaddr when calling this function. This prevents the compiler from generating assembly language SEG instructions, which preclude the use of .COM format in the TINY memory model. Some compilers also require type casting of interrupt functions in parameter lists to eliminate spurious compiler errors.

C/C++ Example
	void interrupt far ce_handler (int bp, int di, int si, int ds,
	   	  	 	int es, int dx, int cx, int bx, 
	   	  	 	int ax, int ip, int cs, 
	   	  	 	int flags);
	/* setup critical error handler
	{
	   /* handle the critical error here */
	}
	{
	   void (interrupt far *int_handler)();
	   int_handler = _get_vect (0x24);
	   /* get current interrupt function address */
	   _set_vect (0x24, (intaddr) ce_handler);
	   /* set vector to new int handler */
	   ...
	   _set_vect (0x24, (intaddr) int_handler);
	   /* restore vector to previous interrupt function */
	}

Inline Assembly Example
	#include <inline.h>
	void interrupt far ce_handler (int bp, int di, int si, int ds,
	   	  	 	int es, int dx, int cx, int bx,
	   	  	 	int ax, int ip, int cs, 
	   	  	 	int flags)
	   	  /* setup critical error handler
	{
	   	  /* handle the critical error here */
	}
	   mov  bl,0x24
	   get_vect ();	/* DX:AX = current interrupt 
	   	  	 	   function address */
	   push dx 	    /* save address */
	   push ax
	#if __TINY__
	   mov  dx,cs
	#else
	   mov  dx,seg ce_handler
	#endif
	   mov  ax,offset ce_handler/* DX:AX = new interrupt 
	   	  	 	    handler address */
	   set_vect ();/* set the vector to new int handler */
	   ...
	   pop  ax 	/* restore previous interrupt address */
	   pop  dx
	   set_vect ();/* restore previous interrupt function */
	   ...
	}

Source file _MDSVECT.ASM ASM equiv SET_VECT
See also
_get_vec, _isr_getstat, _isr_hremove, _isr_install, _isr_remove, _isr_remove, _set_vec

_set_verify


Descrip
Sets or clears the DOS verify flag.

Syntax
#include <miscdos.h>
void _set_verify(int newstate);

Returns
None

Notes
This function sets the state of the DOS verify flag to newstate. When verify is off, disk writes are not verified; when verify is on, all disk writes are verified to ensure that data is properly written.

The following symbolic constants (defined in MISCDOS.INC) may be used to specify the state of the verify flag:

VER_OFF (0x00) Disk writes are not verified
VER_ON(0x01) Disk writes are verified

C/C++ Example
	{
	   _verify_save ();
	   ...
	   _set_verify (1);/* turn verify on */
	   ...
	   _set_verify (0);/* turn verify off */
	   ...
	   _verify_restore ();
	}

Inline Assembly Example
	#include <inline.h>
	   ...
	   verify_save ();
	   ...
	   mov al,1
	   set_verify ();	/* turn verify on */
	   ...
	   mov al,0
	   set_verify ();	/* turn verify off */
	   ...
	   verify_restore ();

Source file _MDSVERF.ASM ASM equiv SET_VERIFY
See also
_get_verify, _verify_restore

_verify_off


Descrip
Disables DOS write verification.

Syntax
#include <miscdos.h>
void _verify_off(void);

Returns
None

Notes
This function clears the DOS verify flag, disabling verification of disk writes.

C/C++ Example
	   _verify_off ()

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

Source file MDVEROFF.ASM ASM equiv VERIFY_OFF
See also
_set_verify, _verify_on

_verify_on


Descrip
Enables DOS write verification.

Syntax
#include <miscdos.h>
void _verify_on(void);

Returns
None

Notes
This function sets the DOS verify flag, enabling verification of disk writes.

C/C++ Example
	   _verify_on ()

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

Source file MDVERON.ASM ASM equiv VERIFY_ON
See also
_set_verify, _verify_off

_verify_restore


Descrip
Restores the original state of the DOS verify flag.

Syntax
#include <miscdos.h>
void _verify_restore(void);

Returns
None

Notes
This function restores the DOS verify flag to the state which was in effect when _verify_save was called. If _verify_save was not previously called, the resulting state of the DOS verify flag is undefined.

_verify_save is usually called soon after the program begins execution. This saves the state of the DOS ctrl-break flag before it is changed by _set_verify, _verify_on, or _verify_off. _verify_restore is then called just before the program terminates to restore the DOS verify flag to its original state. If this is not done, the program may alter the verify status for subsequent programs.

C/C++ Example
	{
	   _verify_save ();
	   ...
	   _set_verify (1);/* turn verify on */
	   ...
	   _set_verify (0);/* turn verify off */
	   ...
	   _verify_restore ();
	}

Inline Assembly Example
	#include <inline.h>
	   verify_save ();
	   ...
	   mov al,1
	   set_verify ();	/* turn verify on */
	   ...
	   mov al,0
	   set_verify ();	/* turn verify off */
	   ...
	   verify_restore ()
	   ...

Source file MDVERSAV.ASM ASM equiv VERIFY_RESTORE
See also
_verify_save

_verify_save


Descrip
Saves the current state of the DOS verify flag.

Syntax
#include <miscdos.h>
void _verify_save(void);

Returns
None

Notes
This function determines the current state of the DOS verify flag and saves it for later restoration using _verify_restore.

_verify_save is usually called soon after the program begins execution. This saves the state of the DOS ctrl-break flag before it is changed by _set_verify, _verify_on, or _verify_off. _verify_restore is then called just before the program terminates to restore the DOS verify flag to its original state. If this is not done, the program may alter the verify status for subsequent programs.

C/C++ Example
	{
	   _verify_save ();
	   ...
	   _set_verify (1);/* turn verify on */
	   ...
	   _set_verify (0);/* turn verify off */
	   ...
	   _verify_restore ();
	}

Inline Assembly Example
	#include <inline.h>
	   verify_save ();
	   ...
	   mov al,1
	   set_verify ();	/* turn verify on */
	   ...
	   mov al,0
	   set_verify ();	/* turn verify off */
	   ...
	   verify_restore ()

Source file MDVERSAV.ASM ASM equiv VERIFY_SAVE
See also
_verify_restore