661 lines
18 KiB
Plaintext
661 lines
18 KiB
Plaintext
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
|
||
|