Black Box 4

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

/ Black Box 4 / BlackBox.cdr / progasm / asmwiz14.arj / ASMWIZ.DOC < prev next >

Wrap

Text File | 1991-09-09 | 41.5 KB | 1,009 lines

The Assembly Wizard's Library page 1 ASMWIZ Copyright (c) 1990-1991 Thomas G. Hanlin III This is ASMWIZ, a library of assembly language routines for assembly language programmers. It is copyrighted and may be distributed only under the following conditions: 1) No fee of over $10.00 may be charged for distribution. This restriction applies only to physical copies and is not meant to prevent distribution by telecommunication. 2) All ASMWIZ files must be distributed together in original, unaltered form. This includes ASMWIZ.DOC, ASMWIZ.MAN, ASMWIZ.NEW, ASMWIZ.XRF, BIBLIO.TXT, EXAMPLE.ASM, EXAMPLE.CGA, EXAMPLE.COM, EXAMPLE.EGA, EXECOM.COM, FILES.LST, PRODUCT.TXT, REGISTER.TXT, 8CREATE.BAT, OCREATE.BAT, MCREATE.BAT, and TCREATE.BAT. 3) BBSes *MAY NOT* add advertisement files to my archive!!! Goldurnit, this should go without saying. Shame on sysops who do this! You use this library at your own risk. It has been tested by me on my own computer, but I will not assume any responsibility for any problems which ASMWIZ may cause you. If you do encounter a problem, please let me know about it, and I will do my best to verify and repair the error. It is expected that if you find ASMWIZ useful, you will register your copy. This entitles you to receive the latest version of ASMWIZ, complete with full source code. The source code is designed for the Microsoft Macro Assembler (MASM) v6.0 and may require minor modifications to assemble with OPTASM, TASM, or older versions of MASM. The ASMWIZ library was designed for use with small assembly programs and is compatible with the creation of COM files. All CALLs are of the NEAR variety. If there is sufficient interest, a FAR model will also be made. For an example of how to set up your program to access the ASMWIZ library, how to LINK the routines, and so forth, see the EXAMPLE.ASM, EXAMPLE.COM, and ?CREATE.BAT files (FILES.LST tells you which batch file to use with which assembler; there are versions for A86, MASM, OPTASM, QuickASM, and TASM). The new EXAMPLE.ASM and .BAT files are due to the efforts of a kind gentleman whose name I have regrettably lost. If you're reading this, sir, please get in touch with me! Note that DOS-dependent services expect DOS 2.0 or higher versions, unless otherwise specified. Services to be added in future versions include additional mouse handling, keyboard control and input services, expanded and extended memory support, background music, ANSI emulation, communications, and much more. If there is something in particular that you'd like to see, please let me know about it. Table of Contents page 2 Overview and Legal Info ................................................ 1 Base Conversions ....................................................... 3 Exception Handling ..................................................... 4 Delays and Countdowns .................................................. 5 File Handling .......................................................... 6 Filename Manipulation .................................................. 8 Long Integer Math ...................................................... 9 Memory Services ....................................................... 10 Mouse Services ........................................................ 11 Sound and Music ....................................................... 12 String Services ....................................................... 13 Telecommunications .................................................... 14 Time and Date ......................................................... 15 Video Services ........................................................ 16 Miscellaneous Services ................................................ 23 Error Codes ........................................................... 24 Base Conversions page 3 The Base Conversion Services provide the ability to convert back and forth between a number and its ASCIIZ representation. Any base from 2-36 may be employed, so these routines encompass binary, decimal, hex and octal conversions. Services are provided for integers and long integers, both signed and unsigned. The following services are available: BC_ASC2INT convert an ASCIIZ string to an unsigned integer BL <-- base from which to convert DS:SI <-- ptr to string ------- AX = unsigned integer BC_ASC2LONG convert an ASCIIZ string to an unsigned long integer BL <-- base from which to convert DS:SI <-- ptr to string ------- DX,AX = unsigned long integer BC_ASC2SINT convert an ASCIIZ string to a signed integer BL <-- base from which to convert DS:SI <-- ptr to string ------- AX = signed integer BC_ASC2SLONG convert an ASCIIZ string to a signed long integer BL <-- base from which to convert DS:SI <-- ptr to string ------- DX,AX = signed long integer BC_INT2ASC convert an unsigned integer to an ASCIIZ string AX <-- unsigned integer BL <-- base to which to convert ES:DI <-- ptr to string buffer (recommend 17 bytes) BC_LONG2ASC convert an unsigned long integer to an ASCIIZ string DX,AX <-- unsigned long integer BL <-- base to which to convert ES:DI <-- ptr to string buffer (recommend 33 bytes) BC_SINT2ASC convert a signed integer to an ASCIIZ string AX <-- signed integer BL <-- base to which to convert ES:DI <-- ptr to string buffer (recommend 18 bytes) BC_SLONG2ASC convert a signed long integer to an ASCIIZ string DX,AX <-- signed long integer BL <-- base to which to convert ES:DI <-- ptr to string buffer (recommend 34 bytes) Exception Handling page 4 The Exception Handling Services allow your program to take control over exception conditions. This covers critical errors and control-break / control-c handling. The critical error handler gives you the ability to recover from critical errors, which would otherwise cause the infamous "A>bort, R>etry, I>gnore" prompt. The break handler allows your program to ignore the Control-C and Control-Break keys or to process them in an orderly manner. This is vital if you are using any of the ASMWIZ services which need to be shut down before the program terminates. Up to eight procedures can be called when ^Break or ^C are used (they will be ignored if you turn off ^Break / ^C). The following services are available: EH_INITCRIT initialize the critical error handler EH_CRITERR check for a critical error EH_CRITDONE terminates the critical error handler EH_INITBREAK initialize the ^C / ^Break handler EH_ADDBREAK add a procedure to be called on ^C / ^Break DX <-- procedure offset (from CS: near code is assumed) EH_SETBREAK allow or ignore ^C and ^Break AL <-- 0 to ignore, 1 to allow EH_SUBBREAK remove a procedure to be called on ^C / ^Break DX <-- procedure offset (from CS: near code is assumed) Delays and Countdowns page 5 The Delay Services are for those times when you want the computer to sit around doing nothing for a while. Delays of various timing resolution are available for anything from small to large waits. Notes on the 100th-second delay and countdown services: Since MD_DONE must be called before the program terminates, you should use the EH_ADDBREAK service to insure that MD_DONE is called if Control-Break or Control-C are permitted to abort the program. Timers 0-1 may be used by ASMWIZ itself for various services. See ASMWIZ.MAN for more details on the 100th-second delay services. The following services are available: MD_DELAY delay for a number of 100ths of seconds CX <-- delay (0-32767) MD_DONE terminate 100th-second delay handler MD_GETTIMER get a delay count AL <-- timer number (0-3) ------- CX = delay * 2 (0-65534) MD_INIT initialize 100th-second delay handler MD_SETTIMER set a delay count AL <-- timer number (0-3) CX <-- delay (0-32767) MD_TICK delay for a number of clock ticks (18ths of seconds) CX <-- delay (0-65535) File Handling page 6 The File Handling Services provide a comprehensive and powerful set of routines for file handling. The usual open file, read/write, file pointer manipulation, and close file operations are supported, of course. New conveniences include automatic network support (file sharing is used if the DOS version is high enough), optional input buffering for extra speed, and special support for text files. A future version of ASMWIZ will allow you to have an indefinite number of files open at a time, using any DOS version. Critical error handling is supported via the Exception Handling Services. These services return with the carry flag set if there is an error. In that case, the AX register returns the error code. Note that, unlike most other services, the file services are allowed to change the AX register regardless of whether an error occurred. The following services are available: DF_CLOSE close a file BX <-- (virtual) file handle DF_DONE terminate the File Handling Services (closes all open files) DF_FLUSH flush a file to disk (updates disk directory) BX <-- (virtual) file handle DF_GETTIME get file time/date stamp BX <-- (virtual) file handle ------- AX = time DX = date DF_HANDLE get DOS file handle, given virtual file handle BX <-- (virtual) file handle ------- BX = (DOS) file handle DF_INIT initialize the File Handling Services DX <-- 0 DF_LOCATE set file read/write pointer BX <-- (virtual) file handle CL <-- use 0 for offset from start, 1 for offset from current position, 2 for offset from end of file DX,AX <-- offset File Handling page 7 DF_OPEN open a file for access AX <-- set bit 0 for read, bit 1 for write, bit 2 for create, bit 3 for text file, others zero DS:DX <-- pointer to ASCIIZ filename CX <-- length of input buffer (zero if no buffer) ES:SI <-- pointer to input buffer, if any ------- BX = (virtual) file handle DF_READ read from a file BX <-- (virtual) file handle CX <-- bytes to read (for text files, is max bytes) DS:DX <-- pointer to read buffer ------- AX = bytes actually read (if NC and not text mode) DF_TIME set file time/date stamp BX <-- (virtual) file handle AX <-- time DX <-- date DF_WHERE get file read/write pointer BX <-- (virtual) file handle ------- DX,AX = offset DF_WRITE write to a file BX <-- (virtual) file handle CX <-- bytes to write (for text files, is ignored) DS:DX <-- pointer to write buffer Filename Manipulation page 8 The Filename Manipulation Services allow various operations on filenames which make it possible to duplicate the capabilities of the DOS command shell. This includes finding a file which matches a specified pattern, forcing a filename to match a given pattern, splitting a filespec into its component parts, and completing a (possibly partial) filespec. The following services are available: FI_COMPLETE complete a filespec from a (possibly) partial specification DS:SI <-- filename (may have drive, dir, "." or "..", etc) DS:BX <-- default extension to be added (sans ".") ES:DI <-- 80-byte buffer for result ------- Flags = CY if the filespec is not valid NC if it went ok FI_MATCH see if a filename matches a specified pattern DS:SI <-- pattern (may contain wildcards) ES:DI <-- filename (may not contain drive or path specs) ------- Flags = ZF if the filename matches the pattern NZ if the filename doesn't match the pattern FI_PATTERN push a filename through a pattern specification DS:SI <-- filename (no drive or directory allowed) DS:BX <-- pattern ES:DI <-- 13-byte buffer for results ------- Flags = CY for some filename/pattern errors NC if it went ok FI_SPLIT split a path specification into drive, directory, filename DS:SI <-- path spec ES:DI <-- 80-byte buffer for results Long Integer Math page 9 The Long Integer Math Services provide support for the basic arithmetic operations on unsigned long integers. They allow you to add two 32-bit integers, subtract one 32-bit integer from another, multiply two 32-bit integers (giving a 64-bit result), and divide a 63-bit integer by a 32-bit integer (giving a 32-bit result and 32-bit remainder). Since 32-bit integers are rather unwieldy unless you're using an 80386 or above (in which case you don't need these services anyway), the numbers are passed back and forth through a buffer in memory. The following services are available: MA_ADD32 add two unsigned long integers DS:SI <-- first operand DS:SI+4 <-- second operand ------- DS:SI+8 = result MA_DIV32 divide an unsigned 63-bit integer by an unsigned long integer DS:SI <-- dividend (64 bits: high bit must be zero) DS:SI+8 <-- divisor (unsigned long integer) ------- DS:SI+12 = quotient (unsigned long integer) DS:SI+16 = remainder (unsigned long integer) MA_MUL32 multiply two unsigned long integers DS:SI <-- first operand DS:SI+4 <-- second operand ------- DS:SI+8 = result (unsigned very long integer: 64 bits) MA_SUB32 subtract one unsigned long integer from another DS:SI <-- first operand DS:SI+4 <-- second operand ------- DS:SI+8 = result Memory Services page 10 The Memory Services provide low-level routines for memory manipulation. They allow you to manipulate addresses, provide a "smart" block move service that automatically handles overlaps between source and destination areas, and allows you to save or restore blocks of memory in BASIC's BSAVE format. Among the address manipulation services are routines to convert an address to have the smallest possible segment and highest possible offset (or vice versa) to allow REP operations to always handle up to 65,519 bytes without wrapping within the segment. This can also be useful in file operations. The following services are available: ME_BINFO get information about a BSAVE-format file DS:DX <-- pointer to ASCIIZ filename ------- ES:SI = segment:offset CX = image size (bytes) Flags = CY if unable to load file; AX is error code ME_BLOAD load a BSAVE-format file into memory DS:DX <-- pointer to ASCIIZ filename ------- Flags = CY if unable to load file; AX is error code ME_BSAVE save a block of memory to a BSAVE-format file DS:DX <-- pointer to ASCIIZ filename ES:SI = segment:offset CX = image size (bytes) ------- Flags = CY if unable to save memory; AX is error code ME_HIGHOFS convert an address to have the lowest segment & highest offset DX:AX <-- segment:offset ------- DX:AX = converted segment:offset ME_LOWOFS convert an address to have the highest segment & lowest offset DX:AX <-- segment:offset ------- DX:AX = converted segment:offset ME_MOVE move a block of memory without overlap conflicts DS:SI <-- source segment:offset ES:DI <-- destination segment:offset CX <-- bytes to move (0 - 65,519) Mouse Services page 11 The Mouse Services provide a simple set of functions for dealing with Microsoft-compatible mouse devices. You may see if a mouse exists, control the mouse cursor, and get information about the mouse buttons. The following services are available: MO_HIDECURSOR hide the mouse cursor MO_INIT see if a mouse is installed (and if so, how many buttons) ------- AL = number of buttons on the mouse (zero if no mouse) MO_LOCATE set the mouse cursor location DH <-- row (1-25) DL <-- column (1-80) MO_RANGE set the mouse cursor range CH <-- top row (1-25) CL <-- leftmost column (1-80) DH <-- bottom row (1-25) DL <-- rightmost column (1-80) MO_SHOWCURSOR show the mouse cursor MO_WHERE get the mouse cursor location and button states ------- AL = left button (0 = not pressed, 1 = pressed) AH = right button (0 = not pressed, 1 = pressed) DH = row (1-25) DL = column (1-80) Sound and Music page 12 The Sound and Music Services provide the ability to generate sound effects and music. The current service is rather on the primitive side. It will be supplemented by a background (interrupt-driven) music command language in a future version of ASMWIZ. The following services are available: MU_SOUND produce a sound of a specified duration and frequency AX <-- frequency (Hertz; about 50-4000 is useful) DX <-- duration (18ths of seconds) String Services (ASCIIZ) page 13 The ASCIIZ String Services provide a wide assortment of services for dealing with null-terminated strings. Note that, although many of the string services are designed to place the result of processing a first string into a second string, it is not actually necessary to use two string buffers. The services are designed so that you can place the results back into the original string buffer by using the same address for both strings. The following routines are included amongst the ASCIIZ String Services: S0_COMPARE compares two strings DS:SI <-- first string ES:DI <-- second string ------- Flags = ZF if equal, NZ if not equal CY if first < second, NC if first >= second S0_DUPE forms a string by duplicating a character ES:DI <-- result string AL <-- character to duplicate CX <-- number of times to repeat the character S0_LEFT copies a specified section from the left of a string DS:SI <-- source string CX <-- number of characters to copy ES:DI <-- result string S0_LENGTH gets the length of a string (excluding the null terminator) DS:SI <-- string ------- CX = string length S0_LOCASE converts a string to lowercase (international) DS:SI <-- source string ES:DI <-- result string S0_MID copies a specified section of a string DS:SI <-- source string DX <-- where to start copying from (1-xx) CX <-- how many characters to copy ES:DI <-- result string S0_RIGHT copies a specified section from the right of a string DS:SI <-- source string CX <-- number of characters to copy ES:DI <-- result string S0_TRIM trims the "white space" (blanks and control characters) from either side (or both sides) of a string DS:SI <-- source string AL <-- set bit 0 to trim the left, bit 1 for right ES:DI <-- result string S0_UPCASE converts a string to uppercase (international) DS:SI <-- source string ES:DI <-- result string Telecommunications page 14 The Telecommunications Services provide functions that are useful for telecommunications. At the moment, this is limited to services that aid in performing file transfers and similar functions. The following routines are included amongst the Telecommunications Services: TC_CHKSUM calculate the Xmodem/Ymodem checksum of a block of data DS:SI <-- pointer to a data block CX <-- length of data block (in bytes) ------- AX = checksum TC_CRC calculate the Xmodem/Ymodem CRC of a block of data DS:SI <-- pointer to a data block CX <-- length of data block (in bytes) ------- AX = resulting CRC Time and Date Services page 15 The Time and Date Services provide international date handling. Based on the country code given it by DOS, these services return strings that represent the current time or date in the appropriate format for that country. These services provide a simple way to make your software work properly on any computer anywhere, across the world. See the COUNTRY entry under CONFIG.SYS in your DOS manual for more details. Note that DOS version 3.0 or greater is required to insure that the date and time delimiters are appropriate. Otherwise, the date and time formats will still be correct, but the delimiters used will be assumed to be "-" for the date and ":" for the time. With DOS versions before 3.0, the time will be presented in 12-hour (am/pm) format. The following routines are included amongst the Time and Date Services: TD_GETDATE get the current date as an ASCIIZ string DS:DX <-- pointer to a buffer (minimum 11 bytes) AL <-- 0 for 2-digit year, 1 for 4-digit year TD_GETTIME get the current date as an ASCIIZ string DS:DX <-- pointer to a buffer (minimum 8 bytes) Video Services page 16 Displaying text is something that almost every program will do. The ASMWIZ library contains numerous sets of video services which make it easy to use the display in a consistent manner. The display services are divided into five sets of routines, each of which provides similar capabilities: DV DOS-level services BV BIOS-level services MV Machine-level services for text modes CG Machine-level services for CGA graphics modes HG Machine-level services for Hercules graphics mode The DOS services provide the maximum level of compatibility. They are also the slowest of the video services and the least flexible. The main practical advantage of using DOS services is that they allow redirection, so the output of your program can be sent to a file, a printer, or a serial port as well as to the display. Since DOS itself has only minimal video support, you will need to make sure an ANSI driver is installed before using these services. See your DOS manual on ANSI.SYS for more information if you need it. The BIOS services provide a very good level of compatibility. They are faster and more flexible than the DOS services. Like the DOS services, these routines are quite likely to work on nonstandard displays. The machine-level services are the least compatible. They will work on any standard PC clone, but not on semi-compatible hardware or with nonstandard display devices. In return for this disadvantage, these services are much faster than the other services and provide a great deal more flexibility. Only the machine-level services support Hercules graphics mode. Video Services page 17 Text Display Speeds Speed tests were conducted on an 8088 machine with a Phoenix BIOS, running MS-DOS 3.30. "Your mileage may differ." The tests were conducted on how quickly strings could be printed to the display. Speeds are listed relative to the slowest display method (DOS services). +-----------+-----------+-----------+-----------+ | DV_STROUT | BV_STROUT | MV_STROUT | CG_STROUT | +------------+-----------+-----------+-----------+-----------+ | Mode 3 | | | | | | text mode | 100% | 162% | 572% | n/a | +------------+-----------+-----------+-----------+-----------+ | Mode 4 | | | | | | CGA lo-res | 100% | 114% | n/a | 180% | +------------+-----------+-----------+-----------+-----------+ | Mode 6 | | | | | | CGA hi-res | 100% | 122% | n/a | 204% | +------------+-----------+-----------+-----------+-----------+ From this chart, you can see that using BIOS display services is 14% - 62% faster than using DOS services. Using machine-level services is 80% - 472% faster than using DOS services, and about 60% - 250% faster than using BIOS services. If system compatibility is a major concern, then note that the DOS services are most compatible, followed by the BIOS services and then the machine-level services. The price you pay for compatibility is speed and flexibility. The machine-level services are the fastest and most flexible, followed by the BIOS services and then the DOS services. Video Services page 18 General Video Information (not applicable to Hercules graphics mode) For all text routines, color/attributes are encoded as a single byte value: bit: 7 6 5 4 3 2 1 0 +---+---+---+---+---+---+---+---+ | B | backgnd | I | foregnd | +---+---+---+---+---+---+---+---+ B: "blink". Set if the color is blinking. I: "intense". Set if the foreground color is intense (bright or light). backgnd, foregnd: the actual foreground and background colors. The bits specify the red, green, and blue components of the color, giving the following list of colors: 0 black (if intense, may or may not be displayed as gray) 1 blue 2 green 3 cyan 4 red 5 magenta 6 brown (if intense, is usually displayed as yellow) 7 white Text in CGA graphics modes is different. If you use BIOS or DOS services, you may only specify a foreground color, which may be 0-3. If you use the CGA machine-level services, you may specify a background color as well as a foreground color. Color encoding is the same as for text mode, with the exception that there are no "blinking" or "intense" bits, and the color range is 0-3 instead of 0-7. The 0-3 range does not follow the above color list (instead, the colors depend on which CGA palette is in use). Screen modes are specified as a single byte, as follows: Mode Resolu. Type Colr Use Adapter(s) Services 0 40x25 b&w 16 text CGA, EGA, VGA MV, BV, DV 1 40x25 color 16 text CGA, EGA, VGA MV, BV, DV 2 80x25 b&w 16 text CGA, EGA, VGA MV, BV, DV def- 3 80x25 color 16 text CGA, EGA, VGA MV, BV, DV 4 320x200 color 4 graphics CGA, EGA, VGA CG, BV, DV 5 320x200 b&w 4 graphics CGA, EGA, VGA CG, BV, DV 6 640x200 color 2 graphics CGA, EGA, VGA CG, BV, DV mda- 7 80x25 b&w - text MDA, EGA, VGA BV 13 320x200 color 16 graphics EGA, VGA BV 14 640x200 color 16 graphics EGA, VGA BV 15 640x350 mono - graphics EGA, VGA BV 16 640x350 color 16 graphics EGA, VGA BV 17 640x480 color 2 graphics VGA BV 18 640x480 color 16 graphics VGA BV 19 320x200 color 256 graphics VGA BV BV = BIOS video services DV = DOS video services MV = Machine-level text services CG = Machine-level CGA graphics services Video Services page 19 All of the video services share a common nomenclature and calling procedure. For many of the services, you will have a choice of whether to use DOS, BIOS, Machine-level (text modes), Machine-level (CGA graphics modes), or Machine-level (Hercules graphics mode). The level is specified as a two-letter code prefix to the routine name, where the codes are as follows: DV DOS Video BV BIOS Video MV Machine-level (text mode) Video CG Machine-level (CGA graphics mode) Video HG Machine-level (Hercules graphics mode) Video The routine to display a string using DOS services, for example, is named DV_STROUT (DOS Video service, String Output). It usually isn't a good idea to "mix and match" video services of different types. The following services are available: CHROUT display a character BV,DV,MV,CG,HG AL <-- character CLS clear the screen and home the cursor BV,DV,MV,CG,HG COLOR set the text color BV,DV,MV,CG,HG AL <-- color/attribute CRLF display a carriage return and a linefeed BV,DV,MV,CG,HG CLEOLN clear from the cursor to the end of the line BV,DV,MV,CG,HG DELCHR delete the character at the cursor , ,MV, , DELLINE delete the current line BV,dv,MV, , GETCOLOR get the text color BV, ,MV,CG,HG ------- AL = color/attribute GETMODE get the current screen mode BV, ,MV, , ------- AL = mode FIXCOLOR whether to convert colors to monochrome BV,DV,MV, , AL <-- whether to convert (0 no, 1 yes) FRAME display a window frame , ,MV, , CH,CL <-- upper left corner (row, column) DH,DL <-- lower right corner (row, column) DS:SI <-- frame char. list (-1 to -9 special) Video Services page 20 HIDECURSOR hide the cursor BV, ,MV, , INIT initialize the video service routines , ,MV,CG, INSCHR insert a space at the cursor , ,MV, , INSLINE insert a row at the current line BV,dv,MV, , LOCATE set the cursor position BV,DV,MV,CG,HG DH <-- row (1-25/43) DL <-- column (1-40/80/90) MODE set the screen mode BV,DV,MV,CG,HG AL <-- mode (see General Video Info) POPUP display a pop-up window BV, ,MV, , DS:DX <-- parameter pointer SAVESIZE calculate bytes needed to save a screen area , ,MV, , ------- AL = bytes SCRREST restore a saved screen area from a buffer , ,MV, , DS:SI <-- buffer pointer DH,DL <-- upper left corner (row, column) SCRSAVE save a screen area into a buffer , ,MV, , ES:DI <-- buffer pointer CH,CL <-- upper left corner (row, column) DH,DL <-- lower right corner (row, column) ------- AX = bytes used to save screen area SHOWCURSOR show the cursor BV, ,MV, , STROUT display a string BV,DV,MV,CG,HG DS:DX <-- pointer to ASCIIZ string WHERE get the current cursor position BV, ,MV,CG,HG DH <-- row (1-25/43) DL <-- column (1-40/80/90) Video Services page 21 The ability to display graphics was once limited and very expensive, but this is no longer true. PC-class computers have a wide variety of graphics standards to choose from. This is useful whether you are interested in games, business charts, computer-aided design, icon-based mouse interfaces, or any number of other applications. The ASMWIZ library provides numerous sets of graphics services which allow easy access to the capabilities of whatever display is installed. The graphics services are divided into sets of routines, with each set of routines handling a specific video mode or modes. This makes it possible to support just the modes you want, without extraneous code being linked in. All graphics services are machine-level and demand hardware compatibility of both your computer and video adapter. This is necessary because DOS doesn't support graphics at all, and the BIOS only supports very slow single-pixel handling. If you are able to run standard graphics programs on your computer, however, you should experience no problems with these services. Video Services page 22 All of the graphics services share a common nomenclature and calling procedure. The video mode is specified as a two-letter code prefix to the routine name, where the codes are as follows: Prefix Mode(s) Adapter Resolution(s) Colors ------ -------- ------- ---------------- ------ G4 4, 5 CGA 320x200 4 G6 6 CGA 640x200 2 GD 13 EGA 320x200 16 GE 14, 16 EGA 640x200, 640x350 16 GH Hercules HGA 720x348 2 The service to display a line in Mode 6, for example, is named G6_LINE. Provisions will be made in a future version of ASMWIZ for automatic handling of any available video mode, as well as conversion of images from one mode to another. The following services are available: BOX draw a box GH,G4,G6,GD,GE CX <-- left X coordinate DX <-- top Y coordinate SI <-- right X coordinate DI <-- bottom Y coordinate AH <-- whether to fill box (0 no, 1 yes) AL <-- color GETPEL get the current color of a point GH,G4,G6 CX <-- X coordinate DX <-- Y coordinate ------- AL = color LINE draw a line GH,G4,G6,GD,GE CX <-- left X coordinate DX <-- top Y coordinate SI <-- right X coordinate DI <-- bottom Y coordinate AL <-- color PLOT plot a point GH,G4,G6,GD,GE CX <-- X coordinate DX <-- Y coordinate AL <-- color Miscellaneous Services page 23 The Miscellaneous Services provide a number of services for various purposes, such as parsing the command line, determining the active video adapter, scanning the environment for a parameter, and generating pseudo-random numbers. They eliminate much of the tedium of these common chores. The following services are available: MI_BOOT reboot the computer (warm boot) MI_GETSCREEN see what type of display is active ------- AH = adapter type (1-6: MDA, Herc, CGA, EGA, MCGA, VGA) AL = color flag (0 color, 1 mono) MI_PARSE parse a command line into filespecs and options DS:SI <-- ptr to command line (for COM files, = CS:0080h) ES:DI <-- ptr to filename buffer (recommend 128 bytes) ES:BX <-- ptr to option buffer (recommend 128 bytes) AL <-- switch character (normally "/" for MS-DOS) ------- AH = number of options AL = number of filenames MI_RANDOM generate a pseudo-random number DX <-- random number range (1-4000) ------- AX = random number (0 to DX - 1) MI_RANDOMIZE initialize the pseudo-random number generator AX <-- random number seed (use 0FFFFh for auto-seeding) MI_SCANENV scan the DOS environment for a parameter DS:SI <-- ptr to the DOS environment or similar table ES:DI <-- ptr to the parm for which to search ------- CY if not found NC if match found; DS:SI points to parm value Error Codes page 24 DOS error codes are returned by various of the DOS services, particularly the file and disk services. The code is returned in the AL register. This is a list of some of the possible errors. 2 file not found 3 path not found 4 too many open files (no handle available) 5 access denied 6 invalid handle 8 insufficient memory 15 invalid drive specified 16 tried to remove current directory 18 no more files Critical error codes are returned by the EH_CRITERR service in the AH register. This is a list of the possible errors. 0 no critical error (if CY is set, it was a DOS error) 1 write-protected disk 2 unknown unit 3 drive not ready 4 unknown command 5 data/CRC error 6 bad request structure length 7 seek error 8 unknown media type 9 sector not found 10 printer out of paper 11 write fault 12 read fault 13 general failure 16 invalid disk change (only used by DOS 3.x and higher)