home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 19 / CD_ASCQ_19_010295.iso / dos / prg / bas / asilib11 / emsxms.doc < prev    next >
Text File  |  1994-10-22  |  17KB  |  464 lines
  1. ******************** EXPANDED AND EXTENDED MEMORY **************************
  2.  
  3. ASILIB's EMS subroutines detect and manipulate Expanded Memory hardware
  4. and software.  Expanded memory, when installed in any PC, can help solve
  5. many memory limitation problems.  Call IsEMS before using any other
  6. ASILIB EMS subroutines.  EMS memory is allocated in blocks of 16k increments.
  7.  
  8.  
  9. Error codes returned by EMS functions are:
  10.  
  11.     &hex0    =     no error
  12.     &hex8000 =     error in memory manager software
  13.     &hex8100 =     error in expanded memory hardware
  14.     &hex8400 =     bad function code passed to memory manager
  15.     &hex8500 =     no EMM handles available
  16.     &hex8900 =     you tried to allocate zero EMS memory
  17.  
  18.  
  19.  
  20. ASILIB also supports XMS memory.  XMS memory is available on most 286 or
  21. better computers with a suitable driver.  On 286 computers, XMS memory will
  22. be much slower than EMS memory.  XMS memory is not available on XT
  23. (or compatible) computers.  Call IsXMS before using any ASILIB XMS
  24. subroutines.  XMS memory is allocated in 1k increments.
  25.  
  26. XMS error codes include:
  27.  
  28.     &hex0000 =                     no error
  29.     &hexA000 =                     all extended memory is allocated
  30.     &hexA100 =                     no handles available
  31.     &hexA200, &hexA300, &hexA500 = handle is invalid
  32.     &hexA400, &hexA600 =           offset is invalid
  33.     &hexA700 =                     length is invalid
  34.  
  35.  
  36. ASILIB includes disk-based Virtual Memory subroutines (VMS) which make
  37. possible the use of disk space as though it were RAM.  Error codes returned
  38. by VMS subroutines are DOS error codes.
  39.  
  40. ASILIB's EMS, VMS and XMS subroutines were written with identical calling
  41. parameters and identical returned information for comparable subroutines.
  42. For example, AllocEMS and AllocXMS are both called with the number of bytes
  43. requested and return a handle and error code.
  44.  
  45.  
  46.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  47.  
  48. ALLOCEMS:     Allocate a block of EMS Expanded memory.
  49.  
  50. Parameters:   bytes&, emshandle, emserror
  51.  
  52.               Bytes& = number of bytes of Expanded memory requested.
  53.               EMShandle = handle for addressing the EMS memory block
  54.               EMSError = EMS error code; EMSHandle is no good if EMSError <> 0.
  55.               See also FreeEMS.
  56.  
  57. Restrictions: Call IsEMS before calling AllocEMS to determine if EMS memory
  58.               is installed; requires ASIC's Extended Math option.
  59.  
  60. Example:
  61.  
  62. REM  I want to allocate a block of EMS memory for my program
  63.  
  64.         call sub "isems", emsflag
  65.         if emsflag = -1 then keepgoing:
  66.         end
  67.  
  68. keepgoing:
  69.         emsbytes& = 100000&
  70.         call sub "allocems", (emsbytes&, emshandle, emserror)
  71.  
  72.  
  73.  
  74.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  75.  
  76. ALLOCXMS:     Allocate a block of XMS Extended memory.
  77.  
  78. Parameters:   bytes&, xmshandle, xmserror
  79.  
  80.               Bytes& = number of bytes of Extended memory requested.
  81.               XMShandle = handle for addressing the XMS memory block
  82.               XMSError = XMS error code; xmshandle is no good if xmserror <> 0.
  83.               See also FreeXMS.
  84.  
  85. Restrictions: IsXMS MUST BE CALLED BEFORE CALLING AllocXMS.
  86.               Requires ASIC's Extended Math option.  XMS memory may not
  87.               be reliable if EMS memory is emulated by EMM386, QEMM or
  88.               other similar memory managers.
  89.  
  90. Example:
  91.  
  92. REM  I want to allocate a block of XMS memory for my program
  93.  
  94.         call sub "isXMS", XMSflag
  95.         if XMSflag = -1 then keepgoing:
  96.         end
  97.  
  98. keepgoing:
  99.         XMSbytes& = 100000&
  100.         call sub "allocXMS", (XMSbytes&, XMShandle, XMSerror)
  101.  
  102.  
  103.  
  104.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  105.  
  106. EMGET:        copy data from EMS memory to system RAM
  107.  
  108. Parameters:   EMSHandle, BytesToCopy&, Segment, Offset, EMSOffset&, EMSError
  109.  
  110.               This subroutine copies BytesToCopy& bytes of data from
  111.               EMSOffset& in the EMS block associated with EMSHandle to
  112.               DOS memory at Segment:offset.  Note that BytesToCopy and
  113.               EMSOffset are both long integers; ASIC's extended math
  114.               option is required.  If something went wrong, an EMS error
  115.               code is returned in EMSError.  The segment address of data
  116.               initilaized by ASIC can be found with ASICDS.
  117.  
  118. Restrictions: Must call IsEMS and AllocEMS before using this subroutine;
  119.               also helpful to have useful data in the EMS block before
  120.               retrieving it (see EMPUT).  ASIC's Extended math option is
  121.               required.
  122.  
  123. Example:
  124.  
  125. REM  I want to copy page 1 of the Hercules memory buffer to
  126. REM  EMS memory and retrieve it at a later time
  127.  
  128.         call sub "isems", emsflag
  129.         if emsflag = 0 then drat:
  130.         hercbytes& = 32768&
  131.         call sub "allocems", (hercbytes&, handle, error)
  132.         if emserror = 0 then GotSomeEMS:
  133.         goto drat:
  134.  
  135. GotSomeEMS:
  136.         hercseg = &hexB000
  137.         hercoffset = &hex8000
  138.         call sub "emput",(handle, hercbytes&, hercseg, hercoffset, 0&, error)
  139.  
  140.         .
  141.         .
  142.         .
  143. REM  later ...
  144. REM  restore the Hercules graph to page 0
  145.         call sub "emget",(handle, hercbytes&, hercseg, 0, 0&, error)
  146.         .
  147.         .
  148.  
  149. REM  go here if no EMS
  150. drat:
  151.         .
  152.         .
  153.  
  154.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  155.  
  156. EMMOVE:       move data within an EMS memory block
  157.  
  158. Parameters:   EMSHandle, Bytes&, Source&, Destination&, EMSError
  159.  
  160.               EMSHandle is a valid handle returned by AllocEMS.  Bytes&
  161.               is the number of bytes you want to move.  Source& is the
  162.               location in the EMS block where the data is, and Destination&
  163.               is the location in the same EMS block where you want the data
  164.               to be copied.  EMMove works properly even when the source
  165.               and destination overlap.
  166.  
  167. Restrictions: Must call IsEMS and AllocEMS to produce valid EMSHandle.  Also
  168.               copy valid data to the EMS memory block with EMPut before
  169.               using EMMove.  ASIC's Extended math option is required.
  170.  
  171. Example:
  172.  
  173.         call sub "emmove", (emshandle, bytes&, source&, destination&, oops)
  174.  
  175.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  176.  
  177. EMPUT:        copy data to EMS memory from system RAM
  178.  
  179. Parameters:   EMSHandle, BytesToCopy&, Segment, Offset, EMSOffset&, EMSError
  180.  
  181.               This subroutine copies BytesToCopy& bytes of data to
  182.               EMSOffset& in the EMS block associated with EMSHandle from
  183.               DOS memory at Segment:offset.  Note that BytesToCopy and
  184.               EMSOffset are both long integers; ASIC's extended math
  185.               option is required.  If something went wrong, an EMS error
  186.               code is returned in EMSError.  The segment address of data
  187.               initilaized by ASIC can be found with ASICDS.
  188.  
  189. Restrictions: Must call IsEMS and AllocEMS before using this subroutine.
  190.               ASIC's Extended math option is required.
  191.  
  192. Example:
  193.  
  194.               See example for EMGET.
  195.  
  196.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  197.  
  198. EMSSPACE:     determine total and available EMS memory
  199.  
  200. Parameters:   no input parameters; returns total&, available&, emserror
  201.  
  202.               EMSSPACE returns the total size of installed EMS memory in
  203.               bytes and the available unallocated EMS memory, also in
  204.               bytes.  EMSError = 0 if there were no problems, otherwise
  205.               an EMS error is returned.  ASIC's extended math option is
  206.               required.
  207.  
  208. Example:
  209.  
  210.         call sub "emsspace", emstotal&. emsfree&, emserror
  211.  
  212.  
  213.  
  214. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  215.  
  216. FLOADEMS:     reads a disk file and copies to EMS memory
  217.  
  218. Parameters:   File$, emshandle, bytes&, errcode
  219.  
  220.               Loads file$ to EMS memory, returning ems handle, size of
  221.               file, and an error code.  Note that errcode may either be
  222.               a DOS error or an EMS error.  Errcode = 0 if there were
  223.               no problems.  ASIC's Extended math option is required.
  224.  
  225. Restrictions: The program must call IsEMS before calling FLoadEMS to
  226.               determine if EMS memory is available.
  227.  
  228. Example:
  229.  
  230.         file$ = "ASILIB.DOC"
  231.         call sub "floadems", file$, emshandle, bytes&, errcode
  232.  
  233.  
  234.  
  235. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  236.  
  237. FLOADXMS:     reads a disk file and copies to XMS memory
  238.  
  239. Parameters:   File$, XMShandle, bytes&, errcode
  240.  
  241.               Loads file$ to XMS memory, returning XMS handle, size of
  242.               file, and an error code.  Note that errcode may either be
  243.               a DOS error or an XMS error.  Errcode = 0 if there were
  244.               no problems.  ASIC's Extended math option is required.
  245.  
  246. Restrictions: The program must call IsXMS before calling FLoadXMS to
  247.               determine if XMS memory is available.
  248.  
  249. Example:
  250.  
  251.         file$ = "ASILIB.DOC"
  252.         call sub "floadxms", file$, xmshandle, bytes&, errcode
  253.  
  254.  
  255.  
  256.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  257.  
  258. FREEEMS:      release EMS memory allocated by other ASILIB subroutines
  259.  
  260. Parameters:   ems handle, emserror
  261.  
  262.               Releases EMS memory assicated with the EMS handle, allowing
  263.               that memory space to be used by other subroutines.  Returns
  264.               emserror = 0 if no problem.
  265.  
  266. Example:
  267.     
  268. REM  Allocate a block of 50000 bytes, then release the block later.
  269.  
  270.         call sub "allocems", 50000&, emshandle
  271.         .
  272.         .
  273.         .
  274.         call sub "freeems", emshandle, emserror
  275.  
  276.  
  277.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  278.  
  279. FREEXMS:      release XMS memory allocated by other ASILIB subroutines
  280.  
  281. Parameters:   xms handle, emserror
  282.  
  283.               Releases XMS memory assicated with the XMS handle, allowing
  284.               that memory space to be used by other subroutines.  Returns
  285.               emserror = 0 if no problem.
  286.  
  287. Example:
  288.     
  289. REM  Allocate a block of 50000 bytes, then release the block later.
  290.  
  291.         call sub "allocxms", 50000&, xmshandle
  292.         .
  293.         .
  294.         .
  295.         call sub "freexms", xmshandle, xmserror
  296.  
  297.  
  298.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  299.  
  300. FSAVEEMS:     Save EMS memory block as a disk file
  301.  
  302. Parameters:   Filename$, emshandle, bytes&, errcode
  303.  
  304.               FSaveEMS copies the first bytes& of EMS memory associated
  305.               with emshandle to a disk file.  If a file by the same name
  306.               already exists, it will be overwritten by the new file.
  307.               Errcode = 0 if there were no problems; either EMS or DOS
  308.               errors are possible if something went wrong.  Note that
  309.               bytes& is a long integer, requiring ASIC's extended math
  310.               option.
  311.  
  312. Restrictions: Requires a valid EMS handle; bytes& must not be greater than
  313.               the size of the memory block associated with emshandle.
  314.  
  315. Example:
  316.  
  317.         file$="emsblock.dat"
  318.         call sub "fsaveems", file$, emshandle, bytes&, errcode
  319.  
  320.  
  321.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  322.  
  323. FSAVEXMS:     Save XMS memory block as a disk file
  324.  
  325. Parameters:   Filename$, xmshandle, bytes&, errcode
  326.  
  327.               FSaveXMS copies the first bytes& of XMS memory associated
  328.               with xmshandle to a disk file.  If a file by the same name
  329.               already exists, it will be overwritten by the new file.
  330.               Errcode = 0 if there were no problems; either XMS or DOS
  331.               errors are possible if something went wrong.  Note that
  332.               bytes& is a long integer, requiring ASIC's extended math
  333.               option.
  334.  
  335. Restrictions: Requires a valid XMS handle; bytes& must not be greater than
  336.               the size of the memory block associated with xmshandle.
  337.  
  338. Example:
  339.  
  340.         file$="xmsblock.dat"
  341.         call sub "fsavexms", file$, xmshandle, bytes&, errcode
  342.  
  343.  
  344.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  345.  
  346. ISEMS:        Determies if Expanded memory is installed
  347.  
  348. Parameters:   No input parameters; returns EMSStatus = 0 if no EMS or
  349.               if EMS is having problems.  EMSStatus = -1 if all OK.
  350.  
  351. Example:
  352.  
  353. REM  determine if EMS memory is installed and ready.
  354.  
  355.         call sub "IsEMS", EMSStatus
  356.  
  357.  
  358.  
  359.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  360.  
  361. ISXMS:        Determines if Extended memory and XMS driver are installed.
  362.  
  363.  
  364. Parameters:   No input parameters; returns XMSStatus = 0 if no XMS or
  365.               if XMS driver is having problems.  XMSStatus = -1 if all OK.
  366.  
  367. Example:
  368.  
  369. REM  determine if XMS memory is installed and ready.
  370.  
  371.         call sub "IsXMS", XMSStatus
  372.  
  373.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  374.  
  375. XMGET:        copy data from XMS memory to system RAM
  376.  
  377. Parameters:   XMSHandle, BytesToCopy&, Segment, Offset, XMSOffset&, XMSError
  378.  
  379.               This subroutine copies BytesToCopy& bytes of data from
  380.               XMSOffset& in the XMS block associated with XMSHandle to
  381.               DOS memory at Segment:offset.  Note that BytesToCopy and
  382.               XMSOffset are both long integers; ASIC's extended math
  383.               option is required.  If something went wrong, an XMS error
  384.               code is returned in XMSError.  The segment address of data
  385.               initiliazed by ASIC can be found with ASICDS
  386.  
  387. Restrictions: Must call IsXMS and AllocXMS before using this subroutine;
  388.               also helpful to have useful data in the XMS block before
  389.               retrieving it (see XMPUT).  ASIC's Extended math option is
  390.               required.
  391.  
  392. Example:
  393.  
  394. REM  I want to copy page 1 of the Hercules memory buffer to
  395. REM  XMS memory and retrieve it at a later time
  396.  
  397.         call sub "isxms", xmsflag
  398.         if xmsflag = 0 then drat:
  399.         hercbytes& = 32768&
  400.         call sub "allocxms", (hercbytes&, handle, error)
  401.         if xmserror = 0 then GotSomeXMS:
  402.         goto drat:
  403.  
  404. GotSomeXMS:
  405.         hercseg = &hexB000
  406.         hercoffset = &hex8000
  407.         call sub "XMput",(handle, hercbytes&, hercseg, hercoffset, 0&, error)
  408.  
  409.         .
  410.         .
  411.         .
  412. REM  later ...
  413. REM  restore the Hercules graph to page 0
  414.         call sub "XMget",(handle, hercbytes&, hercseg, 0, 0&, error)
  415.         .
  416.         .
  417.  
  418. REM  go here if no XMS
  419. drat:
  420.         .
  421.         .
  422.  
  423.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  424.  
  425. XMMOVE:       move data within an XMS memory block
  426.  
  427. Parameters:   XMSHandle, Bytes&, Source&, Destination&, XMSError
  428.  
  429.               XMSHandle is a valid handle returned by AllocXMS.  Bytes&
  430.               is the number of bytes you want to move.  Source& is the
  431.               location in the XMS block where the data is, and Destination&
  432.               is the location in the same XMS block where you want the data
  433.               to be copied.  XMMove works properly even when the source
  434.               and destination overlap.
  435.  
  436. Restrictions: Must call IsXMS and AllocXMS to produce valid XMSHandle.  Also
  437.               copy valid data to the XMS memory block with XMPut before
  438.               using XMMove.  ASIC's Extended math option is required.
  439.  
  440. Example:
  441.  
  442.         call sub "XMmove", xmshandle, bytes&, source&, destination&, oops
  443.  
  444.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  445.  
  446. XMPUT:        copy data to XMS memory from system RAM
  447.  
  448. Parameters:   XMSHandle, BytesToCopy&, Segment, Offset, XMSOffset&, XMSError
  449.  
  450.               This subroutine copies BytesToCopy& bytes of data to
  451.               XMSOffset& in the XMS block associated with XMSHandle from
  452.               DOS memory at Segment:offset.  Note that BytesToCopy and
  453.               XMSOffset are both long integers; ASIC's extended math
  454.               option is required.  If something went wrong, an XMS error
  455.               code is returned in XMSError.  The segment address of data
  456.               initiliazed by ASIC can be found with ASICDS
  457.  
  458. Restrictions: Must call IsXMS and AllocXMS before using this subroutine.
  459.               ASIC's Extended math option is required.
  460.  
  461. Example:
  462.  
  463.               See example for XMGET.
  464.