ClipXMS version 1.10 (demo version) =================================== Introduction ------------ Thank you for your interest in ClipXMS, the XMS/EMS memory solution for Clipper 5! This file contains all the information you need (and more) to use the demo version of ClipXMS. ClipXMS allows real-mode Clipper applications to use XMS (extended) memory, freeing Clipper from its total dependence on EMS (expanded) memory. Just link ClipXMS into your application and end your worries about your user's computer configuration. Every memory manager configuration is compatible with Clipper when using ClipXMS. Demo Installation ----------------- All of the functionality of ClipXMS is contained within the CLIPXMS1.OBJ and CLIPXMS2.OBJ files. By linking in these .OBJ files, your Clipper 5 program will be able to use XMS as well as EMS memory. Your program will also be able to use the ClipXMS() function documented later in this manual. 1. Simply copy the CLIPXMS1.OBJ and CLIPXMS2.OBJ files to a directory on your hard disk where your linker can find the files at link time. 2. You may also want to copy the other files to a CLIPXMS directory on your hard disk, but none of the other files are necessary for the operation of ClipXMS. That's all that is necessary to install ClipXMS. Linking ------- ClipXMS is compatible with Clipper 5.01 and Clipper 5.20. Just add the CLIPXMS1.OBJ and CLIPXMS2.OBJ files to your link script. If you are using a dynamic overlay linker such as Blinker, the CLIPXMS1.OBJ file must be linked into the root, but the CLIPXMS2.OBJ file can be overlaid. The CLIPXMS .OBJ files replace modules found in CLIPPER.LIB. Therefore, it is a good idea to list the CLIPXMS .OBJ files near the beginning of your link script to make sure the linker links them in instead of the modules they replace in CLIPPER.LIB. Using RTLink: RTLINK FILE Main, ClipXMS1, ClipXMS2 An example Blinker link script: FILE Main FILE ClipXMS1 <-- Non-overlayable ClipXMS .OBJ file BEGINAREA FILE ClipXMS2 <-- Overlayable ClipXMS .OBJ file LIB EXTEND ENDAREA Linking with Blinker -------------------- If you are using Blinker, you can easily make two mistakes when linking in ClipXMS. 1) DO NOT list CLIPXMS1.OBJ or CLIPXMS2.OBJ as the first files in your link script -- this confuses Blinker. A Clipper compiled .OBJ file should always be your first file listed in your link script. 2) DO NOT put CLIPXMS1.OBJ in an overlay area, that is, do not list it between a pair of BEGINAREA/ENDAREA statements in your link script. Another example Blinker link script: BEGINAREA FILE Main FILE Func1 FILE Func2 FILE ClipXMS2 <-- Overlayable ClipXMS .OBJ file LIB EXTEND ENDAREA FILE ClipXMS1 <-- Non-overlayable ClipXMS .OBJ file LIB CLIPPER Internal Errors --------------- If your Clipper application reports an internal error between 8100 to 8110, the internal error is due to an internal problem within ClipXMS. If you ever get any of these internal errors, please report them to Martin Technologies immediately. The 'E' Environment Setting --------------------------- Under normal Clipper, the 'E' CLIPPER environment setting limits the amount of EMS memory the Clipper program will allocate at startup. When you link in ClipXMS, the 'E' CLIPPER environment setting will limit both EMS and XMS memory usage. Example to limit EMS and XMS memory usage to 1024K: SET CLIPPER=E:1024 The 'NOEMS' and 'NOXMS' Environment Settings -------------------------------------------- When you link in ClipXMS, two CLIPPER environment variable settings are added to your program, 'NOEMS' and 'NOXMS'. When you specify either of these settings, ClipXMS will behave as if that memory is not available. For example, if you specify 'NOEMS', ClipXMS will look only for XMS memory. If you specify 'NOXMS', ClipXMS will look only for EMS memory. If you specify both, ClipXMS will ignore any available EMS and XMS memory causing Clipper's VM system to swap memory to disk even if EMS or XMS memory is available. Example to set files to 99 and disable EMS usage: SET CLIPPER=F:99;NOEMS The only use for these settings is for testing purposes and debugging purposes if you suspect a problem with the user's EMS or XMS drivers. Please note that these settings affect the ClipXMS() function. The ClipXMS() Function ---------------------- ClipXMS includes a function named ClipXMS() that you can call from your Clipper program. The ClipXMS() function is modeled somewhat after Clipper's MEMORY() function. It takes one numeric parameter indicating the information requested and returns the information as a numeric. ClipXMS(1) returns the ClipXMS version number with two implied decimal points. Example: version 1.10 returns "110". ClipXMS(2) returns your ClipXMS serial number. ClipXMS(3) returns the amount of EMS memory detected at program startup. The NOEMS switch causes this function to return 0. ClipXMS(4) returns the amount of XMS memory detected at program startup. The NOXMS switch causes this function to return 0. ClipXMS(5) returns 0-3 indicating whether this Clipper application is using EMS memory [1], XMS memory [2], running in protected mode [3], or not using any extended memory at all [0]. ClipXMS(6) returns a number greater than 0 if the computer has available extended memory, but the computer's CONFIG.SYS did not load an XMS or EMS memory manager. This number indicates the number of kilobytes (K) of available unmanaged extended memory. You can use this function to inform the user at startup how the Clipper program's performance can be improved by loading a memory manager. Please see the example code on the diskette. XMS and EMS Memory ------------------ All IBM compatible computers except those using the original 8088 microprocessor can have expanded or extended memory. Clipper 5 is limited to using only expanded memory, therefore, if a computer is not properly configured it may have megabytes of extended memory that are not usable by your Clipper applications. The result can be very slow program operation especially in larger applications. When you link in ClipXMS, as long as the computer's CONFIG.SYS loads a memory manager such as HIMEM.SYS, QEMM, or 386MAX, your Clipper application can use any available extended or expanded memory. If no memory manager is present, ClipXMS will not be able to use any available extended memory. In that case, ClipXMS does include the ClipXMS() function which allows your program to alert the user if they have extended memory available, but have not installed a memory manager. For more information see the documentation for the ClipXMS() function. An important side effect of using ClipXMS is that your users no longer have to configure their computers for EMS (expanded) memory. This frees up 64K of high memory allowing your users to load more device drivers and TSRs into high memory with the LOADHIGH command. More About XMS and EMS Memory ----------------------------- ClipXMS will make use of either XMS or EMS memory; ClipXMS cannot use both types of memory at the same time. Therefore, when a Clipper program using ClipXMS is executed on a computer that has both XMS and EMS memory available, ClipXMS will decide which type to use based on which has the most memory available. In truth, ClipXMS will lean slightly towards using EMS memory because EMS memory is slightly faster than XMS memory on most computers. Whether ClipXMS uses XMS or EMS memory doesn't matter on most computers anyway because most memory managers will "share" XMS and EMS memory by mapping the exact same extended memory as both XMS and EMS memory, therefore, allocating one type of memory will also decrease the amount of free memory of the other type. A few memory managers such as DOS 5's HIMEM.SYS and EMM386.EXE will carve out a chunk of XMS memory to use exclusively as EMS memory. In those cases, your user might be better off getting rid of EMS memory completely and leaving it all as XMS memory. That way, there will be more XMS memory available that ClipXMS and other applications can use. If your users are using DOS 6, QEMM, 386Max, BlueMax, or most of the other commercial memory managers, you needn't be concerned because they always share XMS and EMS memory. Protected and Dual Mode ----------------------- ClipXMS is compatible with ExoSpace and Blinker 3's protected mode, but ClipXMS does not benefit protected mode programs because protected mode programs are able to use extended memory directly by themselves. If you do link ClipXMS into a protected mode program, your program will run exactly as it did without ClipXMS. Compatibility with protected mode is important if you are using Blinker 3's dual mode. When you link ClipXMS into a Blinker 3 dual mode program, ClipXMS will not interfere when the program runs in protected mode, but ClipXMS will kick in when the program runs in real mode allowing your real mode program to use XMS memory directly. Troubleshooting --------------- Q. When I run my application linked with ClipXMS, the program hangs, reboots, or reports internal error 5320 or 5321. Why? A. If you are using Blinker, you must link CLIPXMS1.OBJ into the root. Make sure it is not within a BEGINAREA/ENDAREA pair. Also make sure it is listed near the beginning of your link script so the linker will link it in instead of the Clipper modules it replaces. Q. When I link in ClipXMS the linker displays a "duplicate symbol" warning. Why? A. Some versions of Microsoft LINK and some other linkers may exhibit this behavior. If the program runs fine, this error can be ignored. If the program does not run properly, please call our technical support. An update to your linker may get rid of this error. Q. When I link in ClipXMS (using Blinker), I get the following Blinker error. Why? BLINKER : 1116 : fixup overflow at offset 006BH in segment _TEXT A. You have not linked ClipXMS in properly. You have listed one or both of the ClipXMS .OBJ files as the first file in your link script. You MUST list a Clipper compiled .OBJ file as your first .OBJ file. About the Author ---------------- Greg Martin has been providing add-on tools for the Clipper community for over five years. His first Clipper add-on, OverLay()*, has helped thousands of Clipper developers. He also co-authored ExoSpace* and ProVision:Windows*. Although he is no longer associated with any of those products, he is very proud of his previous work. He expects his new company, Martin Technologies, will be providing many more very useful tools such as ClipXMS to the Clipper and VO communities. *Trademark Information ---------------------- *CA/Clipper-ExoSpace is a trademark of Computer Associates International, Inc.; OverLay() and ProVision:Windows are trademarks of SofDesign International, Inc.