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 : <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 : <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)
   

                              *  *  *
