macro.doc

来自「汇编&c语言code」· DOC 代码 · 共 661 行 · 第 1/2 页

	     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)