Calling Macros in DOS.INC and BIOS.INC
You are responsible for saving and restoring registers used in
macros. The "Registers used" field identifies registers to save.
Macros that accept address parameters use internal macros that
allow you to specify addresses in several ways. The macro
automatically identifies the type of the argument and handles it
appropriately. For example, assume the following declarations:
String DB "test$"
pString DW Str
fpString DD Str
Given these values, the macro @DispStr (which displays the string
at DS:DX) has the following effects:
Kind of argument Example Value loaded
Label of byte variable @DispStr String DS:OFFSET String
Near pointer variable @DispStr pString DS:pString
Far pointer variable @DispStr fpString fpString[2]:fpString[0]
Constant @DispStr 0 DS:0
Pointer in register @DispStr si DS:SI
Near Pointer with segment @DispStr pString,es ES:pString
Constant with segment @DispStr 0,es ES:0
Register with segment @DispStr di,es ES:DI
Note that if a far pointer or a segment is given, DS must be
saved before the macro call and restored afterward. Segments may
be given as registers, constants, or word variables.
In syntax, parameters enclosed in brackets are optional.
Paramaters sometimes have a leading symbol to indicate that the
argument must have a certain type, as shown below:
Leading Symbol Example Limitation
# #return Must be constant
& &vector Must be offset address as described above
$ $terminator May be constant or register, but not memory
Parameters with no leading symbol may be constants, registers, or
variables. Parameters are 16-bit except where noted in the description.
Symbols must be previously defined before they can be passed as
arguments to most of the DOS macros. Generally this means that
data must be declared before code in the source file.
DOS Macro Syntax and Description
KEYBOARD INPUT
@GetKey (01h, 07h, 08h, 0Ch)
Gets a keystroke from the keyboard
Syntax: @GetKey [#echo] [,[#break] [,#clearbuf]]
Arguments: echo = nonzero to echo keystroke - default yes
break = nonzero to accept Control-C - default yes
clearbuf = nonzero to clear keyboard buffer - default no
(Arguments may be omitted to get defaults)
Return: ASCII code of key in AL
Registers used: AX used for all, DL used if echo on and ctrl-c off
@GetStr (0Ah)
Gets a string from the keyboard
Syntax: @GetStr &buffer [,[$terminator] [,[#limit] [,segment]]]
Arguments: buffer = Offset of buffer where string will be stored
Byte 1 = Maximum length of string (before call)
Byte 2 = Actual length of string (after call)
Byte 3+ = Bytes of string
terminator = Terminating byte - usually null (0) or $ (24h)
limit = Maximum length of string (if not given as
argument, must be in buffer before macro call)
segment = Segment of buffer (DS if not given)
Return: Pointer to string in SI, length of string in BX
Registers used: AX, DX, BX, SI
OUTPUT
@DispCh (02h)
Displays one or more characters to screen
Syntax: @DispCh char [,char]...
Arguments: char = 8-bit ASCII code
Return: Code in AL
Registers used: AX and DL
@PrtCh (05h)
Prints one or more characters to LPT1
Syntax: @PrtCh char [,char]...
Arguments: char = 8-bit ASCII code
Return: Code in AL
Registers used: AX and DL
@DispStr (09h)
Displays a $-terminated string
Syntax: @DispStr &address [,segment]
Arguments: address = Address of string terminated by "$" (24h)
segment = Segment of address string (DS if not given)
Return: None
Registers used: AX and DS
DEVICE I/O
@Read (3Fh)
Reads data from a file or device
Syntax: @Read &buffer, length [,[handle] [,segment]]
Arguments: buffer = Offset of buffer where data will be stored
length = Length of data in bytes
handle = File or device handle; if none given,
keyboard (handle 0) is assumed
segment = Segment of address string (DS if not given)
Return: If carry clear, bytes read in AX
Registers used: Always AX, DX, BX, and CX; DS if segment changed
@Write (40h)
Writes data to a file or device
Syntax: @Write &buffer, length, [,[handle] [,segment]]
Arguments: buffer = Offset of buffer where data is stored
length = Length of data in bytes
handle = File or device handle; if none given, screen
(handle 1) is assumed
segment = Segment of address string (DS if not given)
Return: If carry clear, bytes written in AX
Registers used: Always AX, DX, BX, and CX; DS if segment changed
FILE CONTROL
@MakeFil (3Ch, 5Ah, 5Bh)
Creates a file
Syntax: @MakeFil &path [,[attrib] [,[segment] [,#kind]]]
Arguments: path = ASCIIZ string of file
attrib = File atrribute (0 is default if none given)
segment = Segment of address string (DS if not given)
kind = If none given, a file is always created even if
one already exists. Under DOS 3+ "tmp" can be
given to create a unique file or "new" to create
file only if one doesn't already exist.
Return: If carrry clear, file handle in AX
Registers used: Always AX, DX, and CX; DS if segment changed
@OpenFil (3Dh)
Opens a file for input or output
Syntax: @OpenFil &path, #access [,segment]
Arguments: path = ASCIIZ string of file
access = File access code
segment = Segment of address string (DS if not given)
Return: If carrry set, error code in AX
Registers used: Always AX and DX; DS if segment changed
@ClosFil (3Eh)
Closes an open file handle
Syntax: @ClosFil handle
Arguments: handle = Previously opened file handle
Return: If carrry set, error code in AX
Registers used: AX and BX
@DelFil (41h)
Deletes a specified file
Syntax: @DelFil &path [,segment]
Arguments: path = Offset of ASCIIZ filespec
segment = Segment of path (DS if none given)
Return: If carrry set, error code in AX
Registers used: AX and DX; DS if segment changed
@MoveFil (56h)
Moves or renames a file by changing its path specification.
Syntax: @MoveFil &old, &new [,[segold] [,segnew]]
Arguments: old = Offset of file spec to be renamed
new = Offset of new file spec
segold = Segment of old name (DS if none given)
segnew = Segment of new name (ES if none given)
Return: If carry set, error code in AX
Registers used: AX, DX, and DI; DS and ES if corresponding segments changed
@GetFirst (4Eh) and @GetNext (4Fh)
Parses file specifications (optionally including wild cards) into
file names
Syntax: @GetFirst &path [,[attribute] [,segment]]
@GetNext
Arguments: path = Offset of ASCIIZ filespec (can have wild cards)
attribute = File attribute to search for (0 for normal if
none given)
segment = Segment of path (DS if none given)
Return: If carrry set, error code in AX
Registers used: @GetFirst = AX, CX, and DX; DS if segment changed
@GetNext = AX only
@GetDTA (1Ah) and @SetDTA (2Fh)
Gets or sets the Disk Transfer Address (DTA)
Syntax: @GetDTA
@SetDTA &buffer [,segment]
Arguments: buffer = Offset of new DTA buffer
segment = Segment of new DTA buffer (DS if none given)
Return: @GetDTA = ES:BX points to DTA
@SetDTA = None
Registers used: AX for both; DS and DX for @SetDTA; ES and BX for @GetDTA
@GetFilSz (42h)
Gets the file size by moving the file pointer to end of the file.
Note that the file pointer is reset to zero. Thus this macro should
not be called during operations that move the pointer.
Syntax: @GetFilSz handle
Arguments: handle = Previously opened file handle
Return: If carrry clear, file length in DX:AX
Registers used: AX, BX, CX, and DX
@MovePrtAbs and @MovePtrRel (42h)
Moves the file pointer in an open file. The pointer can be moved to
an absolute position, or relative to its current position.
Syntax: @MovePrtAbs handle [,distance]
@MovePrtRel handle [,distance]
Arguments: handle = Previously opened file handle
distance = Distance to move pointer - must be a 16-bit
constant or a 16- or 32-bit variable; or
leave blank and set distance in CX:DX before
macro call
Return: If carrry clear, file pointer position in DX:AX
Registers used: AX, BX, CX, and DX
DIRECTORY CONTROL
@MkDir, (39h), @RmDir (3Ah), and @ChDir (3Bh)
Creates, deletes, or changes to the specified directory
Syntax: @MkDir &path [,segment]
@RmDir &path [,segment]
@ChDir &path [,segment]
Arguments: path = Offset of ASCIIZ string to
segment = Segment of path (DS if none given)
Return: If carrry set, error code in AX
Registers used: AX and DX; DS if segment changed
@GetDir (47h)
Returns the current directory of the specified drive
Syntax: @GetDir &path [,[drive] [,segment]]
Arguments: buffer = Offset of buffer to receive ASCIIZ directory
drive = 8-bit drive number - 0=current, 1=A, 2=B, etc.
(0 if none given)
segment = Segment of path (DS if none given)
Return: If carrry set, error code in AX
Registers used: AX, SI, and DL; DS if segment changes
DRIVE CONTROL
@GetDrv (0Eh) and @SetDrv (19h)
Gets or sets the current drive
Syntax: @GetDrv
@SetDrv drive
Argument: drive = 8-bit drive number (0=A, 1=B, etc.)
Return: @GetDrv = Drive number in AL (0=A, 1=B, etc.)
@SetDrv = Number of drives in AL
Registers used: AX for both; DL for @SetDrv
@ChkDrv (36h)
Gets various data about a disk
Syntax: @ChkDrv [drive]
Argument: drive = 8-bit drive number (0=current,A=1, B=2, etc.);
if none given, current assumed
Return: AX = Sectors per cluster (-1 if drive invalid)
BX = Available clusters
CX = Bytes per sector
DX = Clusters per drive
Registers used: AX, BX, CX, and DX
PROCESS CONTROL
@Exit (4Ch)
Exits to DOS with return code
Syntax: @Exit [#return]
Argument: return = 8-bit code to return to DOS; if none given,
AL is used
Return: None
Registers used: AX
@Exec (4Bh)
Executes a child process or an overlay
Syntax: @Exec path, params [,[segpath] [,[segparams] [,overlay]]]
Arguments: path = Offset of ASCIIZ filespec to be executed
params = Offset of process parameter block
segpath = Segment of filespec (DS if none given)
segparams = Segment of parameter block (ES if none given)
overlay = If not defined, normal process executed;
if defined, overlay executed
Return: If carry set, error code
Registers used: AX, SI, and DI; DS and ES if corresponding segments given
@GetRet (4Dh)
Gets the return code of a child process
Syntax: @GetRet
Argument: None
Return: Return code in AX
Register used: AX
@TSR (31h)
Terminates a program, but leaves it resident in memory
Syntax: @TSR paragraphs [,#return]
Arguments: return = Code to return to DOS; if none, AL used
paragraphs = Memory in paragraphs (16 bytes) to
allocate for resident program
Return: None
Registers used: AX and DX
MEMORY CONTROL
@FreeBlok (49h)
Frees a block of memory
Syntax: @FreeBlok [segment]
Argument: segment = Starting address of memory to be freed;
if none, ES address assumed
Return: If carry set, error code in AX
Register used: AX; ES if segment given
@GetBlok (48h)
Allocates a block of memory
Syntax: @GetBlok paragraphs
Argument: paragraphs = Paragraphs (16 bytes) of memory wanted
Return: AX and ES = Segment address of allocated memory
BX = Paragraphs actually allocated (may be
less than requested if memory is short)
Register used: AX and BX
@ModBlok (48h)
Modifies an allocated block of memory
Syntax: @ModBlok paragraphs [,segment]
Argument: paragraphs = Paragraphs (16 bytes) of memory wanted
segment = Starting address of memory to be freed;
if none, ES address assumed
Return: If carry set, error code in AX, else:
ES = Segment address of allocated memory
BX = If carry is clear, paragraphs allocated
Register used: AX and BX; ES if segment given
MISCELLANEOUS
@GetDate (2Ah) and @SetDate (2Bh)
Gets or sets the system date
Syntax: @GetDate
@SetDate month, day, year
Arguments: year = 16-bit year (1980-2099)
month = 8-bit month (1-12)
day = 8-bit day (1-31)
Return: For @GetDate:
AL = Day of week (0 = Sunday, 1 = Monday, etc.)
CX = Year (1980-2099)
DL = Month (1-12)
DH = Day (1-31)
For @SetDate:
AL = If date was valid 0, else -1
Registers used: AX, CX, and DX
@GetTime (2Ch) and @SetTime (2Dh)
Gets or sets the system time
Syntax: @GetTime
@SetTime hour,minute,second,hundredth
Arguments: hour = 8-bit hour (0-23)
minute = 8-bit hour (0-59)
second = 8-bit hour (0-59)
hundredth = 8-bit hour (0-99)
Return: For @GetTime:
CL = Hour (0-23)
CH = Minute (0-59)
DL = Second (0-59)
DH = Hundredth (0-99)
For @SetTime:
AL = If time was valid 0, else -1
Registers used: AX, CX, and DX
@GetVer (30h)
Gets the DOS version
Syntax: @GetVer
Argument: None
Return: AL = Major version (0 for versions prior to 2.0)
AH = Minor version
BH = OEM serial number
BL:CX = 24-bit user number
Register used: AX, BX, and CX
@GetInt (35h) and @SetInt (25h)
Gets or sets the vector for a specified interrupt routine
Syntax: @GetInt #interrupt
@SetInt #interrupt, &vector [,segment]
Arguments: interrupt = 8-bit interrupt number
vector = Offset of interrupt routine
segment = Segment of routine - if none given, DS assumed
for data; segment ignored for code labels
Return: @GetInt = None
@SetInt = ES:BX points to interrupt routine
Registers used: AX for both; ES and BX for @GetInt; DS and DS for @SetInt
BIOS Macro Syntax and Description
MODE, PAGE, AND COLOR CONTROL
@GetMode (I 10h F 0Fh)
Gets the current video mode and page
Syntax: @GetMode
Arguments: None
Return: AL = Mode
AH = Width in characters
BH = Page
Registers used: AX and BH
@SetMode (I 10h F 00h)
Gets the current video mode and page
Syntax: @SetMode mode
Arguments: mode = 8-bit video mode
Return: none
Registers used: AX
@SetColor (I 10h F 0Bh)
Sets the background color
Syntax: @SetColor color
Arguments: color = 8-bit background color (0-15);
border color in text modes
Return: none
Registers used: AX and BX
@SetPalet (I 10h F 0Bh)
Sets the color palette
Syntax: @SetPalet color
Arguments: color = 8-bit color palette (0-1 for modes 5 and 6)
Return: none
Registers used: AX and BX
@SetPage (I 10h F 05h)
Sets the video page
Syntax: @SetPage page
Arguments: page = 8-bit page number; 0-3 for modes 2 and 3
Return: none
Registers used: AX
CHARACTER AND CURSOR CONTROL
@GetCur (I 10h F 04h)
Gets the cursor position and size
Syntax: @GetCur [page]
Arguments: page = 8-bit page with cursor (if none, 0 assumed)
Return: DL = Column
DH = Row
CL = Starting scan line
CH = Ending scan line
Registers used: AX, DX, CX, and BH
@SetCurPos (I 10h F 02h)
Sets the cursor position
Syntax: @SetCurSz [column] [,[row] [,page]]
Arguments: column = 8-bit column; if none, DL used
row = 8-bit row; if none, DH used
page = 8-bit page with cursor (if none, 0 assumed)
Return: none
Registers used: AX, DX, and BH
@SetCurSz (I 10h F 01h)
Sets the cursor size and shape by specifying active scan lines. The
CGA adapter the lines are 0-7. The monochrome adapter has lines 0-13.
Syntax: @SetCurSz startline, endline
Arguments: startline = 8-bit starting scan line (default CGA=6; MA=12)
endline = 8-bit ending scan line (default CGA=7; MA=13)
Return: none
Registers used: AX and CX
@GetChAtr (I 10h F 08h)
Gets the character and attribute at the cursor location
Syntax: @GetChAtr [page]
Arguments: page = 8-bit page to check (if none, 0 assumed)
Return: AH = Attribute
AL = ASCII character
Registers used: AX and BH
@PutChAtr (I 10h F 09h) and @PutCh (I 10h F 0Ah)
Puts one or more characters and attributes at the current cursor
position. For @PutCh, the current attribute is used in text modes
and any specified attribute is ignored.
Syntax: @PutChAtr [character] [,[attrib] [,[page] [,count]]]
Arguments: character = 8-bit ASCII character to put; if none, AL used
attrib = 8-bit attribute to put; if none, BL used
page = 8-bit page to put on (if none, 0 assumed)
count = Number to put (if none, 1 assumed)
Return: AH = Attribute
AL = ASCII character
Registers used: AX, BX, CX
@Scroll (I 10h F 06h and 07h)
Scrolls a specified window up or down
Syntax: @Scroll dist [,[attr] [,[uprow [,[upcol [,[dnrow] [,dncol]]]]]
Arguments: dist = 8-bit number of lines to scroll; positive
scrolls down; negative scrolls up; 0 clears
attr = 8-bit attribute for blank lines (if none, 07h)
uprow = Upper left row (if none, CH used)
upcol = Upper left column (if none, CL used)
dnrow = Lower right row (if none, DH used)
dncol = Lower right column (if none, DL used)
Return: none
Registers used: AX, CX, DX, and BH
@Cls (I 10h F 06, 08h, and 02h)
Clears the screen of the current page
Syntax: @Cls
Arguments: None
Return: None
Registers used: AX, BX, CX, and DX
tundra