home *** CD-ROM | disk | FTP | other *** search
/ Borland Programmer's Resource / Borland_Programmers_Resource_CD_1995.iso / code / bcpp / file1 / readme.txt < prev    next >
Encoding:
Text File  |  1995-05-19  |  9.9 KB  |  250 lines
  1.  
  2.                         EMS Functions & Utilities
  3.  
  4.                     (c) 1993 4D Interactive Systems, Inc.
  5.  
  6.                                Written by
  7.                               Paul Penrose
  8.  
  9.  
  10. LEGAL STUFF
  11. -----------
  12.  
  13. The files in this archive (4DEMS.ZIP) are being released as FREEWARE.  This
  14. means that you may use the programs and functions enclosed (see below for a
  15. complete list) for whatever use you wish, at no cost, with the following
  16. restrictions:
  17.  
  18.         1.) The 4D Interactive Systems copyright notices are not removed or
  19.             altered in any way.
  20.  
  21.         2.) The following notice is included in any documentation, printed or
  22.             in electronic form, that accompanies any program or package 
  23.             containing any or all of the aformentioned programs and/or
  24.             functions:
  25.  
  26.                         EMS functions provided and (c) 1993 by
  27.                              4D Interactive Systems, Inc.
  28.  
  29.  
  30. Warranties:
  31. Basically there are none, either expressed or implied.  We do not make any
  32. claims as to the usefulness of the programs and functions included for any
  33. particular purpose.  Niether are we responsible for any loss incurred by
  34. their use.  Any rights not specifically granted in this document are
  35. reserved.
  36.  
  37. CONTENTS
  38. --------
  39.  
  40. This archive contains some of the EMS functions we created to take advantage
  41. of EMS memory.  Included is a function library used to call the EMS services,
  42. a program to test the EMS driver, a program to free allocated EMS pages by
  43. name, and a TSR to reserve EMS pages from greedy programs.  It is assumed
  44. that the user is already familar with the C language and EMS basics.  You
  45. should have the following files:
  46.  
  47.         README.TXT
  48.         EMS.ASM
  49.         EMS.H
  50.         EMSTEST.C
  51.         EMSTEST.PRJ
  52.         EMSTEST.MAK
  53.         EMSTEST.EXE
  54.         EMSFREE.C
  55.         EMSFREE.PRJ
  56.         EMSFREE.MAK
  57.         EMSFREE.EXE
  58.         RESEMS.ASM
  59.         RESEMS.EXE
  60.  
  61. EMS Functions
  62. -------------
  63.  
  64. This package provides C callable functions to access the basic LIM 4.0 EMS
  65. services.  It is composed of EMS.ASM which contains the code, and EMS.H
  66. which contains the structures, function prototypes, and external declarations
  67. needed to use the functions.  The following functions are available:
  68.  
  69. int ems_init(void)
  70.  
  71.     This function is used to initialize the function package.  It returns a
  72.     TRUE (1) if a valid EMS driver exists, otherwise FALSE (0) will be
  73.     returned.  None of the other functions will work correctly if ems_int()
  74.     is not called, or if it is called and returns a FALSE.
  75.  
  76. unsigned int ems_num_free_pages(int true_size)
  77.  
  78.     This function returns the number of free EMS pages available.  The
  79.     parameter 'true_size' should be set to TRUE (!0) to force the function
  80.     to pass along a signature that will cause the RESEMS TSR to return the
  81.     true amount of free pages, if RESEMS has been installed.  See the
  82.     section below on RESEMS for more information.
  83.  
  84. int ems_alloc(int num_pages, char *name)
  85.  
  86.     This function is used to allocate pages of EMS memory and optionally
  87.     assocate a name with it.  If the pages can't be allocated then a -1
  88.     will be returned, otherwise a handle will be returned that is used with
  89.     many of the following functions to identify the EMS pages just allocated.
  90.  
  91. int ems_free(int handle)
  92.  
  93.     This function is used to free EMS pages that were previously allocated.
  94.     Note that this function can fail if the handle has a mapping context
  95.     saved for it that has not been restored.
  96.  
  97. int ems_map_page(int handle, int logical_page, int physical_page)
  98.  
  99.     This function is used to map an EMS logical page to a physical page in
  100.     the EMS page frame.  If the page is mapped successfully, then a TRUE is
  101.     returned, otherwise a FALSE is returned.  A page must be mapped into
  102.     the page frame in order to be accessed by your program.
  103.  
  104. int ems_unmap_page(int handle, int physical_page)
  105.  
  106.     This function is used to unmap an EMS page from the EMS page frame.  Once
  107.     a page is unmapped it can't be accessed by your program until it is
  108.     mapped into the page frame again.
  109.  
  110. int ems_num_physical_pages(void)
  111.  
  112.     This function returns the number of physical pages available in the EMS
  113.     page frame.  Normally this number is four, but don't count on it.
  114.  
  115. int ems_num_open_handles(void)
  116.  
  117.     This function returns the number of open EMS handles.  Open handles are
  118.     defined as those handles that are currently in use ('opened' by a call
  119.     to ems_alloc).
  120.  
  121. int ems_get_handle_directory(handle_directory_struct *hdir)
  122.  
  123.     This function returns a map of all open EMS handles.  The information is
  124.     returned in the array pointed at by the parameter 'hdir'.  The space for
  125.     the array must have already been malloc'ed or declared before the call
  126.     to this function.  The structure handle_directory_struct can be found in
  127.     the EMS.H file.  If successfull, TRUE will be returned, else FALSE will
  128.     be returned.
  129.  
  130. int ems_find_handle(char *handle_name)
  131.  
  132.     This function returns the handle number associated with the name
  133.     'handle_name'.  If no match is found, -1 will be returned instead.
  134.  
  135. int ems_save_mapping_context(int handle)
  136.  
  137.     This function is used to save the current mapping state of the EMS page
  138.     frame.  Once saved, it can quickly be restored by a call to the
  139.     ems_restore_mapping_context() function (see below).  Only one context can
  140.     be stored per handle at one time and the handle can't be freed while
  141.     there is a context saved for it.
  142.  
  143. int ems_restore_mapping_context(int handle)
  144.  
  145.     This function is used to restore the mapping state of the EMS page that
  146.     was previously saved for the specifed handle.  Once called, further
  147.     calls to this function for the same handle will fail until the
  148.     ems_save_mapping_context() function is called again.
  149.  
  150. The following variables are used by the functions:
  151.  
  152. unsigned char ems_errnum
  153.  
  154.     This variable contains the function number of the most recently used
  155.     EMS service.  In the case of an error, this will be the service that
  156.     returned the error.
  157.  
  158. unsigned char ems_function
  159.  
  160.     This variable contains the error number of the most recent error returned
  161.     by an EMS service.
  162.  
  163. unsigned char ems_version
  164.  
  165.     This variable contains the EMS version number detected by the ems_init()
  166.     function.  For example, 4.0 will be coded as 0x40.
  167.  
  168. unsigned int ems_pageframe
  169.  
  170.     This variable contains the segment of the EMS page frame.
  171.  
  172.  
  173. EMSTEST program
  174. ---------------
  175.  
  176. This program was initially written to test the EMS function library.  Now we
  177. include it in our commerical products that use the EMS library to test the
  178. customer's EMS capibility.  It was written in C and is a good example of how
  179. to call most of the functions in the EMS library.
  180.  
  181. EMSFREE program
  182. ---------------
  183.  
  184. While developing programs that use EMS memory we discovered that if the
  185. program crashed (nobody's perfect <grin>) it could leave open EMS handles.
  186. This memory would be unavailable until the machine was rebooted (or if
  187. running under OS/2, the VDM was closed), so we wrote a simple program that
  188. will free EMS handles by name.  This was good enough for us since we always
  189. name our EMS memory, but an obvious improvement would be to allow using a
  190. handle number as well as a name for the parameter.  Another one would be to
  191. steal some code from the EMSTEST program to print out a map of all the open
  192. handles if the handle specified did not exist.  I'll leave that as an
  193. excercise for the reader!
  194.  
  195. RESEMS program
  196. --------------
  197.  
  198. While testing some software we had developed that used EMS memory we
  199. discoved that there are some programs out there that will grab all available
  200. EMS memory (whether they need it or not) leaving none for our program! There
  201. is at least one BBS that does this as well as TD286 and TD386.  No doubt
  202. there are more.  We resolved this problem by writing a TSR that intercepts
  203. the EMS 'get free pages' service and returns a number that is LESS than
  204. the actual number of free pages.  How can this help your application?  Good
  205. question.  The answer is that the TSR will recognize a "signature" placed in
  206. some of the unused registers and will return the actual number of EMS pages.
  207. This can be used reserve an number of EMS pages for use only by applications
  208. that pass the signature.  The signature is the value 4444H and must be
  209. placed in both the BX and DX registers when the 'get free pages' (EMS
  210. function 42H) is called.
  211.  
  212. I won't go into how the TSR works - that's an entire discussion in its own
  213. right - but I have tested it on DOS 5.0 and OS/2 VDMs and it has worked
  214. flawlessly.  To use it just type RESEMS nn, where nn is the number of EMS
  215. pages that you want to reserve (hide from other apps).  After the TSR is
  216. installed you can use the program again to change the number of EMS pages
  217. reserved.
  218.  
  219.  
  220. Compiling the Programs
  221. ----------------------
  222.  
  223. The C programs were compiled with Borland C++ 3.1, and the ASM modules were
  224. assembled with TASM 3.1 using TASMs IDEAL mode.  If you have a different
  225. compiler and/or assembler you will have to figure out how what changes need
  226. to be made.  I don't think you'll have many problems with the C modules, but
  227. converting from the IDEAL mode to, say, MASM mode would not be for the faint
  228. of heart.
  229.  
  230. For those of you using the Borland products, you are in luck.  Just use the
  231. enclosed PRJ and/or MAK files to recompile EMSTEST and EMSFREE programs.  To
  232. reasseble the RESEMS program just issue the command 'TASM -mx RESEMS'.
  233.  
  234. Support
  235. -------
  236.  
  237. Since this is FREEWARE we can't afford to spend much time supporting users.
  238. However, if you do find a bug, I would appreciate it if you would drop me a
  239. note, and we can both benefit.  Have fun.
  240.  
  241. Paul A. Penrose
  242. 4D Interactive Systems, Inc.
  243. 1885 University Ave, West
  244. Suite 229
  245. St. Paul, MN  55104
  246. 612-646-8104
  247. Compuserve: 72610,3377
  248. Internet: 72610.3377@compuServe.COM
  249.  
  250.