Contents of the S50004.TXT file
CLIPPER 5.0 SUPPORT BULLETIN #4
BULLETIN REVISED: 02 Nov. 1990
PRODUCT: Clipper 5.0
AFFECTED VERSIONS: Rev. 1.00 - 1.03
SUBJECT: Top Ten Questions on Clipper 5.0.
1.1 Why did the utilities not build during the install ?
For an answer to this question please refer to CLIPPER 5.0
SUPPORT BULLETIN #2. The bulletin is available on NANFORUM in
data Library 16 under the name S50002.TXT. Also available in
Library 16 is INSTCL.BAT, a batch file which will manually
complete the installation of the utilities.
1.2 Why are my 5.0 .EXE's bigger than S87 ?
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
Compiling with the debugging option (/B) increases the size of
the .EXE file. When you are through debugging your application,
you should recompile it without the debugging option. Compiling
with the /L option (omit line number information) 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 5.0 SUPPORT BULLETIN #3. This bulletin is available on
NANFORUM in data Library 16 under the name S50003.TXT.
For information about determining how much memory is required to
run 5.0 applications, see below.
1.3 How much memory do 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 5.0 SUPPORT BULLETIN #3. This bulletin is available
on NANFORUM in data Library 16 under the name S50003.TXT.
The memory requirements of a Clipper 5.0 application can be
roughly divided into three categories:
This is the memory needed to initially read the application's
executable image into memory. The load size is determined at
link time; it is always the same for a given .EXE. .RTLink
displays the load size in parentheses at the end of every link.
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 pre-linked 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 pre-linked libraries refer to Chapter 4 of your
Programming and Utilities Guide (for .PLLs refer also to the
README file supplied with Clipper 5.0).
Fixed-memory is the memory allocated for system tables and other
non-virtualized data. Memory allocated by C or Assembler
functions (for example, Summer87 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 which allocate
fixed memory may increase this requirement, as may certain
Clipper programming practices (for more information on
fixed-memory allocations, refer to bulletin #3).
Swap space is the memory used by the Virtual Memory Manager(VMM)
to "swap" virtualized data in and out of main 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 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 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.
The database utility program supplied in source code form with
Clipper 5.0. DBU uses almost all of the features of Clipper 5.0.
.RTLink reports a load size of approximately 285K. Although DBU
can execute in less than 400K, it tends to bog down 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.
1.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 5.0
SUPPORT BULLETIN #3. This bulletin is available on NANFORUM in
data Library 16 under the name S50003.TXT.
1.5 What is "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. .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 that this error may occur because a
single object module was very large. If neither of the above
solutions eliminates this error message, and you have one or more
.OBJ files larger than 64K, try compiling your .PRG files
individually using the /M compiler option. Make sure to 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
1.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:
IF NOT ERRORLEVEL 1 RTLINK FI %1
This method of compile and link 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 which have changed since the previous
compile. You might also wish to take advantage of the improved
turn-around times which can be had from using Pre-Linked Library
(.PLL) files. Therefore, it should be noted that most
applications will outgrow this type of simple Batch file quickly.
1.7 Why do I get "memory overbooked" when compiling a large .prg?
This message is generated because the .PRG(s) that the Clipper
Compiler was attempting to process required more memory than the
compiler had available.
This error can occur on programs which contain 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 "DO PrgFileName", or when compiling many
modules into the same .OBJ using a .CLP list.
In all cases, either the program must be reorganized into smaller
units or the compiler must be given more memory to run in.
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.
1.8 Why does my Summer'87 errorsys.prg not work with 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 5.0.
Should an unchanged S87 compiled version of errorsys.prg be
presented to the linker, it might create an "eut0032" error.
If the S87 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.
1.9 Why do I get "input parsing error" with RTLINK FIRST?
RTLink is capable of supporting syntax which is compatible with
Microsoft's LINK (POSITIONAL) and Phoenix Technologies PLINK86
Page 3-2 of the Getting Started book contains a linking example
This example assumes the POSITIONAL syntax. By default, however,
.RTLink uses the FREEFORMAT syntax. The example should read:
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.
1.10 Why do I get "Undefined Function : " at runtime?
The functions Alltrim() and Right() are not in Extend.LIB.
Instead, they are preprocessed into Substr() calls by the
preprocessor with a #translate() directive.
Index (.ntx) files contain the "key" expression as text in the
file header and evaluation of the key at runtime is achieved by
macro-expansion (&). 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'ed (&), the
Alltrim() function will not be found.
To work around this problem you can change your index keys and
macro's to Substr() calls or add the following program shorts to
parameter p1, p2
return Substr(p1, -p2, p2)