CD Actual 14

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

/ CD Actual 14 / CDACTUAL.iso / cdactual / demobin / share / program / Basic / QLIB57.ZIP / EMSXMS.DOC < prev next >

Wrap

Text File | 1993-02-10 | 21.1 KB | 608 lines

QLIB5 EMSXMS.DOC expanded and extended memory subroutines Copyright (C) 1991-1993 Douglas Herr ■ all rights reserved Expanded Memory subroutines take advantage of expanded memory conforming to the Lotus/Intel/Microsoft (LIM) Expanded Memory Specification (EMS). QLIB EMS subroutines allow your programs to store vast amounts of data in Expanded memory rather than creating temporary files on a disk. A well- designed program using Expanded memory can be much faster than if Expanded memory isn't used. Three primary versions of the EMS have been released: 3.0, 3.2 and 4.0. QLIB's EMS subroutines will work with all EMS versions. EMS memory is allocated in "pages" of 16k bytes (actually 16,384 bytes) each. Error codes returned by QLIB's EMS subroutines are: 0 = no error &H80 = memory manager software error - non-recoverable &H81 = expanded memory hardware error - non-recoverable &H83 = invalid EMS handle &H85 = no available EMS handles &H87 = not enough memory pages &H88 = not enough memory pages available &H89 = you tried to allocate zero pages XMS memory is available on many 286 or better computers with a suitable driver. On 286 computers, XMS memory will be much slower than EMS memory. XMS memory is not available on XT (or compatible) computers. XMS error codes include: 0 = no error &HA0 = all extended memory is allocated &HA1 = no handles available &HA2, &HA3, &HA5 = handle is invalid &HA4, &HA6 = offset is invalid &HA7 = length is invalid ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: handle% = AllocEMS(bytes&) object file: ems.obj Allocates a block of EMS memory, returning a handle for subsequent access to the memory block. Up to 2,097,120 bytes may be allocated per handle if that much EMS memory is installed. Any EMS memory blocks must be released with FreeEMS(handle%) before your program ends, or the memory allocated by AllocEMS will not be available to any other programs. AllocEMS updates the EMSError flag if something went wrong. Note that EMS memory is available in "pages" of 16k bytes; AllocEMS will allocate multiple "pages" if required, but any EMS memory allocation will be in multiples of 16k bytes. Example: REM $INCLUDE: 'qlib.bi' . . . bytes& = 32000 handle% = AllocEMS(bytes&) IF EMSError THEN ... ' check for errors ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: handle% = AllocXMS(bytes&) object file: xms.obj Allocates a block of memory from extended memory, returning a handle for subsequent access to the memory block. AllocXMS updates the XMSError flag if something went wrong. Before exiting your program, you must release any XMS handles with FreeXMS(handle%), or else the memory allocated by AllocXMS will not be available to any other programs. XMS handles are in short supply, so you should plan your program to use fewer large XMS blocks rather than many small XMS blocks. Note that bytes& is a LONG integer, and you may allocate as much memory as your system has, up to 2,147,450,880 bytes. Example: REM $INCLUDE: 'qlib.bi' IF IsXMS THEN bytes& = 100000 handle% = AllocXMS(bytes&) ' allocate memory from XMS pool IF XMSError GOTO oops . . . ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: oops% = EMSError object file: ems.obj EMSError is used after using a QLIB EMS function or subroutine to determine if there was an EMS problem. EMS error codes are listed on the first page of this EMSXMS.DOC. Example: REM $INCLUDE: 'qlib.bi' . . . handle% = AllocEMS(bytes&) IF EMSError THEN ... ' test for errors ' handle no good if errors ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: free& = EMSFree object file: emsfree.obj EMSFree determines the total unallocated EMS memory available to your program. Note that free& is a LONG integer. Example: REM $INCLUDE: 'qlib.bi' IF IsEMS THEN free& = EMSFree ' get EMS memory available ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: total& = EMSTotal object file: emsfree.obj EMSTotal determines the total EMS memory installed in the computer. Note that total& is a LONG integer. Example: REM $INCLUDE: 'qlib.bi' IF IsEMS THEN total& = EMSTotal ' get EMS memory installed ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: EMSVersion(maj%, min%) object file: ems30.obj Determines EMS version installed. Use EMSReady to determine if EMS memory is installed. Example: CALL EMSVersion(maj%, min%) ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: EMGet(handle%, emsptr&, aseg%, aptr%, bytes&) object file: emputget.obj (huge model: lowds2hi.obj) Copies data from EMS memory allocated by AllocEMS to an array. aseg% and aptr% are segment and offset pointers to the array, bytes& is the number of bytes to be copied, and handle% is the handle returned by AllocEMS. EMSptr& is the byte offset in the EMS memory block where you want the read to start. Note that EMSptr& = 0 at the start of the block. EMGet updates the EMSError flag. Example: REM $INCLUDE: 'qlib.bi' CALL EMGet(handle%, emsptr&, aseg%, aptr, bytes&) IF EMSError THEN ' check for errors ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: EMGet1(handle%, emsptr&, number%) Subroutine: EMGet2(handle%, emsptr&, number%) Subroutine: EMGet4(handle%, emsptr&, number[& or !]) Subroutine: EMGet8(handle%, emsptr&, number[# or @]) object file: emget.obj ($emspage.obj) Copies data from EMS memory to a single number. EMGet1 gets a single byte, EMGet2 gets an INTEGER, EMGet4 gets a LONG or SINGLE number, and EMGet8 gets a DOUBLE, CURRENCY or COMPLEX number. (COMPLEX number support may be found in COMPLEX.DOC.) EMGet[n] sets the EMSError flag if something went wrong. handle% = EMS handle emsptr& = (LONG) offset of the number in the EMS block number[%, &, !, # or @] = number returnd by EMGet[n] Example: REM $INCLUDE: 'qlib.bi' DIM a#(999) ' DOUBLE array ' program establishes values for array . . . REM save a#() in EMS memory IF IsEMS THEN bytes& = CLNG(1000& * 8) ' DOUBLE data is 8 bytes long handle% = AllocEMS(bytes&) IF EMSError THEN ... ' check for errors aseg% = VARSEG(a#(0)): aptr% = VARPTR(a#(0)) emsptr& = 0 CALL EMPut(handle%, emsptr&, aseg%, aptr%, bytes&) IF EMSError THEN ... ' check for errors . . ENDIF . . REM I need to retrieve a#(12) from EMS emsptr& = CLNG(12 * 8) ' calculate offset in EMS CALL EMGet8(handle%, emsptr&, a#(12)) ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: EMPut(handle%, emoffset&, dataseg%, dataptr%, bytes&) object file: emputget.obj ($emspage.obj) EMPut copies data to EMS memory from DOS or BASIC memory blocks. EMPut safely handles even huge blocks of data > 64k in size. Example: REM $INCLUDE: 'qlib.bi' REM I'll use expanded memory to store several 25-row text screens REM while I use graphics mode IF NOT IsEMS THEN PRINT "This example uses EXPANDED memory" PRINT "You cannot run this demo": END ENDIF bytes& = 16000 ' EMS drivers allocate ' a minimum of 16k per block handle% = AllocEMS(bytes&) IF EMSError THEN PRINT "There's a problem with EMS memory" PRINT "You cannot run this demo": END ENDIF bytes& = 4000 ' 4,000 bytes for 80x25 screen screenseg = &HB800 ' color monitor emoffset& = 0 FOR i = 0 to 3 CALL EMPut(handle%, emoffset&, screenseg, 0, bytes&) emoffset& = emoffset& + bytes& screenseg = screenseg + &H100 NEXT i . . . REM sometime later ... bytes& = 4000 ' 4,000 bytes for 80x25 screen screenseg = &HB800 ' color monitor emoffset& = 0 FOR i = 0 to 3 CALL EMGet(handle%, emoffset&, screenseg, 0, bytes&) emoffset& = emoffset& + bytes& screenseg = screenseg + &H0100 NEXT i ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: EMPut1(handle%, emsptr&, number%) Subroutine: EMPut2(handle%, emsptr&, number%) Subroutine: EMPut4(handle%, emsptr&, number[& or !]) Subroutine: EMPut8(handle%, emsptr&, number[# or @]) object file: emget.obj ($emspage.obj) Copies data to EMS memory from a single number. EMPut1 copies a single byte, EMPut2 copies an INTEGER, EMPut4 copies a LONG or SINGLE number, and EMPut8 copies a DOUBLE, CURRENCY or COMPLEX number. (COMPLEX number support may be found in COMPLEX.DOC.) EMPut[n] sets the EMSError flag if something wnet wrong. handle% = EMS handle emsptr& = (LONG) offset of the number in the EMS block number[%, &, !, # or @] = number to be copied to EMS memory Example: REM $INCLUDE: 'qlib.bi' DIM a#(999) ' DOUBLE array ' program establishes values for array . . . REM save a#() in EMS memory IF IsEMS THEN bytes& = CLNG(1000& * 8) ' DOUBLE data is 8 bytes long handle% = AllocEMS(bytes&) IF EMSError THEN ... ' check for errors aseg% = VARSEG(a#(0)): aptr% = VARPTR(a#(0)) emsptr& = 0 CALL EMPut(handle%, emsptr&, aseg%, aptr%, bytes&) IF EMSError THEN ... ' check for errors . . ENDIF . . REM a#(12) has changed and I need to update the the copy in EMS emsptr& = CLNG(12 * 8) ' calculate offset in EMS CALL EMPut8(handle%, emsptr&, a#(12)) IF EMSError THEN ... ' check for errors ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: handle% = FLoadEMS(filename$) object file: floadems.obj (ems.obj, q$alloc.obj, $asciiz.obj, fsize.obj) FLoadEMS reads a file from a disk and copies it into EMS memory. FLoadEMS assumes that EMS is installed. Use IsEMS to determine if the computer has EMS memory. FLoadEMS temporarily uses 16k of DOS memory to read the file, but the file may be any size, up to 2,147,450,880 bytes if that much EMS is available. This shouldn't be a problem. Several files may be loaded in EMS memory if memory is available. Use FreeEMS to release the EMS memory when you're done using it. If you don't release the EMS memory before the program ends, that memory will not be available to other programs. Handle% returnd by FLoadEMS is a valid EMS handle, unless either DOSError or EMSError <> 0. FLoadEMS fails if insufficient EMS memory is available, if 16k DOS memory is not available, or if the specified file cannot be opened or read. See EMSError in this EMSXMS.DOC and DOSError in SYSTEM.DOC. Example: REM $INCLUDE: 'qlib.bi' SCREEN 12 ' VGA graphics mode ' progam draws something on screen ' I want to save the screen for later filename$ = "screen.12" ' clever (?) file name CALL GSave(filename$, oops) ' see GRAPHICS.DOC IF oops THEN ' check for errors . . . ENDIF . . . ' load "screen.12" into EMS memory ' and copy to the screen handle% = FLoadEMS(filename$) IF DOSError OR EMSError THEN ' check for errors . ' handle% not valid if error . . ENDIF CALL GLoadEMS(handle%) ' see GRAPHICS.DOC IF EMSError THEN ... ' more error control ' all done: release EMS memory CALL FreeEMS(handle%) ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: handle% = FLoadXMS(filename$) object file: floadxms.obj (xms.obj, q$alloc.obj, $asciiz.obj, fsize.obj) Similar to FLoadEMS on previous page, but uses XMS memory instead of EMS memory. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: FreeEMS(handle%) object file: ems.obj Releases a block of EMS memory allocated by AllocEMS. Your program should release any EMS blocks before the program terminates, or that memory will not be available to other programs. Do not confuse this subroutine with the EMSFree function, which determines the total expanded memory available. Example: REM $INCLUDE: 'qlib.bi' REM this example allocates an EMS memory block and later REM releases it REM see if extended memory is available REM and set a flag if so EMSused = 0 IF IsEMS THEN EMSused = 1 bytes& = 16384 ' one EMS "page" handle% = AllocEMS(bytes&) IF EMSError THEM EMSused = 0 ENDIF . ' more program here . . REM release the EMS memory CALL FreeEMS(handle%) ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: FreeXMS(handle%) object file: xms.obj De-allocates (releases) extended memory allocated by AllocXMS. Your program should release all XMS memory block before exiting, or those blocks will not be available to other programs. Do not confuse this subroutine with the XMSFree function, which determines the total extended memory available. Example: REM $INCLUDE: 'qlib.bi' REM this example allocates an XMS memory block and later REM releases it REM see if extended memory is available REM and set a flag if so XMSused = 0 IF IsXMS THEN XMSused = 1 kbytes = 16 ' 16,384 bytes handle% = AllocXMS(kbytes) IF XMSError THEM XMSused = 0 ENDIF . ' more program here . . REM release the XMS memory CALL FreeXMS(handle%) ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: r% = IsEMS object file: isems.obj Determines if EMS memory is installed in the computer. Returns r% = -1 if EMS is installed, r% = 0 if not. Example: REM $INCLUDE: 'qlib.bi' IF IsEMS THEN PRINT "EMS is installed" ELSE PRINT "no EMS memory or driver not installed" END IF ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: r% = IsXMS object file: xms.obj Determines if XMS memory is installed in the computer. Returns r% = -1 if XMS is installed, r% = 0 if not. Example: REM $INCLUDE: 'qlib.bi' IF IsXMS THEN PRINT "XMS is installed" ELSE PRINT "no XMS memory or driver not installed" END IF ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: kbytes% = XMSContig object file: xmscont.obj (xms.obj) XMSContig determines the largest contiguous XMS memory block available to your program. The total available extended memory may more than the value returned by XMSContig; see XMSFree. Note that the number returned by XMSContig is kbytes, not bytes. Example: REM $INCLUDE: 'qlib.bi' IF IsXMS THEN PRINT "Total XMS memory available is "; PRINT XMSFree PRINT "The largest contiguous XMS block is "; PRINT XMSContig ENDIF ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: errorcode% = XMSError object file: xms.obj XMSError is used after a call to a QLIB XMS subroutine to determine if an error was encountered by the XMS driver. Example: REM $INCLUDE: 'qlib.bi' IF IsXMS THEN maxXMS = XMSFree ' get total XMS memory available IF XMSError THEN ... ' check for errors after XMSFree . . . ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Function: kbytes% = XMSFree object file: xmsfree.obj (xms.obj) XMSFree determines the total XMS memory available to your program. The available extended memory may not be contiguous; see XMSContig to determine the largest contiguous block of XMS memory available. Note that the number returned by XMSFree is kbytes, not bytes. Do not confuse this function with the FreeXMS subroutine, which releases a previously allocated XMS memory block. Example: REM $INCLUDE: 'qlib.bi' IF IsXMS THEN PRINT "Total XMS memory available is "; PRINT XMSFree ENDIF ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: XMGet(handle%, xmoffset&, dataseg%, dataoffset%, bytes&) object files: xmputget.obj (xms.obj) XMGet copies data from an extended memory block to DOS memory. handle% is the XMS handle returned by AllocXMS, xmoffset is the location in the extended memory block where the data is stored (the start of the block is at xmoffset& = 0), dataseg% and dataoffset% define the location of the DOS memory area and bytes& is the number of bytes to copy from extended memory to DOS memory. Note that xmoffset& and bytes& are both LONG integers. Example: REM $INCLUDE 'qlib.bi' REM I'll use extended memory to store several 25-row text screens REM while I use graphics mode IF NOT IsXMS THEN PRINT "This example uses EXTENDED memory" PRINT "You cannot run this demo": END ENDIF kbytes% = 16 ' my XMS driver allocates ' a minimum of 16k per block handle% = AllocXMS(kbytes) IF XMSError THEN PRINT "There's a problem with XMS memory" PRINT "You cannot run this demo": END ENDIF bytes& = 4000 ' 4,000 bytes for 80x25 screen screenseg = &HB800 ' color monitor xmoffset& = 0 FOR i = 0 to 3 CALL XMPut(handle%, xmoffset&, screenseg, 0, bytes&) xmoffset& = xmoffset& + bytes& screenseg = screenseg + &H100 NEXT i . . . REM sometime later ... bytes& = 4000 ' 4,000 bytes for 80x25 screen screenseg = &HB800 ' color monitor xmoffset& = 0 FOR i = 0 to 3 CALL XMGet(handle%, xmoffset&, screenseg, 0, bytes&) xmoffset& = xmoffset& + bytes& screenseg = screenseg + &H0100 NEXT i ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ Subroutine: XMPut(handle%, xmoffset&, dataseg%, dataoffset%, bytes&) object files: xmputget.obj (xms.obj) XMPut copies data from DOS memory to an extended memory block. See XMGet for example.