home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 9 / CD_ASCQ_09_1193.iso / news / 558 / virtmem / virtmem.doc < prev    next >
Text File  |  1993-09-09  |  17KB  |  464 lines
  1. (***************************************************************)
  2. VIRTUAL MEMORY SYSTEM  Version 1.0
  3. From Patel Enterprises
  4. (***************************************************************)
  5.  
  6. The following set of functions and procedures may be used in
  7. your program to give your applications virtual memory capability.
  8. When requesting memory, the system uses the following resources
  9. (if available) in the order indicated:
  10.  
  11.             Extended memory (XMS)
  12.             Expanded memory (EMS)
  13.             Conventional memory
  14.             Disk space
  15.  
  16. To properly set up this system, your program must call VMInit
  17. prior to calling any other routines. Also, you must call VMClose
  18. before exiting. The function/procedure descriptions below provide
  19. further information on the functionality of each routine. Certain
  20. limitations of this software is also described below.
  21.  
  22. You will need an extended memory manager (XMM) such as HIMEM.SYS
  23. in order to access your XMS memory. You will also need an
  24. expanded memory manager (EMM) to access your EMS memory. Both
  25. EMM386 and QEMM386 have been thoroughly tested without any
  26. problems. My recommendation is that you install only the XMM,
  27. whenever possible, because XMS memory can be accessed quicker
  28. than EMM memory. Also, if you have little or none of both types
  29. of memory, or if you anticipate much  use of disk space as
  30. memory, some type of disk caching utility will help reduce
  31. frequent disk access which slows down your program.
  32.  
  33. For your information, this software has been successfully used in
  34. several commercially available applications. However, as with any
  35. software, I cannot guarantee that this software will meet your
  36. requirements or that the software operation will be uninterrupted
  37. or error free.
  38.  
  39. In no event shall I be liable to you for any damages or loss of
  40. any kind arising out of the use or the inability to use this
  41. software. As such, the entire risk is assumed by you.
  42.  
  43. You may freely copy and distribute this software, provided that
  44. no modifications are made to any of the files. Also, the files
  45. must be distributed together, not individually.
  46.  
  47. Files in this package are:
  48.  
  49.                             VIRTMEM.DOC  - this file
  50.                             VIRTMEM6.TPU - Unit for TP 6.0
  51.                             VIRTMEM7.TPU - Unit for TP 7.0
  52.                             VIRTTEST.PAS - Sample code
  53.  
  54. If you do use this software, please send US$10 to the following
  55. address. I will try to make available units for Turbo Pascal 5.5
  56. or older upon request. I would appreciate comments and/or
  57. suggestions from all. They may also be sent to me at this
  58. address, or to me on EXEC-PC, the largest BBS in the world.
  59.  
  60.             Jash Patel
  61.             325 Fawn Valley
  62.             Lansing, KS 66043-1723
  63.  
  64. (***************************************************************)
  65. DATA TYPES and VARIABLES
  66. (***************************************************************)
  67.  
  68. Type
  69.    VMHandleType  - Handle used to identify virtual memory blocks.
  70.    VMMemoryType  - Values that may be returned by VMQueryInfo to
  71.                    indicate the type of memory used by the
  72.                    virtual memory block. Possibles values: XMS,
  73.                    EMS, CMS and DMS.
  74.    VMErrCodeType - A Word.
  75.  
  76. Var
  77.    VMMajor,
  78.    VMMinor  : Word - These variables contain the version number
  79.                      for the virtual memory system, for example,
  80.                      if version 1.0, VMMajor = 1 and VMMinor = 0.
  81.  
  82. (***************************************************************)
  83. FUNCTION/PROCEDURE DESCRIPTIONS
  84. (***************************************************************)
  85.  
  86. Procedure VMInit (Path : String; SafetyPool : LongInt);
  87.  
  88. Parameters:
  89.    Path       - Directory where disk memory is to be allocated.
  90.                 Path may not be blank and must include a drive
  91.                 and a directory. Example: C:\TEMP or A:\
  92.    SafetyPool - The virtual memory system will not allocate from
  93.                 conventional memory when the largest contiguous
  94.                 conventional memory block is less than or equal
  95.                 to this value. If this value is less than 0,
  96.                 SafetyPool defaults to 65536 bytes. Using a large
  97.                 value (such as MaxLongInt) cause the virtual
  98.                 memory manager not to dispense any conventional
  99.                 memory. This is what you should do if you intend
  100.                 to access many memory block simultaneously - see
  101.                 VMLock.
  102.  
  103. Return value:
  104.    None
  105.  
  106. Note:
  107.    This procedure performs the necessary virtual memory system
  108.    initialization. It must be called prior to calling any other
  109.    procedure or functions. VMInit allocates all available
  110.    extended and/or expanded memory at this time, and then
  111.    allocates 64KB of conventional memory for use by the virtual
  112.    memory manager.
  113.  
  114. (***************************************************************)
  115.  
  116. Procedure VMClose;
  117.  
  118. Parameters:
  119.    None
  120.  
  121. Return value:
  122.    None
  123.  
  124. Note:
  125.    Your program must call VMClose before exiting. This procedure
  126.    performs the necessary clean up, including releasing the
  127.    extended, expanded and conventional memory allocated by
  128.    VMInit. All memory dispensed to you from the extended and/or
  129.    expanded memory pool is effectively releases even if you did
  130.    not release it by calling VMFree. Turbo Pascal automatically
  131.    releases all unfreed conventional memory. Disk memory,
  132.    however, if not released by you, will result in swap files on
  133.    disk. If this happens you should delete them.
  134.  
  135. (***************************************************************)
  136.  
  137. Function VMInstalled : Boolean;
  138.  
  139. Parameters:
  140.    None
  141.  
  142. Return value:
  143.    TRUE  - Indicates that virtual memory manager is installed.
  144.    FALSE - Virtual memory manager not installed.
  145.  
  146. (***************************************************************)
  147.  
  148. Function VMXMSInstalled : Boolean;
  149.  
  150. Parameters:
  151.    None
  152.  
  153. Return value:
  154.    TRUE  - Indicates that extended memory is available and will
  155.            be used when memory is requested.
  156.    FALSE - Extended memory not available.
  157.  
  158. Note:
  159.    Conventional memory and disk memory is always available even
  160.    if extended memory is not available.
  161.  
  162. (***************************************************************)
  163.  
  164. Function VMEMSInstalled : Boolean;
  165.  
  166. Parameters:
  167.    None
  168.  
  169. Return value:
  170.    TRUE  - Indicates that expanded memory is available and will
  171.            be used when memory is requested.
  172.    FALSE - Expanded memory not available.
  173.  
  174. Note:
  175.    Conventional memory and disk memory is always available even
  176.    if expanded memory is not available.
  177.  
  178. (***************************************************************)
  179.  
  180. Function VMXMSAvail : LongInt;
  181.  
  182. Parameters:
  183.    None
  184.  
  185. Return value:
  186.    Returns the total amount of extended memory available.
  187.  
  188. (***************************************************************)
  189.  
  190. Function VMEMSAvail : LongInt;
  191.  
  192. Parameters:
  193.    None
  194.  
  195. Return value:
  196.    Returns the total amount of expanded memory available.
  197.  
  198. (***************************************************************)
  199.  
  200. Function VMCMSAvail : LongInt;
  201.  
  202. Parameters:
  203.    None
  204.  
  205. Return value:
  206.    Returns the size of the largest contiguous conventional memory
  207.    minus safety pool size specified when calling VMInit. This
  208.    value may also be obtained as follows:
  209.  
  210.    If VMSafetyPool >= MaxAvail Then
  211.       VMCMSAvail := 0
  212.    Else
  213.       VMCMSAvail := MaxAvail-VMSafetyPool;
  214.  
  215. (***************************************************************)
  216.  
  217. Function VMDMSAvail : LongInt;
  218.  
  219. Parameters:
  220.    None
  221.  
  222. Return value:
  223.    Returns the number of free bytes on the disk drive specified
  224.    by the path passed to VMInit;
  225.  
  226. (***************************************************************)
  227.  
  228. Function VMAvailable : LongInt;
  229.  
  230. Parameters:
  231.    None
  232.  
  233. Return value:
  234.    Returns the sum of values returned by VMXMSAvail, VMEMSAvail,
  235.    VMCMSAvail and VMDMSAvail.
  236.  
  237. (***************************************************************)
  238.  
  239. Procedure VMAlloc (Var Handle : VMHandleType; Size : Word);
  240.  
  241. Parameters:
  242.    Handle - Handle for the memory block requested. After the
  243.             requested memory is allocated, the contents of this
  244.             variable is used to identify the memory block. You
  245.             must not discard this information in order to use
  246.             this memory.
  247.    Size   - Amount of memory requested. This value must be larger
  248.             than 0 and should be an even number. If an odd number
  249.             is specified, the size is automatically incremented
  250.             by 1. The largest value may be 65535.
  251.  
  252. Return value:
  253.    None
  254.  
  255. Note:
  256.    The virtual memory manager will allow you to allocate a
  257.    maximum of 6553 blocks of memory, regardless of how much more
  258.    memory you may have. The virtual memory descriptor table must
  259.    reside within a single 64KB segment. Each table entry takes 10
  260.    bytes, hence 65536 Div 10 = 6553 entries. In order to use the
  261.    memory block you allocated, you must lock it first - see
  262.    VMLock.
  263.  
  264. (***************************************************************)
  265.  
  266. Procedure VMFree (Var Handle : VMHandleType);
  267.  
  268. Parameters:
  269.    Handle - Handle for the memory block to release. You must make
  270.             sure that there are no locks on this memory block, or
  271.             it will not be released.
  272.  
  273. Return value:
  274.    None
  275.  
  276. (***************************************************************)
  277.  
  278. Function VMLock (Var Handle : VMHandleType) : Pointer;
  279.  
  280. Parameters:
  281.    Handle - Handle for the memory block to lock.
  282.  
  283. Return value:
  284.    A pointer to the memory block in conventional memory.
  285.  
  286. Note:
  287.    When a virtual memory block is allocated by VMAlloc, it isn't
  288.    immediately available to you. When you lock the memory block,
  289.    it is moved into conventional memory unless, of course, if it
  290.    is already in conventional memory. For example, if the block
  291.    of memory resides on disk, locking it causes it to be read
  292.    into conventional memory, and its address return to you as a
  293.    pointer. At this point you may write to or read from this
  294.    memory. When you unlock it the data is sent back to the disk,
  295.    and the conventional memory is freed so that you may lock in
  296.    other blocks of virtual memory. The same applies to extended
  297.    and expanded memory. It is not necessary to unlock a block in
  298.    order to lock another, but it is recommended that you do, as
  299.    explained below.
  300.  
  301.    You may have already realized a problem with this - what if
  302.    there isn't enough conventional memory to lock the virtual
  303.    memory block? VMLock will return NIL in this case. The key is
  304.    to allocate small blocks of memory instead of large ones.
  305.    Locked blocks take up conventional memory, ignoring safety
  306.    pool. Also, you should not have many locked blocks
  307.    simultaneously. A block should be locked, read from or written
  308.    to, and immediately unlocked.
  309.  
  310.    Locking an already locked memory block do not use addition
  311.    conventional memory. Doing so only returns the pointer to the
  312.    memory used. In addition, the lock counter is incremented. A
  313.    block may be locked consecutively as many as 255 times.
  314.  
  315. (***************************************************************)
  316.  
  317. Procedure VMUnlock (Var Handle : VMHandleType);
  318.  
  319. Parameters:
  320.    Handle - Handle for the memory block to lock.
  321.  
  322. Return value:
  323.    None
  324.  
  325. Note:
  326.    Unlocks the virtual memory block if the lock counter is 1.
  327.    If the counter is larger than 1, it is decremented by 1. See
  328.    VMLock.
  329.  
  330.  
  331. (***************************************************************)
  332.  
  333. Procedure VMQueryInfo (    Handle : VMHandleType;
  334.                        Var Size   : Word;
  335.                        Var Mem    : VMMemoryType;
  336.                        Var Locked : Boolean);
  337.  
  338. Parameters:
  339.    Handle - Handle for the memory block.
  340.    Size   - On return, indicates the size of the allocated block.
  341.    Mem    - On return, indicates the type of memory used when
  342.             allocateby VMAlloc. Values may be XMS, EMS, CMS or
  343.             DMS.
  344.    Locked - Indicates whether this handle is locked or not.
  345.  
  346. Return value:
  347.    None
  348.  
  349. Note:
  350.    Queries for information about a virtual memory block.
  351.  
  352. (***************************************************************)
  353.  
  354. Function VMResult : VMErrCodeType;
  355.  
  356. Parameters:
  357.    None
  358.  
  359. Return value:
  360.    Error code.
  361.  
  362. Note:
  363.    Extensive error checking is performed by most of the
  364.    functions and procedures. When an error occures, the error
  365.    code is stored in an internal variable. Any error code other
  366.    than VMOk indicates that an error occured. VMResult returns
  367.    this code and resets the code to VMOk. As long as this code is
  368.    not VMOk, most of the procedures and functions will just
  369.    return without doing anything. Hence, you must call VMResult
  370.    after every procedure or function call with the exception of
  371.    the following:
  372.  
  373.    Procedure VMQueryInfo;
  374.    Function VMXMSInstalled;
  375.    Function VMEMSInstalled;
  376.    Function VMXMSAvail;
  377.    Function VMEMSAvail;
  378.    Function VMCMSAvail;
  379.  
  380. (***************************************************************)
  381.  
  382. Function VMErrorMsg (ErrCode : VMErrCodeType) : String;
  383.  
  384. Parameters:
  385.    ErrCode - This is the error code returned by VMResult
  386.  
  387. Return value:
  388.    A string containing a brief description of the error.
  389.  
  390. Note:
  391.    The following are the possible error codes and their
  392.    descriptions:
  393.  
  394.    VMOk                - 'No error'
  395.    VMNoDriverErr       - 'Driver not installed (VM)'
  396.    VMInitDoneErr       - 'Driver already installed (VM)'
  397.    VMDriverInitErr     - 'Insufficent memory to install driver (VM)'
  398.    VMInvalidPathErr    - 'Invalid file path (VM)'
  399.    VMMemParamsErr      - 'Invalid memory usage parameters (VM)'
  400.    VMHandleErr         - 'Invalid handle (VM)'
  401.    VMInvalidDrvErr     - 'Invalid drive letter (VM)'
  402.    VMOutOfMemErr       - 'Insufficient virtual memory (VM)'
  403.    VMOutOfHandlesErr   - 'No free handles available (VM)'
  404.    VMFileCreateErr     - 'Swap file creation error (VM)'
  405.    VMFileAllocErr      - 'Swap file allocation error (VM)'
  406.    VMFileUnallocErr    - 'Swap file unallocation error (VM)'
  407.    VMHandleLockedErr   - 'Handle is locked (VM)'
  408.    VMHandleUnlockedErr - 'Handle is not locked (VM)'
  409.    VMNoRequestErr      - 'No virtual memory requested (VM)'
  410.    VMFileOpenErr       - 'Error opening swap file (VM)'
  411.    VMFileReadErr       - 'Error reading swap file (VM)'
  412.    VMFileWriteErr      - 'Error writing swap file (VM)'
  413.    VMUnallocErr        - 'Error unallocating memory (VM)'
  414.    VMTooManyLocksErr   - 'Handle locked too many times (VM)'
  415.  
  416.    XMSNoDriverErr       - 'Driver not installed (XMS)'
  417.    XMSInitDoneErr       - 'Driver already installed (XMS)'
  418.    XMSFunctionCallErr   - 'Unknown function call (XMS)'
  419.    XMSVDiskFoundErr     - 'RAMDISK detected (XMS)'
  420.    XMSA20Err            - 'Error at handler A20 (XMS)'
  421.    XMSGeneralErr        - 'General driver error (XMS)'
  422.    XMSUnrecoverableErr  - 'Unrecoverable error (XMS)'
  423.    XMSNoHMAErr          - 'HMA does not exist (XMS)'
  424.    XMSHMAInUseErr       - 'HMA already in use (XMS)'
  425.    XMSHMAOutOfSpaceErr  - 'HMA out of space (XMS)'
  426.    XMSHMANotAllocateErr - 'HMA not allocated (XMS)'
  427.    XMSA20StillOnErr     - 'Handler A20 still on (XMS)'
  428.    XMSOutOfMemoryErr    - 'Insufficient extended memory (XMS)'
  429.    XMSOutOfHandlesErr   - 'No free handles available (XMS)'
  430.    XMSHandleErr         - 'Invalid handle (XMS)'
  431.    XMSSrcHandleErr      - 'Inavlid source handle (XMS)'
  432.    XMSSrcOffsetErr      - 'Invalid source offset (XMS)'
  433.    XMSDestHandleErr     - 'Invalid destination handle (XMS)'
  434.    XMSDestOffsetErr     - 'Invalid destination offset (XMS)'
  435.    XMSInvalidLenErr     - 'Invalid length (XMS)'
  436.    XMSOverlapErr        - 'Illegal overlapping (XMS)'
  437.    XMSParityErr         - 'Parity error (XMS)'
  438.    XMSUMBUnlockedErr    - 'UMB is not locked (XMS)'
  439.    XMSUMBLockedErr      - 'UMB is still locked (XMS)'
  440.    XMSUMBOverflowErr    - 'UMB lock counter overflow (XMS)'
  441.    XMSUMBLockFailedErr  - 'UMB cannot be locked (XMS)'
  442.    XMSUMBTooLargeErr    - 'UMB too large (XMS)'
  443.    XMSOutOfUMBErr       - 'No more UMB available (XMS)'
  444.    XMSUMBSegmentErr     - 'Invalid UMB segment address (XMS)'
  445.  
  446.    EMSNoDriverErr     - 'Driver not installed (EMS)'
  447.    EMSInitDoneErr     - 'Driver already installed (EMS)'
  448.    EMSDriverErr       - 'Driver error (EMS)'
  449.    EMSHardwareErr     - 'Hardware error (EMS)'
  450.    EMSHandleErr       - 'Invalid handle (EMS)'
  451.    EMSFunctionCallErr - 'Unknown function call (EMS)'
  452.    EMSOutOfHandlesErr - 'No free handles available (EMS)'
  453.    EMSMapSaveRestErr  - 'Error when saving/restoring mapping (EMS)'
  454.    EMSMoreAvailErr    - 'More pages requested than are available (EMS)'
  455.    EMSMoreFreeErr     - 'More pages requested than are free (EMS)'
  456.    EMSNoRequestErr    - 'No pages requested (EMS)'
  457.    EMSLogicalPageErr  - 'Logical page does not belong to handle (EMS)'
  458.    EMSPhysicalPageErr - 'Invalid physical page number (EMS)'
  459.    EMSMapRangeFullErr - 'Mapping memory range is full (EMS)'
  460.    EMSMapSaveDoneErr  - 'Map save has already been done (EMS)'
  461.    EMSMapSaveFirstErr - 'Mapping must be saved first (EMS)'
  462.  
  463. (***************************************************************)
  464.