Programmer Power Tools

home *** CD-ROM | disk | FTP | other *** search

/ Programmer Power Tools / Programmer Power Tools.iso / asmutl / usoftpd.arc / MACRO.DOC < prev next >

Wrap

Text File | 1987-07-31 | 17.6 KB | 661 lines

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