Clipper Support Bulletin #4 Top ten questions Copyright (c) 1991, 1992 Nantucket Corporation. All rights reserved. Version: Clipper 5.0, revisions 1.00 - 1.03 Date: 2nd November, 1990 Revised: 20th May, 1992 Status: Inactive ================================================================================ This Support Bulletin covers the following topics: 1. Why did the utilities not build during installation? 2. Why are my Clipper 5.0 .EXE's bigger than Summer '87 .EXEs? 3. How much memory do Clipper 5.0 applications require? 3.1. Load Size 3.2. Fixed-Memory Allocations 3.3. Swap Space 4. What does "swap space exhausted" mean? 5. What is the "eut0032" error from .RTLink? 6. Where is the CL.BAT file? 7. Why do I get "memory overbooked" when compiling a large (.prg)? 8. Why does my Summer '87 Errorsys.prg not work with Clipper 5.0? 9. Why do I get "input parsing error" with RTLINK FIRST? 10.Why do I get "Undefined Function : " at runtime? ================================================================================ 1. Why did the utilities not build during installation? For an answer to this question, please refer to Clipper Support Bulletin #2. This bulletin is available on NANFORUM in Library 16 under the name S50002.TXT. Also available in Library 16 is INSTCL.BAT, a batch file that will manually complete the installation of the utilities. ================================================================================ 2. Why are my Clipper 5.0 .EXE's bigger than Summer '87 .EXEs? Clipper 5.0 executable (.EXE) files are often (though not always) larger than equivalent Summer '87 executables. Generally, this is because of the increased size of the Clipper runtime support system (the support code is larger because of the larger feature set in Clipper 5.0 and because the runtime system is more modular than in previous releases). PLEASE NOTE: the amount of memory needed to successfully run a Clipper 5.0 application is only indirectly related to the size of the executable file. In particular, increasing the amount of compiled Clipper code [compiled (.prg) files] in an application has very little effect on the amount of memory required to run the application. This is because all compiled Clipper code is automatically placed into dynamic overlays by .RTLink. Dynamically overlayed code is paged in and out of memory as needed during execution; the amount of compiled Clipper code affects the .EXE size but not the amount of memory required to run the application. In some cases, the physical size of the .EXE file (as opposed to the amount of memory needed for execution) is a concern. An example would be a large application that you wish to distribute on floppy disks. Clipper 5.0 offers several options for breaking an application into multiple files. For more information, refer to Chapter 4 of your Programming and Utilities Guide. Compiling with the debugging (/B) option increases the size of the .EXE file. When you have finished debugging your application, you should recompile all of the (.prg) files without the debugging option. Compiling with the /L option (omit line number information) also reduces the size of your .EXE file. For information on these options, refer to Chapter 3 of your Programming and Utilities Guide. For information about how .RTLink creates dynamic overlays (and how to statically overlay non-Clipper code), refer to Chapter 4 of your Programming and Utilities Guide. For information about how dynamic overlays are handled during execution (and other runtime memory management issues), refer to Clipper Support Bulletin #3. This bulletin is available on NANFORUM in Library 16 under the name S50003.TXT. For information about determining how much memory is required to run Clipper 5.0 applications, see below. ================================================================================ 3. How much memory do Clipper 5.0 applications require? PLEASE NOTE: the size of the executable (.EXE) file is only indirectly related to the amount of free memory required to successfully run the application (see above). For detailed information on Clipper 5.0 memory management, refer to Clipper Support Bulletin #3. This bulletin is available on NANFORUM in Library 16 under the name S50003.TXT. The memory requirements of a Clipper 5.0 application can be roughly divided into three categories: load size, fixed-memory allocations, and swap space. ---------------------------------------------------------------------------- 3.1. Load Size This is the memory needed to initially read the application's executable image into memory. The load size is determined at link time and is always the same for a given .EXE. .RTLink displays the load size in parentheses at the end of every link. For example, (203k). Load size is affected only slightly by the amount of compiled Clipper code in the application [this is because, by default, all compiled Clipper code is dynamically overlayed (see above).]. However, load size is significantly affected by the amount of non-Clipper (C and Assembler) code being used. This includes Clipper support code and third-party library code. Linking with a prelinked library (.PLL) can unnecessarily increase load size if your application is not actually using all of the code in the .PLL. For information on statically overlaying C and assembler code and building various configurations of prelinked libraries refer to Chapter 4 of your Programming and Utilities Guide (for .PLLs, refer also to the README file supplied with Clipper 5.0). ---------------------------------------------------------------------------- 3.2. Fixed-Memory Allocations Fixed memory is the memory allocated for system tables and other non-virtualized data. Memory allocated by C or Assembler functions (for example, Summer '87 versions of third-party libraries or overlay managers) is usually fixed memory. The fixed- memory requirement depends on which features of the system are being used. For most Clipper applications it ranges from 16K to 64K. Third-party libraries or overlay managers that allocate fixed memory may increase this requirement, as may certain Clipper programming practices (for more information on fixed-memory allocations, refer to Support Bulletin #3). ---------------------------------------------------------------------------- 3.3. Swap Space Swap space is the memory used by the Virtual Memory Manager(VMM) to swap virtualized data in and out of conventional memory. By default, the VMM uses all available memory as swap space; fixed allocations decrease the amount of swap space available (for more information, refer to Support Bulletin #3). The amount of memory needed to successfully run a particular application depends primarily on its load size and fixed-memory requirements. A general rule of thumb is that an application will require from 100K to 200K in addition to the load size reported by .RTLink. For large applications that use most of the features of Clipper, the 100K figure is usually a bare minimum; execution may be slow due to heavy swapping activity by the VMM (unless Expanded Memory is available, see Support Bulletin #3). A "hello world" program, consisting of this simple statement: ? "hello world" causes .RTLink to report a load size of approximately 125K. The application requires roughly 200K of free memory to execute (load size plus 75K). Note that increasing the size of the program (by repeating the statement 2000 times, for example) has a negligible effect on the load size and the memory requirement. As noted above, this is because of dynamic overlaying. Let's take DBU as an example. DBU is the database utility program supplied in source code form with Clipper 5.0, and it uses almost all of the features of Clipper 5.0. When linking DBU, .RTLink reports a load size of approximately 285K. Although DBU can execute in less than 400K, it tends to execute more slowly due to VMM disk swapping activity. With 425K available, swapping activity is lessened and is generally unobtrusive. As more memory is made available (or if Expanded Memory is available) performance improves, especially on large file operations. ================================================================================ 4. What does "swap space exhausted" mean? This indicates that the Clipper 5.0 Virtual Memory Manager no longer has enough main memory to work with. For more information, refer to the sections above. See also Clipper Support Bulletin #3. This bulletin is available on NANFORUM in Library 16 under the name S50003.TXT. ================================================================================ 5. What is the "eut0032" error from .RTLink? This message appears to have three possible causes: 1. There are Summer '87 compiled .OBJs or .LIBs in the current directory, or they appear in directories referenced in the LIB or OBJ environment variables, or Summer '87 .OBJs or .LIBs are referenced via a DOS APPEND command. The bundled version of .RTLink is not compatible with Summer '87 compiled programs. 2. A function or procedure has been defined twice. Removal of the duplicate declaration will solve the problem. 3. Some reports indicate this error may occur because a single object (.OBJ) module was very large. If neither of the solutions specified above eliminates this error, and you have one or more .OBJ files larger than 64K, try compiling your (.prg) files individually using the /M option. Make sure you supply all of the resultant .OBJ files to .RTLink for linking. For more information on compiler options and linking multiple .OBJ files, refer to Chapters 3 and 4 of your Programming and Utilities Guide. ================================================================================ 6. Where is the CL.BAT file? This file was inadvertently left off the distribution disks. It is a simple file. Here are the contents of CL.BAT: CLIPPER %1 IF NOT ERRORLEVEL 1 RTLINK FI %1 This method of compiling and linking is good for very small applications and test programs. Most of you will wish to take advantage of a more modular (component) application build strategy and use the RMAKE utility to only compile those files that have changed since the previous compile. You might also wish to take advantage of the improved turn-around times that can be achieved by using prelinked library (.PLL) files. Therefore, it should be noted that most applications will outgrow this type of simple batch file quickly. ================================================================================ 7. Why do I get "memory overbooked" when compiling a large (.prg)? This Clipper compiler generates this message when the [.prg(s)] being processed required more memory than the compiler has available. This error can occur on program (.prg) files containing very large functions or procedures (greater than 60K), especially when the compiler is running with very little free memory available (for example, when using many TSR utilities or executing the compiler from within a text editor). The problem can also occur when attempting to compile a monolithic application that cascades through many multiple (.prg) files through the use of the DO command, or when compiling many modules into the same object (.OBJ) file using a compiler script (.CLP) file. In all cases, either the program must be reorganized into smaller units or the compiler must be given more memory in which to run. The preferred solution is to limit individual functions and procedures to a reasonable size, group them into reasonably sized source files, and compile the files individually using the /M compiler option. The resultant .OBJ files are then presented as a list to .RTLink. This results in better program structure and also gives you the option of using the RMAKE utility to avoid unnecessary compilation. For information on compiling, linking, and using RMAKE, refer to your Programming and Utilities Guide. ================================================================================ 8. Why does my Summer '87 Errorsys.prg not work with Clipper 5.0? The Error System has been changed between versions and you must rework your old Errorsys.prg to conform to the new methods and recompile with Clipper 5.0. Should an unchanged Summer '87 compiled version of Errorsys.prg be presented to the linker, it might generate an "eut0032" error. If the Summer '87 Errorsys.prg is recompiled, then the application will successfully link. However, an Internal Error 612 will occur at runtime when an attempt is made to call the error handler. See the Clipper 5.0 version of Errorsys.prg (located by default in your \CLIPPER5\SOURCE\SYS directory) for an example of a Clipper 5.0 error handler. For more information on error handling with Clipper 5.0, call and ask for our paper entitled "Error Handling Startegies." ================================================================================ 9. Why do I get "input parsing error" with RTLINK FIRST? .RTLink is capable of supporting syntax compatible with Microsoft's LINK (using POSITIONAL mode) and Phoenix Technologies PLINK86 (using FREEFORMAT mode). Page 3-2 of the Getting Started book contains a linking example that reads: C>RTLink First This example assumes the POSITIONAL syntax. By default, however, .RTLink uses the FREEFORMAT syntax. The example should read: C>RTLink FI First The "FI" is short for "FILE," a keyword in the FREEFORMAT syntax. For more information on .RTLink, refer to Chapter 4 of your Programming and Utilitites Guide. ================================================================================ 10.Why do I get "Undefined Function : " at runtime? The Clipper functions ALLTRIM() and RIGHT() are not located in EXTEND.LIB. Instead, they are preprocessed into SUBSTR() calls by the preprocessor with a #translate directive. Index (.ntx) files contain the key expressions as text in the file header and evaluation of the key at runtime is achieved by compiling the key expression using the macro (&) operator. There is no way for the preprocessor to effect a change to the key expresion in the index file. Therefore, at runtime when the key for the index is evaluated the ALLTRIM() [or RIGHT()] function can't be found. Anything inside quotation marks ("" or '' or []) will not be affected by preprocessor directives. Therefore, if an expression is stored in a memory variable and then macro compiled the ALLTRIM() function will not be found. To work around this problem change your index keys to use SUBSTR() calls or add the following functions to your program: FUNCTION Alltrim( cString ) RETURN LTRIM(RTRIM(cString)) FUNCTION Right( cString, nCount) RETURN SUBSTR(cString, -nCount, nCount) * * *